--- a/make/indexsections.py	Sun Oct 07 02:14:32 2007 -0500
+++ b/make/indexsections.py	Mon Oct 08 04:19:54 2007 -0500
@@ -12,6 +12,9 @@
     depth -= 1
   return depth
 
+# Read through HTML code to find and process some extra tags, describing
+# content sections to be numbered and indexed.
+
 def process(data, idx):
   line = data[0].count("\n")
   depth = 0
@@ -22,9 +25,16 @@
   for i in data[1:]:
     i = i.split(">",1)
     tag = i[0].split(None,1)
+
+    # The magic tag to output the condensed list of all numbered sections.
+    # This recurses to call this function again, printing out different data.
+
     if tag[0] == "put_index_here":
       if not idx: process(data, 1)
       continue
+
+    # Parse one of our magic "span" tags describing a section.
+
     if tag[0] == "span":
       if len(tag) == 0 or not tag[1].startswith("id="):
         sys.stderr.write("Bad span at line %s: %s" % (line,i[0]))
@@ -34,18 +44,28 @@
       spans.append("_".join(tag.split()))
       secnum[-1] += 1
       secstr = ".".join(map(lambda a: str(a), secnum))
+
+      # If we're writing out the index...
       if idx:
         depth = adjust_depth(len(spans)-1, depth)
         if depth: style="li"
         else: style="h2"
-        sys.stdout.write('%s<%s><a href="#%s">%s %s</a></%s>\n' % ("  "*len(spans),style,spans[-1],secstr,tag,style))
+        sys.stdout.write('%s<%s><a href="#%s" name="%s">%s %s</a></%s>\n' % ("  "*len(spans),style,spans[-1],secstr,secstr,tag,style))
+
+      # If we're writing out the contents...
       else:
-        sys.stdout.write('<h2><a name="%s">%s %s</a></h2>\n' % (spans[-1],secstr,tag))
+        sys.stdout.write('<h2><a href="#%s" name="%s">%s %s</a></h2>\n' % (secstr,spans[-1],secstr,tag))
         sys.stdout.write('<%s>%s' % (i[0], i[1]))
       secnum.append(0)
+
+    # End of a section, pop it off the stack.
+
     elif tag[0] == "/span":
       spans.pop()
       secnum.pop()
+
+    # This tag wasn't one of ours, so output it verbatim.  (It's HTML.)
+
     else:
       if not idx: sys.stdout.write('<%s>%s' % (i[0], i[1]));
     line += i[1].count("\n")