                          Usage instructions


This being a modification to the standard X font server, it is
entirely compatible with it.  Relevant manual pages are xfs(1) (fs(1)
on some systems) and X(3x) (X(7) on some systems).  The naming scheme
used for X fonts is called the `X Logical Font Description', and you
may want to read the XLFD specification, which can be found in the file
`xc/doc/hardcopy/XLFD/xlfd.PS.Z'.

In order to use TrueType fonts, you will need to create a
`fonts.scale' file in a directory containing TrueType fonts.  You will
then type:

  % mkfontdir

in that directory, which will copy the contents of the `fonts.scale'
file a file called `fonts.dir'.  The rationale for this somewhat
baroque procedure can be found in the mkfontdir(1) manual page.

Here's an example of a `fonts.scale' file:
----------------------------------------------------------------------
5
times.ttf -monotype-times-medium-r-normal--0-0-0-0-p-0-iso8859-1
times.ttf -monotype-times-medium-r-normal--0-0-0-0-p-0-iso8859-2
times.ttf -monotype-times-medium-r-normal--0-0-0-0-p-0-iso8859-5
times.ttf -monotype-times-medium-r-normal--0-0-0-0-p-0-koi8-r
times.ttf -monotype-times-medium-r-normal--0-0-0-0-p-0-iso10646-1
----------------------------------------------------------------------

This `fonts.dir' defines 5 scalable fonts, described by their XLFD
name, and all referring to the same font file.  Those fonts differ
only in the encoding used.  The full list of encodings handled
includes:

  `iso10646-1'
  `iso8859-<n>'  for <n>=1 to 10
  `koi8-r'
  `koi8-u'
  `microsoft-symbol'
  `apple-roman'
  `truetype-raw'

Of course, most fonts will not contain all the glyphs needed for these
encodings.

Two of those encodings are unusual.  `iso10646-1' refers to Unicode.
`truetype-raw' simply lists all the glyphs in the font file in the raw
order of their indices.  It is not likely to be useful for anything
except testing (`ftview' is a better tool for viewing all the glyphs
in a font file).

The encodings `microsoft-symbol' and `apple-roman' are only likely to
be useful with symbol fonts (Macintosh symbol fonts often have an
encoding table tagged as `apple-roman').

A complete `fonts.scale' file for a set of common fonts is provided in
the file `fonts.scale.sample'.

You will also need a config file.  This is the one that I use:

----------------------------------------------------------------------
clone-self = off
use-syslog = off

client-limit = 20

catalogue = /home/jec/fonts/ttf

error-file = /home/jec/fonts/xfs.errors

# in decipoints
default-point-size = 120

# x,y
default-resolutions = 75,75,100,100
----------------------------------------------------------------------

If you have both bitmap fonts and scalable fonts, the scalable fonts
should appear first in the catalogue entry.  This should make the
server prefer scalable fonts to scaling bitmap fonts, but still use a
bitmap font when there is an exact match.

You can then run the font server, for example by doing:

  % xfs -port 7100 -config /path/to/your/config/file &

(If there is another font server running, you might need to use a
different port.)

First check that the server works without adding it to your fontpath:

  % fslsfonts -server localhost:7100
  % fslsfonts -ll -server localhost:7100 \
      -fn '-monotype-times-medium-r-normal--0-0-0-0-p-0-iso8859-1'
  % showfont -server localhost:7100 \
      -fn '-monotype-times-medium-r-normal--0-0-0-0-p-0-iso8859-1'

You can then add the new server to the font path:

  % xset +fp tcp/localhost:7100

Useful tools for examining fonts include xlsfonts(1) (especially with -ll
and -lll), showfont(1) and xfd(1).

  % xfd -fn '-monotype-times-medium-r-normal--0-140-0-0-p-0-iso8859-1' &

Subsetting:

  % xfd \
      -fn '-monotype-times-medium-r-normal--0-140-0-0-p-0-iso8859-1[32_127]' &

Linear transformations:

  % xfd \
      -fn '-monotype-times-medium-r-normal--0-[14 0 3 14]-0-0-p-0-iso8859-1' &



Notes:

1. Some applications have resource files that specify fonts such as:

  -*-times-medium-r-*--*-120-*-*-p-*-*-*

Due to the miracles of lexicographic ordering, such patterns will
resolve to Unicode fonts, which will break applications that do not
expect to see 16-bit fonts.  Such resource files should be fixed to
specify at least something like

  -*-times-medium-r-*--*-120-*-*-p-*-iso8859-1

and preferably the more deterministic

  -monotype-times-medium-r-normal--*-120-*-*-p-*-iso8859-1


2. There is no standard (registered) way of referring to a Unicode
encoding in X11.  I have chosen `iso10646-1' for compatibility with
the `ETL' fonts (available in the `contrib' directory on `ftp.x.org').


3. Currently, the code rasterises all the glyphs at a font at font
open time.  While there are advantages to this strategy (metrics are
precise, the font file can be closed immediately, etc.), it can take
quite a long time for very large fonts.  A partial solution is to
modify your application (or its resources) to use subsetting.

Suppose that you want to use a large Unicode font but are only
interested in the first four blocks of Unicode (Basic Latin, Latin-1
Supplement, Latin Extended-A, Latin Extended-B).  Then your
application might request a font such as:

  -bitstream-cyberbit-medium-r-normal--0-0-0-0-p-0-iso10646-1[0_0x1FF]

which only includes the needed glyphs.  The current list of blocks in
Unicode can be found in

  <URL:ftp://ftp.unicode.org/Public/UNIDATA/BLOCKS.TXT>


4. Many TrueType fonts are broken.  In particular, some have been
`rigged' to contain e.g. an ISO 8859-2 encoding vector labeled as some
Microsoft CodePage, or some Macintosh encoding.  Except for the
concession made by including the `apple-roman' encoding, this code
does not support such broken fonts.
