Provided by: latex2html_2019.2-debian1-1_all bug

NAME

       pstoimg - Convert a PostScript file to a bitmap image using Ghostscript and the Netpbm utilities

SYNOPSIS

       pstoimg -help | -version

       pstoimg [ -antialias ] [ -aaliastext ] [ -center num ] [ -color num ] [ -crop code ] [ -debug ]
       [ -density num] [ -depth num ] [ -discard ] [ -flip code ] [ -geometry XxY ] [ -interlaced ]
       [ -margins X,Y ] [ -multipage ] [ -out file ] [ -quiet ] [ -rightjustify num ] [ -scale num ]
       [ -tmp path ] [ -topjustify [x]num ] [ -transparent ] [ -type type ] [ -shoreup num[d] ] [ -white ] file
       [ file2 ... ]

OPTIONS

       The command line options may be abbreviated to the shortest unique prefix.

       -help
           Show this help page and exit.

       -version
           Show the release and version of pstoimg and exit.

       -antialias
           Use Ghostscript's anti-aliasing feature for rendering "softer" images.  This applies to lines and
           edges of polygonal and oval or circular shapes.  Only valid if Ghostscript 4.03 or higher is
           installed.

       -aaliastext
           Use Ghostscript's anti-aliasing feature for "smoother" font characters, without the jagged edges.
           Similar to -antialias for graphic components.  Only valid if Ghostscript 4.03 or higher is installed.

       -center num
           Add the appropriate amount of whitespace to the left of the image so that the image appears to be
           centered in a total width of num pixels.

       -crop code
           Crop the bitmap from the given directions. code may be a string of several cropping instructions,
           which are executed strictly in the given order. Possible values are: h (horizontal, i.e. crop top and
           bottom), v (vertical), tblr (top, bottom, left, right) and a (all directions). A special case is s:
           "shave" the image at the bottom, but only if a single line of whitespace exists.

       -debug
           Turn on debugging output. This can get rather verbose. Any intermediate files generated are not
           removed to help debugging.

       -density num
           The density (resolution) in DPI in which to render the bitmap. The default is 72.

       -depth num or -color num
           Specify the color depth of the bitmap. Legal values are 1 (black & white), 8 (256 colors) and 24
           (true color).

       -discard
           Delete the input postscript file if the conversion was successful. Setting the environment DISCARD to
           a true value (as perl sees it) has the same effect.

       -flip code
           Flip all generated output bitmaps. The following codes are recognized: lr (flip left-right), tb (flip
           top-bottom), xy (flip bottom/left-top/right), r90 and ccw (rotate by 90 degrees counterclockwise),
           r270 and cw (rotate 90 degrees clockwise) and r180 (rotate 180 degrees).

       -geometry XxY
           Render only this "window" of the PostScript file. If given, this option can dramatically reduce
           memory requirements and speed up conversion. The geometry is automatically detected in case of EPS
           files (Encapsulated PostScript).

       -interlaced
           Generate an interlaced bitmap. Interlaced images build up from coarse to fine as they are loaded.
           This option may not work on every installation and/or bitmap type, depending of the capabilities of
           external programs.

       -margins X,Y
           The offset of the rectangle in the postscript file that is going to be rendered from top/left. Can be
           used together with -geometry to further reduce the size of the intermediate bitmap file generated by
           Ghostscript.

       -multipage
           Process a multi-page PostScript file, i.e. create an individual bitmap for every page. The resulting
           files are numbered: The decimal number (starting with 1) is appended to the basename of the
           PostScript input file (or the basename of the filename specified with -out), while keeping the
           extension.

       -out file
           The file where to write the bitmap. If multiple PostScript files are supplied on the command line,
           this option is ignored. The bitmap type extension is appended automatically if file does not contain
           a dot.  In connection with -multipage file is extended by the page number as shown in this example:

           -outfile foo.gif  --------> foo1.gif, foo2.gif, ...

       -quiet
           Do not print anything except error messages.

       -rightjustify num
           Add the appropriate amount of whitespace to the left of the image so that it appears to be aligned to
           the right in a total width of num pixels.

       -scale factor
           Scale the image by factor. Valid choices are any numbers greater than zero. Useful choices are
           numbers between 0.1 - 5.  Large numbers may generate very large intermediate files and will take
           longer to process. If this option is omitted, the environment SCALE is considered.

       -shoreup num[d]
           Make height and width of the bitmap(s) an exact multiple of num. If num is followed by a "d", then
           half the extra vertical space is placed underneath. This option is useful, if you want to have
           "blown-up" images of high quality for print, but downscale them in HTML using "<IMG WIDTH=x
           HEIGHT=y>". If the actual image is is not an integer multiple of x,y then browsers tend to display
           distorted images.

       -tmp path
           Use path to store temporary files. Defaults to /tmp on this installation. This parameter can be set
           by the environment TMP or TEMP, too.

       -topjustify [x]num
           Add padding whitespace to the image so that it gets a defined height.  If an integer value is given,
           it defines the total height. The whitespace is added at the bottom. If the number is preceded by "x",
           then this multiple of the image height is added as whitespace at the bottom.

       -transparent
           Generate transparent bitmaps, i.e. the background color (white) is transparent if viewed with certain
           viewers (e.g. browsers). This option may not be available due to missing capabilities of external
           programs.

       -type type
           Instruct pstoimg to render the bitmap in type format. Depending on the local installation, pstoimg is
           capable of generating either GIF or PNG bitmaps. This site features the following types: svg png gif

           If omitted, the first type in this list is taken.

       -white
           Remove TeX's page color information from the PostScript file before converting so that a white
           background is used.

DESCRIPTION

       pstoimg iterates over the given input files and runs them through Ghostscript. The resulting pnm
       (portable anymap files) are processed with different Netpbm tools (cropping, color mapping, aligning,
       ...)  and finally converted into (currently) either GIF or PNG format. The bitmaps can now be included
       e.g. in WWW pages.

       The PostScript file is converted as is. If a valid bounding box is found (EPS format), then only this
       area is converted. The image is not cropped by default.

RETURN VALUE

       0   if everything went all right

       x   (x != 0) something went wrong. See the message output.

EXAMPLES

       "pstoimg foo.ps"
           Convert the first page of foo.ps to the default bitmap type.

       "pstoimg -type png -crop a -trans -interlace foo.ps"
           Same as above, but force png output and crop all the whitespace around the image and make the color
           white transparent and generate an interlaced bitmap.

       "pstoimg -multi -out bar -type gif -crop a foo.ps"
           Consider foo.ps a multiple page PostScript file and create output files bar1.gif, bar2.gif, etc.

ENVIRONMENT

       DENSITY, DEPTH, DEBUG, DISCARD
           See -density, -depth, -debug, -discard, respectively.

       GS_LIB
           This variable is set to the path(s) where Ghostscript libraries have been found on this system during
           configuration, but only if the built-in paths are not correct. This fixes the problem of relocation
           that is quite common on Win32 installations. This behavior can be overridden by setting GS_LIB
           manually before starting pstoimg.

       LATEX2HTMLDIR
           The directory where the LaTeX2HTML library and perl modules are found.  Defaults to
           "/usr/share/latex2html" on this installation.

       OUTFILE
           Setting this has the same effect as specifying -out. Please do not rely on this feature any more, it
           will disappear from the next releases!

       PAPERSIZE
           The papersize to use by Ghostscript to render the image. pstoimg tries hard to optimize for rendering
           on the smallest possible bitmap size.  Still this option is there to enable tuning by hand, although
           it is deprecated. If pstoimg finds a better setting, this parameter is ignored.

       SCALE
           See the discussion of -scale.

       TMP and TEMP
           Unless overridden by -tmp, these variables denote a directory where to store temporary files. TMP is
           considered first, then TEMP.

SEE ALSO

       gs, pnmcrop, pnmquant, pbmmake, pnmcat, pnmfile, pnmflip, ppmtogif, pnmtopng, giftool, giftrans.

NOTES

       Several people have suggested to use ImageMagick's convert instead of pstoimg. A few comments on this:
       convert uses (of course) Ghostscript for conversion of PostScript to bitmap, so one still needs gs. And
       for the special requirements of LaTeX2HTML convert's features are not sufficient. The ImageMagick toolset
       has everything in place, but it has some overhead that can prove killing when processing some 100 images.
       pstoimg only does what it really has to, so it should be quite efficient. Don't get me wrong - I like
       ImageMagick, but not in the context of LaTeX2HTML.

CAVEATS

       This utility is automatically configured and built to work on the local setup. If this setup changes
       (e.g. some of the external commands are moved), the script has be be reconfigured.

       Despite the portability of perl, a pstoimg configured on UNIX will probably not work on Win32 and vice
       versa.

BUGS

       Please report bugs to latex2html@tug.org, stating the (debug) output of pstoimg, your perl version and
       the versions of the external tools.  Best is to include the cfgcache.pm file from the configuration
       procedure.

AUTHOR

       Marek Rouchal <marek@saftsack.fs.uni-bayreuth.de>

HISTORY

       This script went through a long evolution, beginning with a modification of Doug Crabill's
       <dgc@cs.purdue.edu> ps2epsi script.  The first perl version was done by Nikos Drakos
       <nikos@cbl.leeds.ac.uk>.  It was gradually improved by numerous LaTeX2HTML developers: Ross Moore
       <ross@maths.mq.edu.au>, Jens Lippmann <lippmann@rbg.informatik.tu-darmstadt.de> and others (sorry for not
       mentioning everyone and thanks for your contributions).