.. _agentguide_modules:

Module Guide
============


Validator
---------

`Validator` validates XML files against a Relax NG.

Configuration
`````````````

To use `Validator` module, a processor has to provide a ``validator.ini``
configuration file.

You have 2 groups of sections to write.

Input Section Group
'''''''''''''''''''

.. code-block:: ini

    [Input]
    file_regex = \.xml$
    content_regex = <publi(set|doc|quiz)

RelaxNG Section Group
'''''''''''''''''''''

.. code-block:: ini

    [RelaxNG]
    publiset = %(here)s/RelaxNG/publiset.rng
    publidoc, version 1.0 = %(here)s/RelaxNG/publidoc.rng
    publiquiz, version 1.0 = %(here)s/RelaxNG/publiquiz.rng


.. ............................................................................

LePrisme
--------

`LePrisme` is a transformation module which uses regular expressions, XSL and,
possibly, python scripts to do its job.

Configuration
`````````````

To use `LePrisme` module, a processor has to provide a ``leprisme.ini``
configuration file.

You can have up to 7 groups of sections to write.

Initialization Section Group
''''''''''''''''''''''''''''

.. code-block:: ini

    [Initialization]
    directories = Images, Audios, Videos
    templates = Publidoc2XHtml
    script =

    [template:Publidoc2XHtml]
    path =
    exclude =
    exclude[!js] = Js, pulse.gif

Input Section Group
'''''''''''''''''''

.. code-block:: ini

    [Input]
    is_dir = false
    file_regex = \.xml$
    content_regex = <publi(doc|set)
    unzip =
    validate = true
    image.ext = svg, png, tif, tiff, jpg, jpeg, eps, gif
    audio.ext = wav, ogg, aac, ac3, mp3
    video.ext = dv, mpg, mov, avi, webm, flv

    [RelaxNG]
    publiset = %(here)s/RelaxNG/publiset.rng
    publidoc = %(here)s/RelaxNG/publidoc.rng

Transformation Section Group
''''''''''''''''''''''''''''

.. code-block:: ini

    [Transformation]
    preprocess = %(here)s/lib/publidoc2xhtml_pre.py
    preregex = %(here)s/Regex/publidoc2xhtml_pre.regex
    preregex.files =
    xsl = %(here)s/Xsl/publidoc2xhtml.xsl
    postregex = %(here)s/Regex/publidoc2xhtml_post.regex
    postregex.files = \.html$
    postprocess = %(here)s/lib/publidoc2xhtml_post.py

* ``preprocess`` and ``postprocess`` are Python scripts which are executed
  respectively as first and last action.
* ``preregex`` and ``postregex`` are regular expression lists which are applied
  respectively just before and just after XSL transformation.
* ``preregex.files`` and ``postregex.files`` are a regular expression to select
  files on which you apply ``preregex`` or ``postregex`` regular expression in
  addition to the main file.
* ``xsl`` is a XSL file.

Each processing is optional, but you must have, at least, one processing.

You can have several transformation sections like ``[Transformation]`` and
``[Transformation:csv]`` or ``[Transformation:1]`` and
``[Transformation:2]``. They are excecuted in the order of the INI file.

Output Section Group
''''''''''''''''''''

.. code-block:: ini

    [Output]
    make_id = token
    format = %(fid)s.epub
    container = OCF
    validate = false

``make_id`` defines how to transform a name into an ID. The default mode is
``token``. We have the following modes:

* ``standard``: it replaces spaces and non alpha or non numerical characters by
  _ and convert in lower case.
* ``token``: as ``standard`` plus accent removal.
* ``class``: as ``token`` minus lower case conversion.
* otherwise, it tries to load ``make_id`` as a module and executes its
  ``make_id(filename)`` method.

Available containers are:

* ``Zip``: create a ZIP archive with the contentof the output.
* ``OCF``: create a Open Container Format file. This container has three
  parameters.

.. code-block:: ini

    [container:OCF]
    root = Container~
    manifest = OEBPS/package.opf://opf:manifest
    checker = java -jar %(here)s/Jar/epubcheck.jar %(ocffile)s

* ``root`` is the relative path to the root directory to archive.
* ``manifest`` is a string like ``<relative_path_to_opf>:<xpath_to_manifest>``
  where ``<relative_path_to_opf>`` is a relative path to OPF file and
  ``<xpath_to_manifest>`` a XPATH expression to select manifest tag.
* ``checker`` is optional and is the command line to validate archive content.

Finalization Section Group
''''''''''''''''''''''''''

.. code-block:: ini

    [Finalization]
    remove_regex = (~|\.tmp)(\.\w{1,4})?$
    script =


.. ............................................................................

Publiseter
----------

`Publiseter` converts a pack into a Publiset XML file.

Configuration
`````````````

To use `Publiseter` module, a processor has to provide a ``publiseter.ini``
configuration file.

You have up to 5 sections to write.

Initialization Section Group
''''''''''''''''''''''''''''

.. code-block:: ini

    [Initialization]
    directories = Images, Audios, Videos

RelaxNG Section Group
'''''''''''''''''''''

.. code-block:: ini

    [RelaxNG]
    publiset = %(here)s/RelaxNG/publiset.rng
    publidoc = %(here)s/RelaxNG/publidoc.rng

Transformation Section Group
''''''''''''''''''''''''''''

.. code-block:: ini

    [Transformation]
    xsl = %(here)s/Xsl/publiset4publidoc.xsl

Output Section Group
''''''''''''''''''''

.. code-block:: ini

    [Output]
    format = %(fid)s.xml
    validate = true

Finalization Section Group
''''''''''''''''''''''''''

.. code-block:: ini

    [Finalization]
    remove_regex = (~|\.tmp)(\.\w{1,4})?$


.. ............................................................................

Generator
----------

`Generator` generate from scratch a content. It can be used to fill a pack
or to process background jobs.

Configuration
`````````````

To use `Generator` module, a processor has to provide a ``generator.ini``
configuration file.

You have one section to write.

Generation Section Group
''''''''''''''''''''''''

.. code-block:: ini

    [Generation]
    process = %(here)s/lib/packfilling.py

You can add other sections for you own python file.