Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 560 insertions, 0 deletions

diff --git a/upstream/fedora-rawhide/man1/pnmtojpeg.1 b/upstream/fedora-rawhide/man1/pnmtojpeg.1
new file mode 100644
index 00000000..b302b44b
--- /dev/null
+++ b/upstream/fedora-rawhide/man1/pnmtojpeg.1
@@ -0,0 +1,560 @@
+\
+.\" 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 "Pnmtojpeg User Manual" 0 "23 April 2007" "netpbm documentation"
+
+.SH NAME
+pnmtojpeg - convert PNM image to a JFIF ("JPEG") image
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpnmtojpeg\fP
+[\fB-exif=\fP\fIfilespec\fP]
+[\fB-quality=\fP\fIn\fP]
+[{\fB-grayscale\fP|\fB-greyscale\fP}]
+[\fB-density=\fP\fIn\fP\fBx\fP\fIn\fP[\fBdpi\fP,\fBdpcm\fP]]
+[\fB-optimize\fP|\fB-optimise\fP]
+[\fB-rgb\fP]
+[\fB-progressive\fP]
+[\fB-comment=\fP\fItext\fP]
+[\fB-dct=\fP{\fBint\fP|\fBfast\fP|\fBfloat\fP}]
+[\fB-arithmetic\fP]
+[\fB-restart=\fP\fIn\fP]
+[\fB-smooth=\fP\fIn\fP]
+[\fB-maxmemory=\fP\fIn\fP]
+[\fB-verbose\fP]
+[\fB-baseline\fP]
+[\fB-qtables=\fP\fIfilespec\fP]
+[\fB-qslots=n[,...]\fP]
+[\fB-sample=\fP\fIH\fP\fBx\fP\fIV\fP[,...]]
+[\fB-scans=\fP\fIfilespec\fP]
+[\fB-tracelevel=\fP\fIN\fP]
+
+\fIfilename\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
+\fBpnmtojpeg\fP converts the named PBM, PGM, or PPM image file, or
+the standard input if no file is named, to a JFIF file on the standard
+output.
+.PP
+\fBpnmtojpeg\fP uses the Independent JPEG Group's JPEG library to
+create the output file.  See \fB
+.UR http://www.ijg.org
+http://www.ijg.org
+.UE
+\& \fP for information
+on the library.
+.PP
+"JFIF" is the correct name for the image format commonly
+known as "JPEG." Strictly speaking, JPEG is a method of
+compression.  The image format using JPEG compression that is by far
+the most common is JFIF.  There is also a subformat of TIFF that uses
+JPEG compression.
+.PP
+EXIF is an image format that is a subformat of JFIF (to wit, a JFIF
+file that contains an EXIF header as an APP1 marker).
+\fBpnmtojpeg\fP creates an EXIF image when you specify the
+\fB-exif\fP option.
+
+.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
+\&), \fBpnmtojpeg\fP recognizes the following
+command line options:
+
+.UN basicopts
+.SS Basic Options
+
+
+.TP
+\fB-exif=\fP\fIfilespec\fP
+This option specifies that the output image is to be EXIF (a subformat
+of JFIF), i.e. it will have an EXIF header as a JFIF APP1 marker.
+The contents of that marker are the contents of the specified file.
+The special value \fB-\fP 
+means to read the EXIF header contents from standard input.  It is
+invalid to specify standard input for both the EXIF header and the
+input image.
+.sp
+The EXIF file starts with a two byte field which is the length of
+the file, including the length field, in pure binary, most significant
+byte first.  The special value of zero for the length field means there
+is to be no EXIF header, i.e. the same as no \fB-exif\fP
+option.  This is useful for when you convert a file from JFIF to PNM
+using \fBjpegtopnm\fP,
+then transform it, then convert it back to JFIF with
+\fBpnmtojpeg\fP, and you don't know whether or not it includes an EXIF header.
+\fBjpegtopnm\fP
+creates an EXIF file containing nothing but two bytes of zero when
+the input JFIF file has no EXIF header.  Thus, you can transfer
+any EXIF header from the input JFIF to the output JFIF without
+worrying about whether an EXIF header actually exists.
+.sp
+The contents of the EXIF file after the length field are the exact
+byte for byte contents of the APP1 marker, not counting the length
+field, that constitutes the EXIF header.
+
+.TP
+\fB-quality=\fP\fIn\fP
+Scale quantization tables to adjust image quality.  \fIn\fP is 0
+(worst) to 100 (best); default is 75.  Below about 25 can produce images
+some interpreters won't be able to interpret.  See below for more info.
+
+.TP
+\fB-grayscale\fP
+.TP
+\fB-greyscale\fP
+.TP
+\fB-rgb\fP
+These options determine the color space used in the JFIF output.
+\fB-grayscale\fP (or \fB-greyscale\fP) means to create a gray scale
+JFIF, converting from color PPM input if necessary.  \fB-rgb\fP means to
+create an RGB JFIF, and the program fails if the input is not PPM.
+.sp
+If you specify neither, The output file is in YCbCr format if the
+input is PPM, and grayscale format if the input is PBM or PGM.
+.sp
+YCbCr format (a color is represented by an intensity value and two
+chrominance values) usually compresses much better than RGB (a color
+is represented by one red, one green, and one blue value).  RGB is
+rare.  But you may be able to convert between JFIF and PPM faster with
+RGB, since it's the same color space PPM uses.
+.sp
+The \fBtestimg.ppm\fP file that comes with Netpbm is 2.3 times
+larger with the \fB-rgb\fP option than with the YCbCr default, and in
+one experiment \fBpnmtojpeg\fP took 16% more CPU time to convert it.
+The extra CPU time probably indicates that processing of all the extra
+compressed data consumed all the CPU time saved by not having to
+convert the RGB inputs to YCbCr.
+.sp
+Grayscale format takes up a lot less space and takes less time to create
+and process than the color formats, even if the image contains nothing
+but black, white, and gray.
+.sp
+The \fB-rgb\fP option was added in Netpbm 10.11 in October 2002.
+
+.TP
+\fB-density=\fP\fIdensity\fP
+This option determines the density (aka resolution) information
+recorded in the JFIF output image.  It does not affect the raster in
+any way; it just tells whoever reads the JFIF how to interpret the
+raster.
+.sp
+The density value takes the form \fIx\fP\fBx\fP\fIy\fP followed
+by an optional unit specifier of \fBdpi\fP or \fBdpcm\fP.  Examples:
+\fB1x1\fP, \fB3x2\fP, \fB300x300dpi\fP, \fB100x200dpcm\fP.  The
+first number is the horizontal density; the 2nd number is the vertical
+density.  Each may be any integer from 1 to 65535.  The unit specifier
+is \fBdpi\fP for dots per inch or \fBdpcm\fP for dots per
+centimeter.  If you don't specify the units, the density information
+goes into the JFIF explicitly stating "density unspecified" (also
+interpreted as "unknown").  This may seem pointless, but note that
+even without specifying the units, the density numbers tell the aspect
+ratio of the pixels.  E.g. \fB1x1\fP tells you the pixels are square.
+\fB3x2\fP tells you the pixels are vertical rectangles.
+.sp
+Note that if you specify different horizontal and vertical
+densities, the resulting JFIF image is \fInot\fP a true
+representation of the input PNM image, because \fBpnmtojpeg\fP
+converts the raster pixel-for-pixel and the pixels of a PNM image are
+defined to be square.  Thus, if you start with a square PNM image and
+specify \fB-density=3x2\fP, the resulting JFIF image is a horizontally
+squashed version of the original.  However, it is common to use an
+input image which is a slight variation on PNM rather than true PNM
+such that the pixels are not square.  In that case, the appropriate
+-density option yields a faithful reproduction of the input pseudo-PNM
+image.
+.sp
+The default is 1x1 in unspecified units.
+.sp
+Before Netpbm 10.15 (April 2003), this option did not exist and the
+\fBpnmtojpeg\fP always created a JFIF with a density of 1x1 in
+unspecified units.
+
+.TP
+\fB-optimize\fP
+ Perform optimization of entropy encoding parameters.  Without
+this, \fBpnmtojpeg\fP uses default encoding parameters.
+\fB-optimize\fP usually makes the JFIF file a little smaller, but
+\fBpnmtojpeg\fP runs somewhat slower and needs much more memory.
+Image quality and speed of decompression are unaffected by
+\fB-optimize\fP.
+
+.TP
+\fB-progressive\fP
+Create a progressive JPEG file (see below).
+.TP
+\fB-comment=\fP\fItext\fP
+Include a comment marker in the JFIF output, with comment text 
+\fItext\fP.
+
+Without this option, there are no comment markers in the output.
+
+
+.PP
+The \fB-quality\fP option lets you trade off compressed file size
+against quality of the reconstructed image: the higher the quality
+setting, the larger the JFIF file, and the closer the output image
+will be to the original input.  Normally you want to use the lowest
+quality setting (smallest file) that decompresses into something
+visually indistinguishable from the original image.  For this purpose
+the quality setting should be between 50 and 95 for reasonable
+results; the default of 75 is often about right.  If you see defects
+at \fB-quality=75\fP, then go up 5 or 10 counts at a time until you
+are happy with the output image.  (The optimal setting will vary from
+one image to another.)
+.PP
+\fB-quality=100\fP generates a quantization table of all 1's,
+minimizing loss in the quantization step (but there is still
+information loss in subsampling, as well as roundoff error).  This
+setting is of interest mainly for experimental purposes.  Quality
+values above about 95 are \fInot\fP recommended for normal use; the
+compressed file size goes up dramatically for hardly any gain in
+output image quality.
+.PP
+In the other direction, quality values below 50 will produce very
+small files of low image quality.  Settings around 5 to 10 might be
+useful in preparing an index of a large image library, for example.
+Try \fB-quality=2\fP (or so) for some amusing Cubist effects.  (Note:
+quality values below about 25 generate 2-byte quantization tables,
+which are considered optional in the JFIF standard.  \fBpnmtojpeg\fP
+emits a warning message when you give such a quality value, because
+some other JFIF programs may be unable to decode the resulting file.
+Use \fB-baseline\fP if you need to ensure compatibility at low
+quality values.)
+.PP
+The \fB-progressive\fP option creates a "progressive
+JPEG" file.  In this type of JFIF file, the data is stored in
+multiple scans of increasing quality.  If the file is being
+transmitted over a slow communications link, the decoder can use the
+first scan to display a low-quality image very quickly, and can then
+improve the display with each subsequent scan.  The final image is
+exactly equivalent to a standard JFIF file of the same quality
+setting, and the total file size is about the same -- often a little
+smaller.
+.PP
+\fBCaution:\fP progressive JPEG is not yet widely
+implemented, so many decoders will be unable to view a progressive
+JPEG file at all.
+.PP
+If you're trying to control the quality/file size tradeoff, you
+might consider the JPEG2000 format instead.  See
+.BR "pamtojpeg2k" (1)\c
+\&.
+
+.UN advancedopts
+.SS Advanced options
+
+
+
+.TP
+\fB-dct=int\fP
+Use integer DCT method (default).
+
+.TP
+\fB-dct=fast\fP
+Use fast integer DCT (less accurate).
+
+.TP
+\fB-dct=float\fP
+Use floating-point DCT method.  The float method is very slightly
+more accurate than the int method, but is much slower unless your
+machine has very fast floating-point hardware.  Also note that results
+of the floating-point method may vary slightly across machines, while
+the integer methods should give the same results everywhere.  The fast
+integer method is much less accurate than the other two.
+
+.TP
+\fB-arithmetic\fP
+Use arithmetic coding.  Default is Huffman encoding.  Arithmetic coding
+tends to get you a smaller result.
+.sp
+You may need patent licenses to use this option.  According to 
+.UR http://www.faqs.org/faqs/jpeg-faq
+the JPEG FAQ
+.UE
+\&,
+This method is covered by patents owned by IBM, AT&T, and Mitsubishi.
+.sp
+The author of the FAQ recommends against using arithmetic coding (and
+therefore this option) because the space savings is not great enough to
+justify the legal hassles.
+.sp
+Most JPEG libraries, including any distributed by the Independent
+JPEG Group since about 1998 are not capable of arithmetic encoding.
+\fBpnmtojpeg\fP uses a JPEG library (either bound to it when the
+\fBpnmtojpeg\fP executable was built or accessed on your system at
+run time) to do the JPEG encoding.  If \fBpnmtojpeg\fP terminates
+with the message, "Sorry, there are legal restrictions on
+arithmetic coding" or "Sorry, arithmetic coding not
+supported," this is the problem.
+     
+.TP
+\fB-restart=\fP\fIn\fP
+Emit a JPEG restart marker every \fIn\fP MCU rows, or every \fIn\fP
+MCU blocks if you append \fBB\fP to the number.  \fB-restart 0\fP
+(the default) means no restart markers.
+
+.TP
+\fB-smooth=\fP\fIn\fP
+Smooth the input image to eliminate dithering noise.  \fIn\fP,
+ranging from 1 to 100, indicates the strength of smoothing.  0 (the
+default) means no smoothing.
+
+.TP
+\fB-maxmemory=\fP\fIn\fP
+Set a limit for amount of memory to use in processing large images.  Value is
+in thousands of bytes, or millions of bytes if you append
+\fBM\fP to the number.  For example, \fB-max=4m\fP
+selects 4,000,000 bytes.  If \fBpnmtojpeg\fP
+needs more space, it will use temporary files.
+
+.TP
+\fB-verbose\fP
+Print to the Standard Error file messages about the conversion process.
+This can be helpful in debugging problems.
+
+.PP
+The \fB-restart\fP option tells \fBpnmtojpeg \fP to insert extra
+markers that allow a JPEG decoder to resynchronize after a
+transmission error.  Without restart markers, any damage to a
+compressed file will usually ruin the image from the point of the
+error to the end of the image; with restart markers, the damage is
+usually confined to the portion of the image up to the next restart
+marker.  Of course, the restart markers occupy extra space.  We
+recommend \fB-restart=1\fP for images that will be transmitted
+across unreliable networks such as Usenet.
+.PP
+The \fB-smooth\fP option filters the input to eliminate
+fine-scale noise.  This is often useful when converting dithered
+images to JFIF: a moderate smoothing factor of 10 to 50 gets rid of
+dithering patterns in the input file, resulting in a smaller JFIF file
+and a better-looking image.  Too large a smoothing factor will visibly
+blur the image, however.
+
+.UN wizardopts
+.SS Wizard Options
+
+
+.TP
+\fB-baseline\fP
+Force baseline-compatible quantization tables to be generated.
+This clamps quantization values to 8 bits even at low quality
+settings.  (This switch is poorly named, since it does not ensure that
+the output is actually baseline JPEG.  For example, you can use
+\fB-baseline\fP and \fB-progressive\fP together.)
+
+.TP
+\fB-qtables=\fP\fIfilespec\fP
+Use the quantization tables given in the specified text file.
+
+.TP
+\fB-qslots=n[,...]\fP
+Select which quantization table to use for each color component.
+
+.TP
+\fB-sample=\fP\fIH\fP\fBx\fP\fIV\fP[,...]
+Set JPEG sampling factors for each color component.
+
+.TP
+\fB-scans=\fP\fIfilespec\fP
+Use the scan script given in the specified text file.  See below
+for information on scan scripts.
+
+.TP
+\fB-tracelevel=\fP\fIN\fP
+This sets the level of debug tracing the program outputs as it runs.
+0 means none, and is the default.  This level primarily controls tracing
+of the JPEG library, and you can get some pretty interesting information
+about the compression process.
+
+
+.PP
+The "wizard" options are intended for experimentation
+with JPEG.  If you don't know what you are doing, \fBdon't use
+them\fP.  These switches are documented further in the file
+wizard.doc that comes with the Independent JPEG Group's JPEG library.
+
+.UN examples
+.SH EXAMPLES
+.PP
+This example compresses the PPM file foo.ppm with a quality factor
+of 60 and saves the output as foo.jpg:
+
+.nf
+    \fBpnmtojpeg -quality=60 foo.ppm > foo.jpg\fP
+
+.fi
+.PP
+Here's a more typical example.  It converts from BMP to JFIF:
+
+.nf
+    \fBcat foo.bmp | bmptoppm | pnmtojpeg > foo.jpg\fP
+
+.fi
+
+.UN loss
+.SH JPEG LOSS
+.PP
+When you compress with JPEG, you lose information -- i.e. the resulting
+image has somewhat lower quality than the original.  This is a characteristic
+of JPEG itself, not any particular program.  So if you do the usual 
+Netpbm thing and convert from JFIF to PNM, manipulate, then convert back
+to JFIF, you will lose quality.  The more you do it, the more you lose.
+Drawings (charts, cartoons, line drawings, and such with few colors
+and sharp edges) suffer the most.
+.PP
+To avoid this, you can use a compressed image format other than
+JPEG.  PNG and JPEG2000 are good choices, and Netpbm contains converters
+for those.
+.PP
+If you need to use JFIF on a drawing, you should experiment with
+\fBpnmtojpeg\fP's \fB-quality\fP and \fB-smooth\fP options to get a
+satisfactory conversion.  \fB-smooth 10\fP or so is often helpful.
+.PP
+Because of the loss, you should do all the manipulation you have to
+do on the image in some other format and convert to JFIF as the last
+step.  And if you can keep a copy in the original format, so much the
+better.
+
+The \fB-optimize\fP option to \fBpnmtojpeg\fP is worth using when
+you are making a "final" version for posting or archiving.
+It's also a win when you are using low quality settings to make very
+small JFIF files; the percentage improvement is often a lot more than
+it is on larger files.  (At present, \fB-optimize\fP mode is
+automatically in effect when you generate a progressive JPEG file).
+.PP
+You can do flipping and rotating transformations losslessly with
+the program \fBjpegtran\fP, which is packaged with the Independent
+Jpeg Group's JPEG library.  \fBjpegtran\fP exercises its intimate
+knowledge of the way JPEG works to do the transformation without ever
+actually decompressing the image.
+
+.UN otherprog
+.SH OTHER PROGRAMS
+.PP
+Another program, \fBcjpeg\fP, is similar.  \fBcjpeg\fP is
+maintained by the Independent JPEG Group and packaged with the JPEG
+library which \fBpnmtojpeg\fP uses for all its JPEG work.  Because of
+that, you may expect it to exploit more current JPEG features.  Also,
+since you have to have the library to run \fBpnmtojpeg\fP, but not
+vice versa, \fBcjpeg\fP may be more commonly available.
+.PP
+On the other hand, \fBcjpeg\fP does not use the NetPBM libraries
+to process its input, as all the NetPBM tools such as \fBpnmtojpeg\fP
+do.  This means it is less likely to be consistent with all the other
+programs that deal with the NetPBM formats.  Also, the command syntax
+of \fBpnmtojpeg\fP is consistent with that of the other Netpbm tools,
+unlike \fBcjpeg\fP.
+
+.UN scanscripts
+.SH SCAN SCRIPTS
+.PP
+Use the \fB-scan\fP option to specify a scan script.  Or use the
+\fB-progressive\fP option to specify a particular built-in scan
+script.
+.PP
+Just what a scan script is, and the basic format of the scan script
+file, is covered in the \fBwizard.doc\fP file that comes with the
+Independent JPEG Group's JPEG library.  Scan scripts are same for
+\fBpnmtojpeg\fP as the are for \fBcjpeg\fP.
+.PP
+This section contains additional information that isn't, but
+probably should be, in that document.
+.PP
+First, there are many restrictions on what is a valid scan script.
+The JPEG library, and thus \fBpnmtojpeg\fP, checks thoroughly for any
+lack of compliance with these restrictions, but does little to tell
+you how the script fails to comply.  The messages are very general and
+sometimes untrue.
+.PP
+To start with, the entries for the DC coefficient must come before any
+entries for the AC coefficients.  The DC coefficient is Coefficient 0;
+all the other coefficients are AC coefficients.  So in an entry for
+the DC coefficient, the two numbers after the colon must be 0 and 0.
+In an entry for AC coefficients, the first number after the colon must
+not be 0.
+.PP
+In a DC entry, the color components must be in increasing order.
+E.g. "0,2,1" before the colon is wrong.  So is "0,0,0".
+.PP
+In an entry for an AC coefficient, you must specify only one color
+component.  I.e. there can be only one number before the colon.
+.PP
+In the first entry for a particular coefficient for a particular color
+component, the "Ah" value must be zero, but the Al value can be any
+valid bit number.  In subsequent entries, Ah must be the Al value from
+the previous entry (for that coefficient for that color component),
+and the Al value must be one less than the Ah value.
+.PP
+The script must ultimately specify at least some of the DC coefficient
+for every color component.  Otherwise, you get the error message
+"Script does not transmit all the data."  You need not specify all of
+the bits of the DC coefficient, or any of the AC coefficients.
+.PP
+There is a standard option in building the JPEG library to omit scan
+script capability.  If for some reason your library was built with
+this option, you get the message "Requested feature was omitted at
+compile time."
+
+.UN environment
+.SH ENVIRONMENT
+
+
+.TP
+\fBJPEGMEM\fP
+If this environment variable is set, its value is the default
+memory limit.  The value is specified as described for the
+\fB-maxmemory\fP option.  An explicit \fB-maxmemory \fP option
+overrides any \fBJPEGMEM\fP.
+
+
+
+.UN seealso
+.SH SEE ALSO
+.BR "jpegtopnm" (1)\c
+\&,
+.BR "pnm" (1)\c
+\&,
+\fBcjpeg\fP man page,
+\fBdjpeg\fP man page,
+\fBjpegtran\fP man page,
+\fBrdjpgcom\fP man page,
+\fBwrjpgcom\fP man page
+.PP
+Wallace, Gregory K.  "The JPEG Still Picture Compression
+Standard", Communications of the ACM, April 1991 (vol. 34,
+no. 4), pp. 30-44.
+
+
+.UN author
+.SH AUTHOR
+
+\fBpnmtojpeg\fP and this manual were derived in large part from
+\fBcjpeg\fP, by the Independent JPEG Group.  The program is otherwise
+by Bryan Henderson on March 07, 2000.
+.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/pnmtojpeg.html
+.PP
\ No newline at end of file