A source extractor for lightweight literate programming

This function handles all the processing for one DocBook source file.

# - - -   p r o c e s s F i l e

def processFile ( fileName ):
    """Process one input file.

      [ inFileName is a string ->
          if inFileName names a readable, valid DocBook XML file ->
            output files named in lit-elts from that file  :=
              lit-content of those lit-elts
            sys.stderr  +:=  error messages from processing that file,
                             if any
          else ->
            sys.stderr  +:=  error message ]
    """

The fragments in a given file may be directed to several different output files. To keep track of the output files we have seen so far, we'll use a dictionary named fileMap, whose keys are file names, and each corresponding value is an open, writeable file handle for that file. We'll write the text to each file as it is encountered, and leave all the files open until the end, at which point we'll close them all.

    #-- 1 --
    fileMap  =  {}

Next we call the etree package to parse the XML file and make it into an element tree. This may raise either of two exceptions:

    #-- 2 --
    # [ if fileName names a readable, valid XML file ->
    #     doc  :=  an ElementTree representing that file
    #   else ->
    #     sys.stderr  +:=  error message(s)
    #     return ]
    try:
        doc  =  etree.parse ( fileName )
    except IOError, detail:
        print >>sys.stderr, ( "*** I/O error opening '%s': %s" %
                              (fileName, detail) )
        return
    except etree.XMLSyntaxError, detail:
        print >>sys.stderr, ( "*** Syntax error opening '%s': %s" %
                              (fileName, detail) )
        return

Now that doc contains the document tree, send it off for processing to Section 4.8, “processDoc(): Process one document tree”.

    #-- 3 --
    # [ (doc is an etree Document) and
    #   (fileMap is a dictionary whose keys are file names and
    #   each corresponding value is a writeable file handle
    #   for that file) ->
    #     fileMap  :=  fileMap with new file names added from
    #         lit-dests in doc
    #     file handles in fileMap  :=  lit-content of those files
    #     sys.stderr  +:=  error messages from processing doc,
    #         if any ]
    processDoc ( fileMap, doc )

Finally, we close all the output files that are values in the fileMap dictionary.

    #-- 4 --
    # [ fileMap is a dictionary whose values are file objects ->
    #     those values  :=  those values, closed ]
    for  outFile in fileMap.values():
        outFile.close()