Since May 2002, Netpbm does not have traditional man pages for
documentation.  BUT YOU CAN CONFIGURE NETPBM, IF YOU WANT, SO YOU GET
ESSENTIALLY THE SAME 'MAN' FUNCTION AS WITH A TRADITIONAL UNIX PACKAGE.

Netpbm's maintainer believes man pages are obsolete and too limiting,
and doesn't have time to maintain the documentation in multiple
formats.  So instead of classic nroff man page format, the Netpbm
documentation is available as HTML, with one HTML file per program,
plus some others.  The current user manual is accessible on the World
Wide Web at <http://netpbm.sourceforge.net/doc>, and if it's practical
for you, you should access it there instead of making a local copy.
This manual is always up to date.  It is not maintained on a release
schedule like the source code is, but rather updated continuously.
The user manual describes past Netpbm function as well as the present,
so you can use the current manual with old Netpbm code.


INSTALLING A LOCAL COPY OF DOCUMENTATION
----------------------------------------

If accessing the manual on the World Wide Web is not convenient for
you (for example, if you want to access it from a computer that is not
always connected to the Internet), just make a local copy of the web
site files using GNU Wget:

  wget --recursive --relative http://netpbm.sourceforge.net/doc/

The above copies all the HTML files from the web site into your current
directory.  You can browse those files directly with a web browser.
If you don't have Wget, get it from ftp://ftp.gnu.org/gnu/wget.  It is
very useful.


GETTING COMMAND HELP WITH A "MAN" COMMAND
-----------------------------------------

You can get the same quick access to program documentation with this
HTML setup as with traditional man pages, using the Manweb program.
This works whether you use the www copy or a local copy of the HTML
files.  Manweb is distributed with Netpbm.  With Manweb and Netpbm
installed and configured appropriately (see below), you can type

  man netpbm

and get the top level page of the Netpbm user manual (with hyperlinks to
all the other pages), or

  man netpbm pnmtogif

or 

  man pnmtogif

to go straight to the Pnmtogif documentation.

Installnetpbm normally installs Manweb and the netpbm.url file that
Manweb needs to find the Netpbm documentation.  Through the Configure
dialog, or editing Makefile.config, you determine whether Manweb
accesses the master web copy or a local copy you installed.

Installnetpbm installs the program as 'manweb'.  If you want to invoke
it as 'man', you'll have to set that up yourself.  Perhaps with a
symbolic link from 'man' to 'manweb'.  Note that 'manweb' is mostly
backward compatible with 'man' so that this is a reasonable thing to
do.


In a standard installation of Netpbm, Installnetpbm also creates a
traditional man page for every Netpbm program it installs, but the man
page just tells you to go to the HTML file.  This way, even if the "man"
program isn't capable of reading the HTML documentation and even if the
user doesn't know specifically where Netpbm documentation lives, he isn't
stranded without information.


VIEWING NETPBM DOC WITH TRADITIONAL MAN PROGRAM
-----------------------------------------------

Some people want to be able to access the Netpbm documentation with an
existing man program that doesn't know HTML.  You can install the
documentation that way, with some loss of quality.  Download the HTML
files, format them into plain displayable text with 'lynx -dump', and
then put those files into a man "cat" directory such as /usr/man/cat1.

The program 'makecat' in the 'buildtools' directory of the Netpbm source
tree does the lynx -dump on a set of files, so do something like this
example:

  mkdir netpbmdoc
  cd netpbmdoc
  wget --recursive --relative http://netpbm.sourceforge.net/doc/
  /usr/src/netpbm/buildtools/makecat *.html
  cp *.1 /usr/man/cat1/
  cd ..
  rm -r netpbmdoc

  man pnmtogif

Note that many of the Netpbm documentation files are not manuals for
particular programs, so the usual flat namespace limitation of man
pages will be exacerbated.

