BDFCTOOL(1) BSD Reference Manual BDFCTOOL(1)
NAME
bdfctool - convert BDF and bdfc font files
SYNOPSIS
bdfctool -c
bdfctool -d [-FGg] [-p unimap]
bdfctool -e [-a]
bdfctool +e
DESCRIPTION
The bdfctool utility converts (mostly) fixed-width bitmap fonts between
the BDF file format as used by XFree86(R) and the bdfc format as speci-
fied below. It operates as a filter, i.e. takes its input from the stan-
dard input stream and writes data to standard output.
The options are as follows:
-a In edit mode, emit ASCII (1:2) encoding for an unset bit ('.'), a
set bit ('#') and the line end separator ('|').
+a In edit mode, emit Unicode (1:1) encoding (default).
-d Decompress the font from bdfc (or BDF) into BDF.
-c Compress the font from BDF or the bdfc edit form to bdfc, also sort-
ing and weeding out any duplicates (later occurrence wins).
-e Expand selected glyphs inside the bdfc file into the edit form,
which uses U+3000 and U+4DC0 to represent unset and set bits,
respectively, so they can be visually edited. This mode operates on
glyphs and does not need to be passed the whole file, e.g. using ^K/
in the jupp text editor.
+e Revert selected glyphs from edit form back to compressed form
(without whole-file validation).
-F Do a fast decompression with no error checking. Run this on files
passed through bdfctool -c, without any subsequent manual or au-
tomated changes, only. Used by the MirBSD XFree86(R) build process.
-G Output a big-endian .gdf (libgd font) instead.
-g Output a little-endian .gdf (libgd font) instead.
-P unimap
Output a PSF version 2 file (see -p below) instead.
-p unimap
Output a PSF version 1 file (Linux text console, SYSLINUX) instead.
If unimap is not exactly a dot ('.'), a .psfu file will be created,
otherwise, a .psf file.
BDFC FORMAT DESCRIPTION
A .bdfc file is a compressed, editable representation of a subset of the
Bitmap Distribution Format (BDF) as used for fixed-width fonts in the
XFree86(R) windowing system.
Every file starts with a line consisting of "=bdfc 1", where '1' is the
version number. The format is line-oriented and only somewhat stateful.
It is optimised for being operated on using the jupp text editor and mksh
shell scripts. Lines starting with an apostrophe U+0027 and a space
U+0020, or consisting of only an apostrophe before the newline, can be
used anywhere inside the file, except within the trailing-data lines of
an edit block (see below), to denote a comment, which is retained (tacked
on to the following character).
Next comes a block of font header information that are just passed
through, prefixed with a "h". After that, list the font properties, pre-
fixed with a "p" each, and followed by a "C" on a line by itself, which
will deal with emitting the STARTPROPERTIES number, the properties and
ENDPROPERTIES and marks the place where CHARS is put in BDF.
Finally, there is the character block, which is somewhat stateless. There
are two types of entries for that block, glyph defaults and glyph data.
The block is ended with a period (".") on a line by itself.
Glyphs are sorted by their font encoding / Unicode code point, and each
glyph occurs only once, although the bdfctool tool in the -c operation
mode is able to take glyphs in any order and weed out duplicates. The
character name can be omitted if it matches the form "uni20AC" where
"20AC" is the four-nibble uppercase Unicode codepoint of the glyph, in
this example the Euro sign.
Glyph defaults are lines in the format
d 540 0 9 0 0 -4
where the first "d" is the line type, and the next values are, in order,
the arguments to the SWIDTH and DWIDTH and the third and fourth argument
to the BBX BDF commands. (The first and second arguments of BBX are
derived from the glyph data line instead.)
The glyph defaults are used in encoding every subsequent glyph for BDF
and are valid until the next glyph default line, which means that a char-
acter block must start with one, and that sorting may need to duplicate
or move such lines, as handled by bdfctool -c.
Finally, let's talk about the glyph data lines. The standard (condensed)
form looks like
c 0020 6 00:00:00:00:00:00:00:00 space
which are, in this order, the type of the line, the encoding of the
glyph, the width (in bit) of the glyph (first argument of BBX), the glyph
data (in whole bytes, uppercase nibbles, as in BDF, but colon-separated;
the number of which yields the second argument to BBX) and the glyph name
(which, as explained above, is optional) consisting of up to 14 al-
phanumeric characters.
The editing form is a multi-line form and must not be used in persistent
storage, revision control or transmission. Its first line looks like
e 0020 6 8 space
which is basically the same as the standard form, except that the number
of lines replaces the bitmap data. This is followed by (in this case
eight) lines that comprise of (in this case six) occurrences of either
U+3000 (to denote an unset pixel) or U+4DC0 (to denote a set pixel), fol-
lowed by U+258C (to denote, as a visual help, the next character). The
compression script also accepts a dot U+002E or a space U+0020 as null-
bit, a hash U+0023 or an asterisk U+002A as set bit, and a pipe sign /
bar U+007C as line end marker. You should use the regular form if your
display font has an 1:2 ratio (e.g. 8x16, 9x18) and the alternative form
if it has an 1:1 ratio (e.g. 8x8 pixels), and switch fonts if it has a
different ratio altogether.
The trailing dot does not denote the end of file for the -c operation, as
it can handle concatenated files, but is used to have an easy way to
switch between the file and glyph sections, since the former does not use
a structured line format.
RETURN VALUES
The bdfctool utility exits with one of the following values:
0 No error occurred.
1 Wrong usage.
2 An error during processing occurred, e.g. invalid input.
3 A strict mode (-d) error occurred, e.g. invalid input.
4 An error in an external program, such as mktemp(1), occurred.
5 The input lines are not comprised solely of printable ASCII.
EXAMPLES
The following example should be a minimal valid font demonstrating all
features of the bdfc format:
=bdfc 1
' $ucs-fonts: 4x6.bdf,v 1.5 2002-08-26 18:05:49+01 mgk25 Rel $
hFONT -Misc-Fixed-Medium-R-Normal--6-60-75-75-C-40-ISO10646-1
hSIZE 6 75 75
hFONTBOUNDINGBOX 4 6 0 -1
pFONT_ASCENT 5
pFONT_DESCENT 1
pDEFAULT_CHAR 0
C
d 640 0 4 0 0 -1
e 0000 4 6 char0
#.#.|
....|
#.#.|
....|
#.#.|
....|
c 0020 4 00:00:00:00:00:00 space
c 018F 4 00:C0:60:A0:40:00
.
SEE ALSO
bdftopcf(1), fstobdf(1)
The XFree86(R) Bitmap Distribution Format, version 2.1, specification
http://php.net/manual/en/function.imageloadfont.php
AUTHORS
mirabilos <m@mirbsd.org> wrote this tool because cvs(1) does not scale
for multi-thousand-line files, to have a one-line-per-glyph format that
matches BDF. Export to other formats was added later to have a Copyfree
font toolkit.
CAVEATS
bdfctool has its own ideas of how a BDF font file should look like, and
if you deviate from that, you might get an error; although, support for
more features can surely be added. More input validation would be nice.
"ENCODING -1" support is missing. The glyph encoding is currently treated
as the primary key; values from 0000 to FFFF inclusive are valid, the
zero-padding is mandatory.
The current practical limit on glyph width is 32. 0-bit wide glyphs cause
an error; those with height 0 are silently converted to an unset 1x1 bit-
map. PSF version 1 fonts require the width to be 8.
Passing a BDF file through bdfctool -d is not equivalent to compressing
then decompressing it. The position of the STARTPROPERTIES line can
change, if bordering comments, for example.
There is no support for padding BDF fonts yet. Output to gdf and psf
fonts requires padded input.
PSF version 1 fonts require exactly 256 or 512 glyphs.
SYSLINUX uses only the first 256 glyphs and ignores the Unicode map.
MirBSD September 4, 2020 2