Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 532 insertions, 0 deletions

diff --git a/upstream/fedora-rawhide/man1/pnmtops.1 b/upstream/fedora-rawhide/man1/pnmtops.1
new file mode 100644
index 00000000..18346682
--- /dev/null
+++ b/upstream/fedora-rawhide/man1/pnmtops.1
@@ -0,0 +1,532 @@
+\
+.\" 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 "Pnmtops User Manual" 0 "20 April 2018" "netpbm documentation"
+
+.SH NAME
+pnmtops - convert PNM image to Postscript
+
+.UN synopsis
+.SH SYNOPSIS
+
+\fBpnmtops\fP
+[\fB-scale=\fP\fIs\fP]
+[\fB-dpi=\fP\fIN\fP[\fBx\fP\fIN\fP]]
+[\fB-imagewidth=\fP\fIn\fP]
+[\fB-imageheight=\fP\fIn\fP]
+[\fB-width=\fP\fIN\fP]
+[\fB-height=\fP\fIN\fP]
+[\fB-equalpixels\fP]
+[\fB-bitspersample=\fP\fIN\fP]
+[\fB-turn\fP|\fB-noturn\fP]
+[\fB-rle\fP|\fB-runlength\fP]
+[\fB-flate\fP]
+[\fB-ascii85\fP]
+[\fB-nocenter\fP|\fB-center\fP]
+[\fB-nosetpage\fP|\fB-setpage\fP]
+[\fB-level=\fP\fIN\fP]
+[\fB-dict\fP]
+[\fB-vmreclaim\fP]
+[\fB-psfilter\fP]
+[\fB-noshowpage\fP]
+[\fB-verbose\fP]
+[\fIpnmfile\fP]
+.PP
+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.
+
+.UN description
+.SH DESCRIPTION
+.PP
+This program is part of
+.BR "Netpbm" (1)\c
+\&.
+.PP
+\fBpnmtops\fP reads a Netpbm image stream as input and produces
+Encapsulated Postscript (EPSF) as output.
+.PP
+(Note: people usually render the name as "PostScript," but we use
+standard typography in the Netpbm manual, so capitalize only the first
+letter).
+.PP
+If the input file is in color (PPM), \fBpnmtops\fP generates a
+color Postscript file.  Some Postscript interpreters can't handle
+color Postscript.  If you have one of these you will need to run your
+image through \fBppmtopgm\fP first.
+.PP
+If you specify no output dimensioning options, the output image is
+dimensioned as if you had specified \fB-scale=1.0\fP, which means
+approximately 72 pixels of the input image generate one inch of output
+(if that fits the page).
+.PP
+Use \fB-imagewidth\fP, \fB-imageheight\fP, \fB-equalpixels\fP,
+\fB-width\fP, \fB-height\fP, and \fB-scale\fP to adjust that.
+.PP
+Each image in the input stream becomes one complete one-page Postscript 
+program in the output.  (This may not be the best way to create a multi-page
+Postscript stream; someone who knows Postscript should work on this).
+.PP
+The line at the top of the file produced by \fBpnmtops\fP is
+either "%!PS-Adobe-3.0 EPSF-3.0" or just
+"%!PS-Adobe-3.0".  The numbers do not reflect the Postscript
+language level, but the version of the DSC comment specification and
+EPS specification implemented.  The Postscript language level is in the
+"%%LanguageLevel:" comment.  \fBpnmtops\fP omits "EPSF-3.0" if you
+specify \fB-setpage\fP, because it is incorrect to claim EPS
+compliance if the file uses \fBsetpagedevice\fP.
+
+
+.SS What is Encapsulated Postscript?
+.PP
+Encapsulated Postscript (EPSF) is a subset of Postscript (i.e. the
+set of streams that conform to EPSF is a subset of those that conform
+to Postscript).  It is designed so that an EPSF stream can be embedded
+in another Postscript stream.  A typical reason to do that is to have an
+EPSF stream that describes a picture you can put in a larger document.
+.PP
+But EPSF is not an image format -- converting from Netpbm format to EPSF
+really means generating a program to print that Netpbm image on paper.  Note
+that there are myriad ways to print an image on paper; \fBpnmtops\fP
+command line options let you control some of them.
+.PP
+An Encapsulated Postscript document conforms to the DSC (Document
+Structuring Convention).  The DSC defines some Postscript comments
+(they're comments from a Postscript point of view, but have semantic
+value from a DSC point of view).
+.PP
+More information about Encapsulated Postscript is at 
+.BR "
+http://www.tailrecursive.org/postscript/eps.html" (1)\c
+\&.
+.PP
+Many of the ideas in \fBpnmtops\fP come from Dirk Krause's \fBbmeps\fP.
+See 
+.UR #seealso
+SEE ALSO
+.UE
+\&.
+
+.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
+\&), \fBpnmtops\fP recognizes the following
+command line options:
+
+
+.TP
+\fB-imagewidth\fP, \fB-imageheight\fP
+Tells how wide and high you want the image on the page, in inches.
+The aspect ratio of the image is preserved, so if you specify both of these,
+the image on the page will be the largest image that will fit within the
+box of those dimensions.
+.sp
+If these dimensions are greater than the page size, you get Postscript
+output that runs off the page.
+.sp
+You cannot use \fBimagewidth\fP or \fBimageheight\fP with
+\fB-scale\fP or \fB-equalpixels\fP.
+
+.TP
+\fB-equalpixels\fP
+This option causes the output image to have the same number of pixels
+as the input image.  So if the output device is 600 dpi and your image
+is 3000 pixels wide, the output image would be 5 inches wide.
+.sp
+You cannot use \fB-equalpixels\fP with \fB-imagewidth\fP,
+\fB-imageheight\fP, or \fB-scale\fP.
+
+.TP
+\fB-bitspersample=\fP\fIN\fP
+This option selects the number of bits for each component of each pixel in
+the Postscript output.  By default, \fBpnmtops\fP chooses the value that
+corresponds to the maxval of the PNM input, subject to constraints of the
+Postscript language.  In particular, if you don't select Postscript level
+2 (\fB-level\fP) with built-in Postscript (\fB-psfilter\fP), the most
+bits per pixel you can have is 8.
+.sp
+The value must be 1, 2, 4, 8, or 12, with 12 being restricted to the
+case described above.
+.sp
+This option was new in Netpbm 10.51 (June 2010).
+
+.TP
+\fB-scale\fP
+tells how big you want the image on the page.  The value is the number of
+inches of output image that you want 72 pixels of the input to generate.
+.sp
+But \fBpnmtops \fP rounds the number to something that is an
+integral number of output device pixels.  E.g. if the output device is
+300 dpi and you specify \fB-scale=1.0\fP, then 75 (not 72) pixels of
+input becomes one inch of output (4 output pixels for each input
+pixel).  Note that the \fB-dpi\fP option tells \fBpnmtops\fP how
+many pixels per inch the output device generates.
+.sp
+If the size so specified does not fit on the page (as measured
+either by the \fB-width\fP and \fB-height\fP options or the default
+page size of 8.5 inches by 11 inches), \fBpnmtops\fP ignores the
+\fB-scale\fP option, issues a warning, and scales the image to fit on
+the page.
+
+.TP
+\fB-dpi=\fP\fIN\fP[\fBx\fP\fIN\fP]
+.sp
+This option specifies the dots per inch resolution of your output
+device.  The default is 300 dpi.  In theory PostScript is
+device-independent and you don't have to worry about this, but in
+practice its raster rendering can have unsightly bands if the device
+pixels and the image pixels aren't in sync.
+.sp
+Also this option is crucial to the working of the
+\fBequalpixels\fP option.
+.sp
+If you specify \fIN\fP\fBx\fP\fIN\fP, the first number is the
+horizontal resolution and the second number is the vertical
+resolution.  If you specify just a single number \fIN\fP, that is the
+resolution in both directions.
+     
+.TP
+\fB-width\fP, \fB-height\fP
+ These options specify the dimensions, in inches, of the page on
+which the output is to be printed.  This can affect the size of the
+output image.
+.sp
+The page size has no effect, however, when you specify the 
+\fB-imagewidth\fP, \fB-imageheight\fP, or \fB-equalpixels\fP options.
+.sp
+These options may also affect positioning of the image on the page and
+even the paper selected (or cut) by the printer/plotter when the
+output is printed.  See the \fB-nosetpage\fP option.
+.sp
+The default is 8.5 inches by 11 inches.
+
+.TP
+\fB-turn\fP
+
+.TP
+\fB-noturn\fP 
+These options control whether the image gets turned 90 degrees.
+Normally, if an image fits the page better when turned (e.g. the image
+is wider than it is tall, but the page is taller than it is wide), it
+gets turned automatically to better fit the page.  If you specify the
+\fB-turn\fP option, \fBpnmtops \fP turns the image no matter what
+its shape; If you specify \fB-noturn\fP, \fBpnmtops\fP does
+\fInot\fP turn it no matter what its shape.
+
+.TP
+\fB-rle\fP
+
+.TP
+\fB-runlength\fP
+These identical options tell \fBpnmtops\fP to use run length
+compression in encoding the image in the Postscript program.  This may
+save time if the host-to-printer link is slow; but normally the
+printer's processing time dominates, so \fB-rle\fP has no effect (and
+in the absence of buffering, may make things slower).
+.sp
+This may, however, make the Postscript program considerable smaller.
+.sp
+This usually doesn't help at all with a color image and
+\fB-psfilter\fP, because in that case, the Postscript program
+\fBpnmtops\fP creates has the red, green, and blue values for each
+pixel together, which means you would see long runs of identical bytes
+only in the unlikely event that the red, green, and blue values for a
+bunch of adjacent pixels are all the same.  But without
+\fB-psfilter\fP, the Postscript program has all the red values, then
+all the green values, then all the blue values, so long runs appear
+wherever there are long stretches of the same color.
+.sp
+Here is an explanation by Jef Poskanzer of why he invented the
+\fB-rle\fP option:
+
+.RS
+I just spent a few hours modifying my pbmtops filter to produce run length
+encoded PostScript output.  The results are not spectacular for me - yes, the
+files are smaller, but the printing times are about the same.  But I'm
+printing over the network.  If you were stuck with the serial line, this would
+be a big win.  I've appended a sample program generated by my filter.  If
+anyone sees ways to improve the code, please let me know, I'm not much of a
+PostScript hacker.  This version of pbmtops will be distributed to
+comp.sources.misc and expo.lcs.mit.edu sometime in October. - Jef
+.RE
+.sp
+This is
+from 
+.UR http://www.lngpstscrpt.tk/re-postscript-run-length-encoding-again
+a forum about Postscript
+.UE
+\&, extracted in October 2010.  Jef added -rle in
+August 1988.  In those days, RS-232 lines (referred to as "serial" in
+the quotation) were typically 9600bps.  2400 bps lines were still around.
+What the quotation calls "the network" is probably a 10 Mbps
+Ethernet connection.
+
+.TP
+\fB-flate\fP
+This option tells \fBpnmtops\fP to use "flate"
+compression (i.e. compression via the "Z" library -- the
+same as PNG).
+.sp
+See the \fB-rle\fP option for information about compression in general.
+.sp
+You must specify \fB-psfilter\fP if you specify \fB-flate\fP.
+.sp
+There exist modern versions of \fBpnmtops\fP that cannot do flate
+compression; these versions were built without the Z library and built not to
+require the Z library.  If you have such a version, it fails with an
+explanatory error message when you specify \fB-flate\fP.
+.sp
+This option was new in Netbpm 10.27 (March 2005).
+.sp
+Before Netpbm 10.32 (February 2006), you could not specify \fB-rle\fP
+and \fB-flate\fP together.
+
+
+.TP
+\fB-ascii85\fP
+By default, \fBpnmtops\fP uses "asciihex" encoding of
+the image raster.  The image raster is a stream of bits, while a Postscript
+program is text, so there has to be an encoding from bits to text.  Asciihex
+encoding is just the common hexadecimal representation of bits.  E.g. 8
+1 bits would be encoded as the two characters "FF".
+.sp
+With the \fB-ascii85\fP option, \fBpnmtops\fP uses
+"ascii85" encoding instead.  This is an encoding in which 32
+bits are encoded into five characters of text.  Thus, it produces less
+text for the same raster than asciihex.  But ascii85 is not available
+in Postscript Level 1, whereas asciihex is.
+.sp
+This option was new in Netbpm 10.27 (March 2005).
+
+.TP
+\fB-psfilter\fP
+\fBpnmtops\fP can generate two different kinds of Encapsulated
+Postscript programs to represent an image.  By default, it generates a
+program that redefines \fBreadstring\fP in a custom manner and
+doesn't rely on any built-in Postscript filters.  But with the
+\fB-psfilter\fP option, \fBpnmtops\fP leaves \fBreadstring\fP alone
+and uses the built-in Postscript filters \fB/ASCII85Decode\fP,
+\fB/ASCIIHexDecode\fP, \fB/RunLengthDecode\fP, and \fB/FlateDecode\fP.
+.sp
+This option was new in Netbpm 10.27 (March 2005).  Before that, 
+\fBpnmtops\fP always used the custom \fBreadstring\fP.
+.sp
+The custom code can't do flate or ascii85 encoding, so you must use
+\fB-psfilter\fP if you want those (see \fB-flate\fP, \fB-ascii85\fP).
+
+.TP
+\fB-level\fP
+This option determines the level (version number) of Postscript that
+\fBpnmtops\fP uses.  By default, \fBpnmtops\fP uses Level 2.  Some
+features of \fBpnmtops\fP are available only in higher Postscript levels,
+so if you specify too low a level for your image and your options,
+\fBpnmtops\fP fails.  For example, \fBpnmtops\fP cannot do a color image
+in Level 1.
+.sp
+This option was new in Netpbm 10.27 (March 2005).  Before that,
+\fBpnmtops\fP always used Level 2.
+
+.TP
+\fB-dict\fP
+This causes the Postscript program create a separated dictionary
+for its local variables and remove it from the stack as it exits.
+.sp
+This option was new in Netbpm 10.27 (March 2005).
+
+.TP
+\fB-vmreclaim\fP
+This option causes the Postscript program to force a memory garbage
+collection as it exits.
+.sp
+This option was new in Netbpm 10.27 (March 2005).
+
+.TP
+\fB-nocenter\fP
+     By default, \fBpnmtops\fP centers the image on the output page.
+     You can cause \fBpnmtops\fP to instead put the image against the
+     lower left corner of the page with the \fB-nocenter \fP
+     option.  This is useful for programs which can include
+     PostScript files, but can't cope with pictures which are not
+     positioned in the lower left corner.
+.sp
+     If you want to position an image on the page arbitrarily, use
+     \fBpamcomp\fP to create an image of the full page with the image in
+     question at the proper place and the rest of the page white, and use
+     \fBpnmtops\fP to convert the composed result to Encapsulated Postscript.
+.sp
+     For backward compatibility, \fBpnmtops\fP accepts the option
+     \fB-center\fP, but it has no effect.
+
+.TP
+\fB-setpage\fP
+     This causes \fBpnmtops\fP to include a "setpagedevice"
+     directive in the output.  This causes the output to violate specifications
+     of EPSF encapsulated Postscript, but if you're not using it in an
+     encapsulated way, may be what you need.  The directive tells the
+     printer/plotter what size paper to use (or cut).  The dimensions it
+     specifies on this directive are those selected by the
+     \fB-width\fP and \fB-height\fP options or defaulted.
+.sp
+From January through May 2002, the default was to include
+     "setpagedevice" and this option did not exist.  Before
+     January 2002, there was no way to include "setpagedevice"
+     and neither the \fB-setpage\fP nor \fB-nosetpage\fP option existed.
+     
+.TP
+\fB-nosetpage\fP
+     This tells \fBpnmtops\fP not to include a "setpagedevice"
+     directive in the output.  This is the default, so the option has no
+     effect.
+.sp
+See the \fB-setpage\fP option for the history of this option.
+
+.TP
+\fB-noshowpage\fP
+     This tells \fBpnmtops\fP not to include a "showpage"
+     directive in the output.  By default, \fBpnmtops\fP includes a
+     "showpage" at the end of the EPSF program.  According to
+     EPSF specs, this is OK, and the program that includes the EPSF is
+     supposed to redefine showpage so this doesn't cause undesirable
+     behavior.  But it's often easier just not to have the showpage.
+.sp
+This options was new in Netpbm 10.27 (March 2005).  Earlier
+     versions of \fBpnmtops\fP always include the showpage.
+
+.TP
+\fB-showpage\fP
+    This tells \fBpnmtops\fP to include a "showpage" directive
+    at the end of the EPSF output.  This is the default, so the option has
+    no effect.
+.sp
+This option was new in Netpbm 10.27 (March 2005).
+
+.TP
+\fB-verbose\fP
+    This causes informational messages about the conversion process and
+    result.
+
+
+
+.UN limitations
+.SH LIMITATIONS
+.PP
+If the PNM image has a maxval greater than 255, \fBpnmtops\fP will
+produce output with 8 bits per sample resolution unless you specify
+-psfilter, even though Postscript Level 2 has a 12 bits per sample
+format.  \fBpnmtops\fP's custom raster-generating code just doesn't
+know the 12 bit format.
+
+.UN applications
+.SH APPLICATIONS
+.PP
+You can use the Postscript output a number of ways.  Many printers take
+Postscript input (but you still need some kind of printer driver to transport
+the Postscript to the printer).
+.PP
+There is also the Ghostscript program (not part of Netpbm), which takes
+Postscript as input and generates an output stream to control any of myriad
+models of printer (but you still need some kind of printer driver to transport
+that stream to the printer).
+.PP
+Ghostscript also can convert the Postscript file to PDF, which is a very
+popular document and image format.  Use Ghostscript's \fBpdfwrite\fP output
+device type.  The program \fBps2pdf\fP (distributed with Ghostscript) is a
+convenient way to run Ghostscript with \fBpdfwrite\fP.
+
+
+.UN seealso
+.SH SEE ALSO
+.PP
+.BR "\fBbmpp\fP" (1)\c
+\& converts
+from Netpbm and other formats to Encapsulated Postscript.
+
+\fBbmpp\fP has a few functions \fBpnmtops\fP does not, such as the ability
+to use LZW compression.
+.PP
+.BR "pnm" (1)\c
+\&,
+\fBgs\fP,
+.BR "psidtopgm" (1)\c
+\&,
+.BR "pstopnm" (1)\c
+\&,
+.BR "pbmtolps" (1)\c
+\&,
+.BR "pbmtoepsi" (1)\c
+\&,
+.BR "pbmtopsg3" (1)\c
+\&,
+.BR "ppmtopgm" (1)\c
+\&,
+
+
+.UN history
+.SH HISTORY
+.PP
+Copyright (C) 1989, 1991 by Jef Poskanzer.
+.PP
+Modified November 1993 by Wolfgang Stuerzlinger, \fIwrzl@gup.uni-linz.ac.at\fP
+.PP
+The program was originally \fBpbmtops\fP.  It became \fBpgmtops\fP in
+October 1988 and was merged with \fBppmtops\fP to form \fBpnmtops\fP in
+January 1991.  \fBppmtops\fP came into being some time before September 1989.
+
+.UN index
+.SH Table Of Contents
+
+.IP \(bu
+
+.UR #synopsis
+SYNOPSIS
+.UE
+\&
+.IP \(bu
+
+.UR #description
+DESCRIPTION
+.UE
+\&
+.IP \(bu
+
+.UR #options
+OPTIONS
+.UE
+\&
+.IP \(bu
+
+.UR #limitations
+LIMITATIONS
+.UE
+\&
+.IP \(bu
+
+.UR #applications
+APPLICATIONS
+.UE
+\&
+.IP \(bu
+
+.UR #seealso
+SEE ALSO
+.UE
+\&
+.IP \(bu
+
+.UR #history
+HISTORY
+.UE
+\&
+.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/pnmtops.html
+.PP
\ No newline at end of file