@c $Id: postscript.texinfo,v 1.17 2001/06/04 15:29:10 m Exp m $
@node PostScript, , Importing Images, Images
@chapter PostScript
@cindex PostScript
@cindex Ghostscript
@cindex EPS
@cindex Encapsulated PostScript
@cindex Duggan, Angus 
@cindex PSUtils
@pindex ghostview
@pindex gs
@pindex psutils

@flushleft
@sf{Debian}: @file{gs}
@sf{Debian}: @file{psutils}
@sf{WWW}: @url{ftp://www.gnu.org/pub/gnu/ghostscript/}
@sf{WWW}: @url{ftp://ftp.dcs.ed.ac.uk/pub/ajcd/}
@sf{WWW}: @url{http://www.cappella.demon.co.uk/tinyfiles/tinymenu.html}
@end flushleft
@*
@noindent
PostScript is a programming language, used to describe
the way a ``page'' (usually a physical sheet of paper) should
look. PostScript files are text files containing the PostScript
commands for drawing images to be printed on pages.

Like plain text files, PostScript files are commonly found on the
Internet (and are used by commercial printers) because, as with plain
text, they can be shared across platforms and hardware without
difficulty. The same PostScript file can be output on a high-end display
or printed on a low-end printer, to the best of that hardware's
capability.  PostScript is a compact and elegant format.

While it's possible to write directly in the PostScript language, and
some people have become adept at programming PostScript, so many tools
and applications convert files to and from PostScript that you don't
have to. @xref{Enscript, , Converting Plain Text for Output}, for a way
to convert plain text into PostScript.

Ghostscript is a free implementation of the PostScript language. The
@code{gs} tool is a Ghostscript interpreter that is used to convert
files from PostScript to other formats, usually for printing to a
non-PostScript printer (@pxref{Preparing PS, , Preparing a PostScript
File for Printing}). The @code{ghostview} tool is used to preview
PostScript files on the screen (@pxref{Previewing PS, , Previewing a
PostScript File}).

EPS, or Encapsulated PostScript, is a file format that describes the
contents of a box within a page. EPS files can be embedded in the page
of a PostScript file, and are therefore commonly used when inserting an
illustration into a document (for example, all of the illustrations in
the @cite{Cookbook} are EPS format files). You can view and print EPS
files just as you would PostScript files.

This chapter includes recipes for formatting and manipulating PostScript
files. Recipes are separated according to whether they work on the
individual, @dfn{logical pages} in a PostScript file (the numbered pages
in the file that are not necessarily the physical pages of output), and
those that work on the entire file as a whole.  

Unless otherwise indicated, the tools in this chapter are part of Angus
Duggan's PSUtils package. These tools can be useful for other purposes
than those described below; see their respective @code{man} pages for
more details.

@menu
* PS Pages::                    Manipulating the pages of a PostScript file.
* PS Files::                    Manipulating a PostScript file as a whole.
* PS Conversions::              Converting PostScript to other formats.
@end menu


@node PS Pages, PS Files, PostScript, PostScript
@comment  node-name,  next,  previous,  up
@section Manipulating PostScript Pages
@cindex manipulating PostScript pages
@cindex PostScript pages, manipulating

@noindent
These recipes work on individual @emph{pages} of PostScript files, and
not the entire file itself.

@menu
* DVIPS Pages::                 Extracting DVI pages to PostScript.
* Extracting Pages::            Extracting pages from a PostScript file.
* Combining Pages::             Combining PostScript pages.
* PS Signatures::               Putting PostScript pages into signatures.
@end menu

@node DVIPS Pages, Extracting Pages, PS Pages, PS Pages
@comment  node-name,  next,  previous,  up
@subsection Extracting DVI Pages to PostScript
@cindex extracting DVI pages to PostScript
@cindex DVI pages, extracting to PostScript
@cindex PostScript pages, extracting from DVI
@pindex dvips

@noindent
To extract specific pages of a DVI (``DeVice Independent'') file to
PostScript, use @code{dvips} and give the page or hyphenated page ranges
to output with the @samp{-pp} option.

@itemize @bullet
@item
To extract only the first page from the file @file{abstract.dvi} and
send the PostScript output to the printer, type:

@example
$ @kbd{dvips -pp1 abstract.dvi @key{RET}}
@end example
@end itemize

By default, @code{dvips} will output to the printer; to save the
PostScript output to a file, give the file name to be used for output
with the @samp{-o} option.

@itemize @bullet
@item
To output as PostScript the pages 137 to 146 of the file
@file{abstract.dvi} to the file @file{abstract.ps}, type:

@example
$ @kbd{dvips -pp137-146 -o abstract.ps abstract.dvi @key{RET}}
@end example
@end itemize


@node Extracting Pages, Combining Pages, DVIPS Pages, PS Pages
@comment  node-name,  next,  previous,  up
@subsection Extracting Pages from a PostScript File
@cindex extracting pages from a PostScript file
@cindex PostScript, extracting pages
@cindex pages, extracting from a PostScript file
@pindex psselect

@noindent
Use @code{psselect} to select pages from a PostScript file; when you
give an input file, it outputs a new PostScript file containing the
specified pages.

Give the pages to select as arguments to the @samp{-p} option; you can
list single pages and ranges of pages separated by commas. Give ranges
as two numbers between a hyphen; thus, @samp{4-6} specifies pages four
through six, inclusive. If you omit the first number in a pair, the
first page is assumed, and if you omit the last number, the last page is
assumed. Pages are written to the new file in the order they are
specified.

@itemize @bullet
To select page 47 from the PostScript file @file{newsletter.ps} and
output it to the file @file{selection.ps}, type:

@example
$ @kbd{psselect -p47 newsletter.ps selection.ps @key{RET}}
@end example

@item
To select the first ten pages, page 104, pages 23 through 28, and page 2
from the file @file{newsletter.ps} and write it to the file
@file{selection.ps}, type:

@example
$ @kbd{psselect -p1-10,104,23-28,2 newsletter.ps selection.ps @key{RET}}
@end example
@end itemize

In the preceding example, page 2 is selected twice.

Prefix a number with an underscore (@samp{_}) to indicate that the given
page number is relative to the last page, counting backwards toward the
first page.

@itemize @bullet
@item
To select the second-to-last through the tenth-to-last pages from the
PostScript file @file{newsletter.ps} and output them to the file
@file{selection.ps}, type:

@example
$ @kbd{psselect -p_2-_10 newsletter.ps selection.ps @key{RET}}
@end example

@item
To select the second-to-last through the tenth pages from the PostScript
file @file{newsletter.ps} and output them to the file
@file{selection.ps}, type:

@example
$ @kbd{psselect -p_2-10 newsletter.ps selection.ps @key{RET}}
@end example
@end itemize

Use the @samp{-e} option to select all even-numbered pages, and use the
@samp{-o} option to select all odd-numbered pages.

@itemize @bullet
@item
To select all of the even pages in the file @file{newsletter.ps} and
write them to a new file, @file{even.ps}, type:

@example
$ @kbd{psselect -e newsletter.ps even.ps @key{RET}}
@end example

@item
To select all of the odd pages in the file @file{newsletter.ps} and
write them to a new file, @file{odd.ps}, type:

@example
$ @kbd{psselect -o newsletter.ps odd.ps @key{RET}}
@end example
@end itemize

Use an underscore (@samp{_}) alone to insert a blank page, and use
@samp{-r} to output pages in @emph{reverse} order.

@itemize @bullet
@item
To select the last ten pages of file @file{newsletter.ps}, followed by a
blank page, followed by the first ten pages, and output them to a new
file, @file{selection.ps}, type:

@example
$ @kbd{psselect -p_1-_10,_,1-10 newsletter.ps selection.ps @key{RET}}
@end example

@item
To select the pages 59, 79, and 99 in the file @file{newsletter.ps}, and
output them in reverse order (with the 99th page first) to a new file,
@file{selection.ps}, type:

@example
$ @kbd{psselect -p59,79,99 -r newsletter.ps selection.ps @key{RET}}
@end example
@end itemize

@sp .25
@noindent
@strong{NOTE:} The same result as the preceding example above could have
been done by omitting the @samp{-r} option and just listing the three
pages in the reverse order:

@example
$ @kbd{psselect -p99,79,59 newsletter.ps selection.ps @key{RET}}
@end example


@node Combining Pages, PS Signatures, Extracting Pages, PS Pages
@comment  node-name,  next,  previous,  up
@subsection Combining PostScript Pages
@cindex combining PostScript pages
@cindex PostScript pages, combining
@cindex lanscape orientation, PostScript pages in
@cindex seascape orientation, PostScript pages in
@pindex psnup

@noindent
Use @code{psnup} to print multiple PostScript pages on a single sheet of
paper; give as an option the number of pages to be combined (or put
``up'') on each sheet.

@itemize @bullet
@item
To make a new PostScript file, @file{double.ps}, putting two pages from
the file @file{single.ps} on each page, type: 

@example
$ @kbd{psnup -2 single.ps double.ps @key{RET}}
@end example
@end itemize

To specify the paper size, give the name of a standard paper size as an
argument to the @samp{-p} option: a3, a4, a5, b5, letter, legal,
tabloid, statement, executive, folio, quarto, or 10x14. You can also
specify any height and width with the @samp{-h} and @samp{-w} options;
units can be specified in centimeters (followed by @samp{cm}) or inches
(followed by @samp{in}). If no size is specified, @code{psnup} assumes a
paper size of a4.

Use the @samp{-l} option when pages are in landscape orientation
(rotated 90 degrees counter-clockwise from portrait orientation), and
@samp{-r} when pages are in seascape orientation (rotated 90 degrees
clockwise from portrait orientation).

Pages are placed in ``row-major'' layout in the output file, where
logical pages are placed in rows across the page. Use the @samp{-c}
option to specify a ``column-major'' layout, where logical pages are
placed in @emph{columns} down the page. Scale the size of the pages by
giving a percentage to multiply the page size by as an argument to the
@samp{-s} option; for example, @samp{-s .5} scales pages to 50 percent
of their original size.

To draw a border around each page, specify the border's width in points
as an argument to the @samp{-d} option (if no width is specified, a
value of 1 is assumed).


@node PS Signatures, , Combining Pages, PS Pages
@comment  node-name,  next,  previous,  up
@subsection Arranging PostScript Pages in Signatures
@cindex arranging PostScript pages in signatures
@cindex PostScript pages, arranging in signatures
@cindex signatures, PostScript
@pindex psbook

@noindent
A @dfn{signature} is a group of pages in a document corresponding to
sheets of paper folded and bound; these pages are normally not in
sequential order in a document (for example, in a document with
eight-page signatures, page 8 and page 1 might both be printed on the
same sheet of paper).

To rearrange the pages of a PostScript file by signature---usually for
printing the file as a book or booklet---use @code{psbook}. Give as
arguments the name of the PostScript file to read from and the name to
use for the output file; it reads the contents of the first, rearranges
the pages, and then writes the PostScript output to the second file.

@itemize @bullet
@item
To rearrange the pages of file @file{newsletter.ps} into a signature and
write it to the file @file{newsletter.bound.ps}, type: 

@example
$ @kbd{psbook newsletter.ps newsletter.bound.ps @key{RET}}
@end example
@end itemize

By default, @code{psbook} uses one signature for the entire file. If
the file doesn't contain a multiple of four pages, it adds blank pages
to the end.

To specify the size of the signature to use---in other words, the number
of pages that will appear on a single piece of paper---give the number
as an argument to the @samp{-s} option. Signature size is always a
multiple of four.

@itemize @bullet
@item
To rearrange the pages of file @file{newsletter.ps} into an eight-sided
signature and write it to @file{newsletter.bound.ps}, type:

@example
$ @kbd{psbook -s8 newsletter.ps newsletter.bound.ps @key{RET}}
@end example
@end itemize


@node PS Files, PS Conversions, PS Pages, PostScript
@comment  node-name,  next,  previous,  up
@section Manipulating PostScript Documents
@cindex manipulating PostScript documents
@cindex PostScript documents, manipulating

@noindent
These recipes work on a PostScript document as a whole.

@menu
* Resizing PS::                 Resizing a PostScript file.
* Combining PS::                Combining PostScript files.
* PS Booklets::                 Making PostScript booklets.
@end menu

@node Resizing PS, Combining PS, PS Files, PS Files
@comment  node-name,  next,  previous,  up
@subsection Resizing a PostScript Document
@cindex resizing a PostScript document
@cindex PostScript document, resizing a
@pindex psresize

@noindent
Use @code{psresize} to resize a PostScript file. It takes as arguments
the file to resize and the output file to write to; you must also
specify the page size of the output file, using the same format as with
the @code{psnup} tool: use @samp{-p} or @samp{-h} and @samp{-w} to
specify the size of the output file, and use @samp{-P} to specify the
size of the input file (@pxref{Combining Pages, , Combining PostScript
Pages}).

@itemize @bullet
@item
To resize the PostScript file @file{double.ps} to US letter-sized paper,
writing output to a new file, @file{doublet.ps}, type:

@example
$ @kbd{psresize -pletter double.ps doublet.ps @key{RET}}
@end example
@end itemize


@node Combining PS, PS Booklets, Resizing PS, PS Files
@comment  node-name,  next,  previous,  up
@subsection Combining PostScript Documents
@cindex combining PostScript documents
@cindex PostScript documents, combining
@pindex psmerge

@noindent
Use @code{psmerge} to concatenate and merge multiple PostScript files
into a single file. Give the names of the files to be merged as
arguments, and @code{psmerge} outputs them to the standard output in the
order given. You can also specify an output file name with the @samp{-o}
option (don't put any spaces between the file name and the option).

@itemize @bullet
@item
To merge the files @file{slide1.ps}, @file{slide2.ps}, and
@file{slide3.ps} into a new PostScript file, @file{slideshow.ps}, type:

@example
$ @kbd{psmerge -oslideshow.ps slide1.ps slide2.ps slide3.ps @key{RET}}
@end example
@end itemize

@sp .25
@noindent
@strong{NOTE:} As of this writing, @code{psmerge} only works with
PostScript files that were made with the same application---which means,
for example, that you can merge multiple files made with @TeX{}, or
multiple files made with @code{xfig}, but not a combination of the two.


@node PS Booklets, , Combining PS, PS Files
@comment  node-name,  next,  previous,  up
@subsection Arranging a PostScript Document in a Booklet
@cindex PostScript document, arranging in a booklet
@cindex booklet, arranging a PostScript document in a

@noindent
To arrange the pages in a PostScript file to make booklets, rearrange
the file in a signature with @code{psbook}, use @code{psnup} to arrange
the pages---two to a printed page in landscape mode---and then use
@code{pstops} to output first the odd and then the even pages.

The trick to doing this properly is to first determine exactly what you
need to do and then calculate the proper measurements for use with
@code{pstops}.

@itemize @bullet
@item
To make a booklet from the file @file{newsletter.ps}:

@enumerate
@item
Rearrange the pages into a signature:

@example
$ @kbd{psbook newsletter.ps newsletter.signature.ps @key{RET}}
@end example

@item
Put the pages two to a page in landscape orientation, at 70 percent of
their original size (typed all on one line):

@example
$ @kbd{psnup -l -pletter -2 -s.7 newsletter.signature.ps >
newsletter.2up.ps @key{RET}} 
@end example

@item
Output the odd pages:

@example
$ @kbd{pstops "2:0(1in,0in)" newsletter.2up.ps > odd.ps @key{RET}}
@end example

@item
Output the even pages:

@example
$ @kbd{pstops "2:-1(1in,0in)" newsletter.2up.ps > even.ps @key{RET}}
@end example
@end enumerate
@end itemize

Then, to print the booklet, you send @file{odd.ps} to the printer, load
the printed pages in the manual feed tray and then send @file{even.ps}
to the printer. This prints the odd and even pages on opposite sides of
the sheets.

@itemize @bullet
@item 
To make a double-sized booklet on letter-sized paper in landscape
orientation, from a file using letter-sized portrait orientation,
type:

@example
@cartouche
$ @kbd{psbook input.ps > temp1.ps @key{RET}}
@var{...processing messages...}
$ @kbd{psnup -l -pletter -2 -s.7 temp1.ps > temp2.ps @key{RET}}
@var{...processing messages...}
$ @kbd{pstops "2:0(1in,0in)" temp2.ps > odd.ps @key{RET}}
@var{...processing messages...}
$ @kbd{pstops "2:-1(1in,0in)" test2.ps > even.ps @key{RET}}
@var{...processing messages...}
$
@end cartouche
@end example
@end itemize


@node PS Conversions, , PS Files, PostScript
@comment  node-name,  next,  previous,  up
@section Converting PostScript
@cindex converting PostScript
@cindex PostScript, converting

@noindent
These recipes show how to convert PostScript files to other formats.
See also the recipes for preparing PostScript files for printing,
@ref{Preparing PS, , Preparing a PostScript File for Printing}.

@menu
* PS To PDF::                   Converting PostScript to PDF.
* PS To Text::                  Converting PostScript to plain text.
@end menu


@node PS To PDF, PS To Text, PS Conversions, PS Conversions
@comment  node-name,  next,  previous,  up
@subsection Converting PostScript to PDF
@cindex converting PostScript to PDF
@cindex PostScript, converting to PDF
@cindex PDF, from PostScript input
@cindex Ghostscript
@pindex ps2pdf
@pindex gs

@noindent
Use @code{ps2pdf}, part of the @code{gs} (``Ghostscript'') package, to
convert a PostScript file to PDF. Give as arguments the name of the
PostScript file to read from, and the name of the PDF file to write to.

@itemize @bullet
@item
To make a PDF file @file{sutra.pdf} from the input file
@file{sutra.ps}, type:

@example
$ @kbd{ps2pdf sutra.ps sutra.pdf @key{RET}}
@end example
@end itemize

This command writes a new file in PDF format called
@file{sutra.pdf}. The original file, @file{sutra.ps}, is not altered.

@sp .25
@noindent
@strong{NOTE:} To make proper PDF conversions, make sure that you have
@code{gs} version 6.01 or higher installed; use the @samp{-v} option
with @code{gs} to output the installed version.


@node PS To Text, , PS To PDF, PS Conversions
@comment  node-name,  next,  previous,  up
@subsection Converting PostScript to Plain Text
@cindex converting PostScript to plain text
@cindex PostScript, converting to plain text
@cindex text, from PostScript
@pindex pstoascii

@noindent
To convert a PostScript file to plain text, use @code{ps2ascii}. Give as
arguments the name of the PostScript file to read from, and the name of
the text file to write to.

@itemize @bullet
@item
To make a text file, @file{sutra.txt}, from the input file
@file{sutra.ps}, type:

@example
$ @kbd{ps2ascii sutra.ps sutra.txt @key{RET}}
@end example
@end itemize

This command writes a text file called @file{sutra.txt}. The original
file, @file{sutra.ps}, is not altered.