diff options
Diffstat (limited to 'upstream/fedora-rawhide/man1/pnmtops.1')
| -rw-r--r-- | upstream/fedora-rawhide/man1/pnmtops.1 | 532 |
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 |