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.3 and 5.1.
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.
Custom subconverters
********************
Footnote
++++++++
Generate a footnote by wrapping any text in a ``span`` with the
class ``footnote``. Specify the footnote text in the ``data-footnote`` attribute.
Example:
::
<span class="footnote" data-footnote="text in footnote">text on the page</span>
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
=====
- Github: https://github.com/4teamwork/ftw.pdfgenerator
- Issues: https://github.com/4teamwork/ftw.pdfgenerator/issues
- 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/
Changelog
=========
1.6.11 (2024-10-02)
-------------------
- Remove line break from table environment end and add a smallbreak instead. [buchi]
1.6.10 (2021-05-06)
-------------------
- Use a cookie instead of session storage to store the debug mode state. [mathias.leimgruber]
1.6.9 (2020-03-11)
------------------
- Add support for converting hexadecimal XML/HTML entities [Nachtalb]
1.6.8 (2020-02-11)
------------------
- Don't use reference_catalog for uid look up, since it does not exist anymore in plone 5. [mathias.leimgruber]
1.6.7 (2020-02-03)
------------------
- Don't use session storage anymore - does not work with plone 5 for anonymous users. [mathias.leimgruber]
1.6.6 (2020-01-17)
------------------
- Fix unicode error (when unicode and non-unicode strings are joined). [busykoala]
1.6.5 (2019-10-29)
------------------
- Fix escaping of underscore in hyperlink labels. [jone]
1.6.4 (2019-03-26)
------------------
- Robustified URL conversion. [Rotonen]
1.6.3 (2019-01-07)
------------------
- Drop support for plone 4.2. [njohner]
- Handle vertical tab special character. [njohner]
1.6.2 (2018-09-13)
------------------
- Fix escaping issues for dash characters in hyperlink labels. [jone]
1.6.1 (2018-05-18)
------------------
- Fix encoding error by passing charset hint to BeautifulSoup when converting tables. [lgraf]
- Add Plone 5 compatibility. [phgross]
- Fixed exporting the zip and latex for pdfs who are setting the pdf title. [phgross]
1.6.0 (2017-03-03)
------------------
- Add possibility to set the pdf title via build arguments. [phgross]
- Support file objects in Builder.add_file. [jone]
- Drop Plone 4.1 support.
1.5.0 (2016-06-08)
------------------
- Implement URL converter for supporting hyphenation in URLs. [jone]
1.4.1 (2016-03-30)
------------------
- Listing converter: avoid using beatiful soup. [jone]
- Fix recursive subconverter locking problem. [jone]
1.4 (2016-03-02)
----------------
- Added footnote subconverter.
[lknoepfel]
1.3.8 (2015-12-11)
------------------
- Don't add rows where not all cells are headcells to the tablehead.
[tschanzt]
- Fix table converting when there are less cells than specified and no colspan attribute is given.
[tschanzt]
1.3.7 (2015-04-13)
------------------
- Fix table converting error when there are more ``<col>`` tags than cells.
[jone]
- HTML converter: fix leading quote when at beginning of string.
[jone]
1.3.6 (2015-03-20)
------------------
- Workaround for too long makeindex argument causing buffer overflow.
[jone]
1.3.5 (2015-02-19)
------------------
- PDF Builder: fix pdflatex after making index.
When references are used in the index, e.g. the index title is in the TOC,
more than one rerun is required after making the index.
[jone]
1.3.4 (2014-09-30)
------------------
- Add a ``quoted_umlauts`` method to the converter.
The method converts all umlauts to the quoted notation.
[jone]
- Index: sort German umlauts correctly by including umlaut.ist.
For this to work properly all \index{} entries must escape umlauts
with quotes, e.g. ``h"oflich``.
[jone]
1.3.3 (2014-07-24)
------------------
- Fix PDF rendering bug when having underscores in internal hyperlinks.
[jone]
1.3.2 (2014-06-11)
------------------
- Improve table layouting.
- Increase vertical padding of table cells.
- Add line break and vertical space after all tables.
[jone]
1.3.1 (2014-06-02)
------------------
- Fix backslash LaTeX to use `\textbackslash` instead of `\\`.
This fixes problems with backslash in certain environments such as tables.
[jone]
1.3.0 (2014-03-04)
------------------
- Run makeindex when ``*.idx`` files were created during PDF build.
This allows to create indexes easily just by using the latex commands.
The builder takes care that the index is built and the PDF rebuilt properly.
[jone]
1.2.10 (2014-02-05)
-------------------
- LaTeX: use math mode for asterisks (*), so they get no longer swallowed.
[jone]
1.2.9 (2014-01-17)
------------------
- Update French translations.
[jone]
- Hyperlinks in footnotes: use \url instead of manual hyphenation hints.
This fixes that "" is visible in footer urls with certain hyperref
package versions.
[jone]
- Table: fix error where rowspan cells made other cells swap rows.
[jone]
- Tables: fix width of cells spanning multiple columns.
This is especially visible when they are centered.
[jone]
1.2.8 (2013-10-21)
------------------
- Make hyphens before commas non-breakable.
[jone]
- Use non-breaking spaces for some more abbreviations.
[jone]
- Remove HTML comments when converting HTML to LaTeX.
[jone]
- Use non-breaking spaces and en-dashes for formatting swiss currency.
[jone]
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]
Raw data
{
"_id": null,
"home_page": "https://github.com/4teamwork/ftw.pdfgenerator",
"name": "ftw.pdfgenerator",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "ftw pdf generator",
"author": "4teamwork AG",
"author_email": "mailto:info@4teamwork.ch",
"download_url": "https://files.pythonhosted.org/packages/53/cc/09596d748ea018f7b8111ea710b51cc3f2c62f1f6451e8ab696815316a1d/ftw.pdfgenerator-1.6.11.tar.gz",
"platform": null,
"description": "Introduction\n============\n\n``ftw.pdfgenerator`` is meant to be used for generating PDFs from structured\ndata using predefined `LaTeX`_ views. It is not useful for converting\nfull HTML pages into `LaTeX`_ / PDFs, although it is able to convert small HTML\nchunks into `LaTeX`_.\n\n.. figure:: http://onegov.ch/approved.png/image\n :align: right\n :target: http://onegov.ch/community/zertifizierte-module/ftw.pdfgenerator\n\n Certified: 01/2013\n\n\nRequirements\n============\n\n``ftw.pdfgenerator`` requires a TeX distribution with a ``pdflatex`` executable to be installed.\n\nThese TeX distributions are recommended:\n\n- Mac OS: `MacTeX`_\n- Linux / Unix: `TeX Live`_\n- Windows: `MiKTeX`_\n\nThe package is compatible with `Plone`_ 4.3 and 5.1.\n\n\nInstalling\n==========\n\nAdd ``ftw.pdfgenerator`` to your buildout configuration:\n\n::\n\n [instance]\n eggs =\n ftw.pdfgenerator\n\nUsage\n=====\n\nThe pdfgenerator uses LaTeX for generating the PDF. You need to provide a\nlayout and a view for your context for being able to create a PDF.\n\n\nReal world examples\n-------------------\n\nSome packages using ``ftw.pdfgenerator``:\n\n- ``ftw.meeting`` has a PDF export of the meeting minutes:\n https://github.com/4teamwork/ftw.meeting/tree/master/ftw/meeting/latex\n- ``ftw.book`` produces a PDF of the book recursively:\n https://github.com/4teamwork/ftw.book/tree/master/ftw/book/latex\n\n\nDefining a layout\n-----------------\n\nA layout is a multi adapter addapting ``context, request, builder``. You can\neasily define a new layout using the `mako`_ templating engine\n(example: ``layout.py``):\n\n::\n\n >>> from example.conference.session import ISession\n >>> from ftw.pdfgenerator.interfaces import IBuilder\n >>> from ftw.pdfgenerator.interfaces import ICustomizableLayout\n >>> from ftw.pdfgenerator.layout.customizable import CustomizableLayout\n >>> from zope.component import adapts\n >>> from zope.interface import Interface\n >>> from zope.interface import implements\n\n >>> class SessionLayout(MakoLayoutBase):\n ... adapts(ISession, Interface, IBuilder)\n ... implements(ICustomizableLayout)\n ...\n ... template_directories = ['session_templates']\n ... template_name = 'layout.tex'\n ...\n ... def before_render_hook(self):\n ... self.use_babel()\n ... self.use_package('inputenc', options='utf8')\n ... self.use_package('fontenc', options='T1')\n\n\nRegister the layout with zcml (example: ``configure.zcml``):\n\n::\n\n <configure\n xmlns=\"http://namespaces.zope.org/zope\"\n xmlns:browser=\"http://namespaces.zope.org/browser\">\n\n <adapter factory=\".layout.SessionLayout\"\n provides=\"ftw.pdfgenerator.interfaces.ILaTeXLayout\" />\n\n </configure>\n\n\nCreate a template as defined in ``SessionLayout.template_name``\n(example: ``session_templates/layout.tex``):\n\n::\n\n <%block name=\"documentclass\">\n \\documentclass[a4paper,10pt]{article}\n </%block>\n\n <%block name=\"usePackages\">\n ${packages}\n </%block>\n\n <%block name=\"beneathPackages\">\n </%block>\n\n\n <%block name=\"aboveDocument\">\n </%block>\n\n \\begin{document}\n\n <%block name=\"documentTop\">\n % if logo:\n ${logo}\n % endif\n </%block>\n\n ${content}\n\n <%block name=\"documentBottom\">\n </%block>\n\n \\end{document}\n\n\nThere are more methods on the layout, see the definition in\n``ftw.pdfgenerator.interfaces.ILaTeXLayout``.\n\n\nDefining a LaTeX view\n---------------------\n\nFor every context for which a PDF is generated a LaTeX view (``ILaTeXView``)\nis rendered. The view is a multi adapter adapting ``context, request, layout``.\nThere is a view based on the `mako`_ templating engine which can be extended\n(example: ``views.py``):\n\n::\n\n >>> from example.conference.session import ISession\n >>> from ftw.pdfgenerator.interfaces import ILaTeXLayout\n >>> from ftw.pdfgenerator.interfaces import ILaTeXView\n >>> from ftw.pdfgenerator.view import MakoLaTeXView\n >>> from zope.component import adapts\n >>> from zope.interface import Interface\n >>> from zope.interface import implements\n\n >>> class SessionLaTeXView(MakoLaTeXView):\n ... adapts(ISession, Interface, ILaTeXLayout)\n ... implements(ILaTeXView)\n ...\n ... template_directories = ['session_templates']\n ... template_name = 'view.tex'\n ...\n ... def get_render_arguments(self):\n ... return {'title': self.convert(self.context.Title()),\n ... 'description': self.convert(self.context.description),\n ... 'details': self.convert(self.context.details)}\n\n\nRegister the view with zcml (example: ``configure.zcml``):\n\n::\n\n <configure\n xmlns=\"http://namespaces.zope.org/zope\"\n xmlns:browser=\"http://namespaces.zope.org/browser\">\n\n <adapter factory=\".views.SessionLaTeXView\"\n provides=\"ftw.pdfgenerator.interfaces.ILaTeXView\" />\n\n </configure>\n\n\nCreate a template with the name defined in the class\n(example: ``session_templates/view.tex``):\n\n::\n\n \\section*{${title}}\n % if description:\n \\small ${description}\n % endif\n \\normalsize ${details}\n\n\nGenerating a PDF\n----------------\n\nWhen a layout and a view for the context are registered the PDF can be\ngenerated by simply calling the view ``@@export_pdf`` on the context.\n\n\nRecursive views\n---------------\n\nWhen extending from ``ftw.pdfgenerator.view.RecursiveLaTeXView`` and inserting\nthe variable ``latex_content`` in your template, the view automatically renders\nall children for which a ``ILaTeXView`` is found.\n\n\nHTML to LaTeX conversion\n------------------------\n\n``ftw.pdfgenerator`` comes with a simple but powerful HTML to LaTeX converter\nwhich is optimized for the common WYSIWYG-Editors used in Plone.\n\nThe converter can be used:\n\n- in views, using ``self.convert(html)``\n- in layouts, using ``self.get_converter().convert(html)``\n\nIt uses regular expressions for the simple conversions and python\nsubconverters for the more complicated conversions. The converter is heavily\ncustomizable.\n\nCustom subconverters\n********************\n\nFootnote\n++++++++\n\nGenerate a footnote by wrapping any text in a ``span`` with the\nclass ``footnote``. Specify the footnote text in the ``data-footnote`` attribute.\nExample:\n\n::\n\n <span class=\"footnote\" data-footnote=\"text in footnote\">text on the page</span>\n\nCustomizable layouts\n--------------------\n\nWhen using multiple, independent addon packages using ``ftw.pdfgenerator``,\nevery package may implement a new, specific layout. This can be painful if\nthere is a need to customize all layouts and add a logo image for example.\n\nFor making this easier all customizable layouts can be customized with one\nsingle adapter. This only works for layouts subclassing\n``ftw.pdfgenerator.layout.customizable.CustomizableLayout``. Those layouts\nneed to follow certain concepts and provide inheritable blocks in the `mako`_\ntemplate. Ensure you follow the standards by subclassing and running the\ntests from\n``ftw.pdfgenerator.tests.test_customizable_layout.TestCustomizableLayout``.\n\nImplementing customization adapter is very simple when customizable layouts\nare used. For example we change the logo image (assume the logo is at\n``custom/mylogo.png``):\n\n::\n\n >>> from ftw.pdfgenerator.customization import LayoutCustomization\n >>> from ftw.pdfgenerator.interfaces import ILayoutCustomization\n >>> from zope.interface import implements\n >>>\n >>> class MyCustomization(LayoutCustomization):\n ... implements(ILayoutCustomization)\n ...\n ... template_directories = ['custom']\n ... template_name = 'layout_customization.tex'\n ...\n ... def before_render_hook(self):\n ... self.add_raw_template_file('mylogo.png')\n ... self.layout.use_package('graphicx')\n ...\n ... def get_render_arguments(self, args):\n ... args['logo'] = r'\\includegraphics{mylogo.png}'\n ... return args\n\nIt is also possible to change the template and fill predefined slots\n(example: ``custom/layout_customization.tex``):\n\n::\n\n <%inherit file=\"original_layout\" />\n <%block name=\"documentTop\">\n my branding\n </%block>\n\nThe layout customization adapter adapts ``context``, ``request`` and the original\n``layout``.\n\n\nTables\n======\n\n``ftw.pdfgenerator`` is able to convert HTML-Tables to LaTeX. Since HTML and LaTeX\nhave completely different presentation concepts the convertion is limitted.\n\nFor getting the best results theese rules should be followed:\n\n- Define the width of every column. The table will be streched to the text width in\n the defined proportions. Without defining the widths LaTeX is unable to insert\n newlines dynamically.\n\n- Use relative widths (%).\n\n- Define table headings using ``<thead>`` for long tables which may be splitted over\n multiple pages.\n\nCSS classes:\n\n``page-break`` (<table>)\n Force the ``longtable`` environment, allowing LaTeX to split up the table over\n multiple pages.\n\n``no-page-break`` (<table>)\n Force the ``tabular`` environment, prohibiting LaTeX from splitting the table up\n over multiple pages. If the table is longer than the page it is truncated - content\n may be missing in this case.\n\n``border-grid`` / ``listing`` (<table>)\n Display the table in a grid: every cell has a border on every side.\n\n``notListed`` (<table>)\n When using a ``<caption>``, do not list the table in the list of tables.\n\n``border-left`` (<td>, <th>)\n Display a border on the left side of the cell.\n\n``border-right`` (<td>, <th>)\n Display a border on the right side of the cell.\n\n``border-top`` (<td>, <th>)\n Display a border on the top side of the cell.\n\n``border-bottom`` (<td>, <th>)\n Display a border on the bottom side of the cell.\n\n``right`` (<td>, <th>)\n Right align the content of the cell.\n\n``left`` (<td>, <th>)\n Left align the content of the cell.\n\n``center`` (<td>, <th>)\n Center the content of the cell.\n\n``indent2`` (<td>, <th>)\n Indent the content by 0.2 cm.\n\n``indent10`` (<td>, <th>)\n Indent the content by 1 cm.\n\n``bold`` (<td>, <th>)\n Display cell contents in bold font.\n\n``grey`` (<td>, <th>)\n Display cell content with grey text color.\n\n``footnotesize`` (<td>, <th>)\n Display cell content with smaller font size (``\\footnotesize``).\n\n``scriptsize`` (<td>, <th>)\n Display cell content with smaller font size (``\\scriptsize``).\n\n\n\nLinks\n=====\n\n- Github: https://github.com/4teamwork/ftw.pdfgenerator\n- Issues: https://github.com/4teamwork/ftw.pdfgenerator/issues\n- Pypi: http://pypi.python.org/pypi/ftw.pdfgenerator\n- Continuous integration: https://jenkins.4teamwork.ch/search?q=ftw.pdfgenerator\n\nCopyright\n=========\n\nThis package is copyright by `4teamwork <http://www.4teamwork.ch/>`_.\n\n``ftw.pdfgenerator`` is licensed under GNU General Public License, version 2.\n\n\n.. _LaTeX: http://www.latex-project.org/\n.. _Plone: http://www.plone.org/\n.. _MacTeX: http://www.tug.org/mactex/2011/\n.. _Tex Live: http://www.tug.org/texlive/\n.. _MiKTeX: http://www.miktex.org/\n.. _mako: http://www.makotemplates.org/\n\nChangelog\n=========\n\n1.6.11 (2024-10-02)\n-------------------\n\n- Remove line break from table environment end and add a smallbreak instead. [buchi]\n\n\n1.6.10 (2021-05-06)\n-------------------\n\n- Use a cookie instead of session storage to store the debug mode state. [mathias.leimgruber]\n\n\n1.6.9 (2020-03-11)\n------------------\n\n- Add support for converting hexadecimal XML/HTML entities [Nachtalb]\n\n\n1.6.8 (2020-02-11)\n------------------\n\n- Don't use reference_catalog for uid look up, since it does not exist anymore in plone 5. [mathias.leimgruber]\n\n\n1.6.7 (2020-02-03)\n------------------\n\n- Don't use session storage anymore - does not work with plone 5 for anonymous users. [mathias.leimgruber]\n\n\n1.6.6 (2020-01-17)\n------------------\n\n- Fix unicode error (when unicode and non-unicode strings are joined). [busykoala]\n\n\n1.6.5 (2019-10-29)\n------------------\n\n- Fix escaping of underscore in hyperlink labels. [jone]\n\n\n1.6.4 (2019-03-26)\n------------------\n\n- Robustified URL conversion. [Rotonen]\n\n\n1.6.3 (2019-01-07)\n------------------\n\n- Drop support for plone 4.2. [njohner]\n- Handle vertical tab special character. [njohner]\n\n\n1.6.2 (2018-09-13)\n------------------\n\n- Fix escaping issues for dash characters in hyperlink labels. [jone]\n\n1.6.1 (2018-05-18)\n------------------\n\n- Fix encoding error by passing charset hint to BeautifulSoup when converting tables. [lgraf]\n\n- Add Plone 5 compatibility. [phgross]\n\n- Fixed exporting the zip and latex for pdfs who are setting the pdf title. [phgross]\n\n\n1.6.0 (2017-03-03)\n------------------\n\n- Add possibility to set the pdf title via build arguments. [phgross]\n\n- Support file objects in Builder.add_file. [jone]\n\n- Drop Plone 4.1 support.\n\n\n1.5.0 (2016-06-08)\n------------------\n\n- Implement URL converter for supporting hyphenation in URLs. [jone]\n\n\n1.4.1 (2016-03-30)\n------------------\n\n- Listing converter: avoid using beatiful soup. [jone]\n\n- Fix recursive subconverter locking problem. [jone]\n\n\n1.4 (2016-03-02)\n----------------\n\n- Added footnote subconverter.\n [lknoepfel]\n\n\n1.3.8 (2015-12-11)\n------------------\n\n- Don't add rows where not all cells are headcells to the tablehead.\n [tschanzt]\n\n- Fix table converting when there are less cells than specified and no colspan attribute is given.\n [tschanzt]\n\n\n1.3.7 (2015-04-13)\n------------------\n\n- Fix table converting error when there are more ``<col>`` tags than cells.\n [jone]\n\n- HTML converter: fix leading quote when at beginning of string.\n [jone]\n\n\n1.3.6 (2015-03-20)\n------------------\n\n- Workaround for too long makeindex argument causing buffer overflow.\n [jone]\n\n\n1.3.5 (2015-02-19)\n------------------\n\n- PDF Builder: fix pdflatex after making index.\n When references are used in the index, e.g. the index title is in the TOC,\n more than one rerun is required after making the index.\n [jone]\n\n\n1.3.4 (2014-09-30)\n------------------\n\n- Add a ``quoted_umlauts`` method to the converter.\n The method converts all umlauts to the quoted notation.\n [jone]\n\n- Index: sort German umlauts correctly by including umlaut.ist.\n For this to work properly all \\index{} entries must escape umlauts\n with quotes, e.g. ``h\"oflich``.\n [jone]\n\n\n1.3.3 (2014-07-24)\n------------------\n\n- Fix PDF rendering bug when having underscores in internal hyperlinks.\n [jone]\n\n\n1.3.2 (2014-06-11)\n------------------\n\n- Improve table layouting.\n\n - Increase vertical padding of table cells.\n - Add line break and vertical space after all tables.\n\n [jone]\n\n\n1.3.1 (2014-06-02)\n------------------\n\n- Fix backslash LaTeX to use `\\textbackslash` instead of `\\\\`.\n This fixes problems with backslash in certain environments such as tables.\n [jone]\n\n\n1.3.0 (2014-03-04)\n------------------\n\n- Run makeindex when ``*.idx`` files were created during PDF build.\n This allows to create indexes easily just by using the latex commands.\n The builder takes care that the index is built and the PDF rebuilt properly.\n [jone]\n\n\n1.2.10 (2014-02-05)\n-------------------\n\n- LaTeX: use math mode for asterisks (*), so they get no longer swallowed.\n [jone]\n\n\n1.2.9 (2014-01-17)\n------------------\n\n- Update French translations.\n [jone]\n\n- Hyperlinks in footnotes: use \\url instead of manual hyphenation hints.\n This fixes that \"\" is visible in footer urls with certain hyperref\n package versions.\n [jone]\n\n- Table: fix error where rowspan cells made other cells swap rows.\n [jone]\n\n- Tables: fix width of cells spanning multiple columns.\n This is especially visible when they are centered.\n [jone]\n\n\n1.2.8 (2013-10-21)\n------------------\n\n- Make hyphens before commas non-breakable.\n [jone]\n\n- Use non-breaking spaces for some more abbreviations.\n [jone]\n\n- Remove HTML comments when converting HTML to LaTeX.\n [jone]\n\n- Use non-breaking spaces and en-dashes for formatting swiss currency.\n [jone]\n\n\n1.2.7 (2013-05-24)\n------------------\n\n- Table width calculation: treat \"px\" the same as widths without measure units.\n [jone]\n\n\n1.2.6 (2013-04-17)\n------------------\n\n- Update package classifiers.\n [jone]\n\n\n1.2.5 (2013-01-24)\n------------------\n\n- Use local text formatting commands, such as \\textbf instead of {\\bf }. #13\n [jone]\n\n- onegov.ch approved: add badge to readme.\n [jone]\n\n- Declare missing dependencies.\n [jone]\n\n- Make layout annotatable.\n This allows to store certain informations while building the PDF.\n [jone]\n\n- Plone 4.3 compatibility.\n [jone]\n\n\n1.2.4 (2012-08-21)\n------------------\n\n- Tables: fix wrong indentation when using combined css classes\n \"right\" and \"bold\".\n [jone]\n\n- Tables: support width definition in \"style\" attribute of cells. #10\n [jone]\n\n- Fix ampersand escaping in urls. #11\n [jone]\n\n- Templating: fix template lookup for five based browser views which\n are wrapped into a meta class.\n [jone]\n\n- List conversion: handle empty list items.\n\n - Removing them in ordered and unordered lists.\n - Keep them in definition lists, since two tags result in one item.\n\n [jone]\n\n\n1.2.3 (2012-06-13)\n------------------\n\n- Table converter: fix centering of cell contents by using correct\n LaTeX (\\centering instead of \\center\\vspace{-1.5em}).\n [jone]\n\n- Hyperlink:\n\n - Support resolveUid (with upper U) resolution.\n - Remove \"./\" from concatenated relative urls.\n - Support hyphenation in urls.\n\n [jone]\n\n\n1.2.2 (2012-06-11)\n------------------\n\n- Improve support for mathematic characters (utf8 and html-entities).\n [jone]\n\n- Table: support \"summary\" attribute as caption (TinyMCE support).\n [jone]\n\n- Handle hyphenation characters and entities.\n [jone]\n\n- Hyperlinks: handle underscores and hash keys in urls.\n [jone]\n\n- Fix centering of table captions which used to affect contents beneath.\n [jone]\n\n- Fix quotation marks around bold text.\n [jone]\n\n\n1.2.1 (2012-05-10)\n------------------\n\n- Table converter: fix TypeError when using colspan without defining any widths.\n [jone]\n\n\n1.2 (2012-05-09)\n----------------\n\n- HTML to LaTeX: escape $ charactor. Otherwise it enables math-mode.\n [jone]\n\n- Tables: use seperate caption implementation for non-floating environments.\n [jone]\n\n- Tables: fix border collapse bug when using rowspan.\n [jone]\n\n- Tables: calculate widths properly respecting \\tabcolsep.\n [jone]\n\n- Tables: support plone css classes (grid, listing, vertical).\n [jone]\n\n\n1.1.2 (2012-05-02)\n------------------\n\n- Add convert_plain method to converter and view.\n [phgross]\n\n- Add encode_htmlentities utils function.\n [phgross]\n\n\n1.1.1 (2012-04-30)\n------------------\n\n- Listing converter: limit nested lists to four levels since LaTeX has this limit.\n [jone]\n\n- Listing converter: fix bug when nested lists are not within a item.\n [jone]\n\n- Add provide_request_layer util method to directly provide an interface on the request\n [eschmutz]\n\n\n1.1 (2012-03-22)\n----------------\n\n- Improve testing speed by using ``ftw.testing``.\n [jone]\n\n- Add table converter css classes:\n indent2 -> indent the content 0.2cm\n indent10 -> indent the content 1cm\n bold -> display content with bold font\n grey -> Display cell content with grey text color.\n footnotesize -> Display cell content with smaller font size.\n scriptsize -> Display cell content with smaller font size.\n [jone]\n\n- Listing converter: cleanup bad html in case when lists are nested without list items.\n FCKEditor somehow produces that sometimes.\n [jone]\n\n- Implement customizable layouts.\n [jone]\n\n\n1.0.2 (2012-03-08)\n------------------\n\n- Table converter: add css classes for aligning cells (\"right\", \"center\", \"left\").\n [jone]\n\n- Table converter: add cell-border functionality, using css classes \"border-right\",\n \"border-left\", \"border-top\" and \"border-bottom\".\n [jone]\n\n- Table converter: improve grid border, add classes \"border-grid\" and \"listing\" for enabling grid borders.\n [jone]\n\n- Table converter: use \"tabular\" for small tables. #3\n [jone]\n\n\n1.0.1 (2012-03-05)\n------------------\n\n- Add use_babel function to layout, enabling the preferred language.\n [jone]\n\n\n1.0b2 (2012-02-28)\n------------------\n\n- Added missing MANIFEST.in.\n [phgross]\n\n\n1.0b1 (2012-02-24)\n------------------\n\n- Added a \"debug-pdf\" view, enabling the pdf debug mode temporarily.\n [jone]\n\n- Added some French translations\n [ttschanz]\n\n- Implement hyperlink converter.\n [jone]\n\n- Implement convertion of definition lists.\n [jone]\n\n- Rename as_pdf view to export_pdf.\n [jone]\n",
"bugtrack_url": null,
"license": "GPL2",
"summary": "A library for generating PDF representations of Plone objects with LaTeX.",
"version": "1.6.11",
"project_urls": {
"Homepage": "https://github.com/4teamwork/ftw.pdfgenerator"
},
"split_keywords": [
"ftw",
"pdf",
"generator"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "53cc09596d748ea018f7b8111ea710b51cc3f2c62f1f6451e8ab696815316a1d",
"md5": "ed3503f4acf4666351443c63ba022b44",
"sha256": "279ce70794a8916f34ff63708461abd6b7c03fb1298889d270b3197667a8809b"
},
"downloads": -1,
"filename": "ftw.pdfgenerator-1.6.11.tar.gz",
"has_sig": false,
"md5_digest": "ed3503f4acf4666351443c63ba022b44",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 93259,
"upload_time": "2024-10-02T08:57:58",
"upload_time_iso_8601": "2024-10-02T08:57:58.565056Z",
"url": "https://files.pythonhosted.org/packages/53/cc/09596d748ea018f7b8111ea710b51cc3f2c62f1f6451e8ab696815316a1d/ftw.pdfgenerator-1.6.11.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-02 08:57:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "4teamwork",
"github_project": "ftw.pdfgenerator",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "ftw.pdfgenerator"
}
JSON
