doclib: Clean up documentation generation

[senf.git] / doclib / fix-links.py

diff --git a/doclib/fix-links.py b/doclib/fix-links.py
index 440a33b..27ee4d5 100644 (file)
--- a/doclib/fix-links.py
+++ b/doclib/fix-links.py
@@ -1,4 +1,30 @@
 #!/usr/bin/python
+#
+# This tool will hack the doxygen generated documentation to fix link
+# errors produced by doxygen.
+#
+# This works because most anchors doxygen generates are unique 32 char
+# hash values. To speed up the operation, the tool will not check all
+# the files itself but will let 'linklint' do the grunt
+# work. fix-links.py reads the 'errorX.txt' and 'errorAX.txt' files
+# generated by linklint. These files list links to missing files
+# (errorX.html) and links to missing anchors
+# (errorAX.html). fix-links.py works in the following way:
+#
+# - Build a complete index of all unique anchors found in any html
+#   file. The index will only include *unique* anchors. Anchors found
+#   multiple times are removed from the index
+#
+# - The index is extended to include all unique names of html files
+#
+# - Scn the linklint result and check the bad links against the
+#   index. If the file or anchor is found in the index, an accoringly
+#   corrected link is generated otherwise the link is removed.
+#
+# One additional twak is, that fix-links.py will successively remove
+# initial 'g' charachters from anchors until the link is found in the
+# index. Doxygen seems to create links with the wrong number of 'g'
+# charachters in front sometimes.
 
 import sys,os.path,fnmatch, HTMLParser, getopt, re
 
@@ -256,7 +282,7 @@ total, found, fixed, removed = fixer.stats()
 if verbose:
     sys.stderr.write("\nRemoved links:\n")
     for (anchor, label), files in removed.items():
-        sys.stdout.write("%-36.36s %-48.48s %s\n"
+        sys.stderr.write("%-36.36s %-48.48s %s\n"
                          % ( anchor,
                              "(%s)" % label[:46],
                              " ".join(files.keys())) )