latex2html/pstoimg.1

.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "PSTOIMG 1"
.TH PSTOIMG 1 "2005-03-20" "perl v5.8.4" "User Contributed Perl Documentation"
.SH "NAME"
pstoimg \- Convert a PostScript file to a bitmap image using 
Ghostscript and the Netpbm utilities
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBpstoimg\fR \fB\-help\fR | \fB\-version\fR
.PP
\&\fBpstoimg\fR
[\ \fB\-antialias\fR\ ]
[\ \fB\-aaliastext\fR\ ]
[\ \fB\-center\fR\ \fInum\fR\ ]
[\ \fB\-color\fR\ \fInum\fR\ ]
[\ \fB\-crop\fR\ \fIcode\fR\ ]
[\ \fB\-debug\fR\ ]
[\ \fB\-density\fR\ \fInum\fR]
[\ \fB\-depth\fR\ \fInum\fR\ ]
[\ \fB\-discard\fR\ ]
[\ \fB\-flip\fR\ \fIcode\fR\ ]
[\ \fB\-geometry\fR\ \fIX\fRx\fIY\fR\ ]
[\ \fB\-interlaced\fR\ ]
[\ \fB\-margins\fR\ \fIX\fR,\fIY\fR\ ]
[\ \fB\-multipage\fR\ ]
[\ \fB\-out\fR\ \fIfile\fR\ ]
[\ \fB\-quiet\fR\ ]
[\ \fB\-rightjustify\fR\ \fInum\fR\ ]
[\ \fB\-scale\fR\ \fInum\fR\ ]
[\ \fB\-tmp\fR\ \fIpath\fR\ ]
[\ \fB\-topjustify\fR\ [\fBx\fR]\fInum\fR\ ]
[\ \fB\-transparent\fR\ ]
[\ \fB\-type\fR\ \fItype\fR\ ]
[\ \fB\-shoreup\fR\ \fInum\fR[\fBd\fR]\ ]
[\ \fB\-white\fR\ ]
\&\fIfile\fR
[\ \fIfile2\fR\ ...\ ]
.SH "OPTIONS"
.IX Header "OPTIONS"
The command line options may be abbreviated to the shortest unique
prefix.
.IP "\fB\-help\fR" 4
.IX Item "-help"
Show this help page and exit.
.IP "\fB\-version\fR" 4
.IX Item "-version"
Show the release and version of pstoimg and exit.
.IP "\fB\-antialias\fR" 4
.IX Item "-antialias"
Use Ghostscript's anti-aliasing feature for rendering \*(L"softer\*(R" images.
This applies to lines and edges of polygonal and oval or circular shapes.
Only valid if Ghostscipt 4.03 or higher is installed.
.IP "\fB\-aaliastext\fR" 4
.IX Item "-aaliastext"
Use Ghostscript's anti-aliasing feature for \*(L"smoother\*(R" font characters,
without the jagged edges. Similar to \fB\-antialias\fR for graphic components.
Only valid if Ghostscipt 4.03 or higher is installed.
.IP "\fB\-center\fR \fInum\fR" 4
.IX Item "-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 \fInum\fR pixels.
.IP "\fB\-crop\fR \fIcode\fR" 4
.IX Item "-crop code"
Crop the bitmap from the given directions. \fIcode\fR may be a string of
several cropping instructions, which are executed strictly in the given
order. Possible values are: \fBh\fR (horizontal, i.e. crop top and
bottom), \fBv\fR (vertical), \fBtblr\fR (top, bottom, left, right) and \fBa\fR (all
directions). A special case is \fBs\fR: \*(L"shave\*(R" the image at the bottom, but only
if a single line of whitespace exists.
.IP "\fB\-debug\fR" 4
.IX Item "-debug"
Turn on debugging output. This can get rather verbose. Any intermediate
files generated are not removed to help debugging.
.IP "\fB\-density\fR \fInum\fR" 4
.IX Item "-density num"
The density (resolution) in \s-1DPI\s0 in which to render the bitmap. The default
is 72.
.IP "\fB\-depth\fR \fInum\fR or \fB\-color\fR \fInum\fR" 4
.IX Item "-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).
.IP "\fB\-discard\fR" 4
.IX Item "-discard"
Delete the input postscript file if the conversion was successful. Setting
the environment \s-1DISCARD\s0 to a true value (as perl sees it) has the same
effect.
.IP "\fB\-flip\fR \fIcode\fR" 4
.IX Item "-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).
.IP "\fB\-geometry\fR \fIX\fRx\fIY\fR" 4
.IX Item "-geometry XxY"
Render only this \*(L"window\*(R" 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 \s-1EPS\s0 files (Encapsulated
PostScript).
.IP "\fB\-interlaced\fR" 4
.IX Item "-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.
.IP "\fB\-margins\fR \fIX\fR,\fIY\fR" 4
.IX Item "-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 \fB\-geometry\fR to further
reduce the size of the intermediate bitmap file generated by Ghostscript.
.IP "\fB\-multipage\fR" 4
.IX Item "-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 \fB\-out\fR), while
keeping the extension.
.IP "\fB\-out\fR \fIfile\fR" 4
.IX Item "-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 \fIfile\fR does not contain a dot.
In connection with \fB\-multipage\fR \fIfile\fR is extended by the page number
as shown in this example:
.Sp
\&\-outfile foo.gif  \-\-\-\-\-\-\-\-> foo1.gif, foo2.gif, ...
.IP "\fB\-quiet\fR" 4
.IX Item "-quiet"
Do not print anything except error messages.
.IP "\fB\-rightjustify\fR \fInum\fR" 4
.IX Item "-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 \fInum\fR pixels.
.IP "\fB\-scale\fR \fIfactor\fR" 4
.IX Item "-scale factor"
Scale the image by \fIfactor\fR. 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 \s-1SCALE\s0 is
considered.
.IP "\fB\-shoreup\fR \fInum\fR[\fBd\fR]" 4
.IX Item "-shoreup num[d]"
Make height and width of the bitmap(s) an exact multiple of \fInum\fR. If
\&\fInum\fR is followed by a \*(L"d\*(R", then half the extra vertical space is placed
underneath. This option is useful, if you want to have \*(L"blown\-up\*(R" images
of high quality for print, but downscale them in \s-1HTML\s0 using
\&\f(CW\*(C`<IMG WIDTH=x HEIGHT=y>\*(C'\fR. If the actual image is is not an
integer multiple of x,y then browsers tend to display distorted images.
.IP "\fB\-tmp\fR \fIpath\fR" 4
.IX Item "-tmp path"
Use \fIpath\fR to store temporary files. Defaults to /tmp on this
installation. This parameter can be set by the environment \fB\s-1TMP\s0\fR or 
\&\fB\s-1TEMP\s0\fR, too.
.IP "\fB\-topjustify\fR [\fBx\fR]\fInum\fR" 4
.IX Item "-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 \*(L"x\*(R", then this
multiple of the image height is added as whitespace at the bottom.
.IP "\fB\-transparent\fR" 4
.IX Item "-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.
.IP "\fB\-type\fR \fItype\fR" 4
.IX Item "-type type"
Instruct pstoimg to render the bitmap in \fItype\fR format. Depending on 
the local installation, pstoimg is capable of generating either \s-1GIF\s0 or
\&\s-1PNG\s0 bitmaps. This site features the following types: png gif
.Sp
If omitted, the first type in this list is taken.
.IP "\fB\-white\fR" 4
.IX Item "-white"
Remove TeX's page color information from the PostScript file before 
converting so that a white background is used.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBpstoimg\fR iterates over the given input files and runs them through
Ghostscipt. The resulting pnm (portable anymap files) are processed
with different Netpbm tools (cropping, color mapping, aligning, ...)
and finally converted into (currently) either \s-1GIF\s0 or \s-1PNG\s0 format. The
bitmaps can now be included e.g. in \s-1WWW\s0 pages.
.PP
The PostScript file is converted as is. If a valid bounding box is
found (\s-1EPS\s0 format), then only this area is converted. The image is
\&\fInot\fR cropped by default.
.SH "RETURN VALUE"
.IX Header "RETURN VALUE"
.IP "0" 4
if everything went all right
.IP "x" 4
.IX Item "x"
(x != 0) something went wrong. See the message output.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
.ie n .IP """pstoimg foo.ps""" 4
.el .IP "\f(CWpstoimg foo.ps\fR" 4
.IX Item "pstoimg foo.ps"
Convert the first page of foo.ps to the default bitmap type.
.ie n .IP """pstoimg \-type png \-crop a \-trans \-interlace foo.ps""" 4
.el .IP "\f(CWpstoimg \-type png \-crop a \-trans \-interlace foo.ps\fR" 4
.IX Item "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.
.ie n .IP """pstoimg \-multi \-out bar \-type gif \-crop a foo.ps""" 4
.el .IP "\f(CWpstoimg \-multi \-out bar \-type gif \-crop a foo.ps\fR" 4
.IX Item "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.
.SH "ENVIRONMENT"
.IX Header "ENVIRONMENT"
.IP "\s-1DENSITY\s0, \s-1DEPTH\s0, \s-1DEBUG\s0, \s-1DISCARD\s0" 4
.IX Item "DENSITY, DEPTH, DEBUG, DISCARD"
See \fB\-density\fR, \fB\-depth\fR, \fB\-debug\fR, \fB\-discard\fR, respectively.
.IP "\s-1GS_LIB\s0" 4
.IX Item "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 \s-1GS_LIB\s0 manually before starting pstoimg.
.IP "\s-1LATEX2HTMLDIR\s0" 4
.IX Item "LATEX2HTMLDIR"
The directory where the LaTeX2HTML library and perl modules are found.
Defaults to \*(L"/usr/share/latex2html\*(R" on this installation.
.IP "\s-1OUTFILE\s0" 4
.IX Item "OUTFILE"
Setting this has the same effect as specifying \fB\-out\fR. Please do not rely
on this feature any more, it will disappear from the next releases!
.IP "\s-1PAPERSIZE\s0" 4
.IX Item "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.
.IP "\s-1SCALE\s0" 4
.IX Item "SCALE"
See the discussion of \fB\-scale\fR.
.IP "\s-1TMP\s0 and \s-1TEMP\s0" 4
.IX Item "TMP and TEMP"
Unless overridden by \fB\-tmp\fR, these variables denote a directory where
to store temporary files. \s-1TMP\s0 is considered first, then \s-1TEMP\s0.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
gs, pnmcrop, pnmquant, pbmmake, pnmcat, pnmfile, pnmflip, ppmtogif,
pnmtopng, giftool, giftrans.
.SH "NOTES"
.IX Header "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.
.SH "CAVEATS"
.IX Header "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.
.PP
Despite the portability of perl, a pstoimg configured on \s-1UNIX\s0 will
probably not work on Win32 and vice versa.
.SH "BUGS"
.IX Header "BUGS"
This is a major enhancement release, so there may be a few bugs. As
the user inteface changed a bit, some of your tools that were using
pstoimg may not work any more. 
.PP
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.
.SH "AUTHOR"
.IX Header "AUTHOR"
Marek Rouchal <marek@saftsack.fs.uni\-bayreuth.de>
.SH "HISTORY"
.IX Header "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@mpce.mq.edu.au>, Jens Lippmann 
<lippmann@rbg.informatik.tu\-darmstadt.de> and others (sorry for not
mentioning everyone and thanks for your contributions).