⟦4d45fbcb9⟧

TextFile

\subsection{The \dviselect\ program}\label{sec:dviselect}
The \dviselect\ program
allows plucking a subset of pages out of a \dvi\ file.
By putting this in a separate program,
all \dvi\ drivers can enjoy the same functionality
and the same syntax for extracting pages.
Some drivers may also have a more limited form of page selection built in,
but \dviselect\ works everywhere.

The program is invoked as:
\begin{quote}
{\tt dviselect} [{\tt -s}] [{\tt -i} {\it infile\/}]
[{\tt -o} {\it outfile\/}] {\it list of pages\/}
[{\it infile\/} [{\it outfile\/}]]
\end{quote}
If no {\it infile\/} or {\it outfile\/} is given,
\dviselect\ reads its standard input and writes its standard output.
The {\tt -s} option simply makes \dviselect\ do its work silently.
(Normally it prints the ten \cccount\ registers  \`a la \TeX.)
An argument is taken as an {\it infile\/} or {\it outfile\/} name
if it begins with an alphabetic character or a slash,\footnote
{If it starts with the word {\tt even} or {\tt odd},
it is taken to be a range.
The name {\tt even.dvi}, for instance,
is considered a syntax error,
because the {\tt even} and {\tt .} parts look like a valid range
but the {\tt dvi} part does not.}
otherwise it is considered to be part of the list of pages.
For instance, to name the output file {\tt 123.dvi},
you must use the {\tt -o} option,
or use shell redirection as in the examples below.

You can refer to a page by absolute position within the \dvi\ file
or by its ten \cccount\ registers.
The first page has absolute position 1, the second 2, and so forth.
The \cccount\ registers, on the other hand,
may (and often do) count in a bizarre sequence.
\ccount0\ is usually the `page number',
and plain \TeX\ sets \ccount0\ to $1$, and increments it,
for the body of the text,
or to $-1$ and decrements it for frontspiece material
(preface, table of contents, and the like).
Frontspiece material thus has negative page numbers,
and asking for only positive pages will discard it.
\LaTeX, however, sometimes sets \ccount0\ to 1
in the frontspiece material,
then resets it to 1 again at the beginning of the main text.
This means that there can be two `page 1's,
and when there are, the command
\begin{quote}
\begin{verbatim}
dviselect 1 < myfile.dvi > page1.dvi
\end{verbatim}
\end{quote}
will select both of them.

There are a large and confusing number of ways to avoid this.
The most straightforward way is to select by absolute position.
If you want the second page 1, and it happens to be the sixth
page within the \dvi\ file,
\begin{quote}
\begin{verbatim}
dviselect =6 < myfile.dvi > page1.dvi
\end{verbatim}
\end{quote}
will select it.
The leading equal sign `{\tt =}' says that this is an absolute
page specifier.
We will get into the more confusing method
(which is nonetheless more powerful)
soon.

To select pages 1 through 5,
you could write {\tt dviselect 1 2 3 4 5},
but it is more convenient to use a range:
\begin{quote}
\begin{verbatim}
dviselect 1:5 < myfile.dvi > firstfew.dvi
\end{verbatim}
\end{quote}
This makes a bigger difference when you need pages 1 through 100.
Page ranges also work for absolute selectors:
\begin{quote}
\begin{verbatim}
dviselect =1:5 < myfile.dvi > firstfew.dvi
\end{verbatim}
\end{quote}
picks up the first five pages in the \dvi\ file,
no matter what their page number.
This is about as complicated as absolute selectors get.

To get at the frontspiece material in a Plain \TeX\ document,
you might want to get all the negative-numbered pages
(the ones where \ccount0\ is $-1$, or $-2$, or $-30$, or whatever).
You can do this by giving negative numbers to \dviselect.
Unfortunately, the `{\tt -}' character has other special meanings,
so you have to use an underscore `{\tt\char`\_}':
\begin{quote}
\begin{verbatim}
dviselect _100:_1 < myfile.dvi > front.dvi
\end{verbatim}
\end{quote}
If you are not sure how many pages there are,
just leave out one number:
\begin{quote}
\begin{verbatim}
dviselect :_1 < myfile.dvi > front.dvi
dviselect 1: < myfile.dvi > body.dvi
\end{verbatim}
\end{quote}
If the number on the left is missing,
that means `negative infinity',
and if the one on the right is missing,
that means `positive infinity'.
Leaving out both numbers makes the range $-\infty$ to $+\infty$,
which selects everything.
(This is not useless; read on.)
You can leave numbers out of absolute ranges as well.

This is fine for selecting a known set of pages,
but does not do much good
if you want to select pages according to what is on them
rather than what their page numbers are.
If you arrange for some of the other \cccount\ registers
to hold values telling what is on pages,
you can select by these.
For instance,
if you convince \LaTeX\ to put chapter numbers in \ccount1\
(e.g., with the magic sequence noted in \S\ref{sec:dvicount}),
you can extract chapter 1
with the command
\begin{quote}
\begin{verbatim}
dviselect '*.1' < myfile.dvi > ch1.dvi
\end{verbatim}
\end{quote}
The asterisk `{\tt *}' here is equivalent to a bare colon:
it selects everything.
The reason that you get only the pages from chapter 1---or
more precisely, those where \ccount1\ is 1---is
that both halves of the selector must be satisfied.
Here, \ccount0\ must be between $-\infty$~and~$+\infty$
and \ccount1\ must be between $1$ and $1$.
If you were to run
\begin{quote}
\begin{verbatim}
dviselect 1:5.2 < myfile.dvi > temp.dvi
\end{verbatim}
\end{quote}
you would get only those pages where \ccount0\ (the `page number')
is between $1$ and $5$ {\em and\/} \ccount1\ is $2$.
If there were no such pages, {\tt temp.dvi} would be empty.\footnote
{Not entirely empty: it would still have a preamble and a postamble,
just no pages.}

Occasionally you may want to print something {\em double sided}.
On most laser printers,
this means you have to print all the odd-numbered pages first,
then put the paper back into the printer
and print all the even-numbered pages (or vice versa;
if you do this in the right order,
your output will be properly collated,
but the right order depends on your printer).
You can do this relatively easily with \dviselect:
\begin{quote}
\begin{verbatim}
dviselect even < myfile.dvi > even.dvi
dviselect odd < myfile.dvi > odd.dvi
\end{verbatim}
\end{quote}
The {\tt even} specifier selects all the pages where \ccount0\ is even
(this includes page 0 and any negative even numbers);
the {\tt odd} specifier is its counterpart.
These specifiers are in fact just like any other range,
and you can use them with absolute selectors
or in combination with other ranges.
If you have chapter numbers in \ccount1, for instance,
the command
\begin{quote}
\begin{verbatim}
dviselect '*.odd' < myfile.dvi > oddchapters.dvi
\end{verbatim}
\end{quote}
would select all the odd-numbered chapters.

If you have made it this far,
you may be ready for the full-blown explanation.
Selections are made by taking the union of a list of {\em page selectors}.
Page selectors are separated by commas or whitespace;
they are absolute if they begin with an equals sign `{\tt =}'
and refer to the \cccount\ registers otherwise.
A page selector is composed of {\em ranges\/} separated by periods.
Each range is one of:
a pair of numbers separated by a colon $m\colon\!n$;
a single number $n$, equivalent to $n\colon\!n$;
the word {\tt even};
the word {\tt odd};
or an empty range (bare colon, empty string, or asterisk).
An empty range matches every value;
other ranges match their natural values.
Each period advances to the next \cccount\ register
(an absolute selector cannot include periods).
All unspecified registers are unrestricted (as if by `{\tt *}').
A page is selected if all ten of its \cccount\ registers match
at least one page selector,
or if its absolute page number matches
at least one absolute page range.
Pages in the output file are in the same order
as those in the input file;
the only difference is that some pages may be missing.\footnote
{Actually, the fonts may also get renumbered, and usually do.
The output \dvi\ file also omits any mention of a font that is not used
on the pages selected.
Selecting no pages gives a \dvi\ file that needs no fonts.}

Thus, the following lists are all equivalent:
\begin{quote}
\begin{verbatim}
1:3.*.*.*.1:.*.*.*.*.*
1:3.:.:.:.1:
1:3....1:
1....1:,2....1:,3....1:
\end{verbatim}
\end{quote}
All of these select those pages where:
\begin{quote}
\ccount0\ is between 1 and 3; \\
\ccount1\ is any value; \\
\ccount2\ is any value; \\
\ccount3\ is any value; \\
\ccount4\ is positive ($\ge 1$); \\
\ccount5\ is any value; \\
\ccount6\ is any value; \\
\ccount7\ is any value; \\
\ccount8\ is any value; and \\
\ccount9\ is any value.
\end{quote}
(The last list is made up of three separate selectors,
each of which gets one of the specific \ccount0\ values.)

The most important thing to remember, though,
is that \dviselect\ can only select by \cccount\ values
in the \dvi\ file,
and it is up to you
to get \TeX\ or \LaTeX\ to put out meaningful values.
Otherwise you may be stuck with selecting by absolute page numbers.
DataMuseum.dk

DKUUG/EUUG Conference tapes

⟦4d45fbcb9⟧ TextFile

Derivation

TextFile
