summaryrefslogtreecommitdiff
path: root/dviware/catdvi/catdvi.1
blob: b772793bd9250cbac40955742b0d8904a8d1b1b8 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
.TH CATDVI 1 "8 November 2002"
.SH NAME
catdvi \- a DVI to plain text converter
.\"
.\"
.\"
.SH SYNOPSIS
.B catdvi
[\fB\-d\ \fIdebuglevel\fB, \-\-debug=\fIdebuglevel\fR]
[\fB\-e\ \fIoutenc\fB, \-\-output-encoding=\fIoutenc\fR]
[\fB\-p\ \fIpagespec\fB, \-\-first-page=\fIpagespec\fR]
[\fB\-l\ \fIpagespec\fB, \-\-last-page=\fIpagespec\fR]
.RB [ \-N,
.BR \-\-list-page-numbers ]
.RB [ \-s,
.BR \-\-sequential ]
.RB [ \-U,
.BR \-\-show-unknown-glyphs ]
.RB [ \-h,
.BR \-\-help ]
.RB [ \-\-version ]
.RB [ \-\-copyright ]
.RI [ dvi-file ]
.br
.\"
.\"
.\"
.SH DESCRIPTION
This manual page documents
.B catdvi
version 0.14
.PP
.B catdvi
reads the
.SM DVI
(typesetter DeVice Independent) file
.I dvi-file
and dumps a plain text approximation of the document it describes to stdout.
If the argument
.I dvi-file
is omitted or a dash (`\-'),
.B catdvi
will read from stdin.
Several
.I output encodings
(different character sets of the plain text output) are supported,
most notably
.SM UTF-8.
.PP
The current version of
.B catdvi
is a work in progress;
it may not be robust enough for production use,
but already works fine with linear english text.
Many mathematical symbols (e.g.\& the uppercase greek letters)
and moderately complex formulae also come out right.                            
.PP 
The program needs to read the
.SM TFM
(Tex Font Metric) files corresponding to the fonts used in the
.SM DVI
file.
These are searched (and, if necessary and possible, created on the
fly) through the
.I Kpathsea
library.
.PP
In order to correctly translate a
.SM DVI
file to text, the
.I input encoding
of the fonts used in it (i.e. a meaning-preserving mapping from
font code points to Unicode) must be known. There are a lot of different
font encodings in use. At the time of writing,
.B catdvi
understands the following input encodings:
.TP
`TEX TEXT'
Knuth's original font encoding, also known as OT1.
.TP
`TEX TEXT WITHOUT F-LIGATURES'
A variant of the above.
.TP
`EXTENDED TEX FONT ENCODING \- LATIN'
The Cork encoding, also known as T1.
.TP
`TEX MATH ITALIC'
The encoding of Knuth's math italic fonts, also known as OML.
.TP
`TEX MATH SYMBOLS'
The encoding of Knuth's math symbol fonts, also known as OMS.
.TP
`TEX MATH EXTENSION' (most of it)
The encoding of Knuth's math extension fonts (big operators, brackets, etc.),
also known as OMX.
.TP
`TEX TYPEWRITER TEXT'
The encoding of Knuth's typewriter type fonts.
.TP
`LATEX SYMBOLS'
The encoding of the lasy fonts.
.TP
Henrik Theilings European currency symbol (`eurosym') font.
.TP
`TEX TEXT COMPANION SYMBOLS 1---TS1' (almost everything)
The encoding of the text companion fonts.
.TP
Martin Vogels symbol (`MarVoSym') font.
Both the 1998 and the 2000 version are supported as far as possible --
about half of the symbols are not representable in Unicode.
.TP
`BLACKBOARD'
The encoding of the blackboard bold math (`bbm') fonts.
.TP
All AMS fonts except the Cyrillic ones.
This includes the AMS math symbols group A and group B, Euler fraktur,
Euler cursive, Euler script and Euler compatible extension fonts.
.PP
It is impossible to do perfect translation from unmarked-up
.SM DVI
to plain text,
since the former does only describe the layout of a page,
and a translator such as this should really know where words and
paragraphs end, and more importantly, which glyphs should be aligned
vertically and which shouldn't.
The current alignment algorithm tries to preserve the relative
horizontal positions of word beginnings; this works well in most cases.
Word breaks are detected using simple heuristics;
paragraphs are not detected at all (and no paragraph fill is attempted).
.PP
The price of alignment is that the output will likely be more than 80
columns wide, even though
.B catdvi
tries very hard not to use more columns than strictly necessary.
Output is usually less than 120 columns, almost always less than 132
columns wide. It may be a good idea to switch your terminal to one of
these modes if possible.
.PP
.\"
.\"
.\"
.SH OPTIONS
The program follows the usual GNU command line syntax, with long
options starting with two dashes.
.TP
.BI \-d\  debuglevel ,\ \-\-debug= debuglevel
Set the debug output level to
.I debuglevel
(default is 10).
Large values will result in lots of debug output, 0 in none at all.
The maximal debug output level currently used is 150.
.\"
.\"
.TP
.BI \-e\  outenc ,\ \-\-output-encoding= outenc
Specify the encoding of the output character set.
.I outenc
can be one of the numbers or names from the table below.
Names are case insensitive.
The following output encodings should be available:
.br
\&
.br
0:\ UTF-8
.br
1:\ US-ASCII
.br
2:\ ISO-8859-1                                         
.br
3:\ ISO-8859-15                                         
.br
\&
.br
The command
.B catdvi \-\-help
(see below) will give a more up-to-date list of all compiled-in output
encodings. The default encoding is 1.
.\"
.\"
.TP
.BI \-p\  pagespec ,\ \-\-first-page= pagespec
Do not output pages before page
.IR pagespec .
Pages can be specified in three different ways; the first two
are exactly the same as for
.BR dvips (1).
.RS
.PP
A (possibly negative) number
.I num
specifies a TeX page number, which is stored as the so-called
.I count0
value in the
.SM DVI
file for every page.
Plain TeX uses negative page numbers for roman-numbered frontmatter
(title page, preface,
.SM TOC,
etc.) so the
.I count0
values compare as
.RS
-1 < -2 < -3 < ... < 1 < 2 < 3 < ...
.RE
There may be several pages with the same
.I count0
value in a single
.SM DVI
file. This usually happens in documents with a per-chapter page numbering
scheme.
.PP
A number prefixed by an equals sign
.RI (`= num ')
specifies a physical page, i\.e\. the
.IR num -th
page appearing in the
.SM DVI
file. Numbering starts with 1.
Note that with the long form of the option you actually need
.I two
equals signs, one as part of the long option and one as part of the
page specification. Example:
.RS
.B catdvi
\-\-first-page==5 foo.dvi
.RE
.PP
The third form of a page specification, two numbers separated by a colon
.RI (` num1 : num2 '),
is useful for documents with separately-numbered parts, e.g. chapters.
It refers to the page with
.I count0
value equal to
.I num2
that
.B catdvi
believes to be in part
.IB num1 .
Since those part numbers are not stored in the
.SM DVI
file, the program has to guess them:
an internal
.I chapter
counter is increased by one every time
the
.I count0
value of the current page is not greater (in above ordering) than that
of the previous page.
The counter is initialized to 1 if the first page
has negative
.I count0
value and to 0 otherwise. (A document with separately numbered parts
will probably have separately numbered frontmatter as well, and then this
rule keeps the internal counter equal to
real world part numbers.)
.RE
.\"
.\"
.TP
.BI \-l\  pagespec ,\ \-\-last-page= pagespec
Do not output pages after page
.IR pagespec .
Pages are specified exactly as for the
.B \-\-first-page
option above.
.\"
.\"
.TP
.B \-N, \-\-list-page-numbers
Instead of the contents of pages, output their
physical page count,
.I count0
value and
.I chapter
count (see the
.B \-\-first-page
option above for a definition of these).
.\"
.\"
.TP
.B \-s, \-\-sequential
Do not attempt to reproduce the page layout;
output glyphs in the order they appear in the
.SM DVI
file. This may be useful with e.g. multi-column page layouts.
.\"
.\"
.TP
.B \-U, \-\-show-unknown-glyphs
Show the Unicode number of unknown glyphs instead of `?'.
.\"
.\"
.TP
.B \-h, \-\-help
Show usage information and a list of available output encodings,
then exit.
.\"
.\"
.TP
.B \-\-version
Show version information and exit.
.\"
.\"
.TP
.B \-\-copyright
Show copyright information and exit.                                           
.\"
.\"
.\"
.SH ENVIRONMENT
The usual environment variables TFMFONTS, TEXFONTS, etc.\& for
.I Kpathsea
font search and creation apply.
Refer to the
.I Kpathsea
documentation for details.
.\"
.\"
.\"
.SH "SEE ALSO"
.BR xdvi (1),
.BR dvips (1),
.BR tex (1),
.BR mktextfm (1),
the
.I Kpathsea
texinfo documentation,
.BR utf-8 (7).
.\"
.\"
.\"
.SH BUGS
These things do not work (yet):
.IP \(bu
No rules are converted.
.IP \(bu
Extensible recipes (very large brackets, braces, etc. built out of several
smaller pieces) are not properly handled.
.IP \(bu
Complicated math formulae are sometimes misaligned (mostly due to lack
of appropriate word break heuristics).
.IP \(bu
Some fonts and font encodings are not recognised yet.
.IP \(bu
Most mathematical symbols have no representation in the available
output character sets except Unicode, and hence show up as `?' unless
.SM UTF-8
output encoding is selected. A textual transcription would be desirable.
.LP
Watch out for these:
.IP \(bu
If there is a space where it does not belong or if there is no space
where there should be one,
report this as a bug (send the
.SM DVI
file to the
.B catdvi
maintainer, stating where in the file the bug is seen).
.\"
.\"
.\"
.SH AUTHORS
.B catdvi
was written by
Antti-Juhani Kaijanaho <gaia@iki.fi>,
based on a skeletal version by J.H.M.\ Dassen (Ray).
Bjoern Brill <brill@fs.math.uni-frankfurt.de>
did further improvements and currently maintains the program.
.PP
The manual page was compiled by Bjoern Brill, using
material written by the first two program authors.