Metadata-Version: 1.1
Name: pypfop
Version: 0.2.0
Summary: Document preprocessor for Apache FOP.
Home-page: https://bitbucket.org/cyraxjoe/pypfop
Author: Joel Rivera
Author-email: rivera@joel.mx
License: Copyright 2013 Joel Rivera

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
Description: .. -*- rst -*-
        
        Python Preprocessor of the Formatting Objects Processor [pypfop]
        ================================================================
        
        Document preprocessor for `Apache FOP`_.
        
        How does it works?
        ------------------
        It does what the huge title is implying, preprocess a *higher* level template
        to generate *dynamically* an specific `XSL-FO`_ document, which then gets 
        fed to `Apache FOP`_ to generate the expected output. So that means that
        this packages *requires Java*  ``>_<'``, but fear not!, it is almost transparent 
        to the python application.
        
        In general the internal workflow is::
        
            template ->  mako -> apply css ->  xsl-fo ->  fop -> *Document*
        
        
        Installation
        ------------
        
        1. Install pypfop::
        
            pip install pypfop
        
        2. Install `Apache FOP`_:
        
           #. Download the binary package of fop1.1 either the  zip_ or tar_ package.
           #. Decompress in wherever place you like and set environment variable ``FOP_CMD``
              to the ``bin/fop`` of the decompressed folder. [1]_
        
        
        Usage
        -----
        
        The language
        ^^^^^^^^^^^^^
        
        The language to generate the documents is almost the same as the xsl-fo, the only
        difference is that is not necessary to set the xml namespace to all the elements,
        for example::
        
           <fo:table>
            <fo:table-header>
               <fo:table-row>
                  <fo:table-cell>
                    <fo:block>Project</fo:block>
                  </fo:table-cell>
               </fo:table-row>
            </fo:table-header>
            <fo:table-body>
               <fo:table-row>
                 <fo:table-cell>
                    <fo:block>pypfop</fo:block>
                </fo:table-cell>
               </fo:table-row>
            </fo:table-body>
           </fo:table>
        
        can be written like this::
          
           <table>
            <table-header>
               <table-row>
                  <table-cell>
                    <block>Project</block>
                  </table-cell>
               </table-row>
            </table-header>
            <table-body>
               <table-row>
                 <table-cell>
                    <block>pypfopp</block>
                </table-cell>
               </table-row>
            </table-body>
           </table>
        
        
        The higher level template language
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        At the time the only supported template language is mako_ it should not be very
        complicated to extend to your favorite template language based in the implementation
        of mako (which is pretty straight forward) and hopefully contribute back to the project :).
        
        For example the previous table can be generated with this mako template assuming the
        `header` and `rows` variables are passed to the `Document.generate` method::
        
        
            <table>
              <table-header>
                <table-row>
                  % for name in header:
                  <table-cell>
                    <block>${name}</block>
                  </table-cell>
                  % endfor
                </table-row>
              </table-header>
              <table-body>
                % for row in rows:
                   <table-row>
                 % for cell in row:  
                    <table-cell>
                      <block>${cell}</block>
                    </table-cell>
                 % endfor
                   </table-row>
                % endfor
              </table-body>
            </table>
        
        
        Skeletons
        ^^^^^^^^^
        The previous examples are really just a fragment a document to be able to generate
        a full document with metadata, paper size, margins, etc. To avoid the repetitive
        work to write this kind of base document pypfop come with skeletons documents, the
        purpose if this documents is to be inherited at each template, at the time
        the only implemented skeleton is in `pypfop/skeletons/mako/simple-letter-base.fo.mako`,
        which include place holders for metadata about the document and two regions, body
        and footer, with a few defaults, which of course can be overwritten with the
        appropriate parameters.
        
        To be a fully functional template for pypfop the previous table need to be like this.
        
        
        *simple-table.fo.mako*::
        
            <%inherit file="simple-letter-base.fo.mako" />
            <table id="main-table">
              <table-header>
                <table-row>
                  % for name in header:
                  <table-cell>
                    <block>${name}</block>
                  </table-cell>
                  % endfor
                </table-row>
              </table-header>
              <table-body>
                % for row in rows:
                   <table-row>
                 % for cell in row:  
                    <table-cell>
                      <block>${cell}</block>
                    </table-cell>
                 % endfor
                   </table-row>
                % endfor
              </table-body>
            </table>
        
        The skeletons directory is set in the template directory path by default.
        
        
        Format and style with CSS
        ^^^^^^^^^^^^^^^^^^^^^^^^^
        Independent of the *higher level language* that the content of the document is
        written the style and formatting use *CSS*, to be more specific it can 
        parse the rules that cssutils_ support a very good subset of CSS2 and CSS3,
        for example support things like ``:nth-child(X)`` and ``@import url(XX)``.
        
        The properties that can be set are the same as in the specification of xsl-fo,
        check out the section of `About XSL-FO syntax`_ except that you can
        use classes as selectors, xsl-fo does not support the ``class`` attribute
        the the pypfop parser is going to look for ``class`` substitute with the
        specific style and then remove the ``class`` attribute.
        
        For example I could define the style for the previous table in three files.
        
        *simple_table.css*::
        
            @import url("general.css");
            @import url("colors.css");
                
            #main-table > table-header > table-row{
                text-align: center;
                font-weight: bold;
            }
            
            #main-table > table-header table-cell{
                padding: 2mm 0 0mm;
            }
        
        
        *general.css*::
        
            flow[flow-name="xsl-region-body"] {
                font-size: 10pt;
                font-family: Helvetica;
            }
        
        *colors.css*::
        
            #main-table> table-body > table-row > table-cell:first-child{
                color: red;
            }    
            #main-table> table-body > table-row > table-cell:nth-child(2){
                color: blue;
            }
            #main-table> table-body > table-row > table-cell:nth-child(3){
                color: cyan;
            }
            #main-table> table-body > table-row > table-cell:last-child{
                color: green;
            }
        
        
        Generate the document
        ^^^^^^^^^^^^^^^^^^^^^
        They are different ways to implement the ``Document`` class to your needs, 
        but for the sake of simplicity this is a way to generate the document::
        
        
            from pypfop import Document
            from pypfop.makotemplates import TemplateFactory
        
            tfactory = TemplateFactory()
            params = {'header': ['Project', 'Website', 'Language', 'Notes'],
                      'rows': [('pypfop', 'https://bitbucket.org/cyraxjoe/pypfop', 
                                'Python', 'Abstraction on top of Apache FOP'),
        			('Apache FOP', 'https://xmlgraphics.apache.org/fop/', 
                                'Java', '')] }
            doc = Document(tfactory('simple-table.fo.mako'), 'simple_table.css')
            print(doc.generate(params)) # generate returns the path of the generated file.
        
        
        Supported Document formats
        ^^^^^^^^^^^^^^^^^^^^^^^^^^
        In the previous example we didn't define the output of the `Document` in that case
        the default output of ``pdf`` is used, but the supported outputs are the same as
        in `Apache FOP output formats`_.
        
        From ``pypfop.__init__``::
        
            VALID_OFORMATS = frozenset(('awt', 'pdf', 'mif', 'rtf',
                                        'tiff', 'png', 'pcl', 'ps', 'txt'))
        
        
        The output format can be set in ``Document.__init__`` or ``Document.generate`` ::
        
            doc = Document(tfactory('simple-table.fo.mako'), 'simple_table.css',
                           oformat='rtf')
        
        or ::
        
           doc.generate(params, oformat='rtf')
        
        
        About XSL-FO syntax
        ^^^^^^^^^^^^^^^^^^^
        
        As you should notice already it is required to know how to format xsl-fo documents
        which in most part are very similar to the HTML counterparts (except that anything needs 
        to be in ``block`` tags), the best reference that I could find online is in the `XML Bible`_.
        
        
        Why!
        ----
        
        This project it use to be part of a larger project of one of my customers, 
        which I decide early on that I will use *only python 3*, terrible decision 
        if you want to generate pdf files easily or at least at the moment.
        I was looking to have some kind of *template* to the very rigid format of
        the average invoice and billing order, so pypfop came to relieve that pain.
        
        .. [1] Actually you can set the command at another level, check the ``Document`` class. 
        
        .. _`Apache FOP`: https://xmlgraphics.apache.org/fop/
        .. _XSL-FO: https://en.wikipedia.org/wiki/XSL_Formatting_Objects
        .. _zip: http://apache.webxcreen.org/xmlgraphics/fop/binaries/fop-1.1-bin.zip
        .. _tar: http://apache.webxcreen.org/xmlgraphics/fop/binaries/fop-1.1-bin.tar.gz
        .. _`XML Bible`:  http://www.ibiblio.org/xml/books/bible3/chapters/ch16.html
        .. _mako: http://www.makotemplates.org/
        .. _cssutils: http://pypi.python.org/pypi/cssutils
        .. _`Apache FOP output formats`: https://xmlgraphics.apache.org/fop/1.1/output.html
        
Platform: linux2
Platform: win32
Platform: cygwin
Platform: darwin
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 2.5
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.0
Classifier: Programming Language :: Python :: 3.1
Classifier: Programming Language :: Python :: 3.2
Classifier: Programming Language :: Python :: 3.3
Classifier: Topic :: Office/Business
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Text Processing :: Filters
Provides: pypfop
