diff options
| author | giraffedata <giraffedata@9d0c8265-081b-0410-96cb-a4ca84ce46f8> | 2016-02-13 18:40:19 +0000 |
|---|---|---|
| committer | giraffedata <giraffedata@9d0c8265-081b-0410-96cb-a4ca84ce46f8> | 2016-02-13 18:40:19 +0000 |
| commit | 903ed02c0978edc6c8cd52d66425a84390e26bdc (patch) | |
| tree | af43c594dff48c6908d678010c1c84946e5451ed | |
| parent | 342bb390870f16034fba04be98ee287bab89e410 (diff) | |
| download | netpbm-mirror-903ed02c0978edc6c8cd52d66425a84390e26bdc.tar.gz netpbm-mirror-903ed02c0978edc6c8cd52d66425a84390e26bdc.tar.xz netpbm-mirror-903ed02c0978edc6c8cd52d66425a84390e26bdc.zip | |
various fixes
git-svn-id: http://svn.code.sf.net/p/netpbm/code/trunk@2680 9d0c8265-081b-0410-96cb-a4ca84ce46f8
| -rwxr-xr-x | buildtools/makeman | 23 | ||||
| -rw-r--r-- | buildtools/manpage.mk | 608 | ||||
| -rw-r--r-- | doc/USERDOC | 108 |
3 files changed, 296 insertions, 443 deletions
diff --git a/buildtools/makeman b/buildtools/makeman index 94ee2172..538accad 100755 --- a/buildtools/makeman +++ b/buildtools/makeman @@ -24,6 +24,13 @@ # # By Eric S. Raymond <esr@thyrsus.com> # Version 1.0, July 26 2004 +# +# Modified by Akira F. Urushibata <afu@wta.att.ne.jp> +# Version 1.1, February 11 2016 +# +# Added ability to process — − +# Added footer message to clarify original source. +# import os, sys, exceptions, re @@ -37,6 +44,12 @@ warning = r'''\ .\" against that, and send it to the Netpbm maintainer. ''' +footerprefix = '''.SH DOCUMENT SOURCE +This manual page was generated by the Netpbm tool 'makeman' from HTML +source. The master documentation is at +.IP +.B http://netpbm.sourceforge.net/doc/''' + class LiftException(exceptions.Exception): def __init__(self, message, retval=1): self.message = message @@ -56,6 +69,7 @@ def makeman(name, file, indoc): 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('<html xmlns="http://www.w3.org/1999/xhtml">', "") + indoc = indoc.replace('<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">', "") indoc = indoc.replace("<HEAD>", "").replace("</HEAD>", "") indoc = indoc.replace("<head>", "").replace("</head>", "") indoc = re.sub('(?i)<A HREF="#index">Table Of Contents</A>', "", indoc) @@ -92,6 +106,7 @@ def makeman(name, file, indoc): title = None indoc = titlematch.sub("", indoc) indoc = re.sub("(?i)\n*<BR>\n+", "\n", indoc) + indoc = re.sub("(?i)<BR>", "\n", indoc) indoc = ('.TH "%s" %d "%s" "%s"\n' % (title,section,date,source)) + indoc # Literal layout indoc = re.sub("(?i)\n *<PRE>", "\n.nf", indoc) @@ -203,11 +218,18 @@ def makeman(name, file, indoc): indoc = re.sub(r"<\?makeman (.*) \?>", r'\1', indoc) # Comments indoc = re.sub("<!--([^\n])*-->", r'.\"\1', indoc) + # Acronyms + indoc = re.sub('<acronym [a-zA-Z0-9:= \n"]*>', "", indoc) + indoc = re.sub("</acronym>", "", indoc) # Image tags indoc = re.sub(' *<img src="([^"]*)" alt="([^"]*)"( *[a-z]*="?[0-9]*"?)*>', ".B \\2\n.IMG -C \\1", indoc) # Special characters indoc = indoc.replace(""", "'") indoc = indoc.replace(" ", "\\ ") + indoc = indoc.replace("−", "-") + indoc = indoc.replace("—", "-") + indoc = indoc.replace("μ", "mu") + indoc = indoc.replace("σ", "sigma") # Tables indoc = re.sub(' *<table[^>]*>.*', ".TS", indoc) indoc = re.sub(" *</table>.*", ".TE", indoc) @@ -241,6 +263,7 @@ def makeman(name, file, indoc): indoc = indoc.replace("\n@%@%@", "\n\\&.") # Mark these generated pages so people won't hand-hack them. indoc = warning + indoc + indoc = indoc + footerprefix + os.path.basename(file) +"\n.PP" return indoc def main(args, mainout=sys.stdout, mainerr=sys.stderr): diff --git a/buildtools/manpage.mk b/buildtools/manpage.mk index 76116ffe..acd2d40f 100644 --- a/buildtools/manpage.mk +++ b/buildtools/manpage.mk @@ -1,414 +1,204 @@ # Make Unix man pages from Netpbm HTML user manual - -MAKEMAN = makeman - -MANDIR = /usr/share/man/ - -# These can convert to man pages cleanly -MAN1 = \ - 411toppm.1 \ - anytopnm.1 \ - asciitopgm.1 \ - atktopbm.1 \ - bioradtopgm.1 \ - bmptopnm.1 \ - bmptoppm.1 \ - brushtopbm.1 \ - cameratopam.1 \ - cmuwmtopbm.1 \ - ddbugtopbm.1 \ - escp2topbm.1 \ - eyuvtoppm.1 \ - fiascotopnm.1 \ - fitstopnm.1 \ - fstopgm.1 \ - g3topbm.1 \ - gemtopbm.1 \ - gemtopnm.1 \ - giftopnm.1 \ - gouldtoppm.1 \ - hdifftopam.1 \ - hipstopgm.1 \ - hpcdtoppm.1 \ - icontopbm.1 \ - ilbmtoppm.1 \ - imgtoppm.1 \ - infotopam.1 \ - jbigtopnm.1 \ - jpeg2ktopam.1 \ - jpegtopnm.1 \ - leaftoppm.1 \ - lispmtopgm.1 \ - macptopbm.1 \ - manweb.1 \ - mdatopbm.1 \ - mgrtopbm.1 \ - mrf.1 \ - mrftopbm.1 \ - mtvtoppm.1 \ - neotoppm.1 \ - palmtopnm.1 \ - pamaddnoise.1 \ - pamarith.1 \ - pambackground.1 \ - pambayer.1 \ - pamchannel.1 \ - pamcomp.1 \ - pamcut.1 \ - pamdeinterlace.1 \ - pamdepth.1 \ - pamdice.1 \ - pamditherbw.1 \ - pamedge.1 \ - pamendian.1 \ - pamenlarge.1 \ - pamfile.1 \ - pamfixtrunc.1 \ - pamflip.1 \ - pamfunc.1 \ - pamgauss.1 \ - pamgradient.1 \ - pamlookup.1 \ - pammasksharpen.1 \ - pammixinterlace.1 \ - pamoil.1 \ - pamperspective.1 \ - pampick.1 \ - pampop9.1 \ - pamrgbatopng.1 \ - pamscale.1 \ - pamseq.1 \ - pamsharpmap.1 \ - pamsharpness.1 \ - pamslice.1 \ - pamsplit.1 \ - pamstack.1 \ - pamstereogram.1 \ - pamstretch-gen.1 \ - pamstretch.1 \ - pamsumm.1 \ - pamsummcol.1 \ - pamthreshold.1 \ - pamtilt.1 \ - pamtodjvurle.1 \ - pamtofits.1 \ - pamtogif.1 \ - pamtohdiff.1 \ - pamtohtmltbl.1 \ - pamtojpeg2k.1 \ - pamtopfm.1 \ - pamtopnm.1 \ - pamtosvg.1 \ - pamtotga.1 \ - pamtotiff.1 \ - pamtouil.1 \ - pamtoxvmini.1 \ - pamx.1 \ - pbmclean.1 \ - pbmlife.1 \ - pbmmake.1 \ - pbmmask.1 \ - pbmpage.1 \ - pbmpscale.1 \ - pbmreduce.1 \ - pbmtext.1 \ - pbmtextps.1 \ - pbmto10x.1 \ - pbmto4425.1 \ - pbmtoascii.1 \ - pbmtoatk.1 \ - pbmtobbnbg.1 \ - pbmtocmuwm.1 \ - pbmtodjvurle.1 \ - pbmtoepsi.1 \ - pbmtoepson.1 \ - pbmtoescp2.1 \ - pbmtog3.1 \ - pbmtogem.1 \ - pbmtogo.1 \ - pbmtoibm23xx.1 \ - pbmtoicon.1 \ - pbmtolj.1 \ - pbmtoln03.1 \ - pbmtolps.1 \ - pbmtomacp.1 \ - pbmtomatrixorbital.1 \ - pbmtomda.1 \ - pbmtomgr.1 \ - pbmtomrf.1 \ - pbmtonokia.1 \ - pbmtopgm.1 \ - pbmtopi3.1 \ - pbmtopk.1 \ - pbmtoplot.1 \ - pbmtoppa.1 \ - pbmtopsg3.1 \ - pbmtoptx.1 \ - pbmtowbmp.1 \ - pbmtox10bm.1 \ - pbmtoxbm.1 \ - pbmtoybm.1 \ - pbmtozinc.1 \ - pbmupc.1 \ - pc1toppm.1 \ - pcdovtoppm.1 \ - pcxtoppm.1 \ - pfmtopam.1 \ - pgmabel.1 \ - pgmbentley.1 \ - pgmcrater.1 \ - pgmdeshadow.1 \ - pgmedge.1 \ - pgmenhance.1 \ - pgmhist.1 \ - pgmkernel.1 \ - pgmmake.1 \ - pgmmedian.1 \ - pgmminkowski.1 \ - pgmmorphconv.1 \ - pgmnoise.1 \ - pgmnorm.1 \ - pgmoil.1 \ - pgmramp.1 \ - pgmslice.1 \ - pgmtexture.1 \ - pgmtofs.1 \ - pgmtolispm.1 \ - pgmtopbm.1 \ - pgmtopgm.1 \ - pgmtoppm.1 \ - pi1toppm.1 \ - pi3topbm.1 \ - picttoppm.1 \ - pjtoppm.1 \ - pktopbm.1 \ - pngtopnm.1 \ - pnmalias.1 \ - pnmarith.1 \ - pnmcat.1 \ - pnmcolormap.1 \ - pnmcomp.1 \ - pnmconvol.1 \ - pnmcrop.1 \ - pnmcut.1 \ - pnmdepth.1 \ - pnmenlarge.1 \ - pnmfile.1 \ - pnmgamma.1 \ - pnmhisteq.1 \ - pnmhistmap.1 \ - pnmindex.1 \ - pnminterp.1 \ - pnminvert.1 \ - pnmmargin.1 \ - pnmmontage.1 \ - pnmnlfilt.1 \ - pnmnoraw.1 \ - pnmnorm.1 \ - pnmpad.1 \ - pnmpaste.1 \ - pnmpsnr.1 \ - pnmquant.1 \ - pnmremap.1 \ - pnmrotate.1 \ - pnmscale.1 \ - pnmscalefixed.1 \ - pnmshear.1 \ - pnmsmooth.1 \ - pnmsplit.1 \ - pnmstitch.1 \ - pnmtile.1 \ - pnmtoddif.1 \ - pnmtofiasco.1 \ - pnmtofits.1 \ - pnmtojbig.1 \ - pnmtojpeg.1 \ - pnmtopalm.1 \ - pnmtopclxl.1 \ - pnmtoplainpnm.1 \ - pnmtopng.1 \ - pnmtopnm.1 \ - pnmtops.1 \ - pnmtorast.1 \ - pnmtorle.1 \ - pnmtosgi.1 \ - pnmtosir.1 \ - pnmtotiff.1 \ - pnmtotiffcmyk.1 \ - pnmtoxwd.1 \ - ppm3d.1 \ - ppmbrighten.1 \ - ppmchange.1 \ - ppmcie.1 \ - ppmcolormask.1 \ - ppmdcfont.1 \ - ppmddumpfont.1 \ - ppmdim.1 \ - ppmdist.1 \ - ppmdither.1 \ - ppmdmkfont.1 \ - ppmdraw.1 \ - ppmfade.1 \ - ppmflash.1 \ - ppmforge.1 \ - ppmglobe.1 \ - ppmhist.1 \ - ppmlabel.1 \ - ppmmake.1 \ - ppmmix.1 \ - ppmnorm.1 \ - ppmntsc.1 \ - ppmpat.1 \ - ppmquant.1 \ - ppmquantall.1 \ - ppmrainbow.1 \ - ppmrelief.1 \ - ppmrough.1 \ - ppmshadow.1 \ - ppmshift.1 \ - ppmspread.1 \ - ppmsvgalib.1 \ - ppmtoacad.1 \ - ppmtoarbtxt.1 \ - ppmtobmp.1 \ - ppmtoeyuv.1 \ - ppmtoicr.1 \ - ppmtoilbm.1 \ - ppmtojpeg.1 \ - ppmtoleaf.1 \ - ppmtolj.1 \ - ppmtomap.1 \ - ppmtomitsu.1 \ - ppmtompeg.1 \ - ppmtoneo.1 \ - ppmtopcx.1 \ - ppmtopgm.1 \ - ppmtopi1.1 \ - ppmtopict.1 \ - ppmtopj.1 \ - ppmtopjxl.1 \ - ppmtoppm.1 \ - ppmtopuzz.1 \ - ppmtorgb3.1 \ - ppmtosixel.1 \ - ppmtoterm.1 \ - ppmtotga.1 \ - ppmtouil.1 \ - ppmtowinicon.1 \ - ppmtoxpm.1 \ - ppmtoyuv.1 \ - ppmtoyuvsplit.1 \ - ppmtv.1 \ - ppmwheel.1 \ - psidtopgm.1 \ - pstopnm.1 \ - qrttoppm.1 \ - rasttopnm.1 \ - rawtopgm.1 \ - rawtoppm.1 \ - rgb3toppm.1 \ - rlatopam.1 \ - rletopnm.1 \ - sbigtopgm.1 \ - sgitopnm.1 \ - sirtopnm.1 \ - sldtoppm.1 \ - spctoppm.1 \ - spottopgm.1 \ - sputoppm.1 \ - tgatoppm.1 \ - thinkjettopbm.1 \ - tifftopnm.1 \ - vidtoppm.1 \ - wbmptopbm.1 \ - winicontoppm.1 \ - xbmtopbm.1 \ - ximtoppm.1 \ - xpmtoppm.1 \ - xvminitoppm.1 \ - xwdtopnm.1 \ - ybmtopbm.1 \ - yuvsplittoppm.1 \ - yuvtoppm.1 \ - zeisstopnm.1 \ - -MAN3 = \ - libnetpbm_image.3 \ - libnetpbm_ug.3 \ - libnetpbm.3 \ - libpbm.3 \ - libpgm.3 \ - libpm.3 \ - libpnm.3 \ - libppm.3 \ - libsystem.3 \ - libtmpfile.3 \ - -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 = netpbm.1 $(MAN1) $(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 - -# 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. -manpages: - @python $(MAKEMAN) -d $(USERGUIDE) index.html $(HTMLMANUALS) +# GNU make version 3.81 or newer recommended. +# Tested with GNU make version 3.80. + +# CAVEAT: USERGUIDE must be a valid directory: even for "make clean"! + +# MAKEFILE_DIR is the directory with this file: manpage.mk. +# Should be buildtools. +# Use $(realpath) and $(lastword) if available. +# (both appear in GNU make v. 3.81) + +ifeq ($(realpath $(CURDIR)/.),$(CURDIR)) + MAKEFILE_DIR := $(dir $(realpath $(lastword $(MAKEFILE_LIST)))) +else + MAKEFILE_DIR := $(dir $(word $(words $(MAKEFILE_LIST)),$(MAKEFILE_LIST))) +endif + +# Python script makeman should be in the same directory. +MAKEMAN ?= $(MAKEFILE_DIR)makeman + +# Install location of manpages. +# Subdirectories man{1,3,5} must exist. +MANDIR ?= /usr/share/man/ + +# Directory with the HTML input files. It must be explicitly set and +# must be a valid directory. + +ifeq ($(USERGUIDE),) + $(error error: Variable USERGUIDE must be explicitly set) +else + ifeq ($(wildcard $(USERGUIDE)/*html),) + $(error error: No HTML files found in $(USERGUIDE)) + endif +endif + +# In the past the following default value was used. +# It works if you've done a SVN checkout for netpbm and userguide in the +# same directory, and you are working in a subdirectory of netpbm, say +# ./buildtools . +# USERGUIDE = ../../userguide + +# The files that don't get converted to manual pages. +# Override at the command line if necessary. + +# error.html: appears when problem occurs when fetching HTML files with wget. +# directory.html: list of Netpbm programs. +# libnetpbm_dir.html: directory to pages describing libnetpbm functions +# hpcdtoppm: Not distributed via Sourceforge for copyright restrictions. +# ppmsvgalib: Not used in systems with X Window System. +# vidtoppm: Does not compile due to missing header files. + +EXCEPTIONS = \ + directory.html \ + error.html \ + hpcdtoppm.html \ + liberror.html \ + libnetpbm_dir.html \ + ppmsvgalib.html \ + vidtoppm.html + +# File lists + +# We do not provide a list of troff manpages to be generated. +# Instead the list is generated afresh from HTML file names. Reasons: +# 1. Any list would have to be updated every time an HTML file is added. +# 2. The suffix (man section) depends on content (a "META" tag) of the +# HTML file. (The mankeman script is clever.) +# 3. In one instance the file stem name changes: index.html => netpbm.1 + +# HTML files in USERGUIDE +HTML_ALL := $(sort $(notdir $(wildcard $(USERGUIDE)/*.html))) +HTMLMANUALS := $(filter-out $(EXCEPTIONS),$(HTML_ALL)) +HTML_REJECT := $(filter $(EXCEPTIONS),$(HTML_ALL)) + +# Subsets of HTMLMANUALS, by target man section +HTML3 := $(shell cd $(USERGUIDE) && \ + fgrep -l -i '<META NAME="manual_section" CONTENT="3">' \ + $(HTMLMANUALS)) +HTML5 := $(shell cd $(USERGUIDE) && \ + fgrep -l -i '<META NAME="manual_section" CONTENT="5">' \ + $(HTMLMANUALS)) +HTML1 := $(filter-out $(HTML3) $(HTML5),$(HTMLMANUALS)) + +# Troff man pages, by section +MAN1 := $(patsubst index.1,netpbm.1,$(HTML1:.html=.1)) +MAN3 := $(HTML3:.html=.3) +MAN5 := $(HTML5:.html=.5) +MANPAGES := $(MAN1) $(MAN3) $(MAN5) + +# XML +XML1 := $(MAN1:.1=.xml) +XML3 := $(MAN3:.3=.xml) +XML5 := $(MAN5:.5=.xml) +XMLPAGES = $(XML1) $(XML3) $(XML5) + +.PHONY : report +report: htmlcount manpagecount + +.PHONY : manpagecount +manpagecount: + @echo Number of actual / expected troff man pages in current directory: + @echo Section 1: $(words $(wildcard $(MAN1))) / $(words $(MAN1)) + @echo Section 3: $(words $(wildcard $(MAN3))) / $(words $(MAN3)) + @echo Section 5: $(words $(wildcard $(MAN5))) / $(words $(MAN5)) + @echo total: $(words $(wildcard $(MANPAGES))) / $(words $(MANPAGES)) + @echo + +.PHONY : htmlcount +htmlcount: + @echo HTML files in USERGUIDE directory: $(USERGUIDE) + @echo Total HTML files: $(words $(HTML_ALL)) + @echo Rejected HTML files: $(HTML_REJECT) : $(words $(HTML_REJECT)) + @echo Valid HTML files: $(words $(HTMLMANUALS)) + @echo + +.PHONY : reportvalid +reportvalid: + @echo Source HTML files in USERGUIDE directory: $(USERGUIDE) + @echo $(HTMLMANUALS) + +# Note that this may give different results from "ls ." +.PHONY : reportman +reportman: + @echo $(MANPAGES) + +# Static rules for converting HTML to troff man -- reports bad lines +# to standard error. +%.1 %.3 %.5: $(USERGUIDE)/%.html + @echo Converting $< to $@ + @python $(MAKEMAN) -d $(USERGUIDE) $(<F) + +netpbm.1: $(USERGUIDE)/index.html + @echo Converting $< to $@ + @python $(MAKEMAN) -d $(USERGUIDE) index.html @mv index.1 netpbm.1 -# Make XML pages, and validate them. -xmlpages: - @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: +# Generate man pages +.PHONY : manpages +manpages: $(MANPAGES) + +# Static rules for converting troff man to XML. +$(XML1): %.xml: %.1 + doclifter -v $< + mv $<.xml $@ + +$(XML3): %.xml: %.3 + doclifter -v $< + mv $<.xml $@ + +$(XML5): %.xml: %.5 + doclifter -v $< + mv $<.xml $@ + +# Generate XML pages. +# TODO: Does not work completely. Some pages have glitches. +.PHONY : xmlpages +xmlpages: manpages $(XMLPAGES) + +# Validate XML pages. +# TODO: Not working. +.PHONY : xmlvalidate +xmlvalidate: xmlpages + xmllint -xinclude --postvalid $< >> /dev/null + +# This will install the generated man pages. +# Note that lists MAN1 MAN3 MAN5 depend upon the names of HTML files +# in the USERGUIDE directory, even after man page generation. +# If the current directory has "pbm.1" but USERGUIDE does not have +# "pbm.html", the document will not be installed. +# If the USERGUIDE directory is empty, no documents will be installed. + +.PHONY : installman +installman: report set -x - for f in netpbm.1 $(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 netpbm.1 $(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 - rm -f $(MANDIR)/man3/libnetpbm_dir.3.gz - # remove pointer man pages (that say, "The man page isn't here") - # which might have been installed previously - for f in $(MAN1); do rm -f $(MANDIR)/man1/$$f; done - for f in $(MAN3); do rm -f $(MANDIR)/man3/$$f; done - for f in $(MAN5); do rm -f $(MANDIR)/man5/$$f; done - + for f in $(wildcard $(MAN1)); do if [ -f $$f ]; then gzip <$$f >$(MANDIR)/man1/$$f.gz; fi; done + for f in $(wildcard $(MAN3)); do if [ -f $$f ]; then gzip <$$f >$(MANDIR)/man3/$$f.gz; fi; done + for f in $(wildcard $(MAN5)); do if [ -f $$f ]; then gzip <$$f >$(MANDIR)/man5/$$f.gz; fi; done + + +# This will uninstall the man pages. +# Only pages with corresponing files in USERGUIDE are deleted. +.PHONY : uninstallman +uninstallman: report + for f in $(MAN1); do if [ -f $(MANDIR)/man1/$$f.gz ]; then rm -f $(MANDIR)/man1/$$f.gz; fi; done + for f in $(MAN3); do if [ -f $(MANDIR)/man3/$$f.gz ]; then rm -f $(MANDIR)/man3/$$f.gz; fi; done + for f in $(MAN5); do if [ -f $(MANDIR)/man5/$$f.gz ]; then rm -f $(MANDIR)/man5/$$f.gz; fi; done + + +# Legacy uninstall target. +#oldclean: +# # Clean up old locations on Fedora Core 2 +# rm -f $(MANDIR)/man1/extendedopacity.1.gz +# rm -f $(MANDIR)/man3/directory.3.gz +# rm -f $(MANDIR)/man3/libnetpbm_dir.3.gz +# # remove pointer man pages (that say, "The man page isn't here") +# # which might have been installed previously +# for f in $(MAN1); do rm -f $(MANDIR)/man1/$$f; done +# for f in $(MAN3); do rm -f $(MANDIR)/man3/$$f; done +# for f in $(MAN5); do rm -f $(MANDIR)/man5/$$f; done + + +.PHONY: clean clean: - @rm -f *.[135] $(XML) - + @rm -f *.[135] $(XML) diff --git a/doc/USERDOC b/doc/USERDOC index 9d883849..045794b9 100644 --- a/doc/USERDOC +++ b/doc/USERDOC @@ -32,11 +32,16 @@ This creates a directory "userguide" in your current directory containing all the same files that are on the web site. -An apparent alternative is just to copy the web site with something like GNU -Wget. However, the Sourceforge web server has limitations on how much you can +An alternative is just to copy the web site with something like GNU Wget. +However, the Sourceforge web server has limitations on how much you can download. In a February 2012 experiment, Sourceforge started refusing HTTP requests (with an Internal Server Error indication and a message saying there -had been too many requests) before all the files could be fetched. +had been too many requests) before all the files could be fetched. But you +can use Wget controls to fool Sourceforge. The following worked in January +2016: + + wget --wait=1 --random-wait \ + --recursive --relative http://netpbm.sourceforge.net/doc/ @@ -97,8 +102,8 @@ ways: 2) convert the HTML to formatted plain text (suitable as man "cat" pages) with the 'makecat' program in the 'buildtools' directory - of the Netpbm source tree. This program just does a - 'lynx -dump'. + of the Netpbm source tree. This program uses the dump feature + of the lynx text web browser for conversion. The "loss of quality" mentioned above is because: @@ -119,46 +124,81 @@ The "loss of quality" mentioned above is because: Also, these methods require manual effort, and technical understanding, on your part to set up. Setting it up is too complex for an automated process to do it for you with any significant -integrity. The examples are guidelines and you shouldn't expect them -to work literally in your situation. +integrity. The examples are guidelines and may not work literally +in your situation. -Here is an old example of making troff pages, which doesn't actually -work anymore, but might be helpful. You'll probably want to use a Subversion -export of the manual instead of a Wget download (see above). - mkdir netpbmdoc - cd netpbmdoc - wget --recursive --relative http://netpbm.sourceforge.net/doc/ - cd netpbm.sourceforge.net/doc - make MAKEMAN=/usr/src/netpbm/buildtools/makeman \ - -f /usr/src/netpbm/buildtools/manpage.mk manpages - make -f /usr/src/netpbm/buildtools/manpage.mk installman - cd ../../.. - rm -r netpbmdoc +MAKING TROFF MAN PAGES +---------------------- - man ppmtogif +1. Start work at the top-level directory of the source package. + +2. Download the HTML files using the subversion command. +The downloaded files will go into "./userguide/". + + svn export https://svn.code.sf.net/p/netpbm/code/userguide -Here is an example of making "cat" pages: +3. Create a work directory named "netpbmdoc". The troff man pages, +as they are converted from HTML pages by the makeman utility, will +be written here. mkdir netpbmdoc cd netpbmdoc - wget --recursive --relative http://netpbm.sourceforge.net/doc/ - cd netpbm.sourceforge.net/doc - /usr/src/netpbm/buildtools/makecat *.html - cp *.1 /usr/man/cat1/ - cd ../../.. - rm -r netpbmdoc + make USERGUIDE=../userguide/ -f ../buildtools/manpage.mk manpages - man ppmtogif +USERGUIDE is the directory containing the input HTML pages. Keep +it intact until installation is complete. + +4. Install the troff man pages, with MANDIR set up appropriately +to the destination. + +MANDIR and MANDIR/{man1,man3,man5} must be existing directories. +The install step usually requires superuser permissions. + + make MANDIR=/usr/local/netpbm/man USERGUIDE=../userguide/ \ + -f ../buildtools/manpage.mk installman + cd ../ + rm -rf netpbmdoc + +5. Adjust MANPATH if necessary and try showing one manual page. + + man pamflip + + +MAKING CAT PAGES +---------------- + +As with the above example for troff man pages, start at the top-level +directory of the source package. + + svn export https://svn.code.sf.net/p/netpbm/code/userguide + + cd ./userguide + ../buildtools/makecat *.html + + cp *.1 /usr/man/cat1/ # Usually requires superuser permission + +The makecat utility reads files from the current directory and writes +the results into the same directory. As noted above, it requires lynx +<http://lynx.invisible-island.net/>. DOCBOOK ------- -You can turn the Netpbm user manual into Docbook XML pages using -Doclifter. Because Doclifter works on troff pages, you have to -convert the documentation down to troff first, which means the Docbook -pages are of lower quality than the main HTML documentation. +You can turn the Netpbm user manual into Docbook XML pages using Doclifter. +Because Doclifter works on troff pages, you have to convert the documentation +down to troff first, which means the Docbook pages are of lower quality than +the master HTML documentation. + +To create Docbook XML, do as follows: + + mkdir netpbmdoc + cd netpbmdoc + make USERGUIDE=../userguide/ -f ../buildtools/manpage.mk xmlpages + +The 'make' executes the HTML to troff conversion step automatically. For the +troff to XML step, there are problems that have not been completely worked +out; conversion of several files will fail. -To create Docbook XML, follow the example above for creating troff -pages, and use 'make xmlpages' instead of 'make manpages'. +There is no equivalent for 'make installman' for the Docbook XML pages. |