miscellaneous update

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

6 files changed, 85 insertions, 33 deletions

diff --git a/pambackground.html b/pambackground.html
index 9fedda8a..5f345dea 100644
--- a/pambackground.html
+++ b/pambackground.html
@@ -60,15 +60,14 @@ building, you could use <b>ppmchange</b> to change all pixels within
 on it.
 
 <p>You might even extract the argument for <b>ppmchange</b> from the image in
-question, using <b>ppmtoarbtxt</b>.  In the foregoing example, we knew the
+question, using <b>pamgetcolor</b>.  In the foregoing example, we knew the
 background was approximately SkyBlue, but if we didn't we could just get the
 color of the top left pixel, in a form suitable for the color arguments
 of <b>ppmchange</b> like this:
 
 <pre>
 <kbd>
-    $ echo "#(fred)/#(fgreen)/#(fblue)" &gt;/tmp/bodyskl
-    $ color=$(pamcut 0 0 1 1 myimage.ppm | ppmtoarbtxt /tmp/bodyskl)
+    $ color=$(pamgetcolor 0,0 -infile=/tmp/bodyskl|cut --fields=2 -delim=' ')
 </kbd>
 </pre>
 
@@ -76,22 +75,20 @@ of <b>ppmchange</b> like this:
 to use <b>pnmquant</b> to produce a version of the image with a very small
 number of colors.  The background would likely then be all one color.
 
-<p>If the <b>pnmquant</b> and <b>ppmchange</b> methods above do not
-adequately distinguish foreground colors from background colors, you can
-try a more elaborate method using <b>pnmremap</b>.
-If you can manually create a palette with
-one color to which all the background pixels are similar, and other colors
-to which the foreground pixels are similar, you can use it as input to
+<p>If the <b>pnmquant</b> and <b>ppmchange</b> methods above do not adequately
+distinguish foreground colors from background colors, you can try a more
+elaborate method using <b>pnmremap</b>.  If you can manually create a palette
+with one color to which all the background pixels are similar, and other
+colors to which the foreground pixels are similar, you can use it as input to
 <b>pnmremap</b> to create a smarter version of what you get with the
 <b>pnmquant</b> or <b>ppmchange</b> methods, so that <b>pambackground</b> is
 more likely to separate background from foreground as your eye does.
 
-<p>The PAM that <b>pambackground</b> creates has a single plane, with
-a maxval of 1.  The sample value 1 means background; 0 means
-foreground.  There is no tuple type.  Some older programs (but none
-that are part of Netpbm) don't know what a PAM is and expect a mask to
-be in the form of a PGM or PBM image.  To convert
-<b>pambackground</b>'s output to PBM, use <b>pamtopnm -assume</b>.  To
+<p>The PAM that <b>pambackground</b> creates has a single plane, with a maxval
+of 1.  The sample value 1 means background; 0 means foreground.  There is no
+tuple type.  Some older programs (but none that are part of Netpbm) don't know
+what a PAM is and expect a mask to be in the form of a PGM or PBM image.  To
+convert <b>pambackground</b>'s output to PBM, use <b>pamtopnm -assume</b>.  To
 convert to PGM, use <b>pgmtopgm</b>.
 
 <P><I>netpbmfile</I> is the file specification of the input file, or
@@ -150,6 +147,7 @@ are see-through holes in the foreground image.
 <B><A HREF="pamtopnm.html">pamtopnm</A></B>,
 <B><A HREF="pgmtopgm.html">pgmtopgm</A></B>,
 <B><A HREF="pamstack.html">pamstack</A></B>,
+<B><A HREF="pamstack.html">pamgetcolor</A></B>,
 <B><A HREF="pnm.html">pnm</A></B>,
 <B><A HREF="pam.html">pam</A></B>,
 
diff --git a/pamflip.html b/pamflip.html
index 05f07d58..c9401f30 100644
--- a/pamflip.html
+++ b/pamflip.html
@@ -38,8 +38,8 @@ its value.
 <p>This program is part of <a href="index.html">Netpbm</a>.
 
 <p><b>pamflip</b> flips a PAM or PNM image top for bottom or left for right,
-or transposes it horizontal for vertical, or rotates it 1, 2, or 3
-quarter turns.
+or transposes it horizontal for vertical, or rotates it 1, 2, or 3 quarter
+turns.
 
 <p>To rotate at other angles, use <b>pnmrotate</b>.  It is much slower,
 though.
@@ -150,10 +150,15 @@ a major factor in your estimate.
 memory you specify, it does the transformation in chunks, using temporary
 files for intermediate results.
 
-<p>Strict horizontal transformations (either left for right or null),
-<b>pamflip</b> never keeps more than one row in memory, so the memory
-size is irrelevant and <b>pamflip</b> doesn't use temporary files.
+<p>In strict horizontal transformations (left for right) or the null
+transformation, <b>pamflip</b> never keeps more than one row in memory, so the
+memory size is irrelevant and <b>pamflip</b> doesn't use temporary files.
 
+<p>In strict vertical transformations (top for bottom), even when you
+allow <b>pamflip</b> enough memory to keep the entire image in virtual memory,
+it accesses it in a single pass, which does not cause any thrashing; the
+chunks in temporary files thus don't help.
+  
 <p>The real memory is important when you do a column for row type of
 transformation (e.g. <b>-rotate90</b>).  In that case, even if
 <b>pamflip</b> can fit the entire image in virtual memory at once, if
diff --git a/pamtopng.html b/pamtopng.html
index 33b529a7..00223f16 100644
--- a/pamtopng.html
+++ b/pamtopng.html
@@ -3,7 +3,7 @@
 <head><title>Pamtopng User Manual</title></head>
 <body>
 <h1>pamtopng</h1>
-Updated: 12 March 2017
+Updated: 13 March 2019
 <BR>
 <a href="#index">Table Of Contents</a>
 
@@ -25,6 +25,7 @@ pamtopng - convert a Netpbm image to PNG
 [<b>-text=</b><i>file</i>]
 [<b>-ztxt=</b><i>file</i>]
 [<b>-itxt=</b><i>file</i>]
+[<b>-interlace</b>]
 [<I>pnmfile</i>]
 
 <?makeman .SH OPTION USAGE ?>
@@ -250,6 +251,31 @@ The format is either a two character "nl" or an extended code like "en-US".
 in the PNG output.  You can specify the year parameter either as a two or four
 digit value.
 
+<dt><b>-interlace</b>
+<dd>
+This causes the PNG file to be interlaced, in Adam7 format.  The interlaced
+format is one in which the raster data starts with a low-resolution
+representation of the entire image, then continues with additional information
+for the entire image, then even more information, etc.  In Adam7 in
+particular, there are seven such passes of the whole image.  This is useful
+when you are receiving the image over a slow communication line as someone is
+waiting to see it.  The simplest thing to do in that case is wait for the
+entire image to arrive and then display it instantly, but then the user is
+wasting time staring at a blank space until the whole image arrives.  With the
+standard non-interlaced format, the data arrives row-by-row starting at the
+top, so the displayer could display each row of the image as it arrives and
+gradually paint down to the bottom.  But with an interlaced image, the
+displayer can start by showing a low-resolution version of the image, then
+gradually improve the display as more data arrives.
+
+<p>When you specify this option, <b>pamtopng</b> must hold the entire image in
+memory at once, whereas without it, the program holds only one raster row at a
+time.  If you don't have enough memory for that, you might suffer extreme
+slowdowns or failure.  <b>pnmtopng</b> does not have this limitation (it holds
+only one row at a time in memory even when generating an interlaced PNG).
+
+<p>This option was new in Netpbm 10.86 (March 2019).
+  
 <dt><b>-verbose</b>
 <dd>
 This causes the program to display various facts about the conversion.
diff --git a/pnmcrop.html b/pnmcrop.html
index 99714a49..ac430178 100644
--- a/pnmcrop.html
+++ b/pnmcrop.html
@@ -181,6 +181,10 @@ image as the <b>-borderfile</b> image, but the original speckled version as
 the input image.  That way, you crop the borders, but retain the true
 foreground image, speckles and all.
 
+<p>The border file must have the same number of images in it as the input
+file; the background color determination for image N of the input is based on
+the image N of the border file.
+
 <p>This option was new in Netpbm 10.29 (August 2005).
 
 <p>Before Netpbm 10.46 (March 2009), the original image and not the
diff --git a/pnmmargin.html b/pnmmargin.html
index 2860621f..cd815a2d 100644
--- a/pnmmargin.html
+++ b/pnmmargin.html
@@ -55,11 +55,13 @@ over the individual margins and does only black and white margins.
 
 <H2 id="seealso">SEE ALSO</H2>
 
-<A HREF="pamcut.html">pamcut</A>
-<A HREF="pnmcrop.html">pnmcrop</A>
-<A HREF="pnmcat.html">pnmcat</A>
-<A HREF="pnmpad.html">pnmpad</A>
-<A HREF="pnm.html">pnm</A>
+<ul>
+<li><A HREF="pamcut.html">pamcut</A>
+<li><A HREF="pnmcrop.html">pnmcrop</A>
+<li><A HREF="pnmcat.html">pnmcat</A>
+<li><A HREF="pnmpad.html">pnmpad</A>
+<li><A HREF="pnm.html">pnm</A>
+</ul>
 
 <H2 id="author">AUTHOR</H2>
 
diff --git a/pnmtopng.html b/pnmtopng.html
index d808766b..167291aa 100644
--- a/pnmtopng.html
+++ b/pnmtopng.html
@@ -3,7 +3,7 @@
 <HEAD><TITLE>Pnmtopng User Manual</TITLE></HEAD>
 <BODY>
 <H1>pnmtopng</H1>
-Updated: 09 October 2016
+Updated: 13 March 2019
 <BR>
 <A HREF="#index">Table Of Contents</A>
 
@@ -135,18 +135,35 @@ with "unrecognized option," fall back to the old syntax.
 <DL COMPACT>
 <DT><B>-verbose</B>
 <DD>
-     Display the format of the output file.
+This causes <b>pnmtopng</b> to display information about the format of the
+output file.
+
 <DT><B>-downscale</B>
 <DD>
-     Enables scaling of maxvalues of more then 65535 to 16 bit. Since
-     this means loss of image data, <b>pnmtopng</b> does not do it by
-     default.
+This enables <b>pnmtopng</b> to scale maxvalues of more then 65535 to 16
+bits. Since this means loss of image data, <b>pnmtopng</b> does not do it by
+default.
+
 <DT><B>-interlace</B>
 <DD>
-     Creates an interlaced PNG file (Adam7).
+This causes the PNG file to be interlaced, in Adam7 format.  The interlaced
+format is one in which the raster data starts with a low-resolution
+representation of the entire image, then continues with additional information
+for the entire image, then even more information, etc.  In Adam7 in
+particular, there are seven such passes of the whole image.  This is useful
+when you are receiving the image over a slow communication line as someone is
+waiting to see it.  The simplest thing to do in that case is wait for the
+entire image to arrive and then display it instantly, but then the user is
+wasting time staring at a blank space until the whole image arrives.  With the
+standard non-interlaced format, the data arrives row-by-row starting at the
+top, so the displayer could display each row of the image as it arrives and
+gradually paint down to the bottom.  But with an interlaced image, the
+displayer can start by showing a low-resolution version of the image, then
+gradually improve the display as more data arrives.
+     
 <DT><B>-alpha=</b><i>filename</i>
 
-<DD> This specifies the transparency (alpha) channel of the image.  You supply
+<DD>This specifies the transparency (alpha) channel of the image.  You supply
 the transparency channel as a standard PGM transparency mask (see
 the <a href="pgm.html">PGM</a> specification.  <b>pnmtopng</b> does not
 necessarily represents the transparency information as a transparency channel