Debian Codegraph @

texmf-dist/doc/man/man1/dvipos.1

raw
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.