Build and Check an X Font Index with mkfontscale

mkfontscale scans scalable fonts and writes the index that mkfontdir needs next, and skipping it is why a TrueType font can go missing. You will build that index, inspect the entries, and decide when the result is safe to hand on. Allow about ten minutes if the font directory already exists.

The examples use the mkfontscale 1.1.3 command from the Debian xfonts-utils package, version 1:7.7+6build3 on this machine. The command normally changes a directory by writing fonts.scale. It does not install fonts, configure an X server, or make a font directory available to clients by itself. You will normally need ordinary write permission for the target directory; use elevated privileges only when the font directory is deliberately owned by root and your system policy permits that change.

1. Check the command and choose a target

Start by confirming the executable and the directory you intend to index. The target can contain TrueType, OpenType or other scalable font files understood by the installed build. Keep the path explicit, especially when a script runs from an unrelated working directory.

$ command -v mkfontscale
/usr/bin/mkfontscale
$ mkfontscale -v
mkfontscale 1.1.3
$ test -d /path/to/font-directory && echo 'directory exists'
directory exists

If the last check fails, stop and correct the path. Do not create an index in the wrong directory just because the command accepts a directory name; a relative directory is read from the current working directory.

2. Generate the default scalable-font index

Pass the font directory as the final argument. With no special options, mkfontscale reads scalable font files and writes fonts.scale in that directory:

$ mkfontscale /path/to/font-directory
$ sed -n '1,12p' /path/to/font-directory/fonts.scale
29
DejaVuSans.ttf -misc-dejavu sans-medium-r-normal--0-0-0-0-p-0-adobe-standard
DejaVuSans.ttf -misc-dejavu sans-medium-r-normal--0-0-0-0-p-0-ascii-0

The first line is the number of indexed entries. The remaining lines pair a file name with an X Logical Font Description, commonly shortened to XLFD. The exact names and count depend on the fonts, encodings and aliases installed on your system, so check the file rather than treating the sample output as a prediction.

$ test -s /path/to/font-directory/fonts.scale && echo 'non-empty index'
non-empty index
$ grep -F 'DejaVuSans.ttf' /path/to/font-directory/fonts.scale | head

3. Protect a hand-edited index

$ cp --preserve=all /path/to/font-directory/fonts.scale /path/to/font-directory/fonts.scale.bak
$ mkfontscale /path/to/font-directory
$ diff -u /path/to/font-directory/fonts.scale.bak /path/to/font-directory/fonts.scale | sed -n '1,80p'

If the new index is wrong, restore the backup with cp --preserve=all and inspect the font set or encoding choices before trying again. If no backup exists, there is no built-in undo for overwritten manual changes.

4. Preview output without writing the directory

Use -o - when you want the generated content on standard output, useful for review or for a controlled temporary file. A relative output name is created inside each directory being processed; the special name - is the exception and means standard output:

$ mkfontscale -o - /path/to/font-directory | sed -n '1,12p'
29
DejaVuSans.ttf -misc-dejavu sans-medium-r-normal--0-0-0-0-p-0-adobe-standard
DejaVuSans.ttf -misc-dejavu sans-medium-r-normal--0-0-0-0-p-0-ascii-0

This preview does not update fonts.scale. If you redirect it, pick a new destination first: shell redirection with > truncates an existing file before mkfontscale has finished, so a failed run can destroy the old output.

$ mkfontscale -o - /path/to/font-directory > /path/to/font-directory/fonts.scale.new
$ test -s /path/to/font-directory/fonts.scale.new
$ mv /path/to/font-directory/fonts.scale.new /path/to/font-directory/fonts.scale

Only run that final mv after inspecting the new file. If the command fails, remove the incomplete fonts.scale.new; the original index is still there.

5. Include or exclude specific input types

• Bitmap fonts are ignored by default. Add -b to read them.
• Scalable fonts can be skipped. Add -s to ignore them.
• Combine carefully. These can be mixed to regenerate a bitmap-oriented directory, but check the output type: with -b, the default output name changes from fonts.scale to fonts.dir. The manual describes -b -s -l as equivalent to mkfontdir.
• Exclude by suffix. Use -x suffix to leave out files ending in it, for example -x .bak to skip backups. It does not delete those files.

$ mkfontscale -b -s -l /path/to/legacy-font-directory
$ test -s /path/to/legacy-font-directory/fonts.dir && echo 'bitmap index written'
bitmap index written

6. Handle encodings only when the directory needs them

For a font tree that uses legacy encoding files, -e directory scans a directory for encodings and writes an encodings.dir file in every processed font directory. -p prefix adds a literal prefix to paths in that file; include a slash in the prefix if you need one. -r keeps non-absolute encoding directories relative, and applies only to later -e options, so option order matters:

$ mkfontscale -n -e /path/to/encodings -p /usr/share/fonts/encodings/ /path/to/font-directory
$ sed -n '1,12p' /path/to/font-directory/encodings.dir

-n is for generating encoding directories only: it does not scan for fonts and does not write font directory files. Do not add it to a normal font-index command by habit. The default enables indexing of ISO 10646:1 font encodings; -u disables that indexing and -U enables it explicitly.

7. Pass the result to the next tool deliberately

Check the generated file, and hand-edit it where necessary, before it becomes input to mkfontdir. That review is where you catch an unwanted font, an unexpected XLFD, or a missing encoding. Keep the generated file in the same directory as the font files it names.

Do not confuse a successful exit status with a complete X font configuration: it only says this indexing operation completed. If an X client still cannot see a font, check the directory permissions, the resulting index, the later mkfontdir or font-server step, and the client's font path separately.