Metadata-Version: 1.0
Name: ftw.pdfgenerator
Version: 1.0.2
Summary: A library for generating PDF representations of Plone objects with LaTeX.
Home-page: http://github.com/4teamwork/ftw.pdfgenerator
Author: 4teamwork GmbH
Author-email: mailto:info@4temamwork.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`_.
        
        
        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 ILaTeXLayout
            >>> from ftw.pdfgenerator.layout.makolayout import MakoLayoutBase
            >>> from zope.component import adapts
            >>> from zope.interface import Interface
            >>> from zope.interface import implements
        
            >>> class SessionLayout(MakoLayoutBase):
            ...     adapts(ISession, Interface, IBuilder)
            ...     implements(ILaTeXLayout)
            ...
            ...     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>
            ...
            ... \begin{document}
            ... ${content}
            ... \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.
        
        
        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/job/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/
        
        Changelog
        =========
        
        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: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License (GPL)
Classifier: Programming Language :: Python
