Metadata-Version: 1.0
Name: ftw.pdfgenerator
Version: 1.2.7
Summary: A library for generating PDF representations of Plone objects with LaTeX.
Home-page: https://github.com/4teamwork/ftw.pdfgenerator
Author: 4teamwork GmbH
Author-email: mailto:info@4teamwork.ch
License: GPL2
Description: Introduction
        ============
        
        ``ftw.pdfgenerator`` is meant to be used for generating PDFs from structured
        data using predefined `LaTeX`_ views. It is not useful for converting
        full HTML pages into `LaTeX`_ / PDFs, although it is able to convert small HTML
        chunks into `LaTeX`_.
        
        .. figure:: http://onegov.ch/approved.png/image
        :align: right
        :target: http://onegov.ch/community/zertifizierte-module/ftw.pdfgenerator
        
        Certified: 01/2013
        
        
        Requirements
        ============
        
        ``ftw.pdfgenerator`` requires a TeX distribution with a ``pdflatex`` executable to be installed.
        
        These TeX distributions are recommended:
        
        - Mac OS: `MacTeX`_
        - Linux / Unix: `TeX Live`_
        - Windows: `MiKTeX`_
        
        The package is compatible with `Plone`_ 4.x.
        
        
        Installing
        ==========
        
        Add ``ftw.pdfgenerator`` to your buildout configuration:
        
        ::
        
        [instance]
        eggs =
        ftw.pdfgenerator
        
        Usage
        =====
        
        The pdfgenerator uses LaTeX for generating the PDF. You need to provide a
        layout and a view for your context for being able to create a PDF.
        
        
        Real world examples
        -------------------
        
        Some packages using ``ftw.pdfgenerator``:
        
        - ``ftw.meeting`` has a PDF export of the meeting minutes:
        https://github.com/4teamwork/ftw.meeting/tree/master/ftw/meeting/latex
        - ``ftw.book`` produces a PDF of the book recursively:
        https://github.com/4teamwork/ftw.book/tree/master/ftw/book/latex
        
        
        Defining a layout
        -----------------
        
        A layout is a multi adapter addapting ``context, request, builder``. You can
        easily define a new layout using the `mako`_ templating engine
        (example: ``layout.py``):
        
        ::
        
        >>> from example.conference.session import ISession
        >>> from ftw.pdfgenerator.interfaces import IBuilder
        >>> from ftw.pdfgenerator.interfaces import ICustomizableLayout
        >>> from ftw.pdfgenerator.layout.customizable import CustomizableLayout
        >>> from zope.component import adapts
        >>> from zope.interface import Interface
        >>> from zope.interface import implements
        
        >>> class SessionLayout(MakoLayoutBase):
        ...     adapts(ISession, Interface, IBuilder)
        ...     implements(ICustomizableLayout)
        ...
        ...     template_directories = ['session_templates']
        ...     template_name = 'layout.tex'
        ...
        ...     def before_render_hook(self):
        ...         self.use_babel()
        ...         self.use_package('inputenc', options='utf8')
        ...         self.use_package('fontenc', options='T1')
        
        
        Register the layout with zcml (example: ``configure.zcml``):
        
        ::
        
        <configure
        xmlns="http://namespaces.zope.org/zope"
        xmlns:browser="http://namespaces.zope.org/browser">
        
        <adapter factory=".layout.SessionLayout"
        provides="ftw.pdfgenerator.interfaces.ILaTeXLayout" />
        
        </configure>
        
        
        Create a template as defined in ``SessionLayout.template_name``
        (example: ``session_templates/layout.tex``):
        
        ::
        
        <%block name="documentclass">
        \documentclass[a4paper,10pt]{article}
        </%block>
        
        <%block name="usePackages">
        ${packages}
        </%block>
        
        <%block name="beneathPackages">
        </%block>
        
        
        <%block name="aboveDocument">
        </%block>
        
        \begin{document}
        
        <%block name="documentTop">
        % if logo:
        ${logo}
        % endif
        </%block>
        
        ${content}
        
        <%block name="documentBottom">
        </%block>
        
        \end{document}
        
        
        There are more methods on the layout, see the definition in
        ``ftw.pdfgenerator.interfaces.ILaTeXLayout``.
        
        
        Defining a LaTeX view
        ---------------------
        
        For every context for which a PDF is generated a LaTeX view (``ILaTeXView``)
        is rendered. The view is a multi adapter adapting ``context, request, layout``.
        There is a view based on the `mako`_ templating engine which can be extended
        (example: ``views.py``):
        
        ::
        
        >>> from example.conference.session import ISession
        >>> from ftw.pdfgenerator.interfaces import ILaTeXLayout
        >>> from ftw.pdfgenerator.interfaces import ILaTeXView
        >>> from ftw.pdfgenerator.view import MakoLaTeXView
        >>> from zope.component import adapts
        >>> from zope.interface import Interface
        >>> from zope.interface import implements
        
        >>> class SessionLaTeXView(MakoLaTeXView):
        ...     adapts(ISession, Interface, ILaTeXLayout)
        ...     implements(ILaTeXView)
        ...
        ...     template_directories = ['session_templates']
        ...     template_name = 'view.tex'
        ...
        ...     def get_render_arguments(self):
        ...         return {'title': self.convert(self.context.Title()),
        ...                 'description': self.convert(self.context.description),
        ...                 'details': self.convert(self.context.details)}
        
        
        Register the view with zcml (example: ``configure.zcml``):
        
        ::
        
        <configure
        xmlns="http://namespaces.zope.org/zope"
        xmlns:browser="http://namespaces.zope.org/browser">
        
        <adapter factory=".views.SessionLaTeXView"
        provides="ftw.pdfgenerator.interfaces.ILaTeXView" />
        
        </configure>
        
        
        Create a template with the name defined in the class
        (example: ``session_templates/view.tex``):
        
        ::
        
        \section*{${title}}
        % if description:
        \small ${description}
        % endif
        \normalsize ${details}
        
        
        Generating a PDF
        ----------------
        
        When a layout and a view for the context are registered the PDF can be
        generated by simply calling the view ``@@export_pdf`` on the context.
        
        
        Recursive views
        ---------------
        
        When extending from ``ftw.pdfgenerator.view.RecursiveLaTeXView`` and inserting
        the variable ``latex_content`` in your template, the view automatically renders
        all children for which a ``ILaTeXView`` is found.
        
        
        HTML to LaTeX conversion
        ------------------------
        
        ``ftw.pdfgenerator`` comes with a simple but powerful HTML to LaTeX converter
        which is optimized for the common WYSIWYG-Editors used in Plone.
        
        The converter can be used:
        
        - in views, using ``self.convert(html)``
        - in layouts, using ``self.get_converter().convert(html)``
        
        It uses regular expressions for the simple conversions and python
        subconverters for the more complicated conversions. The converter is heavily
        customizable.
        
        
        Customizable layouts
        --------------------
        
        When using multiple, independent addon packages using ``ftw.pdfgenerator``,
        every package may implement a new, specific layout. This can be painful if
        there is a need to customize all layouts and add a logo image for example.
        
        For making this easier all customizable layouts can be customized with one
        single adapter. This only works for layouts subclassing
        ``ftw.pdfgenerator.layout.customizable.CustomizableLayout``. Those layouts
        need to follow certain concepts and provide inheritable blocks in the `mako`_
        template. Ensure you follow the standards by subclassing and running the
        tests from
        ``ftw.pdfgenerator.tests.test_customizable_layout.TestCustomizableLayout``.
        
        Implementing customization adapter is very simple when customizable layouts
        are used. For example we change the logo image (assume the logo is at
        ``custom/mylogo.png``):
        
        ::
        
        >>> from ftw.pdfgenerator.customization import LayoutCustomization
        >>> from ftw.pdfgenerator.interfaces import ILayoutCustomization
        >>> from zope.interface import implements
        >>>
        >>> class MyCustomization(LayoutCustomization):
        ...     implements(ILayoutCustomization)
        ...
        ...     template_directories = ['custom']
        ...     template_name = 'layout_customization.tex'
        ...
        ...     def before_render_hook(self):
        ...         self.add_raw_template_file('mylogo.png')
        ...         self.layout.use_package('graphicx')
        ...
        ...     def get_render_arguments(self, args):
        ...         args['logo'] = r'\includegraphics{mylogo.png}'
        ...         return args
        
        It is also possible to change the template and fill predefined slots
        (example: ``custom/layout_customization.tex``):
        
        ::
        
        <%inherit file="original_layout" />
        <%block name="documentTop">
        my branding
        </%block>
        
        The layout customization adapter adapts ``context``, ``request`` and the original
        ``layout``.
        
        
        Tables
        ======
        
        ``ftw.pdfgenerator`` is able to convert HTML-Tables to LaTeX. Since HTML and LaTeX
        have completely different presentation concepts the convertion is limitted.
        
        For getting the best results theese rules should be followed:
        
        - Define the width of every column. The table will be streched to the text width in
        the defined proportions. Without defining the widths LaTeX is unable to insert
        newlines dynamically.
        
        - Use relative widths (%).
        
        - Define table headings using ``<thead>`` for long tables which may be splitted over
        multiple pages.
        
        CSS classes:
        
        ``page-break`` (<table>)
        Force the ``longtable`` environment, allowing LaTeX to split up the table over
        multiple pages.
        
        ``no-page-break`` (<table>)
        Force the ``tabular`` environment, prohibiting LaTeX from splitting the table up
        over multiple pages. If the table is longer than the page it is truncated - content
        may be missing in this case.
        
        ``border-grid`` / ``listing`` (<table>)
        Display the table in a grid: every cell has a border on every side.
        
        ``notListed`` (<table>)
        When using a ``<caption>``, do not list the table in the list of tables.
        
        ``border-left`` (<td>, <th>)
        Display a border on the left side of the cell.
        
        ``border-right`` (<td>, <th>)
        Display a border on the right side of the cell.
        
        ``border-top`` (<td>, <th>)
        Display a border on the top side of the cell.
        
        ``border-bottom`` (<td>, <th>)
        Display a border on the bottom side of the cell.
        
        ``right`` (<td>, <th>)
        Right align the content of the cell.
        
        ``left`` (<td>, <th>)
        Left align the content of the cell.
        
        ``center`` (<td>, <th>)
        Center the content of the cell.
        
        ``indent2`` (<td>, <th>)
        Indent the content by 0.2 cm.
        
        ``indent10`` (<td>, <th>)
        Indent the content by 1 cm.
        
        ``bold`` (<td>, <th>)
        Display cell contents in bold font.
        
        ``grey`` (<td>, <th>)
        Display cell content with grey text color.
        
        ``footnotesize`` (<td>, <th>)
        Display cell content with smaller font size (``\footnotesize``).
        
        ``scriptsize`` (<td>, <th>)
        Display cell content with smaller font size (``\scriptsize``).
        
        
        
        Links
        =====
        
        - Main github project repository: https://github.com/4teamwork/ftw.pdfgenerator
        - Issue tracker: https://github.com/4teamwork/ftw.pdfgenerator/issues
        - Package on pypi: http://pypi.python.org/pypi/ftw.pdfgenerator
        - Continuous integration: https://jenkins.4teamwork.ch/search?q=ftw.pdfgenerator
        
        Copyright
        =========
        
        This package is copyright by `4teamwork <http://www.4teamwork.ch/>`_.
        
        ``ftw.pdfgenerator`` is licensed under GNU General Public License, version 2.
        
        
        .. _LaTeX: http://www.latex-project.org/
        .. _Plone: http://www.plone.org/
        .. _MacTeX: http://www.tug.org/mactex/2011/
        .. _Tex Live: http://www.tug.org/texlive/
        .. _MiKTeX: http://www.miktex.org/
        .. _mako: http://www.makotemplates.org/
        
        .. image:: https://cruel-carlota.pagodabox.com/94ca8bd22baa91bf8038e9d2c210aa37
        :alt: githalytics.com
        :target: http://githalytics.com/4teamwork/ftw.pdfgenerator
        
        Changelog
        =========
        
        1.2.7 (2013-05-24)
        ------------------
        
        - Table width calculation: treat "px" the same as widths without measure units.
        [jone]
        
        
        1.2.6 (2013-04-17)
        ------------------
        
        - Update package classifiers.
        [jone]
        
        
        1.2.5 (2013-01-24)
        ------------------
        
        - Use local text formatting commands, such as \textbf instead of {\bf }. #13
        [jone]
        
        - onegov.ch approved: add badge to readme.
        [jone]
        
        - Declare missing dependencies.
        [jone]
        
        - Make layout annotatable.
        This allows to store certain informations while building the PDF.
        [jone]
        
        - Plone 4.3 compatibility.
        [jone]
        
        
        1.2.4 (2012-08-21)
        ------------------
        
        - Tables: fix wrong indentation when using combined css classes
        "right" and "bold".
        [jone]
        
        - Tables: support width definition in "style" attribute of cells. #10
        [jone]
        
        - Fix ampersand escaping in urls. #11
        [jone]
        
        - Templating: fix template lookup for five based browser views which
        are wrapped into a meta class.
        [jone]
        
        - List conversion: handle empty list items.
        
        - Removing them in ordered and unordered lists.
        - Keep them in definition lists, since two tags result in one item.
        
        [jone]
        
        
        1.2.3 (2012-06-13)
        ------------------
        
        - Table converter: fix centering of cell contents by using correct
        LaTeX (\centering instead of \center\vspace{-1.5em}).
        [jone]
        
        - Hyperlink:
        
        - Support resolveUid (with upper U) resolution.
        - Remove "./" from concatenated relative urls.
        - Support hyphenation in urls.
        
        [jone]
        
        
        1.2.2 (2012-06-11)
        ------------------
        
        - Improve support for mathematic characters (utf8 and html-entities).
        [jone]
        
        - Table: support "summary" attribute as caption (TinyMCE support).
        [jone]
        
        - Handle hyphenation characters and entities.
        [jone]
        
        - Hyperlinks: handle underscores and hash keys in urls.
        [jone]
        
        - Fix centering of table captions which used to affect contents beneath.
        [jone]
        
        - Fix quotation marks around bold text.
        [jone]
        
        
        1.2.1 (2012-05-10)
        ------------------
        
        - Table converter: fix TypeError when using colspan without defining any widths.
        [jone]
        
        
        1.2 (2012-05-09)
        ----------------
        
        - HTML to LaTeX: escape $ charactor. Otherwise it enables math-mode.
        [jone]
        
        - Tables: use seperate caption implementation for non-floating environments.
        [jone]
        
        - Tables: fix border collapse bug when using rowspan.
        [jone]
        
        - Tables: calculate widths properly respecting \tabcolsep.
        [jone]
        
        - Tables: support plone css classes (grid, listing, vertical).
        [jone]
        
        
        1.1.2 (2012-05-02)
        ------------------
        
        - Add convert_plain method to converter and view.
        [phgross]
        
        - Add encode_htmlentities utils function.
        [phgross]
        
        
        1.1.1 (2012-04-30)
        ------------------
        
        - Listing converter: limit nested lists to four levels since LaTeX has this limit.
        [jone]
        
        - Listing converter: fix bug when nested lists are not within a item.
        [jone]
        
        - Add provide_request_layer util method to directly provide an interface on the request
        [eschmutz]
        
        
        1.1 (2012-03-22)
        ----------------
        
        - Improve testing speed by using ``ftw.testing``.
        [jone]
        
        - Add table converter css classes:
        indent2 -> indent the content 0.2cm
        indent10 -> indent the content 1cm
        bold -> display content with bold font
        grey -> Display cell content with grey text color.
        footnotesize -> Display cell content with smaller font size.
        scriptsize -> Display cell content with smaller font size.
        [jone]
        
        - Listing converter: cleanup bad html in case when lists are nested without list items.
        FCKEditor somehow produces that sometimes.
        [jone]
        
        - Implement customizable layouts.
        [jone]
        
        
        1.0.2 (2012-03-08)
        ------------------
        
        - Table converter: add css classes for aligning cells ("right", "center", "left").
        [jone]
        
        - Table converter: add cell-border functionality, using css classes "border-right",
        "border-left", "border-top" and "border-bottom".
        [jone]
        
        - Table converter: improve grid border, add classes "border-grid" and "listing" for enabling grid borders.
        [jone]
        
        - Table converter: use "tabular" for small tables. #3
        [jone]
        
        
        1.0.1 (2012-03-05)
        ------------------
        
        - Add use_babel function to layout, enabling the preferred language.
        [jone]
        
        
        1.0b2 (2012-02-28)
        ------------------
        
        - Added missing MANIFEST.in.
        [phgross]
        
        
        1.0b1 (2012-02-24)
        ------------------
        
        - Added a "debug-pdf" view, enabling the pdf debug mode temporarily.
        [jone]
        
        - Added some French translations
        [ttschanz]
        
        - Implement hyperlink converter.
        [jone]
        
        - Implement convertion of definition lists.
        [jone]
        
        - Rename as_pdf view to export_pdf.
        [jone]
        
Keywords: ftw pdf generator
Platform: UNKNOWN
Classifier: Environment :: Web Environment
Classifier: Framework :: Plone
Classifier: Framework :: Plone :: 4.1
Classifier: Framework :: Plone :: 4.2
Classifier: Framework :: Plone :: 4.3
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License (GPL)
Classifier: Programming Language :: Python
Classifier: Topic :: Software Development :: Libraries :: Python Modules
