miscellaneous update

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

6 files changed, 197 insertions, 65 deletions

diff --git a/directory.html b/directory.html
index 7dd56a08..a5b5b367 100644
--- a/directory.html
+++ b/directory.html
@@ -49,40 +49,32 @@
 <DD>convert a PAM image to PBM, PGM, or PPM
 
 <DT><B><a href=pamtogif.html>pamtogif</a>     </B>
-<DD>
-convert PAM or PNM to GIF
+<DD>convert PAM or PNM to GIF
 
 <DT><B><a href=giftopnm.html>giftopnm</a>     </B>
-<DD>
-convert GIF to PNM
+<DD>convert GIF to PNM
 
 <DT><B><a href=pnmtojpeg.html>pnmtojpeg</a>    </B>
-<DD>
-convert PNM to JPEG/JFIF/EXIF format
+<DD>convert PNM to JPEG/JFIF/EXIF format
 
 <DT><B><a href=jpegtopnm.html>jpegtopnm</a>    </B>
-<DD>
-convert JFIF/JPEG/EXIF file to Netpbm format
+<DD>convert JFIF/JPEG/EXIF file to Netpbm format
 
 <DT><B><a href=pamtojpeg2k.html>pamtojpeg2k</a>    </B>
-<DD>
-convert PNM/PAM to JPEG-2000 code stream
+<DD>convert PNM/PAM to JPEG-2000 code stream
 
 <DT><B><a href=jpeg2ktopam.html>jpeg2ktopam</a>    </B>
-<DD>
-convert JPEG-2000 code stream to PAM/PNM
+<DD>convert JPEG-2000 code stream to PAM/PNM
 
 <DT><B><a href=pamtopng.html>pamtopng</a>     </B>
-<DD>
-convert Netpbm format to Portable Network Graphics
+<DD>convert Netpbm format to Portable Network Graphics
 
 <DT><B><a href=pnmtopng.html>pnmtopng</a>     </B>
 <DD>
 convert Netpbm format to Portable Network Graphics
 
 <DT><B><a href=pngtopam.html>pngtopam</a>     </B>
-<DD>
-convert PNG (Portable Network Graphics) to Netpbm formats
+<DD>convert PNG (Portable Network Graphics) to Netpbm formats
 
 <DT><B><a href=pnmtops.html>pnmtops</a>      </B>
 <DD>convert Netpbm formats to Postscript
@@ -100,12 +92,10 @@ convert PNG (Portable Network Graphics) to Netpbm formats
 <DD>convert Netpbm formats to TIFF CMYK file
 
 <DT><B><a href=ppmtobmp.html>ppmtobmp</a>     </B>
-<DD>
-convert PPM to Windows or OS/2 Bitmap file
+<DD>convert PPM to Windows or OS/2 Bitmap file
 
 <DT><B><a href=bmptopnm.html>bmptopnm</a>     </B>
-<DD>
-convert Windows or OS/2 Bitmap file to PPM or PGM
+<DD>convert Windows or OS/2 Bitmap file to PPM or PGM
 
 <DT><B><a href=pbmtog3.html>pbmtog3</a>      </B>
 <DD>convert PBM to Group 3 FAX
@@ -117,8 +107,7 @@ convert Windows or OS/2 Bitmap file to PPM or PGM
 <DD>convert PNM to JBIG BIE (compressed bitmap)
 
 <DT><B><a href=jbigtopnm.html>jbigtopnm</a>    </B>
-<DD>
-convert JBIG BIE (compressed bitmap) to PNM
+<DD>convert JBIG BIE (compressed bitmap) to PNM
 
 <DT><B><a href=pnmtoxwd.html>pnmtoxwd</a>     </B>
 <DD>convert Netpbm formats to X11 window dump
@@ -377,7 +366,7 @@ convert Palm DiddleBug image to PBM
 <DD>convert Atari Degas .pc1 (compressed pi1) to PPM
 
 <DT><B><a href=pcdovtoppm.html>pcdovtoppm</a>      </B>
-<DD>Convert a photo CD PCD overview file to PPM
+<DD>convert a photo CD PCD overview file to PPM
 
 <DT><B><a href=pnmtopclxl.html>pnmtopclxl</a>      </B>
 <DD>convert PNM to HP PCL-XL (PCL 6) printer language
@@ -533,7 +522,7 @@ convert Palm Pilot Image Viewer format to Netpbm formats.
 <dd>convert an SVG (Scalable Vector Graphics) image to Netpbm format
 
 <DT><B><a href=ppmtoterm.html>ppmtoterm</a>     </B>
-<DD>Display PPM image on ANSI standard text terminal
+<DD>display PPM image on ANSI standard text terminal
 
 <DT><B><a href=pamtotga.html>pamtotga</a>     </B>
 <DD>convert PAM to TrueVision Targa file
@@ -557,20 +546,16 @@ convert Palm Pilot Image Viewer format to Netpbm formats.
 <DD>convert WAP (Wireless App Protocol) Wireless Bitmap to PBM
 
 <DT><B><a href=pamtowinicon.html>pamtowinicon</a></B>
-<DD>
-convert PAM to Windows icon file
+<DD>convert PAM to Windows icon file
 
 <DT><B><a href=ppmtowinicon.html>ppmtowinicon</a></B>
-<DD>
-convert PPM to Windows icon file (obsoleted by <b>pamtowinicon</b>).
+<DD>convert PPM to Windows icon file (obsoleted by <b>pamtowinicon</b>).
 
 <DT><B><a href=winicontopam.html>winicontopam</a></B>
-<DD>
-convert Windows icon file to PAM
+<DD>convert Windows icon file to PAM
 
 <DT><B><a href=winicontoppm.html>winicontoppm</a></B>
-<DD>
-convert Windows icon file to PPM (obsoleted by <b>winicontoapm</b>).
+<DD>convert Windows icon file to PPM (obsoleted by <b>winicontoapm</b>).
 
 <DT><B><a href=ximtoppm.html>ximtoppm</a>     </B>
 <DD>convert Xim to PPM
@@ -618,8 +603,7 @@ convert Windows icon file to PPM (obsoleted by <b>winicontoapm</b>).
 <DD>convert PPM to just about any text-based format, using a grammar file
      
 <DT><B><a href=anytopnm.html>anytopnm</a>     </B>
-<DD>
-convert any graphics format to Netpbm format
+<DD>convert any graphics format to Netpbm format
 
 </DL>
 
@@ -854,7 +838,7 @@ a color map containing all possible colors of given maxval
 <DD>perform morphological convolutions on a PGM image: dilation and erosion.
      
 <DT><B><a href="pgmbentley.html">pgmbentley</a>    </B>
-<DD>Bentleyize a PGM image
+<DD>bentleyize a PGM image
 
 <DT><B><a href="pamoil.html">pamoil</a>        </B>
 <DD>turn a PNM or PAM image into an oil painting
@@ -872,11 +856,14 @@ a color map containing all possible colors of given maxval
 <DD>quantize colors on many files
 
 <DT><B><a href=pnmremap.html>pnmremap</a></B>
-<DD>Replace colors in an image with those from a color map
+<DD>replace colors in an image with those from a color map
 
 <DT><B><a href=pamlookup.html>pamlookup</a></b>
 <DD>map an image to a new image by using it as indices into a table
      
+<DT><B><a href=pamunlookup.html>pamunlookup</a></b>
+<DD>inverse of <b>pamlookup</b> - generates the index image
+     
 <DT><B><a href=ppmshift.html>ppmshift</a>      </B>
 <DD>shift lines of PPM image left or right a random amount
 
@@ -887,7 +874,7 @@ a color map containing all possible colors of given maxval
 <DD>shear an image
 
 <DT><B><a href=pamrubber.html>pamrubber</a>    </B>
-<DD>Rubber sheet deforming, distortion, stretching of an image
+<DD>rubber sheet deforming, distortion, stretching of an image
 
 <DT><B><a href=pamaddnoise.html>pamaddnoise</a>     </B>
 <DD>add noise to an image
@@ -896,17 +883,17 @@ a color map containing all possible colors of given maxval
 <dd>replace detail with smooth gradient from one edge to the other
 
 <DT><B><a href=pamperspective.html>pamperspective</a>    </B>
-<DD>Change perspective distortion in an image
+<DD>change perspective distortion in an image
 
 <DT><B><a href=pgmabel.html>pgmabel</a></B>
 <DD>create cross-section of an image using Abel integration for deconvolution
 
 <dt><b><a href="pnmmercator.html">pnmmercator</a></b>
-<dd>Turns a rectangular projection map into a Mercator projection
+<dd>turn a rectangular projection map into a Mercator projection
 
 <DT><B><a href=ppmglobe.html>ppmglobe</a></b>
 
-<DD>Turn a cylindrical projection into strips that can be glued onto a sphere
+<DD>turn a cylindrical projection into strips that can be glued onto a sphere
 
 <DT><B><a href=pnmtile.html>pnmtile</a>       </B>
 <DD>replicate an image into a specified size
@@ -915,7 +902,7 @@ a color map containing all possible colors of given maxval
 <DD>slice an image into many horizontally and/or vertically
 
 <DT><B><a href=pamundice.html>pamundice</a></B>
-<DD>Assemble an image from tiles (opposite of <b>pamdice</b>)
+<DD>assemble an image from tiles (opposite of <b>pamdice</b>)
 
 <DT><B><a href=ppmtorgb3.html>ppmtorgb3</a>     </B>
 <DD>separate a PPM into three PGMs
@@ -938,16 +925,16 @@ a color map containing all possible colors of given maxval
 <DD>deshadow a PGM image
 
 <DT><B><a href=ppmdraw.html>ppmdraw</a>      </B>
-<DD>Draw text, lines, shapes, etc. on an image
+<DD>draw text, lines, shapes, etc. on an image
 
 <DT><B><a href=ppmlabel.html>ppmlabel</a>      </B>
-<DD>Add text to an image
+<DD>add text to an image
 
 <DT><B><a href=pamsummcol.html>pamsummcol</a>      </B>
 <DD>summarize (sum, average, etc) an image by column
 
 <DT><B><a href=ppmfade.html>ppmfade</a></B>
-<DD>Produce series of images fading from one to another
+<DD>produce series of images fading from one to another
      
 </DL>
 
@@ -981,10 +968,10 @@ These all work on the Netpbm formats as input.
 <DD>draw a histogram of a PGM or PPM
 
 <DT><B><a href=pnmcolormap.html>pnmcolormap</a></B>
-<DD>Choose the N best colors to represent an image; create a colormap
+<DD>choose the N best colors to represent an image; create a colormap
 
 <DT><B><a href=pamsumm.html>pamsumm</a>      </B>
-<DD>Summarize (sum, average, etc.) all samples in an image
+<DD>summarize (sum, average, etc.) all samples in an image
      
 <DT><B><a href=pamsharpness.html>pamsharpness</a>      </B>
 <DD>measure the sharpness of an image
@@ -993,16 +980,16 @@ These all work on the Netpbm formats as input.
 <DD>create map of sharpness in an image
 
 <DT><B><a href=pamtilt.html>pamtilt</a></B>
-<DD>Measure the tilt of an image, i.e. document skew
+<DD>measure the tilt of an image, i.e. document skew
 
 <DT><B><a href=pgmminkowski.html>pgmminkowski</a></b>
-<DD>Compute Minkowski integral over a PGM image</DD>
+<DD>compute Minkowski integral over a PGM image</DD>
 
 <DT><B><a href=pbmminkowski.html>pbmminkowski</a></b>
-<DD>Compute Minkowski integral over a PBM image</DD>
+<DD>compute Minkowski integral over a PBM image</DD>
 
 <DT><B><a href=pammosaicknit.html>pammosaicknit</a></B>
-<DD>Validate a mosaic knitting pattern
+<DD>validate a mosaic knitting pattern
 
 </DL>
 
@@ -1027,13 +1014,13 @@ These all work on the Netpbm formats as input.
 <DD>run a shell command on each image of a multi-image stream
 
 <DT><B><a href=pamendian.html>pamendian</a></B>
-<DD>Swap bytes in multi-byte samples of a PAM image
+<DD>swap bytes in multi-byte samples of a PAM image
      
 <DT><b><a href="pamfix.html">pamfix</a></b>
 <dd>salvage a Netpbm image whose file is truncated or has invalid sample values
 
 <DT><b><a href="pamvalidate.html">pamvalidate</a></b>
-<dd>Copy Netpbm image stream, if and only if entire stream is valid Netpbm.
+<dd>copy Netpbm image stream, if and only if entire stream is valid Netpbm.
 
 <DT><B><a href="pbmmask.html">pbmmask</a></B>
 <DD>create a mask bitmap from a regular bitmap
@@ -1063,7 +1050,7 @@ These all work on the Netpbm formats as input.
 <DD>dump a Ppmdfont file
 
 <DT><B><a href="ppmdcfont.html">ppmdcfont</a>         </B>
-<DD>Turn a Ppmdfont file into C source for a builtin font
+<DD>turn a Ppmdfont file into C source for a builtin font
      
 <DT><B><a href="pnmindex.html">pnmindex</a>      </B>
 <DD>build a visual index of a bunch of Netpbm images
diff --git a/fitstopnm.html b/fitstopnm.html
index 7ce160f6..7d870bae 100644
--- a/fitstopnm.html
+++ b/fitstopnm.html
@@ -2,7 +2,7 @@
 <HTML><HEAD><TITLE>Fitstopnm User Manual</TITLE></HEAD>
 <BODY>
 <H1>fitstopnm</H1>
-Updated: 22 May 2007
+Updated: 2 August 2015
 <BR>
 <A HREF="#index">Table Of Contents</A>
 
@@ -34,6 +34,17 @@ input and produces a PPM image if the FITS file consists of 3 image planes
 (NAXIS = 3 and NAXIS3 = 3), or a PGM image if the FITS file consists of 2
 image planes (NAXIS = 2), or if you specify the <B>-image</B> option.
 
+<p>Note that the PPM image is highly unlikely to be a true PPM image, as it is
+not normal for a FITS image to use the third axis as R, G, and B components of
+the pixels.  The most common interpretation when there are 3 axes is that the
+third one is time.  So the image is instead a pseudo-PPM in which the three
+sample values of a pixel represent something other than color components, for
+example gray levels at three instants (this variation on PPM is common in
+programs such as <b>fitstopnm</b> that predate the PAM format).
+
+<p>If you work with FITS images with 3 axes, you should probably always use
+the <b>-image</b> option to avoid getting an unwanted pseudo-PPM image.
+
 <P>The program tells you what kind of PNM image it is writing.
 
 
@@ -43,11 +54,11 @@ image planes (NAXIS = 2), or if you specify the <B>-image</B> option.
 
 <dt><b>-image=</b><i>N</i>
 
-<dd>This is for FITS files with three axes.  The assumption is that
-the third axis is for multiple images, and this option lets you select
-which one you want.
+<dd>This is for FITS files with three axes.  This option says that the third
+axis is for multiple images, and the option value <i>N</i> tells which one you
+want.
 
-<dd><b>-omaxval=</b><i>N</i>
+<dt><b>-omaxval=</b><i>N</i>
 
 <P>This is the maxval that the output PNM image is to have.
 
diff --git a/pamlookup.html b/pamlookup.html
index a4dc16c1..6f8b25e2 100644
--- a/pamlookup.html
+++ b/pamlookup.html
@@ -362,6 +362,7 @@ produce the output:
      
 <H2 id="seealso">SEE ALSO</H2>
 
+<A HREF="pamunlookup.html">pamunlookup</A>,
 <A HREF="pnmremap.html">pnmremap</A>,
 <A HREF="ppmmake.html">ppmmake</A>,
 <A HREF="pnmcat.html">pnmcat</A>,
@@ -392,6 +393,3 @@ produce the output:
 </UL>
 </BODY>
 </HTML>
-
-
-
diff --git a/pamtofits.html b/pamtofits.html
index b3bbe30e..acad58b1 100644
--- a/pamtofits.html
+++ b/pamtofits.html
@@ -66,9 +66,10 @@ FITS format in 1989, so it is something of a de facto standard.  Nobody
 reported trouble with that until 2008.
 
 <p>However, at least some versions of ImageMagick and Gimp (as seen in 2008)
-use bottom to top order, so if you use display a FITS image generated by
-<b>pamtofits</b>, it will appear upside down.  To fix that, use <b>pamflip
--topbottom</b> on the image before feeding it to <b>pamtofits</b>.
+use bottom to top order, so if you use on of these to display a FITS image
+generated by <b>pamtofits</b>, it will appear upside down.  To fix that,
+use <b>pamflip -topbottom</b> on the image before feeding it
+to <b>pamtofits</b>.
 
 <p>Since 2008, people have noted that NASA distributes FITS files with
 bottom to top order.
diff --git a/pamunlookup.html b/pamunlookup.html
new file mode 100644
index 00000000..9509e196
--- /dev/null
+++ b/pamunlookup.html
@@ -0,0 +1,135 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN">
+<HTML>
+<HEAD><title>Pamunlookup User Manual</title></HEAD>
+<BODY>
+<H1>pamunlookup</H1>
+Updated: 9 August 2015
+<BR>
+<A HREF="#index">Table Of Contents</A>
+
+<H2 id="name">NAME</H2>
+pamunlookup - inverse of pamlookup
+
+<H2 id="synopsis">SYNOPSIS</H2>
+
+<B>pamunlookup</B>
+<B>-lookupfile=</B><i>lookupfile</i>
+<I>inputfile</I>
+
+
+<P>All options can be abbreviated to their shortest unique prefix.
+You may use two hyphens instead of one.  You may separate an option
+name and its value with white space instead of an equals sign.
+
+<H2 id="description">DESCRIPTION</H2>
+
+<p>This program is part of <a href="index.html">Netpbm</a>.
+
+<p><b>pamunlookup</b> is best described as the inverse of <b>pamlookup</b>
+(without <b>-byplane</b>).  For example, the following normally yields output
+identical the input:
+
+<pre>
+<kbd>
+    $ cat input.ppm | \
+        pamlookup -lookupfile=map.pam | \
+        pamunlookup -lookupfile=map.pam \
+        &gt; output.ppm
+</kbd>
+</pre>
+
+
+<p>Specifically, <b>pamunlookup</b> takes an input image and produces an
+output image of the same width and height in which each tuple is a single
+number.  That number is the index in a given lookup table of the tuple value
+that is in the same position in the input image.
+
+<p>You specify the lookup table the same way as for
+<a href="pamlookup.html#lookupimage"><b>pamlookup</b></a>.
+
+<p>Where a tuple in the input image is not in the lookup table, the
+number <b>pamunlookup</b> places in the output index image is one greater than
+the highest index in the lookup table.  Accordingly, the maxval of the output
+index image is the size of the lookup table.
+
+
+<h3 id="example">Example</h3>
+
+<P>Here is an example of <b>pamunlookup</b>'s function.
+
+<p>Consider an input image consisting of a 3x2 PPM as follows:
+
+<table summary="output image">
+<?makeman l l l. ?>
+<tr> <td>red</td> <td>yellow</td> <td>red</td> </tr>
+<tr> <td>beige</td> <td>beige</td> <td>beige</td> </tr>
+</table>
+
+and a lookup table consisting of a 3x1 PPM image as follows:
+
+<table summary="3x1 lookup table">
+<?makeman l l l. ?>
+<tr> <td>red</td> <td>yellow</td> <td>beige</td> </tr>
+</table>
+
+The lookup table above says Index 0 corresponds to the color red,
+Index 1 corresponds to yellow, and Index 2 corresponds to beige.  The output
+of <b>pamunlookup</b> is the following index image:
+
+<table summary="3x2x1 index image">
+<?makeman l l l. ?>
+<tr> <td>0</td> <td>1</td> <td>0</td> </tr>
+<tr> <td>2</td> <td>2</td> <td>2</td> </tr>
+</table>
+
+
+<h3 id="misc">Miscellaneous</h3>
+
+<p>The <i>inputfile</i> argument identifies the file containing the index PAM
+or PNM image.  <b>-</b> means Standard Input.  It won't work if both the input
+image file and lookup table file are Standard Input.
+
+The output index image goes to Standard Output.
+
+
+<H2 id="options">OPTIONS</H2>
+
+<DL COMPACT>
+<DT><B>-lookupfile=</B><i>lookupfile</i>
+
+<DD><i>lookupfile</i> names the file that contains the PAM or PNM
+image that is the lookup table.  This option is mandatory.
+
+</DL>
+
+     
+<H2 id="seealso">SEE ALSO</H2>
+
+<A HREF="pamlookup.html">pamlookup</A>,
+<A HREF="ppmchange.html">ppmchange</A>,
+<A HREF="pnmcolormap.html">pnmcolormap</A>,
+<A HREF="pnm.html">pnm</A>,
+<A HREF="pam.html">pam</A>
+
+
+<H2 id="history">HISTORY</h2>
+
+<p><b>pamunlookup</b> was new in Netpbm 10.72 (September 2015).
+
+<HR>
+<H2 id="index">Table Of Contents</H2>
+<UL COMPACT>
+<LI><A HREF="#synopsis">SYNOPSIS</A>
+<LI><A HREF="#description">DESCRIPTION</A>
+  <ul>
+  <li><a href="#example">Example</a>  
+  </ul>
+<LI><A HREF="#options">OPTIONS</A>
+<LI><A HREF="#history">HISTORY</A>
+<LI><A HREF="#seealso">SEE ALSO</A>
+</UL>
+</BODY>
+</HTML>
+
+
+
diff --git a/pgmhist.html b/pgmhist.html
index 42251ad7..02d50cb4 100644
--- a/pgmhist.html
+++ b/pgmhist.html
@@ -33,7 +33,7 @@ gray values or other gray value distribution metrics.
 <p>If you specify none of <b>-median</b>, <b>-quartile</b>, or <b>-decile</b>,
 <b>pgmhist</b> prints a complete histogram showing how many pixels of each
 possible gray value exist in the image.  Along with each gray value, it tells
-you how many pixels are more black and more white that it.
+you how many pixels are more black and more white than it.
 
 <p><b>-median</b>, <b>-quartile</b>, and <b>-decile</b> options cause
 <b>pgmhist</b> instead to print the indicated quantiles.  Each quantile is a