xnomo3.py: Internal maintenance specification

# - - -   h t m l i f y

def htmlify(rawEng, cssClass):
    '''Mark up an English name for HTML

      [ (rawEng is an English name in inverted form) and
        (cssClass is a string or None) ->
          if cssClass is None ->
            return rawEng, normalized, as HTML, with italics marked
            up using an 'i' element
          else ->
            return rawEng, normalized, as HTML, with italics marked
            up using a 'span' element with class=(cssClass) ]          
    '''

The substitution of HTML markup for characters of rawEng is handled by an instance of Section 10.4, “class Htmler: State machine for HTML markup”. That instance's .convert() method looks at each character and returns the HTML equivalent. The instance also keeps track of the number of double-quote (") and underbar (_) characters. That way, it can return a left double-quote (“) for the even-numbered input double-quotes and a right double-quote (”) for the odd-numbered ones. It also converts each even-numbered underbars to the start tag for italic markup and each odd-numbered underbar to the corresponding end tag.

    #-- 1 --
    # [ htmler  :=  a new Htmler instance ]
    htmler = Htmler()

    #-- 2 --
    # [ htmler  :=  htmler with its state reflecting the characters
    #               of rawEng
    #   result  :=  characters of rawEng marked up for HTML using
    #               htmler ]
    result = ''.join(
        [ htmler.convert(c, cssClass)
          for c in rawEng ] )

Finally, we check the .italics and .quotes attributes of htmler to make sure that double-quotes and underbars were balanced.

    #-- 3 --
    # [ if htmler is out of balance ->
    #     raise ValueError
    #   else ->
    #     return result ]
    if htmler.italics:
        raise ValueError("Unbalanced '_' characters: '%s'" % rawEng)
    if htmler.quotes:
        raise ValueError("Unbalanced '\"' characters: '%s'" % rawEng)
    return result