summaryrefslogtreecommitdiff
path: root/dviware/dvitops/dvitops.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/dvitops/dvitops.tex
Initial commit
Diffstat (limited to 'dviware/dvitops/dvitops.tex')
-rw-r--r--dviware/dvitops/dvitops.tex436
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}
+