Directory dviware/mdvi

This is MDVI, a free DVI previewer.

MDVI is distributed under the terms of the GNU General Public License. See
the file `COPYING' for details. 

MDVI is currently is in its early stages of development, and needs much more
work before being considered ready for general use. Although it is quite
usable, it lacks key features that any self-respecting DVI previewer must
include. See the file `TODO' for details.

Requirements
============

  - An ANSI C compiler (tested with gcc and Sun's cc).
  - X11 (no toolkits, just Xlib).
  - kpathsea. Any version should do, but I use 3.3.3. If you want to use
    TrueType fonts, you need at least version 3.2.
  - GNU Make, any version (ftp://ftp.gnu.org/pub/make)
  - To use Type 1 fonts, you also need the T1lib library. Get it from
    ftp://ftp.neuroinformatik.ruhr-uni-bochum.de/pub/software/t1lib/
  - To use TrueType fonts, you need the FreeType library. MDVI currently
    supports only versions 1.x (tested with 1.3) of FreeType. A port to 
    FreeType 2.x should be completed soon. Get 1.x from
    http://freetype.sourceforge.net

You can get all the necessary libraries from MDVI's anonymous FTP site, at
ftp://mdvi.sourceforge.net/pub/mdvi. The files you'll find there are:

    kpathsea-3.3.3.tar.gz   
         A stripped down version of the web2c-7.3.3 package that contains
         the kpathsea library only. Use this if your TeX distribution does
         not use kpathsea to locate files.
    t1lib-1.0.1.tar.gz
         The T1lib library, required to support Type1 PostScript fonts.
    freetype-1.3.tar.gz
         The FreeType library.
    tex-ttf-fonts.tar.gz
         TrueType fonts for use with TeX. These fonts are free, originally
         obtained from ftp://ftp.tug.org.
    dvips-config.tar.gz, pdftex-config.tar.gz
         Fontmap files

Why use MDVI?
=============

Although MDVI is far from complete, it already has some unique features.
Namely:

  - A clean, minimal, but efficient interface. No buttons, no distractions.
  - Rendering of pages in 8 different orientations.
  - Independent horizontal and vertical scaling factors and resolutions
    implemented for all font formats. MDVI can closely match the final
    printed output as produced by dvips or other printer drivers.
  - Ability to partially read a DVI file, including a powerful mechanism to
    select the pages that are actually processed, based on either DVI page
    numbers, TeX \counters, or both.
  - Several ways of sorting pages, which is nice when viewing LaTeX
    documents that have a table of contents. Sorting pages up by TeX number,
    the table of contents comes up as the first page.
  - Modular design, with a clear division between device-independent code to
    process DVI files and the actual rendering of glyphs. Adding support for
    a new font format is a trivial task.
  - Ability to change all rendering parameters on the fly (including
    resolutions).
  - Can process DVI files in `batch mode' without a user interface. Useful
    for detecting font-related problems (and to generate all the fonts
    needed by a DVI file without actually displaying it).
  - Fully customizable via environment variables and `texmf.cnf' - no need
    for yet another configuration file to maintain.
  - Support for fonts in PK, GF, VF and OVF formats.
  - Support for Type1 PostScript fonts, metric files, fontmaps and
    encodings. MDVI can use the same configuration files and fonts used by
    dvips/pdftex.
  - Experimental support for TrueType fonts via FreeType 1.x, using
    PostScript fontmaps and encoding files.
  - Builtin support for font metrics in TFM, AFM, OFM0 and OFM1 formats. If
    a font is missing but a metrics file can be found, MDVI can display a
    box with the right dimensions in its place, or simply ignore the
    characters from that font.
  - Extensible: Support for new fonts and \specials can be added at run-time
    through an extremely simple API.
  - Font support completely configurable at run-time, via environment
    variables and/or command line options.

The most important omissions in MDVI:

  - Support for X resource files.
  - Rendering of PostScript specials (but EPS bounding boxes are displayed
    correctly, unless they are rotated).
  - Transparent glyphs. Currently MDVI uses a cheap trick to simulate
    transparent glyphs, which consists in drawing with a GXand function.
    This will NOT work in many common X visuals, and even when it does it
    still does not yield correct results when the background color is not
    white.
  - Zooming. This effect can still be achieved by changing the resolution or
    the shrinking factor inside the viewer. See the description of keyboard
    commands at the end.
  - It's slower than it could be.

These will be improved in the future, but for now the priority is robustness
and correctness.

Building
========

First make sure you have all the required tools and libraries, described
above, and that they are properly installed. 

If you plan to use Type1 and/or TrueType fonts, you also need to have the
configuration files used by dvips or pdftex installed in kpathsea's texmf
tree. More precisely, you need the PostScript font maps and encoding vector
files.

If your TeX distribution does not use kpathsea, you'll have to install that
library independently. It's not hard at all, and it's worth the effort.

If the kpathsea library is in a standard place, you can just type

        $ ./configure
        $ make
        $ make install

If the `configure' script fails, or if you want to enable additional
features of MDVI, you can use the following options:

  --with-kpathsea-headers=DIRECTORY
  --with-kpathsea-library=DIRECTORY
       Use these to tell the configure script where to look for kpathsea

  --with-type1-fonts
  --with-t1lib-headers=DIRECTORY
  --with-t1lib-library=DIRECTORY
       The option --with-type1-fonts enables support for Type1 fonts. Notice
       that support for these fonts is not enabled by default. The other two
       options tell `configure' where to find t1lib's headers and the
       library itselg.
       
  --with-freetype
  --with-freetype-headers=DIRECTORY
  --with-freetype-library=DIRECTORY
       The option --with-freetype enables support for TrueType fonts. Notice
       that support for these fonts is not enabled by default. The other two
       options tell `configure' where to find FreeType's headers and the
       library itself.
       
  --disable-nls
       If you don't want MDVI to support languages other than english.

Note: I have had problems during the final link against the kpathsea
library on Solaris if the library was compiled with gcc, and MDVI is
compiled with Sun's cc. To solve the problem, just use the commands

       $ ar x `gcc --print-libgcc-file-name` _eprintf.o

and add `_eprintf.o' to KPSE_LIBS in the Makefile. Then the link should be
successful. It shouldn't be hard to make `configure' detect this, but I
don't think it's worth it. If you do, let me know.

Fonts
=====

To use Type1/TrueType fonts, MDVI needs PostScript fontmaps. These are
usually distributed with dvips and pdftex, but you can get them separately
from MDVI's ftp site (see above). Please notice that you need to have a
correct fontmap entry for *each* font you want to use, or the output will be
incorrect.

Using MDVI
==========

MDVI's UI is a bit primitive by today's standards, but it is easy to learn
and powerful. It is driven exclusively with the keyboard, although some
functionality is bound to the mouse. All the parameters that affect the
reading and rendering of DVI files can be specified in the command line, and
also via environment variables. To see a list of these variables, run mdvi
with the `--info' option.

Keyboard commands
-----------------

Although some of this commands may be considered rather exotic, to say the
least, they exist mostly to test the basic DVI interpreter and the rendering
engine.

Keyboard commands without arguments:

        PageUp/PageDown         go to previous/next page
        Control+PageUp          go to the first page
        Control+PageDown        go to the last page
        Up/Down/Left/Right      scroll the window in the given direction
                                (the movement rate can be reduced by holding
                                the Shift key while pressing the direction
                                key, and further reduced by holding the
                                Control key).
        Control+Fn              save the displayed page number
        Fn                      restore a saved page number
        q                       quits MDVI
        b                       switches between human and TeX's eyes
        a                       toggles glyph antialiasing
        l                       redraws the page
        L                       reloads the DVI file from disk
        R                       rotates the page clockwise by 90 degrees
        r                       rotates the page counter-clockwise
        F                       flips the page vertically
        f                       flips the page horizontally
        ?                       displays a summary of keyboard commands on
                                standard output (sorry, but this is all the
                                online help available at this point).

Keyboard commands that accept a numeric argument:

The argument is typed before pressing the specified key. You will not see
it, but it'll be there. Some commands accept negative or even 
floating point numbers.

 Command  Description                                     Neg  Pos  Floats
    p     go to current page + ARG                        yes  yes truncated
    j     jump to page number ARG (last+ARG if negative)  yes  yes truncated
    t     jump to TeX's page number ARG                   yes  yes truncated
    d     change resolution                                no  yes truncated
    m     change magnification                             no  yes  yes
    x     change horizontal shrinking ratio                no  yes truncated
    y     change vertical shrinking ratio                  no  yes truncated
    n     change pixel density (for bitmap shrinking)      no  yes truncated
    g     change gamma correction (for antialiased glyphs) no  yes  yes

where `truncated' means that all the decimal digits are dropped. Be advised
that changing the resolution or the magnification may take some time,
because fonts may need to be recreated by kpathsea. Also, not all fonts
support arbitrary resolutions (Type1 and TrueType fonts do, as far as I
know), and kpathsea may fail with a message saying that it is not able to
guess the MF mode from the specified resolution. Using the --mfmode option
might help.
    
Mouse usage
-----------

    Button 1            displays a ruler that can be moved around the page
    Button 1 + Shift    displays a horizontal ruler only
    Button 1 + Control  displays a vertical ruler only