                          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 (those funky names with fourteen
dashes) 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 scalable fonts, you will need a directory with font
files and a `fonts.scale' file.  You will also need a directory
containing the contents of the `encodings.tar' tarfile, say
`/usr/lib/X11/fonts/encodings'.  You will then type

  % mkfontdir -e /usr/lib/X11/fonts/encodings \
              -e /usr/lib/X11/fonts/encodings/large

(all on one line) in the directory containing the font files, which
will copy the contents of the `fonts.scale' file to a file called
`fonts.dir', and create a file `encodings.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.

Sample `fonts.scale' files for common TrueType, Type 1 and Speedo
files can be found in the files `fonts.scale.*' of the distribution.
Two of them are drop-in replacements for the ones provided with X11R6.
For TrueType font files, `fonts.scale' files are best built with Joerg
Pomnitz' `ttfmkfdir' utility.

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

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
*****************

All three scalable backends (Type 1, Speedo, and TrueType) recode
(properly designed) fonts to fit the encoding specified by the XLFD
names.  A set of common 8 bit encodings is hardwired into the font
system; this set includes

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

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 fonts; this will create a
file `encodings.dir' and a subdirectory `encodings'.  If you want to
use the encodings with fonts in more than one directory, you will want
to softlink the files `encodings.dir' and `encodings'.

Please consult the `README' file in the directory `encodings' for more
information on defining new encodings.


Delayed rasterisation
*********************

In this version of xfsft, rasterisation is delayed, in that glyphs are
rasterized on a strictly as-needed basis, which makes opening fonts
much faster, especially in the case of fonts with a very large number
of glyphs (such as fonts for Ideographic scripts).

The main problem with delayed fonts is that much of the font metric
information is difficult to provide correctly.  The main casualty is
the average width (and the raw average width), which are impossible to
compute without rasterising all the glyphs.  This code attempts to get
them right for monospaced fonts, and provide an educated guess for
others.

More precisely, the average width is computed as follows:

 if the font is marked as fixed width
   set the average width to the maximum width
 else if the font has an `os/2' table
   set the average width to the `weighted average width'
 else
   set the average width to half the maximum width
 fi

This algorithm will produce results that are only meaningful for the
Latin script.

Note that glyph metrics, unlike font metrics, are still computed
accurately.

Rasterisation of charcell fonts is especially aggressively delayed.
In order to benefit from this optimisation, you will need to declare
your fonts as being suitable for this optimisation; i.e. you may want
to replace entries of the form

  -monotype-courier-medium-r-normal--0-0-0-0-m-0-iso10646-1
                                             ^
by

  -monotype-courier-medium-r-normal--0-0-0-0-c-0-iso10646-1
                                             ^

This change is particularly suitable for fonts for Ideographic
scripts.  However, it may lead to stray pixels being cut off in some
cases (observe in particular the right serif of the lowercase `m' at
small sizes).

This version shares glyph pixmap data between X fonts that are
identical except for the encoding; this means that when a font file is
opened under two different encodings, the common glyphs are rasterised
only once.  Finally, if a font file is opened at different sizes, some
context is shared between the instances.


TTC support
***********

TTC files should be included in `fonts.scale' files as

  :3:alamakot.ttc -misc-alamakota-...

where `3' is the number of the face.


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. The X11 protocol forces fonts to provide glyph metrics for all
glyphs at once, which may 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 fonts are broken.  For example, many TrueType fonts are
`rigged' to contain /e.g./ an ISO 8859-2 encoding vector labeled as
some Microsoft CodePage, or some Macintosh encoding.  Similarly, many
Type 1 fonts have Cyrillic characters assigned the names of glyphs in
the Adobe StandardEncodings.

In order to use such fonts, an /ad hoc/ encoding vector may be used.
In the case of Type 1 fonts, an alternative approach is to list them
with the encoding `adobe-fontspecific' in the `fonts.scale' file.

In both cases, you will probably want to include an entry in a
`fonts.alias' file that maps the fonts to the correct XLFD name.

(In the case of Type 1 fonts, such fonts often worked out of the box.
 This is no longer the case, as the backend tries really hard to
 reencode the fonts properly.)
