| 1 |
.TH "DVIPOS" "1" "30 August 2022" "dvipos 20070107 (KPATHSEA)" "ConTeXt" |
| 2 |
.de URL |
| 3 |
\\$2 \(laURL: \\$1 \(ra\\$3 |
| 4 |
.. |
| 5 |
.if \n[.g] .mso www.tmac |
| 6 |
.de EX |
| 7 |
.in +3 |
| 8 |
.nf |
| 9 |
.ft CW |
| 10 |
.. |
| 11 |
.de EE |
| 12 |
.in -3 |
| 13 |
.ft R |
| 14 |
.fi |
| 15 |
.. |
| 16 |
|
| 17 |
.SH NAME |
| 18 |
dvipos \- compute positions in a DVI file |
| 19 |
|
| 20 |
.SH SYNOPSIS |
| 21 |
\fBdvipos\fP [ \fIOPTION\fP... ] \fIinfile[.dvi]\fP |
| 22 |
|
| 23 |
.SH DESCRIPTION |
| 24 |
\fBdvipos\fP parses a DVI file looking for \fIpos:\fP specials. It |
| 25 |
currently recognizes \fIpos:pxy\fP, \fIpos:pxywhd\fP, |
| 26 |
\fIpos:pxyplus\fP, \fIpos:begbox\fP, \fIpos:endbox\fP, |
| 27 |
\fIpos:beglines\fP, and \fIpos:endlines\fP. It then outputs the |
| 28 |
information from those specials along with information that only a DVI |
| 29 |
postprocessor could determine, such as the current \fIx\fP and \fIy\fP |
| 30 |
location. The output looks like: |
| 31 |
.EX |
| 32 |
\\pospxywhd{text:54}{54}{10663sp}{8535sp}{21326sp}{34081sp}{0sp} |
| 33 |
.EE |
| 34 |
and is suitable for including in a |
| 35 |
.BR tex (1) |
| 36 |
or |
| 37 |
.BR pdftex (1) |
| 38 |
auxiliary file, such as \fIdocument.tuo\fP, to be read in by the next |
| 39 |
run of the |
| 40 |
.BR tex (1) |
| 41 |
or similar typesetting engine. |
| 42 |
|
| 43 |
.SH OPTIONS |
| 44 |
|
| 45 |
.TP |
| 46 |
\fB-h, --help\fR |
| 47 |
print usage. |
| 48 |
.TP |
| 49 |
\fB-W, --warning\fR |
| 50 |
print warnings. |
| 51 |
.TP |
| 52 |
\fB-v, --verbose\fR |
| 53 |
print verbose output. |
| 54 |
.TP |
| 55 |
\fB-d, --debug\fR |
| 56 |
print |
| 57 |
.BR dvitype (1) |
| 58 |
debugging data. |
| 59 |
.TP |
| 60 |
\fB-s, --smashchars\fR |
| 61 |
regard height and depth as zero. |
| 62 |
.TP |
| 63 |
\fB-o, --output=\fIFILE\fR |
| 64 |
send all output to FILE. Without this option, output goes to stdout. |
| 65 |
.TP |
| 66 |
\fB-b, --bbox[=\fP\fIFILE\fP]\fR |
| 67 |
send bounding box to FILE (default FILE is \fIinfile.pos\fP). |
| 68 |
.TP |
| 69 |
\fB-f, --framed[=\fP\fIBASE\fP]\fR |
| 70 |
request copy of DVI file, \fIBASE.dvi\fP, with bounding boxes |
| 71 |
\fBframed\fP (default FILE is \fIinfile_frames.dvi\fP). See the |
| 72 |
\fB--framesize\fP option. |
| 73 |
.TP |
| 74 |
\fB-m, --mag=\fIINT\fR |
| 75 |
override |
| 76 |
.BR tex (1) |
| 77 |
magnification by INT. |
| 78 |
.TP |
| 79 |
\fB-w, --framesize=\fIINT\fR |
| 80 |
set frame rule size by INT (default 6554 = .1pt). |
| 81 |
.TP |
| 82 |
\fB-p, --pages=\fIX:Y\fR |
| 83 |
set page ranges from X to Y. |
| 84 |
|
| 85 |
.SH USAGE |
| 86 |
.B dvipos |
| 87 |
is run mostly behind the scenes by ConTeXt's |
| 88 |
.BR texexec (1) |
| 89 |
between runs of |
| 90 |
.BR tex (1) |
| 91 |
or |
| 92 |
.BR pdftex (1), |
| 93 |
in order to provide information to and get information about |
| 94 |
positional graphics. These graphics are provided by the MetaFun |
| 95 |
interface to |
| 96 |
.BR mpost (1). |
| 97 |
\fBdvipos\fP is not used (or needed) in PDF-output mode but is |
| 98 |
needed for DVI-output mode. |
| 99 |
.BR pdftex (1) |
| 100 |
starting with version 1.40 can produce position information even in |
| 101 |
DVI mode, so once the ConTeXt macros take advantage of this feature, |
| 102 |
the need for \fBdvipos\fP will fade. |
| 103 |
|
| 104 |
Until then, here is a typical use of \fBdvipos\fP: |
| 105 |
.EX |
| 106 |
dvipos notes.dvi |
| 107 |
.EE |
| 108 |
The position information that is output is collected by |
| 109 |
.BR texexec (1) |
| 110 |
to include in the \fInotes.tuo\fP auxiliary file to use in the next |
| 111 |
run. |
| 112 |
|
| 113 |
|
| 114 |
.SH EXAMPLES |
| 115 |
.TP |
| 116 |
Extract positions from \fIdoc.dvi\fP, with output to \fIdoc.loc\fP: |
| 117 |
\f(CWdvipos -o doc.loc doc.dvi\fP |
| 118 |
.TP |
| 119 |
Same as above, but also send bbox information to \fIdoc.pos\fP: |
| 120 |
\f(CWdvipos -b -o doc.loc doc.dvi\fP |
| 121 |
.TP |
| 122 |
Instead send bbox information to \fI/tmp/debug.pos\fP: |
| 123 |
\f(CWdvipos -b=/tmp/debug.pos -o doc.loc doc.dvi\fP |
| 124 |
|
| 125 |
.SH "SEE ALSO" |
| 126 |
.BR dvips (1), |
| 127 |
.BR dvitype (1), |
| 128 |
.BR mpost (1), |
| 129 |
.BR pdftex (1), |
| 130 |
.BR tex (1), |
| 131 |
.BR texexec (1). |
| 132 |
|
| 133 |
For more about positional graphics, see the MetaFun documentation on |
| 134 |
the |
| 135 |
.URL "https://wiki.contextgarden.net/MetaFun" "ConTeXt wiki" . |
| 136 |
|
| 137 |
.SH BUGS |
| 138 |
If you specify a file for the \fB-b\fP option, you must join the |
| 139 |
option and name with \fB=\fP rather than (the more common) space: |
| 140 |
.EX |
| 141 |
dvipos -b=/tmp/debug.pos notes.dvi |
| 142 |
.EE |
| 143 |
works, but |
| 144 |
.EX |
| 145 |
dvipos -b /tmp/debug.pos notes.dvi |
| 146 |
.EE |
| 147 |
does not. |
| 148 |
|
| 149 |
.SH AUTHOR |
| 150 |
.B dvipos |
| 151 |
is written by Jin-Hwan Cho <[email protected]>. It is free |
| 152 |
software (GPLv2 or later). This manpage was written by Sanjoy |
| 153 |
Mahajan <[email protected]> and is in the public domain. It is currently |
| 154 |
maintained as part of TeX Live. |