noteweb: Rendering bird field notes for the Web

For design notes, see Section 6, “Design notes”; for the overall flow, see Section 7, “Overall program flow”.

Here is the main, and the intended function for the whole program:

# - - -   m a i n

def main():
    '''Main program.
      [ file 'aou.xml' is a readable, valid taxonomy file ->
          if all monthly files under the current directory are
          valid against birdnotes.rnc ->
            monthly web pages  :=  rendering of those monthly
                files into XHTML, in the same directory, with
                the names changed from .xml to .html
            index page  :=  table of links to monthly web pages
          else ->
            sys.stderr  +:=  error message(s)
            (monthly web pages, index page)  :=  (anything) ]
    '''

An xnomo3.Txny instance will be necessary to represent a phylogenetic arrangement of the birds. This constructor assumes the existence of an aou.xml file in the current directory; see A system for representing bird taxonomy.

    #-- 1 --
    # [ if the command line arguments are valid ->
    #     Args()  :=  a single Args instance representing those
    #                 arguments
    #   else ->
    #     sys.stderr  +:=  usage message
    #     stop execution ]
    Args()

    #-- 2 --
    # [ if there is a readable aou.xml in the current directory
    #   that is valid against txny.rnc ->
    #     txny  :=  a Txny instance representing that file
    #   else ->
    #     sys.stderr  +:=  error message(s)
    #     stop execution ]
    try:
        txny  =  xnomo3.Txny()
    except IOError, detail:
        print >>sys.stderr, ( "*** Can't read the taxonomy file: %s" %
                              detail )
        raise SystemExit

The first step is to create the YearCollection instance that will hold all the data. See Section 21, “class YearCollection: The top-level data structure”.

    #-- 3 --
    # [ yearCollection  :=  a new, empty YearCollection instance ]
    yearCollection  =  YearCollection()

Next, we find all the subdirectories that look like year directories, and add them to yearCollection. See Section 12, “findYears: Locate year directories”.

    #-- 4 --
    # [ yearCollection  :=  yearCollection with years added
    #       corresponding to subdirectories of '.' with year
    #       names 1000-2999 ]
    #   sys.stderr  +:=  error message(s) from invalid monthly XML
    #       files in those subdirectories
    findYears ( txny, yearCollection )

For each year in yearCollection, we look for monthly XML files in the corresponding directory. Invalid XML files result in error messages. Valid ones are rendered into HTML, and each month's parent yearRow instance is informed of its existence. See Section 21.4, “YearCollection.genYearsRev(): Generate years in reverse chronological order” and Section 22.10, “YearRow.writeMonthPages(): Generate monthly pages”.

    #-- 5 --
    # [ monthly web pages  :=  XHTML renderings of BirdNoteSet
    #       instances from yearCollection ]
    for yearRow in yearCollection.genYearsRev():
        yearRow.writeMonthPages()

Now that we know the set of valid months, we can build the index page. See Section 13, “buildIndex(): Build the index page”.

    #-- 6 --
    # [ index page  :=  table of links to monthly web pages
    #       from yearCollection ]
    buildIndex ( yearCollection )