Conversions
===========

PDF
+++

As one conversion option you can generate a PDF document (for the all-in-one
aggregated content) or PDF generated by chapter. Depending on your needs you
can choose among different PDF profiles. 

Options
#######

Transformations:

- ``Remove cross-references``: this option will remove all internal
  cross-references to other content pieces

- ``With front coverpage``: include a front coverpage if configured

- ``With back coverpage``: include a back coverpage if configured

- ``Convert only published content``: only content in workflow state
  ``published`` will be used for conversion

- ``Add debugging information to PDF``: this option will generate an ``Edit``
  link inside the PDF document that allows you to jump directly into the edit
  mode of the related document

- ``Store as ZIP``: this is a debugging or helper option that will store all
  the aggregated content as a ZIP archive. The purpose is to download all
  resources and perform local manual conversions on a local system (e.g. for
  debugging styles).

Hyperlink related options:

- ``No special links treatment``: handling of links is left of the PrinceXML
  converter.  This is the default

- ``Replace hyperlink with link text``: hyperlinks where the linktext
  represents an URL itself will be replaced with the linktext only

- ``Convert hyperlinks into footnotes``: convert hyperlinks into dedicated
  footnotes

Create listings:

- ``Table of contents``: generates a table of contents inside the document

- ``Table list``: generates a table list inside the document

- ``Image list``: generates a listing with all images and captions

PDF:

- ``Quality``: The PDF profile affects the DPI/resolution of included images
  (high quality=large files, low quality=smaller files).


HTML + PDF
----------

The ``HTML + PDF`` conversion tab allows you to generated an HTML version of
your content.  Content can either be aggregated into a single HTML document or
split into individual HTML documents. The counters for headings, images and
tables are preserved by default but you can reset the counters for each
generated HTML document if needed.


EPUB (Ebook)
++++++++++++

You can automatically generate EBook files in EPUB format using the external
``Calibre`` tool (which must be installed on the Produce & Publish server).
You can configure arbitrary Calibre conversion profiles within a template
folder through the ``AuthoringCalibreProfile`` content type. The edit view of
the calibre profile content-type allows you to specify valid command-line
parameters of the ``ebook-convert`` tool which is responsible for the actual
conversion work in Calibre.  (see also
http://calibre-ebook.com/user_manual/cli/ebook-convert.html).

.. image:: images/calibre_add_form.png

The ``Name`` column accepts the name of a parameter including the leading
double ``-`` character and the ``Value`` column takes a related value for the
parameter. Produce & Publish will automatically replace the values of the
placeholder for ``%(title)s`` and ``%(authors)`` with the ``Title`` and ``Contributors`` values 
taken from the root content folder of the conversion project.

.. image:: images/calibre_view_form.png



S5 presentations
++++++++++++++++

Produce & Publish supports the generation of S5 presentations through the
**HTML + PDF** conversion tab.

.. image:: images/s5-generation.png

Inside the table of contents portlet of the converted HTML webpage you will
find the link to the S5 presentation view (or the optional fullscreen view).

.. image:: images/s5-toc-portlet.png

S5 relevant content can be maintained either as a single document or a set of
documents that will be aggregated into one. ``H2`` tags (known as ``Heading``
styles in TinyMCE) are used as split point between slides. So a slide consists
of an ``H2`` tags and the following text until the next ``H2`` tag. So you may arrange
the contents of your slides as one document with many ``H2``/``headings`` for grouping
the slides or multiple documents with also an arbitrary number of ``H2``/headings.

Metadata relevant to the S5 conversion
######################################

The ``title`` and ``description`` metadata of the root content folder are used
on the first slide of the presentation. They are mandatory (which is explictely
checked by Plone). In addition the ``location`` and ``creators`` metadata of
the content folder are included within the first slide if available.

.. image:: images/s5-footer-edit.png

In addition the rendering template has access to all Dublion core metadata
of the content folder itself. The rendering template itself can access
those data through the ``options`` dictionary (in ZPT)::

    <span tal:content="options/s5line1">
    ...
    <span tal:content="options/s5line4">
    <span tal:content="options/title">
    <span tal:content="options/description">
    <span tal:content="options/creators">
    <span tal:content="options/location">
    ...

The generated S5 presentation using the default S5 presentation template
will look like this:

.. image:: images/s5-rendered.png


Exporting generated content
+++++++++++++++++++++++++++

The **HTML + PDF** conversion option of the authoring environment generated by
default HTML. In addition you have conversion options for PDF, EPub and S5. You
can download all generated files (and associated helper files (stylesheets
etc.)) through the ``Download as ZIP archive`` option from the table of
contents portlet.

.. image:: images/download-as-zip.png

This functionality will create a ZIP archive with sub-folder
containing the related files:

    - ``html/index.html`` (generated HTML)
    - ``presentation/index.html`` (for S5)
    - ``pdf/index.pdf`` (PDF files)
    - ``epub/index.epub`` (EPub file)

Every subfolder is self-contained and does not reference to any file outside the folder.
The ZIP archive export can be used for offline work or for feeding the data
into a different document processing pipeline. E.g. you can use the external Calibre
tool for producing an e-book outside the Produce & Publish authoring environment.

