% 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.1 for VAX/VMS\\ \bf Andrew Trevorrow, October 1989 \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 Temporary Files \aligneddots\ 1\\ \TeX\ Output \aligneddots\ 1\\ PostScript Output \aligneddots\ 1\\ Text Output \aligneddots\ 1\\ Command Qualifiers \aligneddots\ 2\\ Error Messages \aligneddots\ 5\\ Including Global PostScript \aligneddots\ 6\\ Using PostScript Fonts \aligneddots\ 6\\ Using PostScript Graphics \aligneddots\ 7 \vspace*{\fill} \thispagestyle{empty} \newpage \setcounter{page}{1} \subsection*{Temporary Files} For each type of input file, PSPRINT will create a temporary file in \verb|sys$scratch|. % SYSDEP This file has a \verb|.tmp| extension and contains the PostScript commands required to print your job. It is automatically deleted once printed; you will only need to delete it if you decide to delete your job from the print queue. \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| qualifier. 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|/landscape| qualifier will rotate the paper so that you can have lines up to 132 characters long (but only 50 lines per page). The \verb|/two| and \verb|/wide| qualifiers are variants of \verb|/text| that use a smaller font to fit two logical pages on each sheet of paper. Type `\verb|psprint foo.ps /text|' if you want to print a PostScript file. \newpage \subsection*{Command Qualifiers} The PSPRINT command can be followed by a variety of qualifiers: \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} If you have access to more than one type of printer, it may be a good idea to define some symbols in your \verb|login.com| file: \begin{itemize} \item \verb|$lw*print :== psprint/dev=LW ! for LaserWriter|\\ \verb|$lino*print :== psprint/dev=LINO ! for Linotronic 300|\\ \verb|$ps40*print :== psprint/dev=PS40 ! for PrintServer 40| \end{itemize} \end{itemize} Some qualifiers only apply to certain devices: \begin{itemize} \item \verb|/nobanner| (only if \verb|/device=LW| or \verb|LINO|) --- prevents PSPRINT producing a banner page. \item \verb|/manualfeed| (only if \verb|/device=LW|) --- 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 qualifiers 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|/landscape| 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 qualifiers 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 qualifiers can only be used with a DVI file: \begin{itemize} \item \verb|/pages=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|/pages|: \begin{itemize} \item \verb|$ psprint foo /pages=2 | --- prints the 2nd DVI page (\TeX\ page \verb|[1]|)\\ \verb|$ psprint foo /pages=:4 | --- prints the first four pages\\ \verb|$ psprint foo /pages=4: | --- prints the last two pages\\ \verb|$ psprint foo /pages=[2] | --- prints \verb|[2.1]| and \verb|[2.2]|\\ \verb|$ psprint foo /pages=1:[2] | --- prints the first four pages\\ \verb|$ psprint foo /pages=[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|. \item \verb|/increment=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|/pages| subrange) and $f+ni$ is less than or equal to the final DVI page selected. The primary use of \verb|/increment| 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 /inc=2 /nobanner /rev| --- 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 /inc=2 /pag=2: /norev| --- prints DVI pages 2, 4, 6, 8 \end{enumerate} Note that the use of \verb|/reverse| with \verb|/increment| has no effect on {\em which\/} pages are printed; it simply changes the {\em order\/} in which they are done. If you intend doing a lot of two-sided printing then it is a good idea to define some symbols in your \verb|login.com| file to avoid making mistakes: \begin{itemize} \item \verb|$ oddpages :== psprint/pag=1:/inc=2/rev/nobanner|\\ \verb|$ evenpages :== psprint/pag=2:/inc=2/norev| \end{itemize} \item \verb|/reverse| or \verb|/noreverse| --- forces PSPRINT to print pages in descending or ascending order respectively. By default PSPRINT prints DVI pages in ascending order. \item \verb|/magnification=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|/stats| --- shows statistics on the rules, fonts, characters and \verb|\special| commands used on each page. \item \verb|/conserve_vm| --- 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_vm| is the default; if \verb|/device=LW| or \verb|PS40| then \verb|/noconserve_vm| is the default. \item \verb|/units=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|/hoffset=dimen| and \verb|/voffset=dimen| --- allow you to shift the printed location of each page. For example, \verb|/hoffset=-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|/units|). \end{itemize} The following qualifiers also apply to a DVI file, but are really for system wizards. Most users should never need to use them since their default values are normally defined once at installation time and are presumably correct: \begin{itemize} \item \verb|/resolution=n| --- specifies the resolution of your printer in pixels per inch; \verb|n| must be a positive integer. \item \verb|/xsize=dimen| and \verb|/ysize=dimen| --- specify the paper size. PSPRINT will check that each DVI page fits within the given dimensions. A \verb|dimen| is any positive integer or real number followed by a two-letter unit (the same as for \verb|/units|). \item \verb|/psprefix=string| --- defines the TFM file name prefix that PSPRINT uses to recognize a PostScript font. \item \verb|/tfm_directory=directory| --- specifies the location of TFM files for PostScript fonts. \item \verb|/font_directory=directory| --- specifies the default directory from which PSPRINT gets all its character bitmap information. This might come in handy if you are using Metafont to create your own fonts or modify existing ones. For example, the following commands tell PSPRINT to first search for fonts in the current directory (\verb|[]|) before looking in the default directory (assumed to be \verb|tex_disk:[tex.pk]|): \begin{itemize} \item \verb|$ define dirlist [],tex_disk:[tex.pk]|\\ \verb|$ psprint foo.dvi /font="dirlist:"| \end{itemize} Use \verb|/stats| to see the default font directory at your site. \item \verb|/dummy_font=file| --- indicates the naming convention and format of all font files. The given file must represent an unmagnified font. \end{itemize} \newpage The \verb|/prep| qualifier only applies to a DVI or PS file: \begin{itemize} \item \verb|/prep=file| --- specifies a file to be included at the end of the normal prologue. This file will normally be a modified version of Apple's Laser Prep. If no file is specified then a default file, \verb|tex_ps:laserprep70.ps|, is included. Such a file is needed to support PostScript files created by pressing Command-F after clicking OK in the Print dialogue of most Macintosh applications. The PostScript code generated by this method relies on the procedures defined in Laser Prep, so if you want to include such code (via a \verb|\special| command for instance) you need to use \verb|/prep| to make sure the appropriate Laser Prep code is loaded first. Command-F files contain comments at the top that indicate which version of Laser Prep they require. Try and choose the nearest matching Laser Prep file provided with PSPRINT; see \verb|tex_ps:laserprep*.ps|. These files contain comments describing how they were created, just in case you need to generate a new version. \end{itemize} The remaining qualifiers apply to all types of input files: \begin{itemize} \item \verb|/landscape| --- 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|/delete| --- deletes the input file after printing. \item \verb|/notify| --- notifies you when the print job has finished. On the PrintServer~40 you'll also see any PostScript messages, a particularly useful feature when debugging a PostScript program. \item \verb|/copies=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|/note=string| --- includes a note on your banner page. For example, to get your output put in box 99, just type `\verb|psprint/note="box 99" ...|'. \item \verb|/queue=string| --- overrides the default queue used by PSPRINT\@. (Some sites may have more than one printer of the same type). \item \verb|/output=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} \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 banner 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_vm| or print a few pages at a time. \item On a Linotronic, use \verb|/lowres|. (\verb|/conserve_vm| 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. If you are using a PrintServer~40 then specify \verb|/notify| to get all PostScript messages sent back to your terminal. \subsection*{Including Global PostScript} When printing a DVI file, PSPRINT looks in your current directory for a file called \verb|global.ps|. If it exists then its contents will be included after the normal prologue. The example \verb|global.ps| file supplied in \verb|tex_ps| shows how to get the word ``DRAFT'' printed in the background on every page. \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; determined by /psprefix value in psdvi.cld 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 --- see \verb|tex_ps:*_fonts.ps|. 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|'. There are some important differences between PostScript fonts and the Computer Modern fonts normally used with \TeX: \begin{enumerate} \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} \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 have a couple of choices: \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 another program to create the graphic image and then convert it into a corresponding PostScript file. The Macintosh is a particularly nice machine for this purpose. Many applications can either dump an EPS (Encapsulated PostScript) file, or you can use the Command-F method mentioned earlier in the discussion of PSPRINT's \verb|/prep| qualifier. \end{enumerate} \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{tex_ps:piechart.ps} \special{tex_ps:greybox.ps} \special{tex_ps:random.ps} \end{verbatim} at appropriate points in the source file. The directory location is given with each PostScript file so you can print a copy of the User Guide from any directory. If the \verb|\special| command is only given a file name then PSPRINT assumes the file is in your current directory. \begin{figure}[h] % produce figure here \vspace{2.1in} \special{tex_ps: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{tex_ps: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{tex_ps: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 200 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}