./" Copyright 2005 G. Adam Stanislav
./" All rights reserved.
.TH PEPS "1" "January 2005" "peps v.2.0" "User Commands"
.SH NAME
peps \- manual page for peps v.2.0
.SH SYNOPSIS
.B peps
[\fIoption \fR...] [\fIfile\fR]
.br
.B xpeps
[\fIoption \fR...] [\fIfile\fR]
.SH DESCRIPTION
.PP
.B Peps
preprocesses an encapsulated Postscript (\fBEPS\fR) file
and passes it on to \fIGhostscript\fR for a conversion into a bitmap.
In version 1.0 the default output was a \fIpnm\fR bitmap, or
optionally a \fIPNG\fR bitmap. As of version 2.0, \fBpeps\fR
default output is a \fIPNG\fR bitmap with 16 million colors,
grayscale with the \fB\-m\fR switch, while a \fIpnm\fR bitmap
is produced when the \fB\-n\fR switch is specified.
Additionally, any other bitmap format supported by \fIGhostscript\fR
can be requested using the \fB\-f\fR switch. \fBXpeps\fR default
output is a color image produced by the \fIGhostscript x11\fR
device, a grayscale image produced by the \fIx11gray4\fR
device with the \fB\-m\fR switch.
.PP
While Postscript does not use the \fB#\fR as a comment delimiter,
\fBpeps\fR will not pass the \fIfirst\fR line of its input to
\fIGhostscript\fR, if that line starts with a \fB#\fR. This is to allow
the Unix shell to treat encapsulated Postscript files as
executable scripts.
.PP
.B Peps
can be used on line to produce images on the fly
using the standard \fBCGI\fR interface.
.B Xpeps
can be used to debug online
.B peps
scripts before posting them on line.
.SH OPTIONS
.PP
The following command line options control \fBpeps\fR and
.B xpeps
behavior. If several contradicting options are used, the later ones
override the earlier ones. Both
.B peps
and
.B xpeps
accept the same switches. However, each will ignore those
switches that do not apply to their operation:
.B Peps
will ignore \fB\-e\fR and \fB\-E\fR, while
.B xpeps
ignores \fB\-c\fR, \fB\-C\fR, \fB\-f\fR, \fB\-M\fR, \fB\-n\fR,
\fB\-u\fR, \fB\-z\fR and \fB\-Z\fR. Nevertheless, even if a switch is
ignored, as long as it is used, it must be used correctly. For example,
.B xpeps
will complain if
.B \-f
is not followed by a syntactically correct name of a
.I Ghostscript
device.

In the description of the switches, unless
.B xpeps
is mentioned explicitly, any time
.B peps
is discussed, the discussion also applies to \fBxpeps\fR.
.TP
\fB\-a\fR <\fIangle\fR>
Declare the \fIangle of rotation\fR of the image in degrees,
about the center of the image. By default the angle is \fB0\fR,
that is no rotation. A positive angle rotates the image
\fIcounter\-clockwise\fR, a negative one \fIclockwise\fR.

Rotation almost always results in a part of the image
being cut off. This can be prevented by using the \fB\-x\fR, \fB\-X\fR,
\fB\-y\fR, and \fB\-Y\fR switches, or by changing the bounding box
with the \fB\-b\fR switch.
.TP
\fB\-b\fR <\fIleft\fR> <\fIbottom\fR> <\fIright\fR> <\fItop\fR>
Override the bounding box, which, by default, is read from the
EPS file header. When this switch is used, \fBpeps\fR
completely ignores the EPS file header. That means the input
does not even need to have an EPS header.
.TP
.B \-c
Print HTTP content type, i.e. the MIME type.
.B Xpeps
always ignores this option.
.B Peps
ignores it if you select an output file instead of the default \fIstdout\fR.
The content type depends on the type of bitmap produced. \fBPeps\fR will
print the HTTP content type followed by \fBtwo\fR new lines into \fIstdout\fR
and only then will it instruct Ghostscript to produce the bitmap and to
send it to \fIstdout\fR. This lets you use \fBpeps\fR as a CGI program
on web sites to produce on the fly images.

Additionally, if gzip compression is turned on, whether by default or with the
.B \-z
switch,
.B peps
will also print the correct HTTP content encoding to \fIstdout\fR.
.TP
.B \-C
Print HTTP content type and exit. Like with the \fB-c\fR option,
\fBpeps\fR will print the MIME type to \fIstdout\fR. Unlike that,
however, it will follow the MIME type by only \fBone\fR new line,
and then it will exit without processing any input. This is
useful for CGI programming when you want full control of the HTTP header. If
.B xpeps
sees this switch, it just exits.
.TP
.B \-d
Show defaults. Since system administrators can compile
.B peps
and
.B xpeps
with different defaults, you can use this switch to see what
defaults are used on your system.
.TP
\fB\-e\fR [\fItime\fR]
By default, 
.B xpeps
waits for you to press enter before removing the image from the display.
With this option,
.B xpeps
will run in the background and will wait for \fItime\fR seconds before
removing the image. If you do not specify the
\fItime\fR,
.B xpeps
will use the default \fItime\fR to wait. This is a very long time (68 years
on 32\-bit machines), though your system administrator may have
compiled
.B xpeps
with a shorter default. You can find out the default \fItime\fR by running

	\fBxpeps -d\fR

This option has no effect on \fBpeps\fR.
.TP
\fB\-E\fR [\fItime\fR]
Same as \fB\-e\fR, but
.B xpeps
will also print its
.I pid
on \fIstdout\fR. This will allow you to
.I kill
.B xpeps
when you no longer need to see the image. Please note that just closing
the window showing the image will not automatically
.I kill
\fBxpeps\fR, you need to
.I kill
it explicitly, or wait till
.I time
seconds expire (which can be never if you do not specify
.I time
explicitly).
.TP
\fB\-f\fR <\fIformat\fR>
Output in a different bitmap format, where \fIformat\fR is a
Ghostscript bitmap/pixmap output device. This option has no effect on
\fBxpeps\fR.
.TP
\fB\-g\fR \fI1\fR | \fI2\fR | \fI4\fR
Anti-aliasing level of graphics. \fB1\fR is \fIno\fR
anti-aliasing, \fB2\fR is \fIsome\fR anti-aliasing,
\fB4\fR is \fIfull\fR anti-aliasing (default is \fB4\fR).
See also \fB-l\fR and \fB-t\fR.
.TP
\fB\-h\fR <\fIresolution\fR>
Horizontal resolution in ppi (default \fB100\fR).
Overrides \fB-w\fR and \fB-W\fR, as well as the horizontal
resolution set by \fB-r\fR.
.TP
.B \-h
Stop processing the command line, show help and exit. Unlike
the option above, it takes no parameters, so \fBpeps\fR can
distinguish between you asking for help and you setting the
horizontal resolution.
.TP
.B \-i
Use \fIstdin\fR for input. This is the default in version 2.0.
Before that, \fBpeps\fR did not accept input from \fIstdin\fR
at all. There was a reason for that: While EPS files must have an EPS
header before they start the actual Postscript code, the EPS
specification allows the creators of EPS files to defer the
.I %%BoundingBox
comment to the trailer. That presents no problem
with files which \fBpeps\fR can process and rewind. But it
does present a problem when reading the input from \fIstdin\fR
which cannot be rewound.

As of version 2.0, \fBpeps\fR accepts its input from
\fIstdin\fR but in that case it requires that either the
.I %%BoundingBox
comment be in the header, or that you use the \fB-b\fR
switch and set the bounding box explicitly.
.TP
\fB\-l\fR \fI1\fR | \fI2\fR | \fI4\fR
Anti-aliasing level of both, graphics and text. \fB1\fR is \fIno\fR
anti-aliasing, \fB2\fR is \fIsome\fR anti-aliasing,
\fB4\fR is \fIfull\fR anti-aliasing (default is \fB4\fR).
It is a shortcut for \fB-g\fR and \fB-t\fR when you want
to set the same anti-aliasing level for both.
.TP
.B \-m
.B Peps
will output in monochrome (grayscale) \fIPNG\fR format.
.B Xpeps
will use the
.I x11gray4 Ghostscript
device (unless compiled with a different default).
.TP
\fB\-M\fR <\fIfile\fR>
If the \fB-c\fR or the \fB-C\fR switch is used, \fBpeps\fR will
look into \fIfile\fR in search of the proper MIME type for
the output format before it looks anywhere else. See the
.B MIME
section below for more details. This option has no effect on \fBxpeps\fR.
.TP
.B \-n
Output in \fIpnm\fR format. This was the default in version 1.0.
This option has no effect on \fBxpeps\fR.
.TP
\fB\-o\fR <\fIfile\fR>
Output to a file named \fIfile\fR. By default \fBpeps\fR sends
its output to \fIstdout\fR. You can also request \fIstdout\fR explicitly
by entering an empty file name, i.e. \fBpeps -o ""\fR or \fBpeps -o ''\fR.
.TP
.B \-p
Output in color \fIPNG\fR format with \fBpeps\fR, or to the \fIx11\fR
device with \fBxpeps\fR. As of version 2.0, this is the
default on most systems though the system administrator has the
option of using the \fIpnm\fR format with
.B peps
as the default, so it is a good idea to use the \fB-p\fR switch explicitly.
.TP
\fB\-q\fR <\fIheight\fR>
The output will be \fIheight\fR pixels high. This overrides
the vertical resolution set by the \fB-v\fR or \fB-r\fR
switches and discards any overrides of vertical resolution
made by the \fB-Q\fR or \fB-W\fR switches. By default the
height of the bitmap is determined mathematically from the vertical
resolution and the height of the bounding box. With this switch
the vertical resolution is calculated from the \fIheight\fR
in pixels and the height of the bounding box. This switch does
not affect the width of the bitmap or the horizontal resolution
set by the \fB-h\fR, \fB-r\fR, \fB-w\fR or \fB-W\fR
switches, but it does replace any override of the horizontal
resolution made by the \fB-Q\fR switch. In other words,
\fB-Q \fI500 \fB-q \fI100\fR has the same effect as \fB-Q \fI100\fR.
.TP
\fB\-Q\fR <\fIheight\fR>
Does everything the \fB-q\fR switch does, but also affects the width
of the bitmap by setting the horizontal resolution the same as
the new vertical resolution. As a result, the bitmap will be \fIheight\fR
pixels high while keeping its height/width ratio as determined by
the bounding box. This switch overrides the \fB-h\fR, \fB-q\fR, \fB-r\fR
and \fB-v\fR switches, and discards any overrides made by the \fB-w\fR
and \fB-W\fR switches.
.TP
\fB\-r\fR <\fIresolution\fR>
Vertical and horizontal resolution in ppi (default \fB100\fR).
Overrides \fB-h\fR, \fB-q\fR, \fB-Q\fR, \fB-v\fR, \fB-w\fR
and \fB-W\fR.
.TP
.B \-s
Turns off Ghostscript safety. By default \fBpeps\fR
passes the \fB-dSAFER\fR switch to Ghostscript which disables unsafe
Postscript commands. With the \fB-s\fR option, \fBpeps\fR
will \fBnot\fR use that Ghostscript switch. In most cases the use of
this option should be avoided.
.TP
\fB\-t\fR \fI1\fR | \fI2\fR | \fI4\fR
Antialiasing level of text. \fB1\fR is \fIno\fR
anti-aliasing, \fB2\fR is \fIsome\fR anti-aliasing,
\fB4\fR is \fIfull\fR anti-aliasing (default is \fB4\fR).
See also \fB-g\fR and \fB-l\fR.
.TP
\fB\-u\fR <\fIuser\fR>
Search \fIuser\fR's home directory for \fIpeps.mime\fR. See the
.B MIME
section for details. This option has no effect on \fBxpeps\fR.
.TP
\fB\-v\fR <\fIresolution\fR>
Vertical resolution in ppi (default \fB100\fR). Overrides \fB-q\fR
and \fB-Q\fR, as well as the vertical resolution set by \fB-r\fR.
.TP
.B \-v
Stop processing the command line, print \fBpeps\fR version
and exit. Unlike the option above, this one
takes no parameters, so \fBpeps\fR can distinguish between the
setting of the vertical resolution and the request to print its
version.
.TP
\fB\-w\fR <\fIwidth\fR>
The output will be \fIwidth\fR pixels wide. This overrides
the horizontal resolution set by the \fB-h\fR or \fB-r\fR
switches and discards any overrides of horizontal resolution
made by the \fB-Q\fR or \fB-W\fR switches. By default the
width of the bitmap is determined mathematically from the horizontal
resolution and the width of the bounding box. With this switch
the horizontal resolution is calculated from the \fIwidth\fR
in pixels and the width of the bounding box. This switch does
not affect the height of the bitmap or the vertical resolution
set by the \fB-q\fR, \fB-Q\fR, \fB-r\fR or \fB-v\fR
switches, but it does replace any override of the vertical
resolution made by the \fB-W\fR switch. In other words,
\fB-W \fI500 \fB-w \fI100\fR is the same as \fB-W \fI100\fR.
.TP
\fB\-W\fR <\fIwidth\fR>
Does everything the \fB-w\fR switch does, but also affects the height
of the bitmap by setting the vertical resolution the same as
the new horizontal resolution. As a result, the bitmap will be \fIwidth\fR
pixels wide while keeping its height/width ratio as determined by
the bounding box. This switch overrides the \fB-h\fR, \fB-r\fR, \fB-v\fR
and \fB-w\fR switches, and discards any overrides made by the \fB-q\fR
and \fB-Q\fR switches.
.TP
\fB\-x\fR <\fIoffset\fR>
Pad the left side of the image by \fIoffset\fR points. If \fIoffset\fR
is negative, a section of the left side of the image is removed. The value
is in Postscript points (default \fB0\fR).
.TP
\fB\-X\fR <\fIoffset\fR>
Pad the right side of the image by \fIoffset\fR points. If \fIoffset\fR
is negative, a section of the right side of the image is removed. The value
is in Postscript points (default \fB0\fR).
.TP
\fB\-y\fR <\fIoffset\fR>
Pad the bottom of the image by \fIoffset\fR points. If \fIoffset\fR
is negative, a section of the bottom of the image is removed. The value
is in Postscript points (default \fB0\fR).
.TP
\fB\-Y\fR <\fIoffset\fR>
Pad the top of the image by \fIoffset\fR points. If \fIoffset\fR
is negative, a section of the top of the image is removed. The value is in
Postscript points (default \fB0\fR).

Effectively, the \fB-x\fR, \fB-X\fR, \fB-y\fR, and \fB-Y\fR switches
allow you to add a frame around the image (its color will depend on the
underlying Postscript code), or to crop the image.
.TP
.B \-z
Turn on gzip compression. By default on most systems it is on when
the \fB\-c\fR switch is used and the \fIHTTP_ACCEPT_ENCODING\fR environmental
variable lists \fIgzip\fR, off otherwise. The system administrators
can, however, compile \fBpeps\fR with different defaults, so the
.B \-z
switch lets you turn it on explicitly. Regardless of the switch,
the gzip compression is turned off when an output file is
selected with \fB\-o\fR. Of course, you can use redirection if
you want to create a compressed file:

	\fBpeps -z -m image.eps > image.png.gz\fR

By the way, setting the \fIGZIP\fR environmetal variable to
\fI-9\fR will improve the compression. See gzip(1) for more
details. If you are using the Apache web server, you can set
it in the \fI.htaccess\fR file:

	\fBSetEnv GZIP -9\fR

This switch has no effect on \fBxpeps\fR.
.TP
.B \-Z
Turn off gzip compression. This switch has no effect on \fBxpeps\fR.
.TP
.B file
Use \fIfile\fR for input. By default, \fBpeps\fR uses
\fIstdin\fR for its input. You can override it by typing
a file name on the command line, before or after any switches
(of course, if a switch takes additional parameters, you
need to type the file name after the parameters). \fBPeps\fR
will treat the file name as it treats any other option, so if you
enter more than one file name, \fBpeps\fR will use the last one.

That also means that \fB-i\fR \fIfile\fR works as expected: \fIfile\fR
will be the input. Though \fB-i\fR tells \fBpeps\fR to use \fIstdin\fR,
the file name that follows will override it, making \fIfile\fR the input.

In the unlikely case that the name of the \fIfile\fR starts with a \fB\-\fR,
precede it with another \fB\-\fR, otherwise \fBpeps\fR will think it is
a switch. So, if the input file name is \fB\-weird\-\fR, enter it on
the command line like this:

	\fB\-\-weird\-\fR
.PP
See \fBhttp://peps.redprince.net\fR for further details and examples.
.SH	MIME
.PP
\fBPeps\fR can produce on the fly images on line from within CGI scripts.
When used with the \fB-c\fR switch, it will write the necessary HTTP
.I Content-type
header to \fIstdout\fR. In order to do that, it must know the \fBMIME\fR
type of its output. It will look for it in several places. It will quit
looking when it finds the MIME type.
.PP
\fBPeps\fR will search the following places in the following order:
.TP
1.
The file specified with the \fB-M\fR switch.
.TP
2.
The file \fIpeps.mime\fR located in a user directory. Which user?
If the \fB-u\fR switch is used, in the home directory of the user
specified by the switch. If the \fB-u\fR switch is not used, it will
use the home directory of the user specified by the \fIPEPSMIME\fR
environmental variable. If neither the \fB-u\fR switch is used nor
does the \fIPEPSMIME\fR environmental variable exist, \fBpeps\fR
will look for \fIpeps.mime\fR in the home directory of the
effective user running \fBpeps\fR.
.TP
3.
The file \fIpeps.mime\fR located in a system directory. By default
that directory is \fI/etc\fR, but the system administrator can compile
\fBpeps\fR to look for it in a different directory.
.TP
4.
A list hardcoded in \fBpeps\fR.
.PP
If \fBpeps\fR does not find the MIME in any of the above, it will default
to \fIimage/x-device\fR, where \fIdevice\fR is the Ghostscript device used.
.PP
Because web servers normally run as \fInobody\fR or a similar special user,
it is necessary to inform \fBpeps\fR which user's home directory to search
for \fIpeps.mime\fR. This can be done explicitly with \fB-u\fR switch. But
it is so easy to forget to use the switch or perhaps to make a typing
mistake. It is, therefore, a good idea to tell the web server to set the
.I PEPSMIME
environmental variable. On the Apache server, this can be accomplished
by entering the following in the \fI.htaccess\fR file:
.PP
	\fBSetEnv PEPSMIME user\fR
.PP
Substitute the actual user name for \fIuser\fR. Remember to keep
.I peps.mime
readable by the process running the web server. This can be accomplished
by issuing the following command:
.PP
	\fBchmod 644 peps.mime\fR
.PP
It is only necessary to issue this command once.
.SH SEE ALSO
.TP
gs(1), gzip(1)
.SH HISTORY
.PP
Both \fBpeps\fR and this manual were written by G. Adam Stanislav, <adam at
redprince dot net>. Version 1.0 was written to meet the needs of the FreeBSD
documentation project to convert Encapsulated Postscript to PNG bitmaps.
Version 2.0 greatly expands on \fBpeps\fR abilities, as it now can be used as a
Unix filter, as an interpreter, and as a tool to produce on the fly images on line.
.B Xpeps
was added in version 2.0 as a debugging tool for 
.B peps
CGI scripts.