hbf2gf - convert a CJK bitmap font into subfonts usable by TeX and Omega.

hbf2gf [-q] %configuration-file[.cfg]

hbf2gf [-q] [-p] [-g] [-n] %subfont-name %x-resolution [%y-scale | %y-resolution]

hbf2gf -t [-q] %subfont-name

hbf2gf --version | --help

CJK bitmap fonts can't be directly used with because the number of characters in such fonts exceeds 256, the limit of a font. Thus it is necessary to split these fonts into subfonts, and this is exactly what hbf2gf does.

As the name says, hbf2gf uses CJK fonts in a certain format which is called Hanzi Bitmap Font (HBF) format. It simply consists of the CJK bitmap file(s) and a text file in a format very similar to the BDF format of the X Window System which describes the bitmap font files: the encoding, the size, etc. The produced files can then be converted with gftopk into standard files.

hbf2gf can be called in three modes:

hbf2gf [-q] configuration-file[.cfg]

This call normally creates a set of files, one file, and a batch file which must be executed after hbf2gf has finished. This script will then call gftopk to convert all files into files, and it will call pltotf to convert the file into a file. Finally it will copy the file so that each file has its file (which are all identical).

If ofm_file is set to `yes' in the configuration file, and files will be created too.

-q makes hbf2gf quiet.

hbf2gf [-q] [-p] [-g] [-n] %subfont-name %x-resolution [%y-scale | %y-resolution]

This mode is intended for use with %mktexpk and its derivates. Only one file together with a file for the given subfont will be computed, taking the horizontal resolution and a vertical scaling factor (if the value is smaller than 10) resp. the vertical resolution (otherwise) from the command line, ignoring the nmb_fonts parameter of the configuration file. The last two characters (which are interpreted as the subfont number) are stripped to get the name for the configuration file (which must end with `c No job file will be created. If option -p is set, no file is created. If -g is set, no file is created. The extension can be controlled with -n; if set, the extension is `c otherwise `c resolution>c -q makes hbf2gf quiet.

hbf2gf -t [-q] %subfont-name

This mode is intended for use with scripts like %mktexpk; it tests whether the specified subfont name leads to an hbf2gf configuration file. It returns 0 on success and prints out the name of that configuration file (provided the -q switch isn't set). This test isn't a thorough one; it only removes the last two characters and checks whether a configuration file with that name exists.

See the next section for more details about configuration files.

Specifying the option --version returns the current version of hbf2gf and the used file search library (e.g. c kpathsea). Usage information is shown with the --help parameter.

Here a sample configuration file (c for a 5656 Chinese font in GB encoding; note that all information about the font is in the file. See the FILE SEARCHING section how HBF fonts and hbf2gf configuration files are found. See the AVAILABILITY section where to get CJK fonts together with its files:

  hbf_header     jfs56.hbf
  mag_x          1
  threshold      128
  comment        jianti fansongti 56x56 pixel font

design_size 14.4

y_offset -13

nmb_files -1

output_name gsfs14

checksum 123456789

dpi_x 300

pk_files no tfm_files yes

coding codingscheme GuoBiao encoded TeX text

pk_directory $HBF_TARGET/pk/modeless/gb2312/gsfs14/ tfm_directory $HBF_TARGET/tfm/gb2312/gsfs14/

A configuration file is a plain text file consisting of keywords and its arguments. A keyword must start a line, otherwise the whole line will be ignored. If the word starting a line is not a keyword, the line will be ignored too. Empty lines will also be skipped. The search for keywords is case insensitive; in contrast, the arguments will be taken exactly as given (except `yes' and `no' which can be written with uppercase or lowercase letters). Each keyword has one argument which must be separated by whitespace (blanks or tabs) from the keyword and must be on the same line. Each line must not be longer than 256 characters.

You can use environment variables in the configuration file. The escape character starting an environment variable in the configuration file is always `c even for operating systems like DOS which has other conventions. hbf2gf recognizes only environment variable names which start with a letter or an underscore, followed by alphanumeric characters or underscores. You can surround the variable with braces to indicate where the variable name ends, for example To get a dollar sign you must write `c The expansion of environment variables in hbf2gf itself (without the help of either kpathsea, emtexdir, or MiKTeX searching routines) is very limited; this feature has been carried over from previous versions. It can't expand variables set in texmf.cnf; it also can't handle more than one directory as the variable's value. Don't use it except for the `pk_directory' and `tfm_directory' parameters!

This is the list of all necessary keywords:

hbf_header

The HBF header file name of the input font(s). hbf2gf uses the given searching mechanism (kpathsea, emtexdir, or MiKTeX) to locate this file.

output_name

The name stem of the output files. A running two digit decimal number starting with `c will be appended. For Unicode fonts see the keyword unicode below. This value is in almost all cases identical to the name of the configuration file.

And now all optional keywords:

x_offset

Increases the character width. Will be applied on both sides; default for non-rotated glyphs is the value given in the HBF header (HBF_BITMAP_BOUNDING_BOX) scaled to design_size (in pixels).

y_offset

Shifts all characters up or down; default for non-rotated glyphs is the value given in the HBF header (HBF_BITMAP_BOUNDING_BOX) scaled to design_size (in pixels).

design_size

The design size (in points) of the font. x_offset and y_offset refer to this size. Default is 10.0.

slant

The slant of the font (given as x / y). Only values in the range 0 slant 1 are allowed. Default is 0.0.

rotation

If set to `yes', all glyphs will be rotated 90 degrees counter-clockwise. The default offsets as given in the HBF header will be ignored (and set to 0). Default is `no'.

mag_x

mag_y Scaling values of the characters to reach design size. If only one magnification is given, x and y values are assumed to be equal. Default is mag_x = mag_y = 1.0.

threshold

A value between 1 and 254 defining a threshold for converting the internal graymap into the output bitmap; lower values cut more pixels. Default value is 128.

comment

A comment describing the font; default is none.

nmb_fonts

The number of subfonts to create. Default value is -1 for creating all fonts.

unicode

If `yes', a two digit hexadecimal number will be used as a running number, starting with the value of the first byte of the first code range. Default is `no'.

min_char

The minimum value of the encoding. You should set this value to get correct subfile offsets if it is not identical to the lowest character code in the HBF file.

dpi_x

dpi_y The horizontal and vertical resolution (in dpi) of the printer. If only one resolution is given, x and y values are assumed to be equal. Default is 300.

checksum

A checksum to identify the files with the appropriate files. The default value of this unsigned 32bit integer is 0.

coding

A comment describing the coding scheme; default is none.

pk_directory

The destination directory of the files; default: none. Attention! The batch file will not check whether this directory exists.

tfm_directory

The destination directory of the files; default: none. Attention! The batch file will not check whether this directory exists.

pk_files

Whether to create files or not; default is `yes'.

tfm_files

Whether to create files or not; default is `yes'.

ofm_file

Whether to create an file or not; default is `no'. The batch file will then use ovp2ovf of the Omega distribution to convert it into an and an file. The file simply maps all subfonts back to a single Omega font.

long_extension

If `yes', files will include the resolution in the extension (e.g. This affects the batch file only (default is `yes').

rm_command

The shell command to remove files; default: `rm'.

cp_command

The shell command to copy files; default: `cp'.

job_extension

The extension of the batch file which calls gftopk and pltotf to convert the and the files into and files respectively; default is none.

hbf2gf uses either the kpathsea, emtexdir, or MiKTeX library for searching files (emtexdir will work only on operating systems which have an MS-DOSish background, i.e., MS-DOS, OS/2, Windows; MiKTeX is for Win32 systems).

kpathsea

emtexdir

MikTeX

The x and y output size must not exceed MAX_CHAR_SIZE, which is defined at compile time; its default value is 1023 (pixel).

ttf2pk(1)

this is the source code written in CWEB which can be converted into a pretty-printed document using cweave. The CJK package also contains a preformatted file.

the CJK documentation files (c

the Hanzi Bitmap File (HBF) standard version 1.3; available at

the Omega documentation available at and the CTAN hosts and mirrors.

The hbf2gf configuration scripts

HBF header files which describe fixed-width bitmap fonts. Note that the bitmap font name(s) themselves as specified in the header files are irrelevant for hbf2gf.

hbf2gf is part of the CJK macro package for available at the CTAN hosts and its mirrors.

CJK fonts together with HBF header files can be found at and its mirrors.

Werner Lemberg

Ross Paterson (the HBF API)