This commit fixes makeman and the HTML sources so that they generate

manual pages that pass strict validation with doclifter.  

The required changes are widely scattered but relatively minor.  Most
are just tweaks to command-invocation syntax descriptions.  One large class of 
these simply moves running text out of SYNOPSIS sections into OPTIONS
sections. Another thing I had to do frequently was regroup syntax description 
so that plain-text tokens (e.g. filenames without surrounding [] or trailing
...) are on the same line with syntactic specials such as [ | ] { } ...

(Both these changes accommodate the limits of mechanical markup parsers
Even doclifter's, which is quite sophisticated and knows how to detect 
some natural-language patterns, has trouble telling some simple forms of 
command synopses from running text and will sometimes try to parse text
commentary as command syntax, with unhappy results.)

This commit also adds (to buildtools/Makefile.manpages) install and
uninstall productions that distribution packagers can use to install
the generated manual pages in /usr/share/man.

I fixed a few spelling and usage bobbles I found along the way.



git-svn-id: http://svn.code.sf.net/p/netpbm/code/trunk@218 9d0c8265-081b-0410-96cb-a4ca84ce46f8

2 files changed, 105 insertions, 43 deletions

diff --git a/buildtools/Makefile.manpage b/buildtools/Makefile.manpage
index e8c17972..b25bc19e 100644
--- a/buildtools/Makefile.manpage
+++ b/buildtools/Makefile.manpage
@@ -4,7 +4,7 @@
 
 MAKEMAN = makeman
 
-MANDIR = /usr/share/man/man1
+MANDIR = /usr/share/man/
 
 # These can convert to man pages cleanly
 MAN1 = \
@@ -16,6 +16,7 @@ MAN1 = \
 	bmptopnm.1 \
 	bmptoppm.1 \
 	brushtopbm.1 \
+	cameratopam.1 \
 	cmuwmtopbm.1 \
 	ddbugtopbm.1 \
 	escp2topbm.1 \
@@ -41,6 +42,7 @@ MAN1 = \
 	leaftoppm.1 \
 	lispmtopgm.1 \
 	macptopbm.1 \
+	manweb.1 \
 	mdatopbm.1 \
 	mgrtopbm.1 \
 	mrf.1 \
@@ -58,6 +60,7 @@ MAN1 = \
 	pamedge.1 \
 	pamendian.1 \
 	pamfile.1 \
+	pamfixtrunc.1 \
 	pamflip.1 \
 	pamfunc.1 \
 	pamgauss.1 \
@@ -74,8 +77,8 @@ MAN1 = \
 	pamstereogram.1 \
 	pamstretch-gen.1 \
 	pamstretch.1 \
-	pamsummcol.1 \
 	pamsumm.1 \
+	pamsummcol.1 \
 	pamtodjvurle.1 \
 	pamtohdiff.1 \
 	pamtohtmltbl.1 \
@@ -186,8 +189,8 @@ MAN1 = \
 	pnmquant.1 \
 	pnmremap.1 \
 	pnmrotate.1 \
-	pnmscalefixed.1 \
 	pnmscale.1 \
+	pnmscalefixed.1 \
 	pnmshear.1 \
 	pnmsmooth.1 \
 	pnmsplit.1 \
@@ -208,8 +211,8 @@ MAN1 = \
 	pnmtorle.1 \
 	pnmtosgi.1 \
 	pnmtosir.1 \
-	pnmtotiffcmyk.1 \
 	pnmtotiff.1 \
+	pnmtotiffcmyk.1 \
 	pnmtoxwd.1 \
 	ppm3d.1 \
 	ppmbrighten.1 \
@@ -230,8 +233,8 @@ MAN1 = \
 	ppmnorm.1 \
 	ppmntsc.1 \
 	ppmpat.1 \
-	ppmquantall.1 \
 	ppmquant.1 \
+	ppmquantall.1 \
 	ppmrainbow.1 \
 	ppmrelief.1 \
 	ppmrough.1 \
@@ -243,12 +246,12 @@ MAN1 = \
 	ppmtoarbtxt.1 \
 	ppmtobmp.1 \
 	ppmtoeyuv.1 \
-	ppmtogif.1 \
 	ppmtoicr.1 \
 	ppmtoilbm.1 \
 	ppmtojpeg.1 \
 	ppmtoleaf.1 \
 	ppmtolj.1 \
+	ppmtomap.1 \
 	ppmtomitsu.1 \
 	ppmtompeg.1 \
 	ppmtoneo.1 \
@@ -301,6 +304,35 @@ MAN1 = \
 	yuvsplittoppm.1 \
 	yuvtoppm.1 \
 	zeisstopnm.1 \
+        pamaddnoise.1 \
+        pambackground.1 \
+        pambayer.1 \
+        pamdepth.1 \
+        pamenlarge.1 \
+        pamgradient.1 \
+        pammasksharpen.1 \
+        pammixinterlace.1 \
+        pampick.1 \
+        pamrgbatopng.1 \
+        pamsplit.1 \
+        pamthreshold.1 \
+        pamtilt.1 \
+        pamtofits.1 \
+        pamtogif.1 \
+        pamtosvg.1 \
+        pamtotiff.1 \
+        pamtoxvmini.1 \
+        pamx.1 \
+        pbmtoibm23xx.1 \
+        pbmtomatrixorbital.1 \
+        pgmdeshadow.1 \
+        pgmmake.1 \
+        pgmmedian.1 \
+        ppmdcfont.1 \
+        ppmddumpfont.1 \
+        ppmdmkfont.1 \
+        ppmdraw.1 \
+        rlatopam.1 \
 
 MAN3 = \
 	libnetpbm.3 \
@@ -318,39 +350,57 @@ MAN5 = \
 	extendedopacity.5 \
 	pam.5 \
 	pbm.5 \
+        pfm.5 \
 	pgm.5 \
 	pnm.5 \
 	ppm.5 \
 
+# These things do get converted to man pages and installed.
 MANPAGES = $(MAN1) netpbm.1 $(MAN3) $(MAN5)
 HTMLMANUALS = $(MAN1:.1=.html) $(MAN3:.3=.html) $(MAN5:.5=.html)
+
+# These things don't get converted to manual pages.
+EXCEPTIONS = directory.html libnetpbm_dir.html libnetpbm_draw.html error.html
+STUBS = pcdindex.1 ppmcolors.1 pnmflip.1 ppmtogif.1
+
+# This works if you've done a full SVN checkout.
+USERGUIDE= ../../userguide
+
 XML = $(HTMLMANUALS:.html=.xml) netpbm.xml
 
-# These things don't get converted to manual pages
-# They're basically link lists, not useful in the man hierarchy.
-EXCEPTIONS = directory.html libnetpbm_dir.html
+# List everything in the userguide directory that is not categorized above.
+# Use this to check that 'make manpages' converts as much as possible
+# of the HTML documentation.
+uncategorized:
+	@echo $(HTMLMANUALS) $(EXCEPTIONS) $(STUBS) | tr " " "\n" | sort >LIST1
+	@(cd $(USERGUIDE); ls | sort) >LIST2
+	@comm -3 LIST1 LIST2
+	@rm LIST1 LIST2
 
-# Make man pages -- reports bad lines to standard error
+# Make man pages -- reports bad lines to standard error.
 manpages:
-	@python $(MAKEMAN) index.html $(HTMLMANUALS) 
-	mv index.1 netpbm.1
+	@python $(MAKEMAN) -d $(USERGUIDE) index.html $(HTMLMANUALS) 
+	@mv index.1 netpbm.1
 
 # Make XML pages, and validate them.
 xmlpages:
-	@for x in $(MANPAGES); do doclifter $$x; done
-	@for x in $(XML); do xmllint -xinclude --postvalid $$x >/dev/null; done
+	@for x in $(MANPAGES); do doclifter -v $$x; done
+	@for x in $(MANPAGES); do xmllint -xinclude --postvalid $$x.xml >/dev/null; done
 
 # This will install the generated man pages
-installman: manpages
-	for f in $(MAN1); do \
-	  if [ -f $$f ]; then gzip <$$f >$(MANDIR)/man1/$$f.gz; fi; \
-	  done
-	for f in $(MAN3); do \
-	  if [ -f $$f ]; then gzip <$$f >$(MANDIR)/man3/$$f.gz; fi; \
-	  done
-	for f in $(MAN5); do \
-	  if [ -f $$f ]; then gzip <$$f >$(MANDIR)/man5/$$f.gz; fi; \
-	  done
+installman:
+	set -x
+	for f in $(MAN1); do if [ -f $$f ]; then gzip <$$f >$(MANDIR)/man1/$$f.gz; fi; done
+	for f in $(MAN3); do if [ -f $$f ]; then gzip <$$f >$(MANDIR)/man3/$$f.gz; fi; done
+	for f in $(MAN5); do if [ -f $$f ]; then gzip <$$f >$(MANDIR)/man5/$$f.gz; fi; done
+
+# This will uninstall them
+uninstallman:
+	for f in $(MAN1); do rm -f $(MANDIR)/man1/$$f.gz; fi; done
+	for f in $(MAN3); do rm -f $(MANDIR)/man3/$$f.gz; fi; done
+	for f in $(MAN5); do rm -f $(MANDIR)/man5/$$f.gz; fi; done
+
+oldclean:
 	# Clean up old locations on Fedora Core 2
 	rm -f $(MANDIR)/man1/extendedopacity.1.gz 
 	rm -f $(MANDIR)/man3/directory.3.gz
diff --git a/buildtools/makeman b/buildtools/makeman
index 634a2c79..2e122779 100755
--- a/buildtools/makeman
+++ b/buildtools/makeman
@@ -19,7 +19,8 @@
 #  * Loses summary information from tables.
 #  * Only permits one <HR> in the HTML, right before the index.
 #
-# Use the makeman: passthrough to insert format lines for tables.
+# You can use the <?makeman ?> PI to pass text directly through to the
+# generated manual page,  A major use is to insert format lines for tables.
 #
 # By Eric S. Raymond <esr@thyrsus.com>
 # Version 1.0, July 26 2004
@@ -29,7 +30,7 @@ import os, sys, exceptions, re
 source = "netpbm documentation"
 section = 1
 
-warning = '''\
+warning = r'''\
 .\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
 .\" Do not hand-hack it!  If you have bug fixes or improvements, please find
 .\" the corresponding HTML page on the Netpbm website, generate a patch
@@ -47,11 +48,15 @@ def makeman(name, file, indoc):
     # Dot at left margin confuses troff.
     # This program generates these,
     indoc = indoc.replace("\n.", "\n@%@%@")
+    # Protect escapes before we try generating font changes.
+    indoc = indoc.replace("\\", r"\e")
     # Header-bashing
+    indoc = indoc.replace('<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "DTD/xhtml11.dtd">', "")
+    indoc = indoc.replace('<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">', "")
     indoc = indoc.replace('<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN">\n',"")
     indoc = indoc.replace('<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">', "")
+    indoc = indoc.replace('<meta http-equiv="Content-Type" content="text/html; charset=us-ascii"/>', "")
     indoc = indoc.replace('<?xml version="1.1" encoding="iso-8859-1" ?>\n',"")
-    indoc = indoc.replace('<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "DTD/xhtml11.dtd">', "")
     indoc = indoc.replace('<html xmlns="http://www.w3.org/1999/xhtml">', "")
     indoc = indoc.replace("<HEAD>", "").replace("</HEAD>", "")
     indoc = indoc.replace("<head>", "").replace("</head>", "")
@@ -93,8 +98,8 @@ def makeman(name, file, indoc):
     # Literal layout
     indoc = re.sub("(?i)\n *<PRE>", "\n.nf", indoc)
     indoc = re.sub("(?i)\n *</PRE>", "\n.fi", indoc)
-    indoc = re.sub("(?i)\n *<BLOCKQUOTE>", "\n.nf", indoc)
-    indoc = re.sub("(?i)\n *</BLOCKQUOTE>", "\n.fi", indoc)
+    indoc = re.sub("(?i)\n *<BLOCKQUOTE>", "\n.RS", indoc)
+    indoc = re.sub("(?i)\n *</BLOCKQUOTE>", "\n.RE", indoc)
     # Highlight processing
     indoc = re.sub("(?i)<B>", r"\\fB", indoc)
     indoc = re.sub("(?i)</B>", r"\\fP", indoc)
@@ -108,6 +113,8 @@ def makeman(name, file, indoc):
     indoc = re.sub("(?i)</TT>", r"\\fP", indoc)
     indoc = re.sub("(?i)<KBD>", r"\\f(CW", indoc)
     indoc = re.sub("(?i)</KBD>", r"\\fP", indoc)
+    indoc = re.sub("(?i)<CODE>", r"\\f(CW", indoc)
+    indoc = re.sub("(?i)</CODE>", r"\\fP", indoc)
     indoc = re.sub("(?i)<STRONG>", r"\\fB", indoc)
     indoc = re.sub("(?i)</STRONG>", r"\\fP", indoc)
     indoc = re.sub("(?i)<SUP>", r"\\u", indoc)
@@ -150,6 +157,7 @@ def makeman(name, file, indoc):
     indoc = indoc.replace("&lt;", "@#!#@").replace("&gt;", "#@!@#").replace("&amp;", "#!@!@!#")
     indoc = indoc.replace("&#215;", r"\(mu")
     indoc = indoc.replace("&#174;", r"\*R")
+    indoc = indoc.replace("&copy;", r"\(co")
     # Turn anchors into .UN tags
     indoc = re.sub('(?i)<A NAME *= *"#?([a-zA-Z][a-zA-Z0-9.-]+)">(?:&nbsp;)*</A>\s*', ".UN \\1\n", indoc)
     # Strip off the index trailer
@@ -159,17 +167,17 @@ def makeman(name, file, indoc):
     indoc = indoc.replace("</BODY>", "").replace("</HTML>", "")
     indoc = indoc.replace("</body>", "").replace("</html>", "")
     # Recognize sections with IDs
-    indoc = re.sub('(?i)<H2><A (?:ID|NAME)="([a-zA-Z]+)">([^><]*)</A></H2>',
+    indoc = re.sub('(?i)<H2><A (?:ID|NAME)="([a-zA-Z][_a-zA-Z0-9-]+)">([^><]*)</A></H2>',
                    ".UN \\1\n.SH \\2", indoc)
-    indoc = re.sub('(?i)<H3><A (?:ID|NAME)="([a-zA-Z]+)">([^><]*)</A></H3>',
+    indoc = re.sub('(?i)<H3><A (?:ID|NAME)="([a-zA-Z][_a-zA-Z0-9-]+)">([^><]*)</A></H3>',
                    ".UN \\1\n.SS \\2", indoc)
-    indoc = re.sub('(?i)<H4><A (?:ID|NAME)="([a-zA-Z]+)">([^><]*)</A></H4>',
+    indoc = re.sub('(?i)<H4><A (?:ID|NAME)="([a-zA-Z][_a-zA-Z0-9-]+)">([^><]*)</A></H4>',
                    ".UN \\1\n.B \\2", indoc)
-    indoc = re.sub('(?i)<H2 (?:ID|NAME)="([a-zA-Z]+)">([^><]*)</H2>',
+    indoc = re.sub('(?i)<H2 (?:ID|NAME)="([a-zA-Z][_a-zA-Z0-9-]+)">([^><]*)</H2>',
                    ".UN \\1\n.SH \\2", indoc)
-    indoc = re.sub('(?i)<H3 (?:ID|NAME)="([a-zA-Z]+)">([^><]*)</H3>',
+    indoc = re.sub('(?i)<H3 (?:ID|NAME)="([a-zA-Z][_a-zA-Z0-9-]+)">([^><]*)</H3>',
                    ".UN \\1\n.SS \\2", indoc)
-    indoc = re.sub('(?i)<H4 (?:ID|NAME)="([a-zA-Z]+)">([^><]*)</H4>',
+    indoc = re.sub('(?i)<H4 (?:ID|NAME)="([a-zA-Z][_a-zA-Z0-9-]+)">([^><]*)</H4>',
                    ".UN \\1\n.B \\2", indoc)
     # Sections without IDs
     indoc = re.sub('(?i)<H2>([^><]*)</H2>', ".SH \\1", indoc)
@@ -192,7 +200,7 @@ def makeman(name, file, indoc):
     # Passthrough
     indoc = re.sub(r"<\?makeman (.*) \?>", r'\1', indoc)
     # Comments
-    indoc = re.sub("<!--([^-])*-->", r'.\"\1', indoc)
+    indoc = re.sub("<!--([^\n])*-->", r'.\"\1', indoc)
     # Image tags
     indoc = re.sub(' *<img src="([^"]*)" alt="([^"]*)"( *[a-z]*="?[0-9]*"?)*>', ".B \\2\n.IMG -C \\1", indoc)
     # Special characters
@@ -217,7 +225,7 @@ def makeman(name, file, indoc):
     # Time for error checking now
     badlines = []
     for line in indoc.split("\n"):
-        if "<" in line or ">" in line or re.search("&.*;", line):
+        if "<" in line or ">" in line.replace(" >", "") or re.search("&.*;", line):
             badlines.append(line)
     if badlines:
         sys.stderr.write(("Bad lines from %s:\n-----------------\n" % file) + "\n".join(badlines) + "\n-----------------\n")
@@ -236,19 +244,22 @@ def makeman(name, file, indoc):
 def main(args, mainout=sys.stdout, mainerr=sys.stderr):
     global sectmap
     import getopt
-    (options, arguments) = getopt.getopt(args, "v")
+    (options, arguments) = getopt.getopt(args, "vd:")
+    dirprefix = ""
     verbosity = 0
     for (switch, val) in options:
-        if switch == '-v':
+        if switch == '-d':	# Set HTML input directory
+            dirprefix = val
+        elif switch == '-v':	# Enable verbose error reporting
             verbosity += 1
     try:
         # First pass: gather locations for crossreferences:
         sectmap = {}
         for file in arguments:
             try: 
-                infp = open(file)
+                infp = open(os.path.join(dirprefix, file))
             except:
-                sys.stderr.write("can't open %s" % name)
+                sys.stderr.write("makeman: can't open %s\n" % file)
                 continue
             indoc = infp.read()
             infp.close()
@@ -277,9 +288,9 @@ def main(args, mainout=sys.stdout, mainerr=sys.stderr):
         # Second pass: do formatting
         for file in arguments:
             try: 
-                infp = open(file)
+                infp = open(os.path.join(dirprefix, file))
             except:
-                sys.stderr.write("can't open %s" % name)
+                sys.stderr.write("makeman: can't open %s\n" % file)
                 continue
             indoc = infp.read()
             infp.close()
@@ -321,6 +332,7 @@ def main(args, mainout=sys.stdout, mainerr=sys.stderr):
             (exc_type, exc_value, exc_traceback) = sys.exc_info()
             raise exc_type, exc_value, exc_traceback
         else:
+            mainerr.write("makeman: internal error!\n")
             return 5
 
 if __name__ == "__main__":