README for using PostScript Type 1 fonts with xdvik
===================================================

Starting with version 22.86, xdvik supports direct display of
PostScript Type 1 fonts using freetype (version 2).  (Prior versions used
t1lib, which is no longer supported.)  Unlike the bitmapped TeX PK fonts
that xdvik used to depend upon, Type 1 fonts only need to be stored in
one size on disk. This means no more waiting for mktexpk runs when
viewing DVI files with previously unused fonts or at a different
resolution, less hassle with temporary directories filling up with
PK files, etc.

To be able to support Type 1 fonts, xdvi uses a config.xdvi file. The
standard `make install' process will copy the file from texmf/config.xdvi
which is suitable for recent TeX Live distributions.
(If the file exists already and has been modified from the
original, the modified file will not be overwritten). Apart from the
section `Debugging your font setup', this README contains mostly
instructions for versions of teTeX older than 1.0.x or non-teTeX
systems; users of teTeX >= 1.0.x and TeX Live should ignore these instructions,
and only consult the `Debugging' section in case of problems with
the Type 1 fonts setup.

Note that xdvi can always use a TeX bitmap (PK) font as a fallback
(produced via mktexpk, which in turn invokes ps2pk or gsftopk), so
it's not vital that xdvi is configured for Type 1 fonts.  However, for
the reasons mentioned above, setting up xdvi properly for Type 1 fonts
is usually preferable.


==========================================================
Instructions for users of older teTeX versions (< 1.0), or
non-teTeX systems:
==========================================================

Xdvi needs to load all Type 1 fonts from disk, which means that it
(just like dvips) needs to translate the TeX names for fonts to
filenames, load encoding vectors according to map files and so on.
This process is governed by fontmap files, which use the same format
as dvips.

The section `Fontmap file format' below and the dvips documentation
contain more information on the fontmap file format.


=================
Font Search Order
=================

The order in which xdvi tries to load a font file is:
1. Virtual fonts
2. Type 1 fonts
3. PK fonts
4. (If xdvi was compiled with gf support:) GF fonts

For example, consider the search for TeX's default font `cmr10'.  In
most texk/TeX Live installations the file cmr10.pfb is present in the
texmf tree.  This means that it is found at step 2 in the search and
the Type 1 font is used.  Currently xdvi handles fonts with no
"implied" encoding (such as cmr10) without configuration.  Most texk and
TeX Live installations come with the Blue Sky Research/Y&Y Type 1 versions
of Knuth's fonts, and xdvi will be able to use them with no further
action.

The 35 `standard PostScript fonts', such as Times Roman, are are
usually available under a different name for previewing the file with
ghostscript. These font files can be used by xdvi, too, and xdvi mimics
ghostscript's process for finding them.  However, this is usually unnecessary,
since TeX Live comes with fonts that can be used in place of those provided
with ghostscript.

As an alternative, these 35 fonts to be copied to a place where xdvi
can find them.  Users of older systems can use the
`t1mapper' script to copy/symlink the required files to a directory
where xdvi can find them; please see the file README.t1mapper and the
manual page of t1mapper for more information.  This support may be dropped
in later versions of xdvi.


===================
Fontmap file format
===================

In principle Xdvi only accepts a subset of the fontmaps used by dvips
and pdftex.  In practice the restrictions are not very restraining.
For a description of the font map file syntax, see the `psfonts.map'
section of the dvips manual (dvips.{texi,dvi,pdf}).

Xdvi accepts fontmaps that obey these rules:

1. The encoding files must have a .enc extention or be included by the
   <[ ... syntax in the fontmap.  Encoding is optional.  The ReEncodeFont
   keyword and its argument is tolerated, but it is _ignored_.  xdvi
   looks for a <foo.enc or <[foo to determine the encoding vector, and
   re-encode the font.

2. The other file in the map line must be a font file in pfa or pfb
   format. The extension need not be included for the sake of xdvi,
   but dvips and pdftex might need it, so it is better to include it when
   using shared fontmap files.

3. There may not be any other input files on a fontmap line.

   Xdvi is not a printer and cannot accept arbitrary postscript
   prologues or set up things in fontmaps.

4. Xdvi decodes the ExtendFont and SlantFont commands in the quoted
   postscript code and the extension factor and slanting is applied
   to the font when displayed.  Any other magic done by the quoted
   PostScript code won't be understood by xdvi.


=========================
Debugging your font setup
=========================

If your Type 1 font setup doesn't work, please check the following:

1. Make sure that xdvi finds your config.xdvi file (this file is optional;
   by default it will use the same map files as dvips lists in its config.ps
   file). If you use it, the file should be located in a directory
   referenced by the TEXINPUTS variable, which can be either set in your
   shell environment, or in your texmf.cnf file.  This directory is generally
   something ending in texmf/dvips/config or texmf-dist/dvips/config .

2. Make sure that xdvi can find the map files listed in your config.xdvi
   file, or in config.ps. Use the `-debug 3968' option for
   xdvi to see where it searches for the files. E.g., with the (ba)sh
   shell:

   $ xdvi -debug 3968 ~/test.dvi 2>&1 | grep xyz.map

   For a successful search, the end of the grep'ed output should
   look like this:
   kdebug:fopen(/some/path/xyz.map, r) => 0x81cccd8

   If the search is not successful, look at the debugging output in
   more detail, checking which variable settings contribute to the
   path where a file is searched.

   Generally, if you have problems here, then you also have them with dvips.

3. Make sure that xdvi finds the Type 1 versions of your fonts. E.g.
   if your texmf tree is located in /usr/local/share/texmf,
   for a minimal LaTeX file like

   \documentclass{minimal}
   \begin{document}test\end{document}

   the command
   $ xdvi -debug 3968 ~/test.dvi 2>&1 | grep cmr10.pfb

   should contain a line at the bottom that looks similar to this:
   kdebug:search(cmr10.pfb) => /usr/local/share/texmf/fonts/type1/bluesky/cm/cmr10.pfb

   Check the settings of TEXMFMAIN, TEXMF and T1FONTS in your
   texmf.cnf file if this doesn't work.


See also kpathsea.pdf and texlive-en.pdf for more information on the
how kpathsea works.


Some common sources of problems:

- You have several texmf.cnf files on your system, and xdvi isn't
  using the one you expect. Use the following command to find out
  which:
  $ xdvi -debug 3968 ~/test.dvi 2>&1 | grep texmf.cnf | grep fopen

- The SELFAUTO... variables are used to define one of the TEXMF or
  XDVIINPUTS variables in texmf.cnf, but xdvi.bin hasn't been
  installed in a path that is compatible with SELFAUTO....
  For example, if your texmf tree is
     /usr/share/texmf/web2c/
  and the search path contains
     {$SELFAUTOLOC,$SELFAUTODIR,$SELFAUTOPARENT}{,{/share,}/texmf{-local,}/web2c}:
  then xdvi.bin should be contained two directories below
  /usr, e.g. in /usr/local/bin/xdvi.bin. ($SELFAUTOPARENT is
  a misnomer in that it actually denotes the grand-parent
  of the current directory, i.e. two levels up in the directory
  hierarchy).

  As a fix, either set XDVIINPUTS in your shell environment, or install
  xdvi.bin in its proper place.