noteweb: Rendering bird field notes for the Web

This method generates one entry in the table of contents at the top of the monthly page.

# - - -   M o n t h C e l l . _ _ d a y T O C

    def __dayTOC ( self, ul, dayNotes, anchorSet, anchorMap ):
        '''Generate a link to the day's entry, with notables if any.

          [ (ul is an et.Element) and
            (dayNotes is a DayNotes instance) and
            (anchorSet is a set) and
            (anchorMap is a dictionary) ->
              ul  +:=  an 'li' item containing a link to the
                  anchor for dayNotes.date, plus the English
                  names for any notable records
              anchorSet  +:=  a new anchor value not in anchorSet
              anchorMap  +:=  an entry whose key is dayNotes
                  and whose value is that new anchor value ]
        '''

First we must create an anchor string that hasn't been used yet. We'll start with "D" plus the dayNotes.date string (which has the form “yyyy-mm-dd”). The anchorSet argument is a Python set instance containing all the anchors that have already been used, so if the simple date is not in that set, we'll use that. If not, we'll try suffix letters 'a', 'b', and so on, until we get a new one.

In theory, if there are 27 or more daily sets, we might run out of letters. However, the author rarely records multiple sets per day. The worst case is a long drive through multiple states, but to drive through 27 states in one day would be a pretty good trick.

        #-- 1 --
        # [ newAnchor  :=  a valid HTML anchor name that is not in
        #       anchorSet ]
        newAnchor  =  "D" + dayNotes.date
        suffix  =  'a'
        while newAnchor in anchorSet:
            newAnchor  =  "D" + dayNotes.date+suffix
            suffix  =  chr(ord(suffix)+1)

Now that we have an anchor string newAnchor that isn't is anchorSet, we know we can use it as the anchor for dayNotes.

        #-- 2 --
        # [ anchorSet  :=  union(anchorSet, newAnchor)
        #   anchorMap  +:=  an entry whose key is dayNotes and
        #       whose value is newAnchor ]
        anchorSet.add ( newAnchor )
        anchorMap[dayNotes]  =  newAnchor

Next we'll create the li (bullet) for this date. Inside the bullet is a link to the anchor we just generated, whose link text is the date, state, and day locality string from dayNotes.

        #-- 3 --
        # [ ul  +:=  a new 'li' element
        #   li  +:=  that element ]
        li  =  et.SubElement ( ul, 'li' )

        #-- 4 --
        # [ li  +:=  a new 'a' element whose URL is ('#'+newAnchor)
        #       and whose link text is (dayNotes.date)+': '+
        #       (dayNotes.regionCode, uppercased)+': '+
        #       (dayNotes.dayLoc.name) ]
        a  =  et.SubElement ( li, 'a', href=('#'+newAnchor) )
        a.text  =  dayNotes.title()

Next we must scan through all the records inside dayNotes and, if any are notable, generate a div with all the bird names from notable records. See Section 23.8, “MonthCell.__notablesBlock(): Display any notable records”.

        #-- 5 --
        # [ if dayNotes contains any notable records ->
        #     li  +:=  a div element containing the bird names
        #         from notable records
        #   else -> I ]
        self.__notablesBlock ( li, dayNotes )