Christmas Bird Count history report system

This function writes all the generated XSL-FO to the temporary “.fo” file.

# - - -   f o W r i t e

def foWrite(db, txny, foFile, circleList, cbcHist):
    '''Generate all the XSL-FO for one PDF report.

      [ (db is a pycbc.CBCDatabase instance) and
        (txny is an xnomo3.Txny instance) and
        (foFile is a writeable file) ->
          if HistArgs() is consistent with db and txny ->
            foFile  +:=  the report requested by HistArgs() using
                db and txny, in XSL-FO format, closed
          else -> raise lib.ScriptError ]
    '''

The task of this function is to generate the report as a complete XSL-FO document. Because these documents can be pretty large, we use the sox and fosox packages (imported as “fo”) to assist. The schema for XSL-FO is pretty large; the reader is assumed to be familiar with it. If not, Dave Pawson's XSL-FO (ISBN 0-596-00355-2) is most helpful.

    #-- 1
    # [ s  :=  a new sox.Sox instance writing to foFile
    #   root  :=  a new root element written to foFile, open ]
    s = Sox(foFile)
    root = fo.root(s)

See Section 10.25, “hist.cgi: foMasters(): Set up the XSL-FO page layout”.

    #-- 2
    # [ s  +:=  a layout-master-set subtree for letter paper,
    #           duplex printing, named lib.REPEAT_MASTER ]
    foMasters(s)

We add the page-sequence element next. This is a container for the static content (running headers and footers) and the document body. See Section 10.27, “hist.cgi: foStatic(): Add running headers and footers”.

    #-- 3
    # [ s  +:=  an open page-sequence element for lib.REPEAT_MASTER
    #       with static content added to lib.ODD_BEFORE and lib.EVEN_BEFORE
    #   pages  :=  that element ]
    pages = fo.pageSequence(s, lib.REPEAT_MASTER)
    foStatic(s)

For the logic that formats the actual content, see Section 10.29, “hist.cgi: foContent(): Generate the index and main table”.

    #-- 4
    # [ s  +:=  (primary index entries displaying circleList) +
    #       (a table displaying cbcHist) ]
    flow = fo.flow(s, "xsl-region-body")
    foContent(s, db, circleList, cbcHist)
    flow.end()

Lastly, emit the closing tags for the page-sequence and root elements.

    #-- 5
    # [ s  +:=  (closing tag for pages) + (closing tag for root) ]
    pages.end()
    root.end()
    s.flush()
    s.cleanup()
    foFile.close()