Allow many more aspects of the generated page to be parameterized, and

add a useful usage message.  Use 'mkmodindex --help' to display it.

1 files changed, 116 insertions, 63 deletions

diff --git a/Doc/tools/mkmodindex b/Doc/tools/mkmodindex
index 16aa109..20c6416 100755
--- a/Doc/tools/mkmodindex
+++ b/Doc/tools/mkmodindex
@@ -1,6 +1,30 @@
 #! /usr/bin/env python
 #  -*- Python -*-
 
+"""usage: %(program)s [options] file...
+
+Supported options:
+
+    --address addr
+    -a addr         Set the address text to include at the end of the generated
+                    HTML; this should be used for contact information.
+    --columns cols
+    -c cols         Set the number of columns each index section should be
+                    displayed in.  The default is 1.
+    --help
+    -h              Display this help message.
+    --letters
+    -l              Split the output into sections by letter.
+    --output file
+    -o file         Write output to 'file' instead of standard out.
+    --iconserver is Use 'is' as the directory containing icons for the
+                    navigation bar.  The default is 'icons'.
+    --title str     Set the page title to 'str'.  The default is 'Global
+                    Module Index'.
+    --uplink url    Set the upward link URL.  The default is './'.
+    --uptitle str   Set the upward link title.  The default is 'Python
+                    Documentation Index'.
+"""
 import buildindex
 import getopt
 import os
@@ -9,6 +33,19 @@ import string
 import sys
 
 
+def usage():
+    program = os.path.basename(sys.argv[0])
+    print __doc__ % {"program": program}
+
+
+def error(msg, rc=2):
+    sys.stdout = sys.stderr
+    print msg
+    print
+    usage()
+    sys.exit(rc)
+
+
 _rx = re.compile(
     '<dt><a href="(module-.*\.html)">'
     '([a-zA-Z_][a-zA-Z0-9_.]*(\s*<em>\(.*\)</em>)?)</a>')
@@ -17,15 +54,53 @@ def main():
     outputfile = "-"
     columns = 1
     letters = 0
-    opts, args = getopt.getopt(sys.argv[1:], "c:lo:",
-                               ["columns=", "letters", "output="])
+    uplink = "./"
+    uptitle = "Python Documentation Index"
+    variables = {"address": "",
+                 "iconserver": "icons",
+                 "imgtype": "gif",
+                 "title": "Global Module Index",
+                 "uplinkalt": "up",
+                 "uplinkicon": "up",
+                 }
+    try:
+        opts, args = getopt.getopt(sys.argv[1:], "a:c:hlo:",
+                                   [# script controls:
+                                    "columns=", "help", "letters", "output=",
+                                    # content components:
+                                    "address=", "iconserver=",
+                                    "title=", "uplink=", "uptitle="])
+    except getopt.error, msg:
+        error(msg)
     for opt, val in opts:
-        if opt in ("-o", "--output"):
+        if opt in ("-a", "--address"):
+            val = string.strip(val)
+            variables["address"] = val and "<address>\n%s\n</address>\n" % val
+        elif opt in ("-h", "--help"):
+            usage()
+            sys.exit()
+        elif opt in ("-o", "--output"):
             outputfile = val
         elif opt in ("-c", "--columns"):
             columns = string.atoi(val)
         elif opt in ("-l", "--letters"):
             letters = 1
+        elif opt == "--title":
+            variables["title"] = string.strip(val)
+        elif opt == "--uplink":
+            uplink = string.strip(val)
+        elif opt == "--uptitle":
+            uptitle = string.strip(val)
+        elif opt == "--iconserver":
+            variables["iconserver"] = string.strip(val) or "."
+    if uplink and uptitle:
+        variables["uplinkalt"] = "up"
+        variables["uplinkicon"] = "up"
+    else:
+        variables["uplinkalt"] = ""
+        variables["uplinkicon"] = "blank"
+    variables["uplink"] = uplink
+    variables["uptitle"] = uptitle
     if not args:
         args = ["-"]
     #
@@ -62,7 +137,10 @@ def main():
     #
     num_nodes = len(nodes)
     # Here's the HTML generation:
-    parts = [HEAD, buildindex.process_nodes(nodes, columns, letters), TAIL]
+    parts = [HEAD % variables,
+             buildindex.process_nodes(nodes, columns, letters),
+             TAIL % variables,
+             ]
     if has_plat_flag:
         parts.insert(1, PLAT_DISCUSS)
     html = string.join(parts, '')
@@ -76,81 +154,56 @@ def main():
         print "%s: %d index nodes" % (program, num_nodes)
 
 
-HEAD = """\
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
-<html>
-<head>
-<title>Global Module Index</title>
-<META NAME="description" CONTENT="Global Module Index">
-<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
-<LINK REL="STYLESHEET" HREF="lib/lib.css">
-<LINK REL="up" HREF="./">
-</head>
-<body bgcolor="#ffffff">
-<div class=navigation>
-<table width="100%" cellpadding=0 cellspacing=2>
-<tr>
-<td><img width=32 height=32 align=bottom border=0 alt="blank"
- src="icons/blank.gif"></td>
-<td><a href="./"><img width=32 height=32 align=bottom border=0 alt="up"
- src="icons/up.gif"></A></td>
-<td><img width=32 height=32 align=bottom border=0 alt="blank"
- src="icons/blank.gif"></td>
-<td align=center bgcolor="#99CCFF" width="100%">
- <b class=title>Global Module Index</b></td>
-<td><img width=32 height=32 align=bottom border=0 alt="blank"
- src="icons/blank.gif"></td>
-<td><img width=32 height=32 align=bottom border=0 alt="blank"
- src="icons/blank.gif"></td>
-<td><img width=32 height=32 align=bottom border=0 alt="blank"
- src="icons/blank.gif"></td>
-</tr></table>
-<b class=navlabel>Up:</b> <span class=sectref><A
- HREF="./">Python Documentation Index</A></span>
-<br><hr></div>
-
-<h2>Global Module Index</h2>
-
-"""
-
 PLAT_DISCUSS = """
 <p> Some module names are followed by an annotation indicating what
 platform they are available on.</p>
 
 """
 
-TAIL = """
+NAVIGATION = """\
 <div class=navigation>
-<hr>
-<table width="100%" cellpadding=0 cellspacing=2>
+<table width="100%%" cellpadding=0 cellspacing=2>
 <tr>
-<td><img width=32 height=32 align=bottom border=0 alt="blank"
- src="icons/blank.gif"></td>
-<td><a href="./"><img width=32 height=32 align=bottom border=0 alt="up"
- src="icons/up.gif"></A></td>
 <td><img width=32 height=32 align=bottom border=0 alt=""
- src="icons/blank.gif"></A></td>
-<td align=center bgcolor="#99CCFF" width="100%">
- <b class=title>Global Module Index</b></td>
+ src="%(iconserver)s/blank.%(imgtype)s"></td>
+<td><a href="./"><img width=32 height=32 align=bottom border=0 alt="%(uplinkalt)s"
+ src="%(iconserver)s/%(uplinkicon)s.%(imgtype)s"></A></td>
 <td><img width=32 height=32 align=bottom border=0 alt=""
- src="icons/blank.gif"></td>
+ src="%(iconserver)s/blank.%(imgtype)s"></td>
+<td align=center bgcolor="#99CCFF" width="100%%">
+ <b class=title>%(title)s</b></td>
 <td><img width=32 height=32 align=bottom border=0 alt=""
- src="icons/blank.gif"></td>
+ src="%(iconserver)s/blank.%(imgtype)s"></td>
 <td><img width=32 height=32 align=bottom border=0 alt=""
- src="icons/blank.gif"></td>
+ src="%(iconserver)s/blank.%(imgtype)s"></td>
+<td><img width=32 height=32 align=bottom border=0 alt=""
+ src="%(iconserver)s/blank.%(imgtype)s"></td>
 </tr></table>
 <b class=navlabel>Up:</b> <span class=sectref><A
- HREF="./">Python Documentation Index</A></span>
-</div>
-<!--End of Navigation Panel-->
-<ADDRESS>
-<hr>Send comments to
-<a href="mailto:python-docs@python.org">python-docs@python.org</a>.
-</ADDRESS>
-</BODY>
-</HTML>
+ href="%(uplink)s">%(uptitle)s</A></span>
+<br><hr></div>
+"""
+
+HEAD = """\
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html>
+<head>
+<title>Global Module Index</title>
+<meta name="description" content="%(title)s">
+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+<link rel="STYLESHEET" href="lib/lib.css">
+</head>
+<body bgcolor=white>
+""" + NAVIGATION + """\
+
+<h2>%(title)s</h2>
+
 """
 
+TAIL = NAVIGATION + """\
+%(address)s</body>
+</html>
+"""
 
 if __name__ == "__main__":
     main()