| 1 |
.\" Copyright (c) 1987-2012 UMD-CS, released under the X11 license; |
| 2 |
.\" see README and source files. |
| 3 |
.TH DVISELECT 1 |
| 4 |
.SH NAME |
| 5 |
dviselect \- extract pages from DVI files |
| 6 |
.SH SYNOPSIS |
| 7 |
.B dviselect |
| 8 |
[ |
| 9 |
.B \-s |
| 10 |
] [ |
| 11 |
.B \-i |
| 12 |
.I infile |
| 13 |
] [ |
| 14 |
.B \-o |
| 15 |
.I outfile |
| 16 |
] |
| 17 |
.I "list of pages" |
| 18 |
[ |
| 19 |
.I infile |
| 20 |
[ |
| 21 |
.I outfile |
| 22 |
] ] |
| 23 |
.SH DESCRIPTION |
| 24 |
.I Dviselect |
| 25 |
selects pages from a DVI file produced by TeX, |
| 26 |
creating a new DVI file |
| 27 |
usable by any of the TeX conversion programs, |
| 28 |
or even by |
| 29 |
.I dviselect |
| 30 |
itself. |
| 31 |
.PP |
| 32 |
A |
| 33 |
.I range |
| 34 |
is a string of the form |
| 35 |
.IR even , |
| 36 |
.IR odd , |
| 37 |
or |
| 38 |
.I first:last |
| 39 |
where both |
| 40 |
.I first |
| 41 |
and |
| 42 |
.I last |
| 43 |
are optional numeric strings, with negative numbers indicated by |
| 44 |
a leading underscore character ``_''. If both |
| 45 |
.I first |
| 46 |
and |
| 47 |
.I last |
| 48 |
are omitted, the colon may also be omitted, or may be replaced |
| 49 |
with an asterisk ``*''. A |
| 50 |
.I page range |
| 51 |
is a list of ranges separated by periods. A |
| 52 |
.I "list of pages" |
| 53 |
is described by a set of page ranges separated by commas and/or white space. |
| 54 |
.PP |
| 55 |
.I Dviselect |
| 56 |
actually looks at the ten |
| 57 |
.I count |
| 58 |
variables that TeX writes; the first of these (\ecount0) is the |
| 59 |
page number, with \ecount1 through \ecount9 having varied uses |
| 60 |
depending on which macro packages are in use. (Typically \ecount1 |
| 61 |
might be a chapter or section number.) A page is included in |
| 62 |
.IR dviselect 's |
| 63 |
output if all its \ecount values match any one of the ranges |
| 64 |
listed on the command line. For example, the command |
| 65 |
``dviselect *.1,35:'' |
| 66 |
might select everything in chapter 1, as well as pages 35 and up. |
| 67 |
``dviselect 10:30'' would select pages 10 through 30 (inclusive). |
| 68 |
``:43'' means everything up to and including page 43 (including |
| 69 |
negative-numbered pages). |
| 70 |
To get all even-numbered pages, use ``even''; |
| 71 |
to get all odd-numbered pages, use ``odd''. |
| 72 |
If a Table of Contents has negative page numbers, ``:_1'' will select it. |
| 73 |
Note that ``*'' must be quoted from the shell; |
| 74 |
the empty string is more convenient to use, if harder to read. |
| 75 |
.PP |
| 76 |
Instead of \ecount values, |
| 77 |
.I dviselect |
| 78 |
can also select by ``absolute page number'', where the first page |
| 79 |
is page 1, the second page 2, and so forth. Absolute page numbers |
| 80 |
are indicated by a leading equal sign ``=''. Ranges of absolute |
| 81 |
pages are also allowed: ``dviselect =3:7'' will extract the third |
| 82 |
through seventh pages. Dot separators are not legal in absolute |
| 83 |
ranges, and there are no negative absolute page numbers. |
| 84 |
Even/odd specifiers, however, are legal; |
| 85 |
``dviselect =even'' selects every other page, |
| 86 |
starting with the second. |
| 87 |
.PP |
| 88 |
More precisely, an asterisk or an empty string implies no limit; |
| 89 |
an equal sign means absolute page number rather than \ecounts; |
| 90 |
a leading colon means everything up to and including the given page; a |
| 91 |
trailing colon means everything from the given page on; |
| 92 |
the word ``even'' means only even values shall be accepted; |
| 93 |
the word ``odd'' means only odd values shall be accepted; and |
| 94 |
a period indicates that the next \ecount should be examined. |
| 95 |
If fewer than 10 ranges are specified, the remaining \ecounts |
| 96 |
are left unrestricted (that is, ``1:5'' and ``1:5.*'' are equivalent). |
| 97 |
A single number \fIn\fP is treated as if it were the range \fIn:n\fP. |
| 98 |
An arbitrary number of page selectors may be given, separated by commas |
| 99 |
or whitespace; a page is selected if any of the selectors matches |
| 100 |
its \ecounts or absolute page number. |
| 101 |
.PP |
| 102 |
Dviselect normally prints the page numbers of the pages selected; the |
| 103 |
.I \-s |
| 104 |
option suppresses this. |
| 105 |
.SH AUTHOR |
| 106 |
Chris Torek, University of Maryland |
| 107 |
.SH "SEE ALSO" |
| 108 |
dviconcat(1), latex(1), tex(1) |
| 109 |
.br |
| 110 |
.I "MC-TeX User's Guide" |
| 111 |
.br |
| 112 |
.I "The TeXbook" |
| 113 |
.SH BUGS |
| 114 |
A leading ``-'' ought to be allowed for negative numbers, but it |
| 115 |
is currently used as a synonym for ``:'', for backwards compatibility. |
| 116 |
.PP |
| 117 |
Section or subsection selection will sometimes fail, for the DVI |
| 118 |
file lists only the \ecount values that were active when the page |
| 119 |
ended. Clever macro packages can alleviate this by making use of |
| 120 |
other ``free'' \ecount registers. Chapters normally begin on new |
| 121 |
pages, and do not suffer from this particular problem. |
| 122 |
.PP |
| 123 |
The heuristic that decides which arguments are page selectors |
| 124 |
and which are file names is often wrong. |
| 125 |
Using shell redirection or the \-i and \-o options is safest. |
| 126 |
.PP |
| 127 |
.I Dviselect |
| 128 |
does not adjust the parameters in the postamble; however, since these |
| 129 |
values are normally used only to size certain structures in the output |
| 130 |
conversion programs, and the parameters never need to be adjusted upward, |
| 131 |
this has not proven to be a problem. |