⟦8d3c4e039⟧

TextFile

% =====================
\chapter{\mac{special}}
% =====================
\label{c-special}

\section{Introduction}
% ====================
	Now let us discuss the handling of \verb+\special+s by this
driver. This is a rather tricky issue, and I certainly do not claim to
offer the best and only possible solution to this problem.  Especially I
am willing to implement any proposed standardization of the
\verb+\special+ handling by drivers.

	There are a lot of problems with \verb+\special+s and while I
thought at first that I could avoid discussing what I did (getting by
with explaining what I implemented) I can't really avoid discussing why
I did certain things a certain way.  Your feedback is very welcome!

\section{Structure of \mac{special} Command Strings}
% ==================================================
\label{s-special}
	Any \verb+\special+ string which is supposed to be recognized by the
driver must start with the string ``{\tt dvitps:}'' (all caps).
The only \verb+\special+ strings which are exempted from this rules are
the \verb+\special+s of {\tt tpic}.
\verb+\special+s without {\tt dvitps:} at the beginning
are ignored.

	This {\tt dvitps:} string must be followed by a keyword. This keyword
identifies the function to be performed.
In case the keyword can not be recognized by the driver a fatal error occurs.

	The keyword then can be followed by arguments. Arguments are
separated by spaces, and there are integer and floating point arguments
which are represented in the usual way. A {\it string\/} argument is
given by including the string in double quotes.

	The \verb+\special+ identifier string {\tt dvitps:} can be
changed by editing {\tt dvitps/h/dvitps.h} although this is discouraged
because of numerous other places where such changes would have to be
performed.

	Here is a very simple example of a special string which prints, on
standard error, the current position's coordinates. This keyword does not
assume any arguments following it.
\btex
	\special{dvitps: Position}
\etex

\section{Recalling Some Basics}
% =============================
At this point let us recall the structure of the \PS{} code generated by
the driver:
\begin{enumerate}
	\item The whole \PS{} file is enclosed in a {\bf save} / {\bf
		restore} pair.
	\item The pass~0 output of a page is not enclosed in a {\bf save} /
		{\bf restore} pair, but
	\item The pass~1 output is enclosed in a {\bf save} / {\bf restore}
		pair.
\end{enumerate}

\section{The List of \mac{special}s Recognized by This Driver}
% ============================================================
	I will now offer the complete list of all the \verb+\special+ command words
recognized by the driver.  Some of the instructions below are explained
here in full. For others you find forward references to where they are
explained.
\begin{itemize}
	\item There are a bunch of {\tt tpic} keywords which are not to be
		preceded by {\tt dvitps:}.  These keywords will not be listed
		here; see the program (file {\tt special.c}) for details.
	\item The keyword {\tt Position} causes the current position's
		coordinates to be printed on standard error (unit is points).
		This occurs during pass~1 processing because no positioning
		information is maintained by the driver during pass~0.
	\item The keyword {\tt Gray} causes a rectangular area to be printed
		in gray. This option is, for instance, used to print verbatim
		listings with a gray background.

			The area to be ``grayed'' is measured by \TeX{} box-like
		dimensions: height, depth and width which are measured with
		respect to the current point. The driver understands the
		dimensions {\tt pt}, {\tt in}, {\tt cm} and {\tt mm}.

			Here is an example of a specification as it is used in this
		document to highlight all verbatim listings (see the \TeX{} macro
		file {\tt book-verb.tex} for details):
\btex
	\special{dvitps: Gray 8.0pt 4.0pt 5.6in}
\etex
	\item The keyword {\tt PrintString} is followed by an arbitrary
		string which is printed on standard error during pass~0 of the
		page where this \verb+\special+ was encountered.

		This command
		could be changed to print out that string during pass~1 or even
		during both passes. The current choice is as good as any other
		choice. An example for using this \verb+\special+ would be
\btex
		\special{dvitps: PrintString "This is fun"}
\etex
	\item {\tt VMReset}: perform a virtual memory reset on this page.
		This will be discussed later in more detail.
	\item There are two keywords {\tt LandscapePage} and {\tt
		PortraitPage} which are discussed later;
		\see{s-special-orientation}.
	\item The keyword {\tt Literal} must be followed by a quoted string.
		This quoted string is copied into the \PS{} file during pass~1
		(and ignored during pass~0).  It is up to the user to do a {\bf
		gsave} at the beginning and a {\bf grestore} at the end, or to
		preserve all the necessary information any other way. This
		instruction is therefore obviously very dangerous.
	\item There are two different include instructions which are used to
		include a file during pass~0 processing of a page or pass~1
		processing of a page. There is {\tt Include0} and {\tt Include1}
		which are each followed by a file name as a string. Here is a
		very short example:
\btex
		\special{dvitps: Include0 "xx.pro"}
		\special{dvitps: Include1 "figure.ps"}
\etex
		The examples already suggest a certain use of these instructions:
		\begin{enumerate}
			\item With {\tt Include0} some special prologue file is
				loaded which is needed by the \PS{} figure stored in file
				{\tt figure.ps}. In other words files read in using {\tt
				Include0} typically only contain procedure definitions.
				You might want to establish your own directory to avoid
				name conflicts.

					Observe that these prologue files are
				registered with the driver and the prologue files are
				downloaded again when a virtual memory reset is generated
				in the driver. Whether to do this is correct or not is
				something honest people can argue about.

					Observe that the driver uses a special path to locate
				prologue files, so prologue file can actually reside in
				a variety of directories. You must avoid name conflicts
				with the standard prologue files as accessed by the
				driver. See directory {\tt dvitps/pro} for details.
			\item With {\tt Include1} some \PS{} code to generate a
				figure or such can be included. Be advised that unless
				you understand precisely what you are doing you are
				probably much better off using psfig; see
				\ChapterRef{c-psfig}, \page, for details.
		\end{enumerate}
\end{itemize}

\section{Source Files}
% ====================
	The following source files in {\tt dvitps/src} are relevant for the
	handling of \verb+\special+s in the driver:
\begin{enumerate}
	\item {\tt special.c}: this file contains routines, which are invoked,
		if a \verb+\special+ command has been found in the
		{\tt DVI} file.

		This file contains the central code for the handling of \verb+\special+s.
		It also contains definitions for {\tt input()} and
		{\tt unput()}, which are used by the lexical analyzer, to
		read the strings of a \verb+\special+.
	\item {\tt special-tokens}: this file contains all keyword tokens, which
		are recognized inside a \verb+\special+ command by the driver.
	\item {\tt special-1.lex}: this file forms the first part of a lexical
		analyzer, through which any \verb+\special+ input
		is analyzed.
	\item {\tt special-2.lex}: this file forms the second part of the
		lexical analyzer which is used to read in \verb+\special+ command
		strings.
\end{enumerate}

\section {{\tt tpic}}
% ===================
\label{s-tpic}
	Thanks to {\tt fletcher@godzilla.cs.utexas.edu} the driver includes
{\tt tpic} support. Most of the routines can be found in {\tt
tpic\_support.c}. There were also some modifications made to
{\tt special.c}, and {\tt special.tokens}.

	The {\tt tpic} support is
controlled via a compile time switch {\tt TPIC} in file {\tt special.c}.
An example of a {\tt tpic} file and its output can be found
in \ChapterRef{c-tpic}, \page. The {\tt TPIC} compile
time constant must be defined in {\tt local-defs}.

\section{Adding Your Own \mac{special} Handling}
% ==============================================
In case you plan to add your own \verb+\special+ commands here is what you have to
do in {\tt dvitps/src}:
\begin{enumerate}
	\item Add new keywords to {\tt special-tokens}.
	\item Modify {\tt special.c} to also parse your
		\verb+\special+	command. This in particular requires to add
		{\tt case} statements in {\tt DoSpecialOfPass0()} and {\tt
		DoSpecialOfPass1()}.
	\item If necessary add your own source files to {\tt IMakefile} of the
		directory {\tt dvitps/src}.
	\item If necessary add a new prologue file to {\tt dvitps/pro} and
		change {\tt IMakefile} in that directory.
	\item If you executed any of the two previous steps go to the {\tt
		setup} directory and run a {\tt make prepare}.
	\item Recompile and install the driver software.
\end{enumerate}

\section{Landscape and Portrait Mode}
% ===================================
\label{s-special-orientation}
	Each document has a ``usual'' orientation which applies to all pages
unless special instructions are given. This orientation is naturally
portrait mode by default. Landscape mode of the whole document can be
invoked using the~{\tt -L} option of the driver.

	The driver offers a way to switch to ``the other orientation'' on a page
by page basis using the \verb+\special+ commands {\tt LandscapePage} or {\tt
PortraitPage}. Naturally the assumption is that the ``usual''
orientation of the document is portrait mode or landscape mode
respectively. The page with a \verb+\special+ as mentioned above will be
printed in the specified mode. But any other page will be printed in the
``usual'' orientation unless a page also contains on of the orientation
\verb+\special+s. In other words, orientation \verb+\special+s apply only
to one page at a time.

	Below you find a very short example of how a page in landscape mode
may be included into a document:
\btex
\def\BeginLandscapePage{% 
	\vfill\supereject
	\begingroup
	\vsize = 6.5in
	\hsize = 8.9in
	\special{dvitps: LandscapePage}
}
\def\EndLandscapePage{
	\vfill\supereject
	\endgroup
}

	This is a landscape test. Let us go
for it. And so here now we have a figure in landscape mode.

\BeginLandscapePage
$$
	\vbox{
							\tabskip = 20pt
		\halign{
			#\hfil&
			#\hfil
			\cr
			This is fun& This too\cr
			This is fun& This too\cr
			This is fun& This too\cr
			\dots&\dots\cr 
			This is fun& This too\cr
			This is fun& This too\cr
		}
	}
$$

\EndLandscapePage
And more stuff is here, the last page in our case.
\bye
\etex

	The solution offered here is not particularly appealing because this
solution forces the previous page to end prematurely. There is no
insertion used which could be done but some
trickery is necessary in order to account for the different values for
\verb+\vsize+ on landscape and portrait pages. It can be done: try it
out, and once you have a clean and straight forward example drop me a
note and I will include it into the documentation.
DataMuseum.dk

DKUUG/EUUG Conference tapes

⟦8d3c4e039⟧ TextFile

Derivation

TextFile
