                          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 older 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'.


Installing fonts and running the font server
********************************************

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 file 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.  More information on encodings can be found later in
this document.

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 = 100,100,75,75
----------------------------------------------------------------------

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
the -ll and -lll flags), 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' &


More on encodings
*****************

The backend automatically recodes (properly designed) fonts to fit the
encoding specified by the XLFD names.  A set of common 8 bit encodings
is hardwired into the backend; this set includes

  `iso10646-1'  (Unicode)
  `iso8859-<n>'  for <n>=1 to 10 and 15
  `koi8-r', `koi8-u', `koi8-ru', and `koi8-uni'
  `microsoft-symbol'
  `apple-roman'

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

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').

More encodings can be added by writing encoding definition files.  A
set of encoding definition files for common but non-standard encodings
is provided in the file `encodings.tar'.  You should untar this file
in the directory in which you have installed your TrueType fonts; this
will create a file `encodings.dir' and a subdirectory `encodings'.
Please consult the `README' file in the directory `encodings' for more
information on defining new encodings.


Notes:
******

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

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

Due to the wonders 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 something more deterministic

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


2. 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>


3. 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.  Such fonts may be
used by writing an /ad hoc/ encoding definition file.
