diff options
author | esr <esr@9d0c8265-081b-0410-96cb-a4ca84ce46f8> | 2007-01-30 00:58:04 +0000 |
---|---|---|
committer | esr <esr@9d0c8265-081b-0410-96cb-a4ca84ce46f8> | 2007-01-30 00:58:04 +0000 |
commit | 4b1cd946bb66d4590d08f7ee05cdddacb301348a (patch) | |
tree | 77558b8d4e7a7c43702a5ff54c74763e8430b3f3 /buildtools | |
parent | db9e768aa06e654762dc888f3254ac941283d169 (diff) | |
download | netpbm-mirror-4b1cd946bb66d4590d08f7ee05cdddacb301348a.tar.gz netpbm-mirror-4b1cd946bb66d4590d08f7ee05cdddacb301348a.tar.xz netpbm-mirror-4b1cd946bb66d4590d08f7ee05cdddacb301348a.zip |
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
Diffstat (limited to 'buildtools')
-rw-r--r-- | buildtools/Makefile.manpage | 98 | ||||
-rwxr-xr-x | buildtools/makeman | 50 |
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("<", "@#!#@").replace(">", "#@!@#").replace("&", "#!@!@!#") indoc = indoc.replace("×", r"\(mu") indoc = indoc.replace("®", r"\*R") + indoc = indoc.replace("©", r"\(co") # Turn anchors into .UN tags indoc = re.sub('(?i)<A NAME *= *"#?([a-zA-Z][a-zA-Z0-9.-]+)">(?: )*</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__": |