Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 316 insertions, 0 deletions

diff --git a/upstream/debian-bookworm/man1/pnmtopalm.1 b/upstream/debian-bookworm/man1/pnmtopalm.1
new file mode 100644
index 00000000..b43cfe5f
--- /dev/null
+++ b/upstream/debian-bookworm/man1/pnmtopalm.1
@@ -0,0 +1,316 @@
+\
+.\" 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
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Pnmtopalm User Manual" 1 "25 August 2017" "netpbm documentation"
+
+.SH NAME
+pnmtopalm - convert a PNM image to a Palm Bitmap
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpnmtopalm\fP
+
+[\fB-verbose\fP]
+
+[\fB-depth=\fP\fIN\fP]
+
+[\fB-maxdepth=\fP\fIN\fP]
+
+[\fB-colormap\fP]
+
+[\fB-transparent=\fP\fIcolorspec\fP]
+
+[\fB-density=\fP\fIN\fP]
+
+[\fB-offset\fP]
+
+[\fB-withdummy\fP]
+[\fB-scanline_compression\fP | \fB-rle_compression\fP |
+\fB-packbits_compression\fP]
+
+[\fIpnmfile\fP]
+.PP
+Minimum unique abbreviation of option is acceptable.  You may use
+double hyphens instead of single hyphen to denote options.  You may use
+white space in place of the equals sign to separate an option name
+from its value.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpnmtopalm\fP reads a PNM image as input, from Standard Input or
+\fIpnmfile\fP and produces a Palm Bitmap as output.
+.PP
+Palm Bitmap files are either grayscale files with 1, 2, or 4 bits per
+pixel, or mapped color files with 8 bit per pixel, or a direct color file with
+16 bits per pixel, and \fBpnmtopalm\fP chooses this color depth based on the
+maxval and number of colors in the input, unless you specify a depth (bits per
+pixel) with \fB-depth\fP.  You can also specify a maximum depth
+with \fB-maxdepth\fP to partially constrain \fBpnmtopalm\fP's choice.  Input
+files must have an appropriate number and set of colors for the selected
+output constraints.
+.PP
+This often means that you should run the PNM image through
+\fBpnmquant\fP or \fBpnmremap\fP before you pass it to
+\fBpnmtopalm\fP.  Netpbm comes with several colormap files you can
+use with \fBpnmremap\fP for this purpose.  They are
+\fIpalmgray2.map\fP (4 shades of gray for a depth of 2),
+\fIpalmgray4.map\fP (16 shades of gray for a depth of 4), and
+\fIpalmcolor8.map\fP (232 colors in default Palm colormap).  In a
+standard Netpbm installation, these are in the Netpbm data directory,
+and you can find the Netpbm data directory with a \fBnetpbm-config
+--datadir\fP shell command.
+.PP
+Example:
+
+.nf
+  pnmremap myimage.ppm \e
+           -mapfile=$(netpbm-config --datadir)/palmgray2.map \e
+  | pnmtopalm -depth=2 >myimage.palm
+
+
+.fi
+.PP
+Compressed Palm Bitmap files, at least the ones \fBpnmtopalm\fP knows how
+to create, cannot have more than 8 bits per pixel.  \fBpnmtopalm\fP defaults
+to 8 bits per pixel if you specify a compressed output.  You can specify the
+number of bits per pixel explicitly with \fB-depth\fP.  \fB-maxdepth\fP
+has the same effect as \fB-depth\fP.  If you specify more than 8 bits per
+pixel with either of these, \fBpnmtopalm\fP fails.
+
+.UN version
+.SS Palm Bitmap Version
+.PP
+\fBpnmtopalm\fP generates a Version 0, 1, 2, or 3 Palm Bitmap.
+It generates the oldest (lowest) version it can for the given image and
+the options you specify.
+
+
+.IP \(bu
+If you specify a density (\fB-density\fP option) higher than
+"low," the version is at least 3.
+
+.IP \(bu
+If you specify transparency (\fB-transparent\fP option) or 
+any compression, the version is at least 2.
+
+.IP \(bu
+If you specify a custom colormap (\fB-colormap\fP option), the
+version is at least 1.
+
+.IP \(bu
+If the image has more than one bit per pixel, the version is at least
+1.  The image has more than one bit per pixel if you specify it with
+\fB-depth\fP or if you let it default and the image has more than
+two colors (or shades of gray).
+
+
+.PP
+All releases of Palm OS can read a Version 0 bitmap.  Palm OS 3.0 and
+later can read a Version 1 bitmap.  Palm OS 3.5 and later can read a
+Version 2 bitmap.  To read a Version 3 bitmap, you need Palm OS Garnet
+or a handheld running the High Density Display Feature Set.
+
+.UN options
+.SH OPTIONS
+.PP
+In addition to the options common to all programs based on libnetpbm
+(most notably \fB-quiet\fP, see 
+.UR index.html#commonoptions
+ Common Options
+.UE
+\&), \fBpnmtopalm\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-verbose\fP
+Display the format of the output file.
+
+.TP
+\fB-depth=\fP\fIN\fP
+Produce a file of depth \fIN\fP, where \fIN\fP must be either 1, 2,
+4, 8, or 16.  Because the default Palm 8-bit colormap is not
+grayscale, if the input is a grayscale or monochrome image, the
+output will never be more than 4 bits deep, regardless of the
+specified depth.  Note that 8-bit color works only in PalmOS 3.5 (and
+higher), and 16-bit direct color works only in PalmOS 4.0 (and
+higher).  However, the 16-bit direct color format is also compatible
+with the various PalmOS 3.x versions used in the Handspring Visor, so
+these images may also work in that device.
+
+.TP
+\fB-maxdepth=\fP\fIN\fP
+Produce a file of minimal depth, but in any case less than \fIN\fP
+bits wide.  If you specify 16-bit, the output will always be 16-bit
+direct color.
+
+.TP
+\fB-offset\fP
+Set the \fBnextDepthOffset\fP field in the palm file header to indicate
+the end of the file (and pad the end of the file to 4 bytes, since
+\fBnextDepthOffset\fP can point only to 4 byte boundaries).
+.sp
+A palm image file can contain multiple renditions of the same image,
+with different color depths, so a viewer can choose one appropriate for
+the display.  The \fBnextDepthOffset\fP field tells where in the stream
+the next rendition begins.
+.sp
+\fBpnmtopalm\fP creates a file that contains only one image, but
+you can separately concatenate multiple one-image files to create a
+multi-image file.  If you do that, you'll need to use \fB-offset\fP
+so that the resulting concatenation is a correct stream.
+.sp
+By default (if you don't specify \fB-offset\fP), \fBpnmtopalm\fP
+generates a \fBnextDepthOffset\fP field that says there is no following
+image (and does not add any padding after the image).
+.sp
+Version 3 Palm Bitmaps actually have a \fBnextBitmapOffset\fP
+field instead of the \fBnextDepthOffset\fP.  The foregoing applies to
+whichever is relevant.
+.sp
+The \fB-offset\fP option was new in Netpbm 10.26 (January 2005).
+Before that, \fBpnmtopalm\fP always set the \fBnextDepthOffset\fP
+field to "none."
+.sp
+Before Netpbm 10.27 (March 2005), you cannot use \fB-offset\fP if
+you create a compressed raster (because \fBpnmtopalm\fP isn't smart
+enough to be able to know the size of the image at the time it writes
+the header).  You also cannot use it with 16 bit color depth or with
+the \fB-colormap\fP option, for much the same reason.
+
+.TP
+\fB-withdummy\fP
+This option tells \fBpnmtopalm\fP to put in the stream, after
+the image, a dummy image header to introduce subsequent high density
+images.
+.sp
+This dummy image header is a special sequence specified in Palm Bitmap
+specifications.  It looks to an older Palm Bitmap interpreter like an invalid
+image header, so such an interpreter will stop reading the stream
+there.  But a new Palm Bitmap interpreter recognizes it for what it is (just
+something to choke an old interpreter) and skips over it.  Presumably,
+you will add to the stream after this high density images which would
+confuse an older interpreter.
+.sp
+If you specify \fB-withdummy\fP, you must also specify \fB-offset\fP,
+since it doesn't make any sense otherwise.
+.sp
+\fB-withdummy\fP was new in Netpbm 10.27 (March 2005).
+
+.TP
+\fB-colormap\fP
+Build a custom colormap and include it in the output file.  This is
+not recommended by Palm, for efficiency reasons.  Otherwise, \fBpnmtopalm\fP
+uses the default Palm colormap for color output.
+
+.TP
+\fB-transparent=\fP\fIcolorspec\fP
+Marks \fIone\fP particular color as fully transparent.
+.sp
+\fIcolorspec\fP is as described for the
+.UR libnetpbm_image.html#colorname
+argument of the \fBpnm_parsecolor()\fP library routine
+.UE
+\&.
+.sp
+Transparency works only on Palm OS 3.5 and higher.
+
+.TP
+\fB-scanline_compression\fP
+Specifies that the output Palm bitmap will use the Palm scanline
+compression scheme.  Scanline compression works only in Palm OS 2.0
+and higher.
+
+.TP
+\fB-rle_compression\fP
+Specifies that the output Palm bitmap will use the Palm RLE
+compression scheme.  RLE compression works only with Palm OS 3.5 and
+higher.
+
+.TP
+\fB-packbits_compression\fP
+Specifies that the output Palm bitmap will use the Palm packbits
+compression scheme.  Packbits compression works only with Palm OS 4.0 and
+higher.
+.sp
+This option was new in Netpbm 10.27 (March 2005).
+
+.TP
+\fB-density\fP=\fIN\fP
+This specifies the Palm Bitmap density.  The density is a number that
+is proportional to the resolution the image should have when displayed.
+The proportionality factor is up to whatever is doing the displaying,
+but it's helpful to think of these numbers as being pixels per inch.
+The allowable values are:
+
+
+.IP \(bu
+72
+.IP \(bu
+108
+.IP \(bu
+144
+.IP \(bu
+216
+.IP \(bu
+288
+
+.sp
+This option was new in Netpbm 10.27 (March 2005).  Earlier Netpbm
+could not generate Version 3 Palm Bitmaps, so there was no such thing
+as density.
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "palmtopnm" (1)\c
+\&,
+.BR "pdbimgtopam" (1)\c
+\&,
+.BR "pnmquant" (1)\c
+\&,
+.BR "pnmremap" (1)\c
+\&,
+.BR "pnm" (1)\c
+\&
+
+.UN notes
+.SH NOTES
+.PP
+Palm Bitmaps may contains multiple renditions of the same bitmap,
+in different depths.  To construct an N-multiple-rendition Palm Bitmap
+with \fBpnmtopalm\fP, first construct renditions 1 through N-1 using
+the \fB-offset\fP option, then construct the Nth image without the
+\fB-offset\fP option.  Then concatenate the individual renditions
+together in a single file using \fBcat\fP.
+.PP
+If you will include both high density and low density renditions,
+put the high density images last and when you create the last of the
+low density images, use the \fB-withdummy\fP option.
+.PP
+If you specify the Palm packbits compression scheme for a 16-bit direct
+color bitmap, this program generates an invalid bitmap.
+
+
+.UN authors
+.SH AUTHORS
+
+This program was originally written as ppmtoTbmp.c, by Ian Goldberg
+and George Caswell.  It was completely re-written by Bill Janssen to
+add color, compression, and transparency function.
+Copyright 1995-2001 by Ian Goldberg, George Caswell, and Bill Janssen.
+.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/pnmtopalm.html
+.PP
\ No newline at end of file