HBF2GF(1)

🌸 NAME 🌸

hbf2gf — the little icon that converts a CJK bitmap font into subfonts that TeX and Omega can actually use 💖 (yes bestie, this is the HBF2GF(1) page from the General Commands Manual, and we're doing this together 🫶)

---

✨ SYNOPSIS ✨

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

---

💅 DESCRIPTION 💅

okay so here's the tea: CJK bitmap fonts literally cannot be used with TeX directly, because these fonts have way more than 256 characters in them, and 256 is the absolute limit of a TeX font. so sad. 😭 the fix? you split those fonts into subfonts, and that is exactly what hbf2gf does. main character energy, no cap.

and like, the name says it all: hbf2gf works with CJK fonts in a specific format called Hanzi Bitmap Font (HBF) format ✨. what even is it? it's just the CJK bitmap file(s) plus a text file, and that text file looks a lot like the BDF format from the X Window System — it describes the bitmap font files: the encoding, the size, etc. the GF files it produces can then be converted with gftopk into standard PK files. slay 💅

so hbf2gf can be called in three modes, bestie, and you gotta know all three:

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

this call normally creates a whole set of GF files, one PL file, and a batch file that you have to run after hbf2gf finishes. that script will then call gftopk to convert all the GF files into PK files, and it will call pltotf to convert the PL file into a TFM file. and finally it copies the TFM file around so that every PK file has its own TFM file (they're all identical, periodt).

if ofm_file is set to ‘yes’ in the configuration file, OFM and OVF files get created too 👑

-q makes hbf2gf quiet 🤫

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

this mode is made for use with mktexpk and its derivates. only one GF file plus a PL file for the given subfont gets computed, and it takes the horizontal resolution plus a vertical scaling factor (if the value is smaller than 10) — or, otherwise, the vertical resolution — straight from the command line, ignoring the nmb_fonts parameter of the configuration file. rude but valid.

the last two characters (which get interpreted as the subfont number) are stripped off to get the name for the configuration file (which must end with ‘.cfg’). no job file gets created.

• if option -p is set, no PL file is created.
• if -g is set, no GF file is created.
• the extension can be controlled with -n; if set, the extension is ‘.gf’, otherwise ‘.<resolution>gf’.
• -q makes hbf2gf quiet 🤫

• hbf2gf -t [-q] subfont-name

this mode is 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 (as long as 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. lowkey lazy, but it's what we have 💀

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. kpathsea). usage information is shown with the --help parameter.

---

🎀 CONFIGURATION FILE 🎀

here's a sample configuration file (gsfs14.cfg) for a 56×56 Chinese font in GB encoding 🐉 note that all the information about the font lives in the jfs56.hbf file. see the FILE SEARCHING section for how HBF fonts and hbf2gf configuration files are found. see the AVAILABILITY section for where to get CJK fonts together with their HBF 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 made of keywords and their arguments 💖

• a keyword must start a line — otherwise the whole line gets ignored 🙈
• if the word starting a line isn't a keyword, the line gets ignored too
• empty lines get skipped as well
• the search for keywords is case insensitive; but the arguments are taken exactly as given (except ‘yes’ and ‘no’, which can be written uppercase or lowercase)
• each keyword has one argument, which must be separated from the keyword by whitespace (blanks or tabs) 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 that starts an environment variable in the configuration file is always ‘$’, even on operating systems like DOS which have other conventions. hbf2gf only recognizes 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 show where the variable name ends, for example ${FOO}. to get an actual dollar sign you must write ‘$$’ 💸

⚠️ 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! 🚨

here's the list of all the 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 ‘01’ gets 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 the optional keywords ✨:

• x_offset — increases the character width. gets 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 Delta_x / Delta_y). only values in the range 0 ≤ slant ≤ 1 are allowed. default is 0.0.
• rotation — if set to ‘yes’, all glyphs get rotated 90 degrees counter-clockwise. the default offsets as given in the HBF header get 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 gets 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 isn't 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 GF files with the appropriate TFM 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 PK files; default: none. ⚠️ attention! the batch file will not check whether this directory exists.
• tfm_directory — the destination directory of the TFM files; default: none. ⚠️ attention! the batch file will not check whether this directory exists.
• pk_files — whether to create PK files or not; default is ‘yes’.
• tfm_files — whether to create TFM files or not; default is ‘yes’.
• ofm_file — whether to create an OPL file or not; default is ‘no’. the batch file will then use ovp2ovf of the Omega distribution to convert it into an OFM and an OVF file. the OPL file simply maps all subfonts back to a single Omega font. 🫶
• long_extension — if ‘yes’, PK files will include the resolution in the extension (e.g. gsso1201.300pk). 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 GF and the PL files into PK and TFM files respectively; default is none.

🔎 FILE SEARCHING 🔎

So here's the thing, bestie — hbf2gf doesn't just vibe around the filesystem by itself. It uses one of three libraries to go find its files: kpathsea, emtexdir, or MiKTeX. And ngl, they're not all for everyone:

• emtexdir only works on operating systems with an MS-DOSish background, aka MS-DOS, OS/2, Windows. It's giving retro 💀
• MiKTeX is for Win32 systems.

---

🌈 kpathsea 🌈

The actual version of kpathsea gets shown right on your screen if you call hbf2gf --version. Cute, right?

Here's the lil table of file type → the kpathsea variable it answers to:

• .hbf → MISCFONTS
• .cfg → HBF2GFINPUTS

Please go consult the info files of kpathsea for the deets on these variables, fr fr. The decision of which naming scheme to use for variables happens during compilation. Not your problem, it's the compiler's 🫶

You should set the TEXMFCNF variable to the directory where your texmf.cnf configuration file resides.

And here's the proper command to find out what value a kpathsea variable is actually set to (we're using MISCFONTS as our example because she's the main character today). This is especially useful if a variable isn't set in texmf.cnf or in the environment — because then you get the default value that's hard-coded into the kpathsea library, and that's the tea you actually wanted 🍓

kpsewhich -progname=hbf2gf -expand-var='$MISCFONTS'

We select the program name too, because it's possible to specify variables which are searched only for a certain program — in our example it would be MISCFONTS.hbf2gf. iykyk ✨

A similar but not identical method is to say:

kpsewhich -progname=hbf2gf -show-path='misc fonts'

• A full list of format types can be obtained by saying kpsewhich --help on the command line prompt.

This is exactly how hbf2gf searches for files. The disadvantage? All variables get expanded, which can cause very long strings. So it's giving novel-length, not bite-size 😭

---

🎀 emtexdir 🎀

Here's the list of suffixes and their related environment variables to be set in autoexec.bat (or in config.sys for OS/2, bestie):

• .hbf → HBFONTS
• .cfg → HBFCFG

If one of the variables isn't set, a warning message is emitted. Heads up 📢

The current directory will always be searched. And as usual, one exclamation mark appended to a directory path causes subdirectories one level deep to be searched; two exclamation marks causes all subdirectories to be searched. Example:

HBFONTS=c:\fonts\hbf!!;d:\myfonts\hbf!

Constructions like c:\fonts!!\hbf aren't possible. Don't try it, she said what she said 💅

---

🦋 MikTeX 🦋

Please consult the documentation files of MiKTeX for more details. That's the whole vibe here, go read their docs 🫶

---

⚠️ LIMITATIONS ⚠️

The x and y output size must not exceed MAX_CHAR_SIZE, which is defined at compile time. Its default value is 1023 (pixel). So if you're out here trying to go bigger than that, no you're not 🙈

---

👀 SEE ALSO 👀

• ttf2pk(1)
• hbf2gf.w — this is the source code written in CWEB, which can be converted into a pretty-printed TeX document using cweave. The CJK package also contains a preformatted hbf2gf.pdf file. So iconic of her to ship both ⭐
• the CJK documentation files (hbf2gf.txt)
• the Hanzi Bitmap File (HBF) standard version 1.3; available at ftp.ifcss.org
• the Omega documentation available at ftp.ens.fr and the CTAN hosts and mirrors

---

📁 FILES 📁

• *.cfg — The hbf2gf configuration scripts.
• *.hbf — 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. Like, don't even worry about them, she's not looking 🫶

---

🌸 AVAILABILITY 🌸

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

CJK fonts together with HBF header files can be found at ftp.ifcss.org and its mirrors. Go get your fonts, bestie 💖

---

👑 AUTHORS 👑

• Werner Lemberg <wl@gnu.org>
• Ross Paterson (the HBF API) <ross@soi.city.ac.uk>

---

And that's the whole page, babes 🎀 This was CJK Version 4.8.5, dated 16-Oct-2021, and it's HBF2GF(1) — go forth and convert those HBF header files, you absolute legend 💅✨