Next / Previous / Contents / Shipman's homepage

6.4. main(): Main program

In general, the program proceeds in these stages.

  1. Check the command line arguments and, assuming the file is readable and valid, parse it into an ElementTree.

  2. Extract the title from the tree. This is necessary because it appears in the header of the output document.

  3. Build an empty XSL-FO document.

  4. Parse the DocBook input file into an ElementTree, and walk through that document looking for section elements. For each one found, add a block to the output document displaying its id and title.

    If the section/title element has other element children, the corresponding output will render certain elements according to the standard TCC presentation and ignore others; see Section 4, “Design of the report”.

  5. Serialize the document to the output file as XML.

docbookindex
# - - -   m a i n

def main():
    '''Main program.

      [ if (the command line names a readable, valid DocBook
        file) and
        (file OUT_FILE_NAME can be created new) ->
          file OUT_FILE_NAME  :=  an XSL-FO document
              describing the id values and indentation
              levels of section elements in the DocBook file
        else ->
          sys.stderr  +:=  error message(s) ]
    '''

See Section 6.5, “argsCheck(): Process the command line arguments and open the input file. This section title was made artificially ridiculously long in order to demonstrate what happens when long titles wrap around for two or even more lines.”.

docbookindex
    #-- 1
    # [ if the command line names a readable, valid DocBook
    #   file ->
    #     inDoc  :=  that file as an et.ElementTree
    #     timestamp  :=  that file's modification timestamp in
    #                    ISO-8601 form
    #   else ->
    #     sys.stderr  +:=  error message(s)
    #     stop execution ]
    (inDoc, timestamp) = argsCheck()

See Section 6.9, “extractTitle: Find the document title”.

docbookindex
    #-- 2
    # [ docTitle  :=  the title text from inDoc rendered as an
    #       FO inline, with selected subelements rendered as FO
    #       and the rest ignored ]
    docTitle = extractTitle(inDoc)

See Section 6.13, “buildFlowTree: Set up an XSL-FO output document”.

docbookindex
    #-- 3
    # [ tree  :=  an h.FlowTree instance with the desired
    #             output page structure
    #   flow  :=  the flow element in that instance ]
    tree, flow = buildFlowTree(docTitle, timestamp)

Because indentation is important, we'll need a hairline vertical rule on the left side of each column that shows where indentation starts. This is done by wrapping the entire flow content in a block-container that applies the appropriate border properties.

docbookindex
    #-- 4 -- 
    # [ flow  +:=  a new block-container with a thin left border
    #   flowContainer  :=  that new block-container ]
    flowContainer = h.subElement(flow,
        E("block-container",
          h.dash(borderLeftWidth='0.4pt', borderRightWidth='0pt',
                 borderTopWidth='0pt', borderBottomWidth='0pt',
                 borderStyle='solid', padding='2pt')))

See Section 6.16, “reportSections.

docbookindex
    #-- 5
    # [ flowContainer  +:=  lines describing section element descendants
    #              of inDoc.root, starting at indent level 0 ]
    reportSections(flowContainer, 0, inDoc.getroot())
    
    #-- 6
    # [ if OUT_FILE_NAME can be opened new ->
    #     file OUT_FILE_NAME  :=  tree as XML
    #   else ->
    #     sys.stderr  +:=  error message(s) ]
    try:
        outFile = file(OUT_FILE_NAME, "w")
        tree.write(outFile)
    except IOError, detail:
        fatal("Can't open the output file '%s'." % OUT_FILE_NAME)