diff options
author | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
commit | e0c6872cf40896c7be36b11dcc744620f10adf1d (patch) | |
tree | 60335e10d2f4354b0674ec22d7b53f0f8abee672 /dviware/dvitops/dvitops.tex |
Initial commit
Diffstat (limited to 'dviware/dvitops/dvitops.tex')
-rw-r--r-- | dviware/dvitops/dvitops.tex | 436 |
1 files changed, 436 insertions, 0 deletions
diff --git a/dviware/dvitops/dvitops.tex b/dviware/dvitops/dvitops.tex new file mode 100644 index 0000000000..524cda5b23 --- /dev/null +++ b/dviware/dvitops/dvitops.tex @@ -0,0 +1,436 @@ +% $Header: /usr/jjc/dvitops/RCS/dvitops.tex,v 1.2 89/02/02 14:08:01 jjc Rel $ +% this is the User Manual for DVITOPS in LaTeX format + +% this macro was borrowed from the manual to Beebe's drivers +\newcommand{\namelistlabel}[1]{\mbox{#1}\hfil} +\newenvironment{namelist}[1]{% +\begin{list}{} + { + \let\makelabel\namelistlabel + \settowidth{\labelwidth}{#1} + \setlength{\leftmargin}{1.1\labelwidth} + } + }{% +\end{list}} +\documentstyle [11pt,a4,ps]{article} +\newcommand{\dvitops}{{\tt DVITOPS}} +\newcommand{\ps}{{\sc Post\-Script}} +\title{\dvitops\ User Manual} +\author{James Clark} +\newcommand{\error}[1]{\subsubsection{{\tt #1}}} + +\begin{document} +\maketitle +\section{Introduction} +\dvitops\ translates a dvi file output of \TeX\ into \ps. It works with +both bitmap fonts and PostScript fonts. When used with the latter it +produces device-independent output. +\section{Usage} +The syntax for the \dvitops\ command is +\begin{flushleft} +{\tt dvitops} [{\it options}] {\it dvi\_file} +\end{flushleft} +You may omit the extension {\tt .dvi} from {\it dvi\_file}. +Options are delimited by the `{\tt -}' character. On MS-DOS, +they can also be delimited by `{\tt /}'. Options with no arguments +can be grouped behind a single delimiter. Option arguments that contain +white space must be enclosed in double-quotes. Option arguments +may, but need not be preceded by white space. +The following options are currently supported: + +\begin{namelist}{{\tt -h} {\it dimension}} +\item[{\tt -c} {\it ncopies}] +Print {\it ncopies\/} copies of each page; +note that the copies will not be collated. +\item[{\tt -h} {\it dimension}] +Horizontal offset. Position the origin {\it dimension} from the left edge +of the page; {\it dimension} must be a number followed by one of the units +of measure used by \TeX, for example {\tt1.5in}. +By default \dvitops\ positions the origin +of each page 1~inch down from and 1~inch to the right of +the upper left corner of the page. +This is the standard behaviour suggested by the Stanford \TeX\ project. +\item[{\tt -v} {\it dimension\/}] +Vertical offset. Position the origin {\it dimension} from the top of the page. +\item[{\tt -m} {\it number\/}] +This replaces the magnification in the +{\tt .dvi} file by {\it number}. This has the same effect as saying + `\verb|\magnification=| {\it number}' in the \TeX\ file. +\item[{\tt -r}] +Reverse the order of the pages. This is useful if you have a printer +such as the Apple LaserWriter which stacks its output face up. If this +option occurs twice on the command line, pages will be in forward order. +This is useful if you include this option in the {\tt DVITOPS} +environment variable. See Section~\ref{ev}. +\item[{\tt -q}] +Work quietly; \dvitops\ will not print the numbers of pages as it +produces them. +\item[{\tt -f} {\it page}] +Select the first page to be processed; +{\it page} is specified by giving a sequence of 1 to 10 numbers or +asterisks separated by dots. For example, the specification `\verb|1.*.-5|' +can be used to refer to a page output by \TeX{} when \verb|\count0| is 1 +and \verb|\count1| is $-5$. +An asterisk matches any number, +so the `\verb|*|' in `\verb|1.*.-5|' means that \verb|\count1| is ignored when +specifying the first page. If several pages match the given specification, +\dvitops\ will begin with the earliest such page in the file. The +default specification is `\verb|*|' which denotes +the page at the beginning of the file, since `\verb|*|' matches any page. +\item[{\tt -n} {\it number}] +Number of pages. Produce at most {\it number} pages. +\item[{\tt -s}] +Sort the pages by their \verb|\count0| value. +Negative numbers precede positive numbers. Negative numbers are sorted +in decreasing order, positive numbers in increasing order. Zero counts +as negative. +\item[{\tt -y} {\it kmem}] +Use at most {\it kmem\/} kbytes of printer memory for +preloading bitmap fonts. +\dvitops\ downloads the fonts that are most frequently used +in the document at the beginning. Other fonts have to be downloaded +on each page that they are used. +By default \dvitops\ will use at most 100k of the printer VM for this. +With this option it will use at most {\it kmem\/}k of VM. +\item[{\tt -p} {\it pagesize}] +This option informs \dvitops\ that {\it pagesize} paper will be used; +{\it pagesize} must be one of letter, legal, a4, b5, corresponding to the +page sizes used by standard \ps\ printers. This option does +not produce any \ps\ code to select this page size. +\dvitops\ needs to know the size of the page +because the \ps\ origin is at the bottom of the page, +and the \TeX\ origin is at the top of the page. If you are using a +non-standard page size, you should choose the nearest standard page size +and adjust the position of the origin using the {\tt -h} and {\tt -v} +options. +\end{namelist} +See Section~\ref{ev} to find out how you can avoid having to +type in the options that you use frequently. + +\section{\ps\ Fonts} +Ordinary \ps\ fonts not in pk format must have an entry in +the font directory file in order to be used with \dvitops. +This file is called {\tt dvitops.fnt}, and should be placed +in the same directory as the macro files used by \TeX. +Comments begin with a \verb|%|. They can start anywhere on the line +and continue to the end of the line. +Blank lines are ignored. +The syntax for each line is +\begin{flushleft} +{\it name} [{\it psname} [{\it encoding}]] +\end{flushleft} +{\it name} is the name of the font as it is known to \TeX, which is the same +as the name of the tfm file (with the extension {\tt .tfm} removed); +{\it psname} is the name of the font as it is known to \ps, for example +{\tt Times-Roman}. If {\it psname} is omitted it will be taken to be the same +as {\it name}. +The {\it encoding} field refers to an encoding file. An encoding file +describes an encoding vector for a font. +It should contain a list of the elements of the encoding vector +(without a preceding \verb|/|) separated by white space. +The file should have an extension of \verb|.enc|, which should be omitted +from {\it encoding}. +This field should be used in two situations: +if you created the tfm file with the {\tt aftopl} utility, +and you specified an encoding file (with the \verb|-e| option), +or if you wish to use \dvitops\ with tfm files intended for +use with some other driver that automatically reencodes fonts. + +\section{Environment variables} +\label{ev} +\dvitops\ needs to be able to find a number of different files. +It uses environment variables to do this. +The environment variables must be all uppercase. +These environment variables all contain +lists. Elements of the list are separated by \verb|:| under UNIX +and by \verb|;| under MS-DOS. +\begin{namelist}{{\tt TEXINPUTS}} +\item[{\tt TEXFONTS}] +If this is set, it should contain a list of directories in which +\dvitops\ should search for tfm files, and encoding files. +\item[{\tt TEXINPUTS}] +If this is set, it should contain a list of directories in which +\dvitops\ should search for its text input files: +{\tt dvitops.fnt}, {\tt dvitops.pro}, +and all the files referenced by \verb|\special| commands. +\item[{\tt TEXPK}] +This should be a list of prototypes of names of pk files. +A \verb|%f| in the prototype will be replaced by the name of the font +being searched for, +and a \verb|%d| by the magnification of the font in dots per inch. +\item[{\tt TEXMAGS}] +This should be a list of all the magnifications in dots per inch for which +there is some pk file. +\end{namelist} +The {\tt DVITOPS} environment variable allows you to avoid having to +type in frequently used options each time you use them. +When \dvitops\ reads its command line arguments, it types in the +value of this variable before any of the other arguments that have been +given. Thus if {\tt DVITOPS} is set to +\begin{verbatim} +-y 200 -r -p a4 +\end{verbatim} +and you type +\begin{verbatim} +dvitops -f 1 user +\end{verbatim} +the effect will be the same as if you had typed +\begin{verbatim} +dvitops -y 200 -r -p a4 -f 1 user +\end{verbatim} +with the environment variable {\tt DVITOPS} unset. + + +\section{{\tt \char'134special} commands} +\TeX\ has a primitive \verb|\special| which allows +arbitrary text to be included in the {\tt .dvi} file. +\dvitops\ uses this to offer a variety of extra facilities. +To be recognised by \dvitops\ the \verb|\special| must begin +with the `tag' {\tt dvitops:}. This tag is followed by a keyword and +possibly some arguments. The tag and keyword are not case-sensitive, +but the arguments are. White space is optional between the tag and the +keyword, but the keyword and arguments must be separated by white space. +A warning will be given if a \verb|\special| command with an +unrecognised tag is encountered, but it is an error if the keyword +following the {\tt dvitops:} tag is unrecognised. +\subsection{Landscape mode} +The command +\begin{verbatim} +\special{dvitops: landscape} +\end{verbatim} +will cause the page on which it occurs to be printed in landscape mode, +i.e. with the top of the page running along the long edge of the paper. +You must specify the command for each page that you want +printed in landscape mode. +\subsection{Graphics} +\label{graph} +You can include graphics in you document with the {\tt import} command. +The syntax of this command is: +\begin{flushleft} +\verb|\special{dvitops: import |{\it filename width height +{\rm[{\it option}\ldots]}}\verb|}| +\end{flushleft} +This option permits you to include a graphic in \ps\ form into the +document. There are three arguments: +{\it filename} is the name of the file containing the graphic, +{\it width} is the desired width of the graphic. +and {\it height} is the desired height of the graphic, +The {\it width} and {\it height} arguments must be specified as dimensions, +that is as a number with an optional decimal point followed by one +of the units of measure recognised by \TeX. The bottom left hand corner +of the graphic will be located at the point where the \verb|\special| +command was issued. +The graphic will be scaled so that it fits into the desired space, +but it will be scaled by the same factor horizontally +and vertically. It will be centred in any surplus +white space. This means that you do not have to know anything about the +dimensions of the graphic to be imported. \dvitops\ gets this +information from the \ps\ file. For example, Figure~\ref{elephant} +\begin{figure}[hbt] +\vspace{2in} +\special{dvitops: import picture.ps \the\textwidth 2in} +\caption{An Elephant} +\label{elephant} +\end{figure} +was produced by the \LaTeX\ commands +\begin{verbatim} +\begin{figure}[hbt] +\vspace{2in} +\special{dvitops: import picture.ps \the\textwidth 2in} +\caption{An Elephant} +\end{figure} +\end{verbatim} +\TeX\ expands \verb|\the\textwidth| to \the\textwidth, which +is the width of the text on the page. Note that the +graphic has been scaled so as to be 2~inches high and has been +centered horizontally with respect to the text. +The file {\tt picture.ps} is the unaltered output of the +Macintosh version of Adobe Illustrator. + +The \ps\ file containing the graphic should comply +with the Encapsulated Postscript Format +(EPSF) standard. EPSF files come in three flavours. The simplest +is just a text file. The first line of such a file will be: +\begin{verbatim} +%!PS-Adobe-2.0 EPSF 1.2 +\end{verbatim} +This is the type of file that \dvitops\ needs. The other two +flavours contain in addition to the \ps\ text a representation +of the image that the \ps\ code will produce; one is intended +for the Macintosh environment, one for the MS-DOS environment. +In order for \dvitops\ successfully to import such a file, the +\ps\ text must be extracted from the file. +A Macintosh EPSF file contains the \ps\ text in its data fork, +and the graphical representation in its resource fork. If such a +file is transferred to another system as a straight +binary (not MacBinary) file, only the contents of the data fork +will in fact be transferred. Thus in order to import a Macintosh +EPSF file into \dvitops\ on another computer, it is only +necessary to transfer the file as a binary file. It may also +be necessary to change the carriage-returns which the Macintosh +uses as its line separator to whatever is used as a line separator +on the computer on which \dvitops\ is running +(carriage-return followed by line feed in MS-DOS, +line-feed in UNIX). +This method has been used successfully to import pictures produced with +Adobe Illustrator, Cricket Draw and Aldus Freehand running on a +Macintosh into \dvitops\ running under MS-DOS. + +\subsection{\ps\ code} +\label{prolog} +\dvitops\ allows you to include your own \ps\ code in a document. +The \ps\ file that is output by \dvitops\ contains two sections: +a prologue and a script. The prologue contains only procedure +definitions and produces no printed output. The script +calls the procedures defined in the prologue to generate the printed +pages. The pages of the script are independent of each other +but dependent on the prologue. \ps\ code that is executed within +the script of the document can only affect the page in which it occurs. +The command +\begin{flushleft} +\verb|\special{dvitops: prolog| {\it filename}\verb|}| +\end{flushleft} +will include {\it filename} in the prologue of the output file; +{\it filename} must contain {\em only} definitions. The command +\begin{flushleft} +\verb|\special{dvitops: inline| {\it anything}\verb|}| +\end{flushleft} +will include {\it anything} in the script of the output file; +{\it anything} should a short piece of \ps\ code +which calls procedures defined in a prologue file. +All the pieces of code from the {\tt inline} commands on a particular +page are held in memory until the end of the page is encountered. +The pieces of code are then output together after all the other output on +the page. The coordinate system in effect is the same as that used by +\TeX: units are scaled points (there are 65536 scaled points in a point); +y coordinates increase down the page; the origin is 1~inch down from +and 1~inch to the right of the upper left hand corner of the page. +Each \verb|\special| command in the {\tt .dvi} file +has an associated position, namely the reference point that would +have been present if a box of height, depth and width zero had appeared +in place of the \verb|\special| command. +\dvitops\ inserts code to move to that position before it outputs +the code from each {\tt inline} command. +(This is what makes the {\tt inline} command useful.) +Note that any definitions +that you make in the code using {\tt inline} commands will only +last until the end of the current page. + +\subsection{Regions} +\dvitops\ allows you to select regions of a page and perform +various operations on them. Regions of the page are selected +using the following specials +\begin{flushleft} +\verb|\special{dvitops: begin |{\it region}\verb|}|\\ +\verb|\special{dvitops: end}| +\end{flushleft} +Anything bracketed between these two commands will be part of the region +called {\it region}; {\it region} can be any alphanumeric string. +Regions cannot be nested; a {\tt begin} +command automatically terminates any previous {\tt begin} command +not already terminated with an {\tt end} command. All regions +are terminated automatically at the end of a page. The same +region can be the subject of more than one {\tt begin} command. +An {\tt end} command must have a preceding {\tt begin} command +on the same page. +Regions can include inline \ps\ and graphics. + +\subsubsection{Transformations} +Once you have selected a region, you can apply a geometrical +transformation to it. +Each transformation is relative to an origin. By default +the origin is \TeX's origin, 1~inch down from and 1~inch to the +right of the upper right hand corner of the page +(unless changed by the {\tt -h} and {\tt -v} options). +This origin can be changed. The command +\begin{flushleft} +\verb|\special{dvitops: origin |{\it region}\verb|}| +\end{flushleft} +makes the current point the origin for {\it region}. +A region can have only one origin. Giving a region an origin +does not alter the position of the region on the page; +it just alters the effect of transformations on that region. +The {\tt origin} command can be given anywhere on the page. + +There are two \verb|\special| commands that perform +transformations: +\begin{flushleft} +\verb|\special{dvitops: rotate |{\it region $\theta$}\verb|}|\\ +\verb|\special{dvitops: transform |{\it region a b c d}\verb|}| +\end{flushleft} +The {\tt transform} command performs the affine transformation +represented by the matrix +\[ \left( \begin{array}{cc} +a &b\\ +c &d\\ +\end{array} \right). \] +The {\tt rotate} command rotates the region about the origin of that +region by $\theta$ degrees in a clockwise direction. It is equivalent +to a {\tt transform} command; it is included because it is inconvenient +to calculate the appropriate transformation matrix for a rotation in \TeX. +Any number of transformations can be applied to a region. They will be +applied in the order in which they are given. +Regions are only affected by transformation commands that appear on the +same page. Apart from this transformation commands can appear at +any point in the document. For example, the following code +\begin{verbatim} +A \special{dvitops: begin example}% +\special{dvitops: origin example}sloping% +\special{dvitops: end} +word. +\special{dvitops: rotate example -30} +\end{verbatim} +will produce +\begin{flushleft} +A \special{dvitops: begin example}% +\special{dvitops: origin example}sloping\special{dvitops: end} word. +\special{dvitops: rotate example -30} +\end{flushleft} +\subsubsection{Color} +You can also choose what color a region should be painted with. +\begin{flushleft} +\verb|\special{dvitops: gray| {\it whiteness}\verb|}|\\ +\verb|\special{dvitops: hsbcolor| {\it hue saturation brightness}\verb|}|\\ +\verb|\special{dvitops: rgbcolor| {\it red green blue}\verb|}| +\end{flushleft} +You should use at most one of these for each region. The arguments must +all be numbers between 0 and 1. A value of 0 for {\it whiteness} +will give black, and a value of 1 white. +You can get interesting effects using the \verb|gray| special. +For example, a macro \verb|\rbox| can be defined like this +\def\rbox#1{% +\leavevmode\setbox0\hbox{\strut#1}\special{dvitops: gray reverse 1}% +\vrule width \wd0 height \ht0 depth \dp0 +\llap{\special{dvitops: begin reverse}\box0\special{dvitops: end}}} +\begin{verbatim} +\def\rbox#1{% + \leavevmode\setbox0\hbox{\strut#1}% + \special{dvitops: gray reverse 1}% + \vrule width \wd0 height \ht0 depth \dp0 + \llap{\special{dvitops: begin reverse}% + \box0 + \special{dvitops: end}}} +\end{verbatim} +Then \verb|\rbox{reverse out}| will produce \rbox{reverse out}. Note +that objects on a page are not necessarily output in the order in +which they occur in the dvi file; in particular, all the text on a page +is output after everything else on the page. + +\section{Errors} +\dvitops\ produces three types of error messages---fatal errors, errors +and warnings. The program will terminate immediately on a fatal error. +Each error message is prefixed by the full pathname of the +\dvitops\ program, followed by a colon and one of +``fatal error'', ``error'' and ``warning.'' +\dvitops\ operates in two passes. On the second pass +\dvitops\ prints an opening bracket followed by the number of a page +just as it is about to start outputting the \ps\ code for that page; +it prints a closing bracket when it's done with a page. +The page number displayed is the values of \verb|\count0| through +\verb|\count9| separated by dots with trailing `.0's suppressed. +\TeX\ does the same. +This enables you to tell on the second pass where \dvitops\ has +encountered the error. + +\end{document} + |