summaryrefslogtreecommitdiff
path: root/dviware/psprint/unix/userguide.tex
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /dviware/psprint/unix/userguide.tex
Initial commit
Diffstat (limited to 'dviware/psprint/unix/userguide.tex')
-rw-r--r--dviware/psprint/unix/userguide.tex563
1 files changed, 563 insertions, 0 deletions
diff --git a/dviware/psprint/unix/userguide.tex b/dviware/psprint/unix/userguide.tex
new file mode 100644
index 0000000000..fe3accffbf
--- /dev/null
+++ b/dviware/psprint/unix/userguide.tex
@@ -0,0 +1,563 @@
+% LaTeX source for PSPRINT User Guide.
+% System-dependent details are indicated by the string "SYSDEP".
+% Cross references are indicated by the string "XREF".
+% Feel free to make modifications applicable to your site.
+
+\documentstyle[11pt]{article}
+
+\nofiles % no auxiliary output
+
+% make sure leading/trailing spaces work correctly in \verb
+{\obeyspaces\gdef {\leavevmode\null\enskip\null}}
+
+% 1 inch margins at left and right:
+\oddsidemargin=0in
+\evensidemargin=0in
+\textwidth=6.25truein % A4 paper is 8.25in wide
+
+% 1 inch margins at top and bottom:
+\headheight=0pt
+\headsep=0pt
+\topmargin=0in
+\textheight=9.7in % A4 paper is 11.7in high
+
+\parindent=0pt
+\parskip=\medskipamount
+\renewcommand\labelitemii{ } % don't use en-dash in nested itemize
+\itemsep=0pt
+
+\def\DVItoVDU{DVIto\kern-.15em VDU}
+\def\aligneddots{\leaders\hbox to .75em{\hss.\hss}\hfill}
+
+\begin{document}
+
+\vspace*{\fill}
+
+\begin{center}
+\Huge\bf PSPRINT User Guide\\ [3mm]
+\normalsize\bf Version 3.0 for Pyramid/OSx\\
+\bf Andrew Trevorrow, October 1988
+\end{center}
+
+\bigskip
+\bigskip
+
+The PSPRINT command drives a variety of PostScript printers
+and can be used to print a DVI file (produced by \TeX\ or \LaTeX),
+a raw PostScript file, or an ordinary text file.
+The currently supported printers include the Apple LaserWriter,
+the Linotronic~300 and DEC's PrintServer~40.
+
+\bigskip
+\begin{center}
+\bf Contents
+\end{center}
+
+ % XREF: check that page #s are up-to-date
+\TeX\ Output \aligneddots\ 1\\
+PostScript Output \aligneddots\ 1\\
+Text Output \aligneddots\ 1\\
+Command Options \aligneddots\ 2\\
+Error Messages \aligneddots\ 5\\
+Using PostScript Fonts \aligneddots\ 6\\
+Using PostScript Graphics \aligneddots\ 7
+
+\vspace*{\fill}
+
+\thispagestyle{empty}
+
+\newpage
+\setcounter{page}{1}
+
+\subsection*{\TeX\ Output}
+
+PSPRINT looks for a DVI file by default. To print \verb|foo.dvi|, simply type:
+\begin{center}
+\verb|psprint foo|
+\end{center}
+PSPRINT will translate \verb|foo.dvi| into
+a temporary PostScript file called \verb|foo.tmp|.
+The DVI and \TeX\ page numbers are displayed as each page is translated.
+(The order in which pages are translated depends on the PostScript
+device being used.)
+If no errors are found, the temporary file is automatically sent to the
+appropriate queue where it is printed (and then deleted).
+
+\subsection*{PostScript Output}
+
+PostScript is a complete programming language with a powerful set of operators
+for manipulating text and graphics. A PostScript program is an ordinary text
+file. If you give it a name like \verb|foo.ps| then sending
+it to the printer is simple:
+\begin{center}
+\verb|psprint foo.ps|
+\end{center}
+If you decide to use some other file extension you'll have to add the
+\verb|-ps| option.
+The final section in this document % XREF
+describes how to merge a PostScript file with a \TeX\ source file.
+People who want to write PostScript programs will need to get the
+{\sl PostScript Language Reference Manual\/} and the
+{\sl PostScript Language Tutorial and Cookbook}. Both books are by
+Adobe Systems Incorporated and published by Addison-Wesley.
+
+\subsection*{Text Output}
+
+To print a normal text file, just use any file extension except
+\verb|.dvi| or \verb|.ps|:
+\begin{center}
+\verb|psprint foo.lis|~~~or~~~\verb|psprint foo.dat|~~~or~~~\dots
+\end{center}
+The output is {\em not\/} collated.
+By default you get 66 lines per page, and any lines more than 80
+characters long are truncated. The \verb|-l| option will
+rotate the paper so that you can have lines up to 132 characters long
+(but only 50 lines per page).
+
+Type `\verb|psprint foo.ps -text|' if you want to print a PostScript file
+rather than have it interpreted. You'll also have to use \verb|-text| if you
+want to print a text file called \verb|foo| but \verb|foo.dvi| also exists.
+
+The \verb|-two| and \verb|-wide| options are variants of \verb|-text|
+that use a smaller font to fit two logical pages on each sheet of
+paper.
+
+These text file facilities may not be available on all types of
+printers, especially the Linotronic.
+
+
+\newpage
+
+\subsection*{Command Options}
+
+The PSPRINT command can be followed by a variety of options:
+\begin{itemize}
+\item \verb|-device printer_type| ---
+tells PSPRINT which type of PostScript printer to use.
+The currently supported \verb|printer_type| values are:
+ \begin{itemize}
+ \item
+ \verb|lw | --- for an Apple LaserWriter (the default)\\ % SYSDEP
+ \verb|lino| --- for a Linotronic~300\\
+ \verb|ps40| --- for DEC's PrintServer~40
+ \end{itemize}
+\end{itemize}
+
+These options only take effect if \verb|-device lw|:
+\begin{itemize}
+
+\item \verb|-noflag| ---
+prevents PSPRINT producing a flag page.
+
+\item \verb|-manual| ---
+assumes you want to manually feed paper into the LaserWriter.
+As soon as the printer sees your job it will wait for you to feed in each
+sheet of paper (it will normally wait up to a minute).
+
+\end{itemize}
+
+These options only take effect if \verb|-device lino|:
+\begin{itemize}
+
+\item \verb|-lowres| ---
+prints a DVI file at low resolution (635 dots per inch).
+By default, \TeX\ output on the Linotronic is printed at 1270 dots per inch.
+The temporary file created by PSPRINT will typically be very large.
+Using \verb|-lowres| reduces both the size of the temporary file
+(by roughly three quarters) and the likelihood of memory problems.
+The print quality will of course be poorer but you'll
+probably need a magnifying glass to see the difference.
+
+\item \verb|-size page_size| ---
+sets the Linotronic page size and orientation.
+Possible \verb|page_size| values are
+\verb|A4P| (the default), \verb|A4L|, \verb|A5P|, \verb|A5L|,
+\verb|B5P|, \verb|B5L| and \verb|A3L|.
+The \verb|P| stands for portrait and the \verb|L| for landscape.
+(Don't confuse the landscape orientation with \verb|-l| which rotates
+the output within the page image, regardless of the \verb|-size| value.)
+The portrait orientations are less wasteful of paper.
+
+\item \verb|-cutmarks| ---
+produces small cut marks at the corners of the page image
+on Linotronic output.
+\verb|-cutmarks| is the default; use \verb|-nocutmarks| to suppress them.
+
+\end{itemize}
+
+The following five options override PSPRINT's assumptions
+about the format of the input file based on the given file specification:
+\begin{itemize}
+\item \verb|-dvi | --- for a DVI file.
+\item \verb|-ps | --- for a PostScript program.
+\item \verb|-text| --- for an ordinary text file.
+\item \verb|-two | ---
+like \verb|-text| but the output is formatted so that two ``pages''
+(both 60 lines by 80 columns) appear on each sheet of paper.
+\item \verb|-wide| ---
+like \verb|-text| but the output is formatted so that two wide ``pages''
+(both 60 lines by 132 columns) appear on each sheet of paper.
+\end{itemize}
+
+\newpage
+
+Some options can only be used with a DVI file:
+\begin{itemize}
+
+\item \verb|-p first:final| --- selects a subrange of pages for printing.
+\verb|first| and \verb|final| can select either DVI page numbers
+(positive integers) or \TeX\ page numbers.
+
+A \TeX\ page specification is of the form \verb|[i0.i1...i9]| where
+\verb|i0| to \verb|i9| are integers separated by periods and represent the
+10 counter values that \TeX\ stores with each DVI page.
+Any number of these integers may be absent and trailing periods may be omitted.
+An absent integer will match any value in the corresponding counter.
+Many DVI pages may match a particular \TeX\ page specification;
+if \verb|first| is a \TeX\ page then the {\em lowest\/}
+matching DVI page is selected, and if \verb|final| is a \TeX\ page then
+the {\em highest\/} matching page is selected.
+
+Assuming \TeX\ generated the 5 DVI pages `\verb|[0] [1] [2.1] [2.2] [3]|',
+here are some examples of how you could use \verb|-p|:
+ \begin{itemize}
+ \item
+ \verb|psprint foo -p 2 | --- prints the 2nd DVI page
+ (\TeX\ page \verb|[1]|)\\
+ \verb|psprint foo -p :4 | --- prints the first four pages\\
+ \verb|psprint foo -p 4: | --- prints the last two pages\\
+ \verb|psprint foo -p '[2]' | --- prints \verb|[2.1]| and \verb|[2.2]|\\
+ \verb|psprint foo -p 1:'[2]' | --- prints the first four pages\\
+ \verb|psprint foo -p '[2.2]':| --- prints the last two pages
+ \end{itemize}
+Note that \verb|first| and \verb|final| are optional; they default to
+the first and last DVI pages respectively.
+Omitting `\verb|:final|' entirely sets \verb|final| equal to \verb|first|.
+Note also the need for quote marks around a \TeX\ page specification.
+
+\item \verb|-i i| ---
+prints pages $f,f+i,f+2i,f+3i,\ldots,f+ni$, where
+$f$ is the first DVI page selected (either 1 or the start
+of a \verb|-p| subrange) and $f+ni$ is less than or equal to
+the final DVI page selected.
+
+The primary use of \verb|-i| is to simplify the printing of a document
+on both sides of the paper. For example, if \verb|foo.dvi| has 8 pages then the
+following steps will produce a double-sided document on a LaserWriter:
+ \begin{enumerate}
+ \item
+ \verb|psprint foo -i 2 -noflag | --- prints DVI pages 7, 5, 3, 1
+ \item
+ Remove the 4 pages from the output tray and carefully put them back
+ into the input cassette so that page 1 remains face up and its
+ top edge goes into the printer first.
+ (If \verb|foo.dvi| had 7 pages then you would only need to remove the
+ top 3 pages from the output tray.)
+ \item
+ \verb|psprint foo -i 2 -p 2: -norev| --- prints DVI pages 2, 4, 6, 8
+ \end{enumerate}
+Note that the use of \verb|-reverse| with \verb|-i| has no effect on
+{\em which\/} pages are printed; it simply changes the {\em order\/} in
+which they are done.
+
+\item \verb|-reverse| or \verb|-noreverse| ---
+forces PSPRINT to print pages in descending or ascending order respectively.
+By default PSPRINT prints DVI pages in an order determined by the type of
+printer you are using. The Apple LaserWriter stacks output sheets face up,
+so PSPRINT normally prints pages in reverse order so that your output will
+be automatically collated. The PrintServer 40 stacks the output face down,
+so PSPRINT normally prints pages in ascending order. The default order
+on the Linotronic is largely irrelevant, since this printer produces pages
+on a continuous roll of paper (the default used is ascending order).
+
+\item \verb|-m n| ---
+overrides the DVI magnification; \verb|n| is a positive integer 1000 times
+the desired magnification and should match one of \TeX's \verb|\magstep|
+values (see chapter 4 of {\sl The \TeX book\/}).
+
+\item \verb|-s| ---
+shows statistics on the rules, fonts, characters and \verb|\special| commands
+used on each page.
+
+\item \verb|-conserve| ---
+forces PSPRINT to conserve the printer's virtual memory at the
+expense of creating a larger output file (character bitmaps will be
+downloaded more often).
+If \verb|-device lino| then \verb|-conserve| is the default;
+if \verb|-device lw| or \verb|ps40| then \verb|-noconserve| is the default.
+
+\item \verb|-u xx| ---
+sets the units of dimensions displayed in some PSPRINT messages
+(e.g., if the page is off the paper).
+\verb|xx| can be one of:
+ \begin{itemize}
+ \item
+ \verb|in| --- for inches (the default)\\ % SYSDEP
+ \verb|cm| --- for centimetres (2.54\,cm = 1\,in)\\
+ \verb|mm| --- for millimetres (25.4\,mm = 1\,in)\\
+ \verb|pt| --- for points (72.27\,pt = 1\,in)\\
+ \verb|pc| --- for picas (1\,pc = 12\,pt)\\
+ \verb|bp| --- for big points (PostScript's default units; 72\,bp = 1\,in)\\
+ \verb|px| --- for pixels (depends on resolution of printer)
+ \end{itemize}
+
+\item \verb|-ho dimen| and \verb|-vo dimen| ---
+allow you to shift the printed location of each page.
+For example, \verb|-ho -0.5in| would
+shift each page half an inch to the left.
+A \verb|dimen| is any integer or real number, possibly negative, followed
+by a two-letter unit (the same as for \verb|-u|).
+
+\end{itemize}
+
+The remaining options apply to all types of input files:
+\begin{itemize}
+
+\item \verb|-l| --- specifies landscaped output
+\begin{picture}(10,7)
+\put(0,0){\framebox(10,7){}}
+\end{picture}\,,
+instead of the default portrait output
+\begin{picture}(7,10)
+\put(0,0){\framebox(7,10){}}
+\end{picture}\,.
+If~a DVI file, PSPRINT will check each page to make sure it fits
+within the rotated paper.
+
+\item \verb|-c n| --- specifies up to 100 copies.
+Use of this facility is not encouraged. Note in particular that
+copies of a multiple-page document will {\em not\/} be collated.
+
+\item \verb|-n string| --- includes a note on your flag page.
+
+\item \verb|-q string| --- overrides the default queue used by PSPRINT\@.
+(Some sites may have more than one printer of the same type). % SYSDEP
+
+\item \verb|-o file| --- sends the PostScript code generated by PSPRINT
+to a file rather than to a printer. Since some of this code is device-specific
+you should only send the file to a PostScript printer of the type that
+PSPRINT intended to use.
+
+\end{itemize}
+
+\newpage
+
+\subsection*{Error Messages}
+
+If PSPRINT detects one or more errors while translating a DVI file then
+the temporary PostScript file is automatically deleted and nothing
+is printed --- not even a flag page.
+The sort of errors you are most likely to see include:
+\begin{itemize}
+\item
+\verb|Page off paper (paper is ...| ---
+the current page contains material beyond one or more paper edges.
+Use \DVItoVDU\ to see where the problem lies.
+\item
+\verb|Couldn't open font file: ...| ---
+your DVI file uses a font at a non-existent size.
+Try a different font magnification in your source file.
+\item
+\verb|Couldn't open \special file: ...| ---
+PSPRINT could not locate the given \verb|\special| file.
+Check the file's spelling and/or directory location.
+\end{itemize}
+Error messages apply to the most recently displayed DVI/\TeX\ page.
+Any message that does not make sense probably indicates some sort of bug.
+Please save a copy of the input file and report the problem to your
+local \TeX nician.
+
+If your DVI file uses a large number of fonts or a few very large fonts then
+you might get an error page with the message ``\verb|VMerror|''.
+This indicates that PostScript's virtual memory has been exhausted,
+and the rest of your job will be flushed.
+This problem is unlikely to worry most people, particularly on the
+PrintServer~40 which has much more VM than the LaserWriter or Linotronic.
+If the problem does occur, there are a few things you can try:
+\begin{enumerate}
+\item
+On a LaserWriter or PrintServer, use \verb|-conserve|
+or print a few pages at a time.
+\item
+On a Linotronic, use \verb|-lowres|.
+(\verb|-conserve| is the default for this device.)
+\end{enumerate}
+If you are sending your own PostScript program then an error should
+produce some sort of message on the printed output.
+
+\newpage
+
+\subsection*{Using PostScript Fonts}
+
+PSPRINT allows the use of PostScript fonts within a \TeX\ or \LaTeX\ document.
+Such fonts can be used at any desired size and no character bitmaps need
+to be downloaded since the shape information is resident in the printer.
+The necessary typesetting information required by PSPRINT is extracted
+from TFM files (\TeX\ Font Metric files).
+A TFM file name beginning with ``\verb|ps-|'' is used to indicate a resident
+PostScript font. % SYSDEP; this prefix is set in psprint
+
+Each type of PostScript printer provides a different set of fonts.
+To be able to use a particular PostScript font you need to know the
+name of its corresponding TFM file and whether it actually exists in
+the printer you want to use. For each PostScript printer currently
+supported there exists a file containing just such information:
+\begin{itemize}
+\item [ ]
+\verb|$tex_ps/lw_fonts.ps | --- converts TFM names into LaserWriter fonts\\
+\verb|$tex_ps/lino_fonts.ps| --- converts TFM names into Linotronic~300 fonts\\
+\verb|$tex_ps/ps40_fonts.ps| --- converts TFM names into PrintServer~40 fonts
+\end{itemize}
+PSPRINT also uses these files, so you can be reasonably confident
+about the validity of their contents.
+To print a list of the PostScript fonts available in your printer you can type
+the command `\verb|psprint $tex_ps/fontlist.ps|'.
+
+(The above file names assume that the environment variable \verb|tex_ps|
+points to the public directory in which various PSPRINT-related files reside.
+To discover what \verb|tex_ps| is at your site, type `\verb|which psprint|'
+and examine the first few lines of the indicated file.)
+
+There are some important differences between PostScript fonts and
+the Computer Modern fonts normally used with \TeX:
+\begin{enumerate}
+\item
+When asking for a PostScript font it is best to use an `\verb|at| $dimen$'
+size specification (e.g., \verb|\font\helv=ps-helv at 13.5pt|) otherwise you
+might end up with a default 1pt font!
+\item
+PostScript fonts usually contain up to 256 characters, with many
+empty locations. Computer Modern fonts can also contain up to 256 characters
+but typically use only the first 128 locations (with very few empty).
+\item
+When a PostScript font is scaled to the same design size as a CM font
+it tends to look darker and larger. You need to be a bit careful
+when mixing the two font designs.
+\item
+The standard \TeX\ commands for accents and foreign letters need to be
+redefined for a PostScript text font. The file \verb|$tex_ps/pstext.tex|
+contains the required macro definitions; note that a few commands
+(\verb|\j|, \verb|\aa|, \verb|\AA|, \verb|\t|) cannot be used at all.
+Another file, \verb|$tex_ps/psfonts.tex|, inputs these macros and illustrates
+the use (and abuse) of PostScript fonts in a \TeX\ document.
+\end{enumerate}
+
+\newpage
+
+\subsection*{Using PostScript Graphics}
+
+Creating figures and illustrations with \TeX\ is very difficult.
+Although it is theoretically possible to place small dots
+anywhere on a page and build up an arbitrarily complex picture,
+time and memory limitations make such a scheme impractical.
+(\LaTeX\ provides a \verb|picture| environment, but it is very inefficient
+and only suitable for small, simple diagrams.)
+PSPRINT allows you to merge PostScript graphics with \TeX\ or \LaTeX\@.
+
+Let's assume you have a file called \verb|fig.ps| that contains
+suitable PostScript commands for generating some sort of figure.
+To include this figure in a \TeX\ or \LaTeX\ document, just type
+`\verb|\special{fig.ps}|' after leaving sufficient space:
+\begin{verbatim}
+ % in a TeX source file % in a LaTeX source file
+ \midinsert \begin{figure}[ht]
+ \vskip 3in \vspace{3in}
+ \special{fig.ps} \special{fig.ps}
+ \centerline{Figure 1: Pie Sales} \caption{Pie Sales}
+ \endinsert \end{figure}
+\end{verbatim}
+It may take a little practice to position the figure correctly.
+When you print a raw PostScript file (e.g., `\verb|psprint fig.ps|')
+the default origin is at the bottom left corner of the paper.
+However, when you include this file in a \TeX\ document the origin is
+automatically moved to the position of the \verb|\special| command.
+
+\verb|\special| can appear almost anywhere in your source file.
+It behaves like an invisible box of zero height and width.
+\TeX\ simply stores the given argument in the DVI file along with the current
+page position. PSPRINT interprets the argument as a file name and then
+includes this file in the information sent to the printer.
+(The included file is bracketed by \verb|save| and \verb|restore| commands
+to prevent any interference to the surrounding typesetting commands.)
+
+You can move the figure about by shifting the \verb|\special| position,
+or by including a \verb|translate| command in the PostScript file.
+The latter option is faster because you don't have to run \TeX\ again.
+For example, `\verb|72 36 translate|' at the start of \verb|fig.ps| would
+move the figure 1\,in right and 0.5\,in up
+(PostScript's default units are ``big points'' where 72\,bp = 1\,in).
+
+Alternatively, you may prefer to place your figure at an absolute position
+on the paper (i.e., at the same position produced by `\verb|psprint fig.ps|').
+Simply include an \verb|initgraphics| command at the start of \verb|fig.ps|.
+The position of the \verb|\special| command then becomes irrelevant;
+just make sure it's on the right page!
+
+The hardest part of the scheme is creating the PostScript file in the first
+place. You are faced with two possibilities:
+\begin{enumerate}
+\item
+Learn enough PostScript to be able to draw your own figures.
+You'll need to get the PostScript books mentioned on page~1.
+\item
+Use a program to convert an existing graphics file
+into a corresponding PostScript file.
+This assumes you are able to produce graphics of some sort
+(e.g., a Zeta plot file) and have access to a suitable conversion program.
+Ask your local graphics wizard whether any such programs are available.
+\end{enumerate}
+\DVItoVDU\ is unable to preview a PostScript file. All it can do is
+tell you the page position of the \verb|\special| command and display the
+given file name.
+
+\newpage
+
+Let's look at a few examples. The public directory \verb|$tex_ps| contains
+the \LaTeX\ source file for this User Guide, as well as a few PostScript
+files used to produce the figures below.
+These figures were created by calling
+\begin{verbatim}
+ \special{piechart.ps}
+ \special{greybox.ps}
+ \special{random.ps}
+\end{verbatim}
+at appropriate points in the source file.
+
+\begin{figure}[h] % produce figure here
+ \vspace{2.1in}
+ \special{piechart.ps} % origin at left margin of text
+ \caption{Pie Sales}
+\end{figure}
+
+\begin{figure}[h] % produce figure here
+ \begin{center}
+ \begin{minipage}{4in}
+ \special{greybox.ps} % origin at top left of minipage box
+ The text in this paragraph box was typeset by \LaTeX\@.
+ The shaded rectangle was created by PostScript.
+ \end{minipage}
+ \end{center}
+ \bigskip % leave additional room for shaded box
+ \caption{Shaded Text Box}
+\end{figure}
+
+\begin{figure}[h] % produce figure here
+ \begin{center}
+ \setlength{\unitlength}{1in}
+ \begin{picture}(1.3,1.3) % dimensions match axis lengths in random.ps
+ \put(0,0){\special{random.ps}} % origin at bottom left corner
+ \end{picture}
+ \end{center}
+ \caption{Random Dots}
+\end{figure}
+
+PSPRINT allows arbitrary PostScript text to appear after the file name in a
+\verb|\special| command. At least one space must be used to terminate the file
+name; further characters are included as a new line at the {\em start\/} of
+the given file. There is a limit of about 80 characters.
+For example, `\verb|\special{fig.ps 2 1 scale}|' could be used to double
+the width of the figure in \verb|fig.ps|.
+Note that it is possible to include the same PostScript file more than once,
+but with a different starting line each time.
+
+\end{document}