Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 327 insertions, 0 deletions

diff --git a/upstream/debian-bookworm/man1/pngtopam.1 b/upstream/debian-bookworm/man1/pngtopam.1
new file mode 100644
index 00000000..a5d89bf9
--- /dev/null
+++ b/upstream/debian-bookworm/man1/pngtopam.1
@@ -0,0 +1,327 @@
+\
+.\" 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 "Pngtopam User Manual" 1 "22 July 2008" "netpbm documentation"
+
+.SH NAME
+pngtopam - convert a PNG image into a Netpbm image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpngtopam\fP
+[\fB-verbose\fP]
+[\fB-alphapam\fP | \fB-alpha\fP | \fB-mix\fP]
+[\fB-background\fP=\fIcolor\fP]
+[\fB-gamma\fP=\fIvalue\fP]
+[\fB-text\fP=\fIfilename\fP]
+[\fB-time\fP]
+[\fB-byrow\fP]
+[\fIpngfile\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
+\fBpngtopam\fP reads a PNG image (Portable Network Graphics) as
+input and produces a Netpbm image as output.  The type of the output file
+depends on the input file - if it's black & white, \fBpngtopam\fP
+creates a PBM file.  If it's grayscale, \fBpngtopam\fP creates a PGM
+file.  Otherwise, it creates a PPM file.  Except that with the
+\fB-alphapam\fP option, it always creates a PAM file.  That file has
+tuple type GRAYSCALE_ALPHA or RGB_ALPHA depending on whether the input
+has color or not.
+.PP
+To convert in the other direction, use \fBpamtopng\fP or
+\fBpnmtopng\fP.  The former is the more modern of the two and can recognize
+transparency information in a PAM file, as you might generate with \fBpngtopam
+-alphapam\fP.  It has existed only since June 2015.  The latter has more
+features, but probably not ones that matter in the modern world.
+
+
+.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
+\&), \fBpngtopam\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-verbose\fP
+Display various information about the input PNG image and the
+conversion process.
+.sp
+If you want even more information about the PNG image, use
+\fBpngcheck\fP (not part of Netpbm).
+     
+.TP
+\fB-alphapam\fP
+Produce a single output image containing the main image (foreground)
+and the transparency channel or transparency mask.  This image is in the PAM
+format with tuple type of either GRAYSCALE_ALPHA (which has a depth of
+2 channels) or RGB_ALPHA (which has a depth of 4 channels).
+.sp
+You can specify only one of \fB-alphapam\fP, \fB-alpha\fP, and
+\fB-mix\fP.  With none of them, \fBpngtopam\fP produces an image of
+the foreground of the input image and discards transparency information.
+.sp
+This option was new in Netpbm 10.44 (September 2008).
+
+.TP
+\fB-alpha\fP
+Output the transparency channel or transparency mask of the image. The
+result is either a PBM file or a PGM file, depending on whether
+different levels of transparency appear.
+.sp
+\fBpngtopam\fP discards the main image (the foreground).
+.sp
+You can specify only one of \fB-alphapam\fP, \fB-alpha\fP, and
+\fB-mix\fP.  With none of them, \fBpngtopam\fP produces an image of
+the foreground of the input image and discards transparency information.
+
+.TP
+\fB-mix\fP
+Compose the image with the transparency or transparency mask against a
+background.  The background color is determined by the bKGD chunk in
+the PNG, except that you can override it with \fB-background\fP.
+If the PNG has no bKGD chunk and you don't specify \fB-background\fP,
+the background color is white.
+.sp
+You can specify only one of \fB-alphapam\fP, \fB-alpha\fP, and
+\fB-mix\fP.  With none of them, \fBpngtopam\fP produces an image of
+the foreground of the input image and discards transparency information.
+
+.TP
+\fB-background=\fP\fIcolor\fP
+This option specifies the background color with which to mix the image
+when you specify \fB-mix\fP.
+.sp
+\fIcolor\fP is as described for the 
+.UR libnetpbm_image.html#colorname
+argument of the \fBpnm_parsecolor()\fP library routine
+.UE
+\&.
+.sp
+Examples:
+
+
+.IP \(bu
+\f(CW-background=rgb:01/ff/80\fP
+.IP \(bu
+\f(CW-background=rgbi:1/255/128\fP
+
+.sp
+If you don't specify \fB-background\fP, the background color is what
+is specified in the PNG image, and if the PNG doesn't specify anything,
+white.
+.sp
+You cannot specify \fB-background\fP unless you also specify
+\fB-mix\fP.  Before Netpbm 10.27 (March 2005), you could specify
+\fB-background\fP without \fB-mix\fP and it was just ignored.  (This
+caused a usability problem).
+
+
+.TP
+\fB-gamma=\fP\fIvalue\fP
+This option causes \fBpngtopam\fP to respect the image gamma information
+in the PNG file (from the gAMA chunk).  Probably by historical accident,
+\fBpngtopam\fP ignores that information by default, assuming the image uses
+the same gamma transformation as a Netpbm image, so the output image has
+different colors than the PNG file actually represents if the PNG doesn't
+actually do that.  (However, it is rare for a PNG file to use a gamma
+transformation different from what the Netpbm formats specify, or if it does,
+to specify with a gAMA chuck what that is).
+.sp
+But when you \fIdo\fP specify \fB-gamma\fP, you get a rather strange
+additional function, probably a historical mistake:
+\fBpngtopam\fP incorporates the specified screen gamma value into the output
+pixels, so that the samples in the Netpbm output deviate from the Netpbm
+format specifications and are appropriate raw intensity values to send to the
+display.  This function essentially just exercises the ability of the PNG
+library to make gamma corrections to the pixels as it reads them from the PNG
+file to produce values appropriate for sending to a certain display in certain
+viewing conditions.  It's a strange function because it has nothing to do with
+PNG and because in Netpbm, the normal way to make gamma corrections
+appropriate for sending to a ceratin display in certain viewing conditions is
+with the program \fBpngtopam\fP, applied to the normal output of
+\fBpngtopam\fP.
+.sp
+If you specify \fB-gamma\fP, but the PNG image does not specify what gamma
+transformation it uses (there is no gAMA chunk), \fBpngtopam\fP assumes a
+simple power transformation with an image gamma of 1.0.  That is probably not
+not the actual image gamma; it is much more likely to be .45.
+.sp
+Because the gammas of uncompensated monitors are around 2.6, which results 
+in an image-gamma of 0.45, some typical situations are: 
+when the image-gamma is 0.45 (use -verbose to check) and the picture is too 
+light, your system is gamma-corrected, so convert with "-gamma 1.0". 
+When no gAMA chunk is present or the image-gamma is 1.0, use 2.2 to make the 
+picture lighter and 0.45 to make the picture darker.
+.sp
+One oddity to be aware of when using \fB-gamma\fP on an image with
+transparency: The PNG image specifies that a certain color is
+transparent, i.e. every pixel in the image of that color is
+transparent.  But \fBpngtopam\fP interprets this as applying to the
+gamma-corrected space, and there may be less precision in that space
+than in the original, which means multiple uncorrected colors map to
+the same corrected color.  So imagine that the image contains 3 shades
+of white (gray) and specifies that one of them is transparent.  After gamma
+correction, those three shades are indistinguishable, so
+\fBpngtopam\fP considers pixels of all three shades to be transparent.
+
+
+.TP
+\fB-text=\fP\fIfile\fP
+Writes the tEXt and zTXt chunks to a file, in a format as
+described in the \fBpnmtopng\fP user manual.  These chunks contain
+text comments or annotations.
+
+.TP
+\fB-time\fP
+Prints the tIME chunk to stderr.
+
+.TP
+\fB-byrow\fP
+This option can make \fBpngtopam\fP run faster or in environments
+where it would otherwise fail.
+.sp
+\fBpngtopam\fP has two ways to do the conversion from PNG to PAM, using
+respectively two facilities of the PNG library:
+
+
+
+.TP
+Whole Image
+Decode the entire image into memory at once, using
+\fBpng_read_image()\fP, then convert to PAM and output row by row.
+   
+.TP
+Row By Row
+Read, convert, and output one row at a time using \fBpng_read_row()\fP.
+
+
+.sp
+Whole Image is generally preferable because the PNG library does more of
+the work, which means it understands more of the PNG format possibilities now
+and in the future.  Also, if the PNG is interlaced, \fBpngtopam\fP does
+not know how to assemble the rows in the right order.
+.sp
+Row By Row uses far less memory, which means with large images, it
+can run in environments where Whole Image cannot and may also run
+faster.  And because Netpbm code does more of the work, it's possible
+that it can be more flexible or at least give better diagnostic
+information if there's something wrong with the PNG.
+.sp
+The Netpbm native code may do something correctly that the PNG library does
+incorrectly, or vice versa.
+.sp
+In Netpbm, we stress function over performance, so by default
+\fBpngtopam\fP uses Whole Image.  You can select Row By Row with
+\fB-byrow\fP if you want the speed or resource requirement improvement.
+.sp
+\fB-byrow\fP was new in Netpbm 10.54 (March 2011).
+
+
+.TP
+\fB-orientraw\fP
+A TIFF stream contains raster data which can be arranged in the
+stream various ways.  Most commonly, it is arranged by rows, with the
+top row first, and the pixels left to right within each row, but many
+other orientations are possible.
+.sp
+The common orientation is the same on the Netpbm formats use, so
+\fBtifftopnm\fP can do its jobs quite efficiently when the TIFF raster
+is oriented that way.
+.sp
+But if the TIFF raster is oriented any other way, it can take a
+considerable amount of processing for \fBtifftopnm\fP to convert it to
+Netpbm format.
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "pamtopng" (1)\c
+\&,
+.BR "pnmtopng" (1)\c
+\&,
+.BR "pngtopnm" (1)\c
+\&,
+\fBptot\fP,
+.BR "pnmgamma" (1)\c
+\&, 
+.BR "pnm" (1)\c
+\&
+.PP
+For information on the PNG format, see 
+.UR http://schaik.com/png
+http://schaik.com/png
+.UE
+\&.
+
+.UN note
+.SH NOTE
+.PP
+A PNG image contains a lot of information that can't be represented in 
+Netpbm formats.  Therefore, you lose information when you convert to 
+another format with "pngtopam | pnmtoxxx".  If there is a specialized 
+converter that converts directly to the other format, e.g. \fBptot\fP
+to convert from PNG to TIFF, you'll get better results using that.
+
+.UN limitations
+.SH LIMITATIONS
+.PP
+There could be an option to include PNG comment chunks in the output
+image as PNM comments instead of putting them in a separate file.
+.PP
+The program could be much faster, with a bit of code optimizing.
+As with any Netpbm program, speed always takes a back seat to quick
+present and future development.
+
+.UN history
+.SH HISTORY
+.PP
+\fBpngtopam\fP was new in Netpbm 10.44, as a replacement for
+\fBpngtopnm\fP.  The main improvement over \fBpngtopnm\fP was that
+it could generate a PAM image with a transparency channel, whereas
+with \fBpngtopnm\fP, you would have to extract the transparency
+channel as a separate file, in a separate run.
+.PP
+\fBpngtopnm\fP was new in Netpbm 8.1 (March 2000), the first big
+change to the package in Netpbm's renaissance.  It and \fBpnmtopng\fP
+were simply copied from the
+.BR "
+\fBpnmtopng\fP package" (1)\c
+\& by Greg Roelofs.  Those were based on
+simpler reference applications by Alexander Lehmann
+<alex@hal.rhein-main.de> and Willem van Schaik
+<willem@schaik.com> and distributed with their PNG library.
+.PP
+Nearly all of the code has changed since it was copied from the
+\fBpnmtopng\fP package, most of it just to improve maintainability.
+
+
+.UN authors
+.SH AUTHORS
+
+Copyright (C) 1995-1997 by Alexander Lehmann and Willem van Schaik.
+.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/pngtopam.html
+.PP
\ No newline at end of file