% This file was converted from HTML to LaTeX with Nathan Torkington's
% html2latex program
% Version 0.9b
\chapter{Post Processing}
There are often times when you will want to take an existing 
PostScript document and manipulate it in some way.  For example, you 
may be publishing a book, and you want to print the pages with wide 
margins for proofing notes (but you don't want to modify the book's 
layout).  Maybe you are printing out some 100-page manual, and you 
want to avoid using most of a rain forest to print it.  Maybe you want 
to print out some document with the word ``Draft'' stamped {\em 
beneath} the pages.  All of these things can be done in PostScript by 
a postprocessor (that is, a program which manipulates an existing 
PostScript file).  Moreover, these are all things which may be 
difficult to manage in the program you used to generate the files.
 
In this section, I'll show you the basic PostScript code to do each of 
these jobs and how to use EPS comments to find the right places to 
insert the additional PostScript.

You are welcome to use these programs as you will.  Bear in mind, 
however, that there are professionally written programs that do these 
jobs and more.  I strongly suggest that you look into buying such a 
program rather than writing your own.  Generally, they have already 
solved most of the problems.  Also, these packages usually come with 
tools you did not even knew were possible.  These examples, therefore, 
are more to give you a taste of what is possible and how to do it, in 
case you want to roll your own post-processing utility.

\section*{Galley Proofs}

A galley proof is a printout of a document in which the margins are 
especially large.  The idea is that you can read over what you have 
printed and have room for writing comments.  This system was important 
in the days of manuscripts and lead-cast type, because the layout of 
your document was under the control of the publisher's typesetter.  
You would receive a galley proof from your publisher and make comments 
about mistakes or changes to be made.
 
When you have control of the typesetting, galley proofs are not so 
important, but you may still want to have them.  Many systems will not 
let you make a galley proof, but fortunately it is not hard to do.
 
The main idea is that you want to scale each page down (to make room 
for the extra big margins) and then translate the document up and to 
the right.
 
Let us say that we want to give ourselves an extra inch of margin on 
the vertical margins (and scale the horizontals to keep the 
proportions correct).  Here is the PostScript code to do that:

\begin{verbatim}
    gsave
      8.5 6.5 sub 2 div inch               % Center page horizontally...
      11 11 6.5 8.5 div mul sub 2 div inch %  and vertically
      translate
      6.5 8.5 div               % Scale page horizontally...
      dup                       %  and vertically
      scale
      % original page code here...
    grestore
\end{verbatim}

Here is a slightly faster version.  Here, we allow the postprocessor 
to do the math for us.  This will print more quickly, since each page 
does not need to do its own division:

\begin{verbatim}
    gsave
      72 93 translate
      .7647 .7647 scale
      % original page code here...
    grestore
\end{verbatim}

Why the \code{gsave} and \code{grestore}?  Well, a good rule of thumb 
is to {\em always} save the graphics state before you go about 
changing it (and remember to restore it when you are done).  Also, one 
of the rules of the document structuring convention is that each page 
should restore the state of the system to what it was when the page 
was about to start.  In other words, the code to layout a page should 
not alter the permanent state of the system (graphics or otherwise).  
This assures that pages can be reordered after the PostScript has been 
generated.

\subsection*{The Hard Part}

The hard part of all of this is knowing {\em where} to insert the new 
code.  Where does one page begin and another end?  You could look for 
calls to showpage, but many programs define their own versions of this 
operator (in the code that is generated by \code{dvips}, for instance, 
it is called \code{eop}).
 
So, how {\em do} we go about recognizing pages?  The document 
structuring conventions provide us with some handy comments for 
flagging page information.  The most important is the \code{\%\%Page:} 
comment.  This comment specifies that the next piece of code is the 
first one for the new page (in fact, it also tells you which page it 
is).  The end of the document should also be marked with a \code{\%\%Trailer:}
comment and a \code{\%\%EOF} comment.  The \code{\%\%Trailer:} comment
specifies that code to be run at the end of the 
document is about to be given (so, we are done with the pages).  The 
\code{\%\%EOF} comment specifies that we are done with the file.  
Again, this specifies that we have processed the last page.
 
So, using these comments, how can we add the needed PostScript?  Well, 
we can start by looking for the first \code{\%\%Page:} comment.  When 
we find it, we insert the \code{translate} and \code{scale} commands 
right after it.  Thereafter, we will preceed each \code{\%\%Page:} with 
a \code{grestore} and insert the translate and scale code after the comment.  
This process continues until we find either a \code{\%\%Trailer:} or a 
\code{\%\%EOF} comment.  The first of these we find is preceeded by a 
\code{grestore}.
 
This is all we need to do.  To make things a bit more concrete, here 
is a {\sc PERL} script to do the job (to make things a bit more 
interesting, I have added a light line around the original page's 
image, so you can know how big it is):
\begin{verbatim}
#!/usr/local/bin/perl
$flag = 0;
while (<>) {
    if (/^%%Page:/) {
      if ($flag) {
          print "grestore\n";
      }
      $flag = 1;
      print $_;
      print "gsave 72 93 translate .7647 .7647 scale\n";
      print "gsave .75 setgray newpath -1 -1 moveto 614 0 rlineto\n";
      print "0 794 rlineto -614 0 rlineto closepath stroke grestore\n";
    } elsif (/^%%Trail/) {
      if ($flag) {
        print "grestore\n";
      }
      print $_;
      $flag = 0;
    } elsif (/^%%EOF/) {
      if ($flag) {
        print "grestore\n";
      }
      print $_;
      $flag = 0;
    } else {
      print;
    }
}
\end{verbatim}

Now, this script is not perfect. Many PostScript files do not comform
as they should. This script can, however, serve as a starting point
for your own, more robust code.

\section*{Two Up}
There are occassions when you might want to print more than one page 
of a PostScript document on a piece of paper.  For example, you may 
have a collection of slides for a presentation, and you may want to 
print them out in condensed form for a kind of digest hand-out.  This 
kind of printing, where two pages are printed side-by-side on a piece 
of paper is called ``two-up,'' for the two pages facing up.  This idea 
generalizes readily to any number of pages (though, of course, 
legibility goes down quickly as the number of pages goes up).  In its 
general form, it is called ``n-up.''

\subsection*{The PostScript}
What is it that is necessary to print in two-up mode?  First, we need 
to translate and rotate each page into the right location of the page, 
then we need to make sure that the page fits in the new area reserved 
for it (we will need to scale it down to about half its original 
size).  If we place the two pages side by side, we will get proper 
two-up form.

The code I will present here will place the odd pages on the left (as 
your looking at the page in landscape orientation) and the even pages 
on the right.  You could do it the other way around, if that makes 
more sense to you.

Here is the code we must wrap around the odd pages:

\begin{verbatim}
    gsave
      504 30 translate  % Position page in middle of region
      90 rotate         % Aim it in the right direction
      .5 .5 scale       % make it small enough
      % original page code here...
    grestore
\end{verbatim}

And here is the code for the even pages:

\begin{verbatim}
    gsave
      504 426 translate % Position page in middle of region
      90 rotate         % Aim it in the right direction
      .5 .5 scale       % make it small enough
      % original page code here...
    grestore
\end{verbatim}

Now, you will notice that I used some curious numbers in the 
\code{translate} command.  The reason I chose these particular numbers 
was that I wanted to center each page in its half of the page.  I knew 
I was going to scale by 0.5, so I computed how much whitespace was 
left and added in the appropriate fudge-factor to center the pages.

You may also notice that I wrap a \code{gsave} and a \code{grestore} 
around the page and the additional code?  The reason for this is that 
each page {\em must} leave the state of the printer unchanged when it 
has been printed.  If you permanently change the state, that state 
change will be in affect for all subsequent pages.  By following this 
rule, you make the pages independent of order.  Some print servers 
must shuffle page order in order to print the document correctly; 
since my pages are independent (at least as far as my code is 
concerned), they will print correctly.

\subsection*{The Hard Part}
Now comes the hard part of recognizing where the pages begin.  The 
technique is essentially the same as what we used for galley proofs, 
so I will spare you the logic here.  Essentially, we will look for 
\code{\%\%Page:} comments.  We will, however, need to keep track of 
whether the current page is an odd page or an even page and insert the 
correct translation code.  Also, as before, we must be careful about 
inserting grestores before subsequent pages and before the \code{\%\%Trailer}
or \code{\%\%EOF} comments.
 
Here is the {\sc PERL} script to do the job:

\begin{verbatim}
#!/usr/local/bin/perl
$flag = 0;            # We have not yet found a page
$even = 0;            # First page is an odd page
$page = 1;            # Start at page #1
$pages = 1;           # Allow %%Pages comment
while (<>) {
    if (/^%%Pages:/ && $pages) {
      print "%%Pages: (atend)\n";
      $pages = 0;
    } elsif (/^%%Page:/) {      # We have found a page
      if ($flag) {
        print "restore\n";    # restore if it isn't the first
      }
      $flag = 1;
      if ($even) {        # Translate for even pages
        print "save\n";   # gsave
        print "504 426 translate\n";
        $even = 0;
        $page++;
      } else {        # Translate for odd pages
        printf("%%%%Page: %d %d\n", $page, $page);
        print "save /showpage {} def\n";
        print "504 30 translate\n";
        $even = 1;
      }            # Code to rotate and shrink
      print "90 rotate .5 .5 scale\n";
    } elsif (/^%%Trail/) {    # Cleanup if a %%Trailer is found
      if ($flag) {
        print "restore\n";
      }
      print $_;
      printf("%%%%Pages: %d\n", \$page);
      $flag = 0;
    } elsif (/^%%EOF/) {    # Cleanup if an %%EOF is found
      if ($flag) {
        print "restore\n";
      }
      print $_;
      $flag = 0;
    } else {
      print;
    }
}
\end{verbatim}

Note the basic similarity with the script for the galley proofs.  
There are some additions, however.  Because we are taking two pages 
and printing them on one page, we need to modify the page numbers.  
The \code{\%\%Pages:} comment specifies how many pages are in the 
document.  If you specify \code{\%\%Pages: (atend)}, you are specifying 
that you do not know the exact number of pages, but you will give the 
information later.

An additional complication is the use of \code{save} and 
\code{restore} rather than \code{gsave} and \code{grestore}.  These 
operators save the {\em entire} state of the printer and restore it 
just as \code{gsave} and \code{grestore} work with the {\em graphics} 
state.  In fact, an implicit \code{gsave} is done by \code{save}; and 
an implicit \code{grestore} is done by \code{restore}.  The reason 
these are used is so that I can redefine \code{showpage} to a 
do-nothing procedure (\code{/showpage \{\} def}) for the odd pages.  
This trick prevents the page from being ejected when the odd page does 
its end of page routines.  Unfortunately, this trick only works if the 
document calls \code{showpage} by name.  If the document bound 
\code{showpage} up or calls some of the lower level operators, this 
program would need to be more sophisticated.

\section*{Draft}
There are times when you will need to stamp a document as a draft.  
That is, you will want to mark the document so that no one can mistake 
it for a finished document, but you do not want to make it illegible.  
Watermarks are perfect for this task.
 
A watermark is any marking which appears {\em behind} the text of the 
page and is generally quite light in apprearence.  The main text of 
the page should be legible above it, and the watermark should be 
visible beneath.

\subsection*{The PostScript}
The PostScript for generating a watermark is quite simple.  After each 
\code{\%\%Page:} comment (and before the actual PostScript code for the 
page, you should insert the code to draw the watermark (safely wrapped 
between a \code{gsave} and \code{grestore} pair.

As a concrete example, let us say we want to print the word ``Draft'' 
down the page beneath the actual text of the page.  Such a watermark 
would be suitable for printing drafts of documents.

Here is the PostScript code to print the watermark:
\begin{verbatim}
    gsave
      .75 setgray
      /Helvetica-Bold findfont 72 scalefont setfont
      80 80 800 {
        306 exch moveto                     % move to the center of the line
        (Draft) dup
        stringwidth pop 2 div neg 0 rmoveto % Center the text horizontally
        show                                % Show the text
      } for                                 % and keep doinging it
    grestore
\end{verbatim}

\subsection*{The Hard Part}
The hard part of the job is to find the pages.  Fortunately, we can 
use the same technique we used for the galley proofs.  Actually, our 
requirements are simpler.  We do not need to wrap the original page 
code in a gsave, grestore pair, as we did before.
 
And here is the PERL script to do the job:

\begin{verbatim}
#!/usr/local/bin/perl
$flag = 0;
while (<>) {
    if (/^%%Page:/) {
      if ($flag) {
        print "grestore\n";
      }
      $flag = 1;
      print $_;
      print "gsave\n";
      print ".75 setgray\n";
      print "/Helvetica-Bold findfont 72 scalefont setfont\n";
      print "80 80 800 { 306 exch moveto\n";
      print "(Draft) dup\n";
      print "stringwidth pop 2 div neg 0 rmoveto show } for\n";
      print "grestore\n";
    } else {
      print;
    }
}
\end{verbatim}
