Provided by: catdvi_0.14-14_amd64 
NAME
catdvi - a DVI to plain text converter
SYNOPSIS
catdvi [-d debuglevel, --debug=debuglevel] [-e outenc, --output-encoding=outenc]
[-p pagespec, --first-page=pagespec] [-l pagespec, --last-page=pagespec] [-N, --list-page-
numbers] [-s, --sequential] [-U, --show-unknown-glyphs] [-h, --help] [--version]
[--copyright] [dvi-file]
DESCRIPTION
This manual page documents catdvi version 0.14
catdvi reads the DVI (typesetter DeVice Independent) file dvi-file and dumps a plain text
approximation of the document it describes to stdout. If the argument dvi-file is omitted
or a dash (`-'), catdvi will read from stdin. Several output encodings (different
character sets of the plain text output) are supported, most notably UTF-8.
The current version of 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.
The program needs to read the TFM (Tex Font Metric) files corresponding to the fonts used
in the DVI file. These are searched (and, if necessary and possible, created on the fly)
through the Kpathsea library.
In order to correctly translate a DVI file to text, the 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, catdvi
understands the following input encodings:
`TEX TEXT'
Knuth's original font encoding, also known as OT1.
`TEX TEXT WITHOUT F-LIGATURES'
A variant of the above.
`EXTENDED TEX FONT ENCODING - LATIN'
The Cork encoding, also known as T1.
`TEX MATH ITALIC'
The encoding of Knuth's math italic fonts, also known as OML.
`TEX MATH SYMBOLS'
The encoding of Knuth's math symbol fonts, also known as OMS.
`TEX MATH EXTENSION' (most of it)
The encoding of Knuth's math extension fonts (big operators, brackets, etc.), also
known as OMX.
`TEX TYPEWRITER TEXT'
The encoding of Knuth's typewriter type fonts.
`LATEX SYMBOLS'
The encoding of the lasy fonts.
Henrik Theilings European currency symbol (`eurosym') font.
`TEX TEXT COMPANION SYMBOLS 1---TS1' (almost everything)
The encoding of the text companion fonts.
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.
`BLACKBOARD'
The encoding of the blackboard bold math (`bbm') fonts.
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.
It is impossible to do perfect translation from unmarked-up 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).
The price of alignment is that the output will likely be more than 80 columns wide, even
though 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.
OPTIONS
The program follows the usual GNU command line syntax, with long options starting with two
dashes.
-d debuglevel, --debug=debuglevel
Set the debug output level to 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.
-e outenc, --output-encoding=outenc
Specify the encoding of the output character set. outenc can be one of the numbers
or names from the table below. Names are case insensitive. The following output
encodings should be available:
0: UTF-8
1: US-ASCII
2: ISO-8859-1
3: ISO-8859-15
The command catdvi --help (see below) will give a more up-to-date list of all
compiled-in output encodings. The default encoding is 1.
-p pagespec, --first-page=pagespec
Do not output pages before page pagespec. Pages can be specified in three
different ways; the first two are exactly the same as for dvips(1).
A (possibly negative) number num specifies a TeX page number, which is stored as
the so-called count0 value in the DVI file for every page. Plain TeX uses negative
page numbers for roman-numbered frontmatter (title page, preface, TOC, etc.) so the
count0 values compare as
-1 < -2 < -3 < ... < 1 < 2 < 3 < ...
There may be several pages with the same count0 value in a single DVI file. This
usually happens in documents with a per-chapter page numbering scheme.
A number prefixed by an equals sign (`=num') specifies a physical page, i.e. the
num-th page appearing in the DVI file. Numbering starts with 1. Note that with the
long form of the option you actually need two equals signs, one as part of the long
option and one as part of the page specification. Example:
catdvi --first-page==5 foo.dvi
The third form of a page specification, two numbers separated by a colon
(`num1:num2'), is useful for documents with separately-numbered parts, e.g.
chapters. It refers to the page with count0 value equal to num2 that catdvi
believes to be in part num1. Since those part numbers are not stored in the DVI
file, the program has to guess them: an internal chapter counter is increased by
one every time the 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 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.)
-l pagespec, --last-page=pagespec
Do not output pages after page pagespec. Pages are specified exactly as for the
--first-page option above.
-N, --list-page-numbers
Instead of the contents of pages, output their physical page count, count0 value
and chapter count (see the --first-page option above for a definition of these).
-s, --sequential
Do not attempt to reproduce the page layout; output glyphs in the order they appear
in the DVI file. This may be useful with e.g. multi-column page layouts.
-U, --show-unknown-glyphs
Show the Unicode number of unknown glyphs instead of `?'.
-h, --help
Show usage information and a list of available output encodings, then exit.
--version
Show version information and exit.
--copyright
Show copyright information and exit.
ENVIRONMENT
The usual environment variables TFMFONTS, TEXFONTS, etc. for Kpathsea font search and
creation apply. Refer to the Kpathsea documentation for details.
SEE ALSO
xdvi(1), dvips(1), tex(1), mktextfm(1), the Kpathsea texinfo documentation, utf-8(7).
BUGS
These things do not work (yet):
• No rules are converted.
• Extensible recipes (very large brackets, braces, etc. built out of several smaller
pieces) are not properly handled.
• Complicated math formulae are sometimes misaligned (mostly due to lack of
appropriate word break heuristics).
• Some fonts and font encodings are not recognised yet.
• Most mathematical symbols have no representation in the available output character
sets except Unicode, and hence show up as `?' unless UTF-8 output encoding is
selected. A textual transcription would be desirable.
Watch out for these:
• 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 DVI file to the catdvi maintainer,
stating where in the file the bug is seen).
AUTHORS
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.
The manual page was compiled by Bjoern Brill, using material written by the first two
program authors.
8 November 2002 CATDVI(1)