1HBF2GF(1) General Commands Manual HBF2GF(1)
2
6 hbf2gf - convert a CJK bitmap font into subfonts usable by TeX and
7 Omega.
8
10 hbf2gf [-q] configuration-file[.cfg]
11 hbf2gf [-q] [-p] [-g] [-n] subfont-name x-resolution
12 [y-scale | y-resolution]
13 hbf2gf -t [-q] subfont-name
14 hbf2gf --version | --help
15
17 CJK bitmap fonts can't be directly used with TeX because the number of
18 characters in such fonts exceeds 256, the limit of a TeX font. Thus it
19 is necessary to split these fonts into subfonts, and this is exactly
20 what hbf2gf does.
21 As the name says, hbf2gf uses CJK fonts in a certain format which is
23 called Hanzi Bitmap Font (HBF) format. It simply consists of the CJK
24 bitmap file(s) and a text file in a format very similar to the BDF for‐
25 mat of the X Window System which describes the bitmap font files: the
26 encoding, the size, etc. The produced GF files can then be converted
27 with gftopk into standard PK files.
28 hbf2gf can be called in three modes:
30 hbf2gf [-q] configuration-file[.cfg]
32 This call normally creates a set of GF files, one PL file, and a
34 batch file which must be executed after hbf2gf has finished. This
35 script will then call gftopk to convert all GF files into PK
36 files, and it will call pltotf to convert the PL file into a TFM
37 file. Finally it will copy the TFM file so that each PK file has
38 its TFM file (which are all identical).
39 If ofm_file is set to ‘yes’ in the configuration file, OFM and OVF
41 files will be created too.
42 -q makes hbf2gf quiet.
44 hbf2gf [-q] [-p] [-g] [-n] subfont-name x-resolution
46 [y-scale | y-resolution]
47 This mode is intended for use with mktexpk and its derivates. On‐
49 ly one GF file together with a PL file for the given subfont will
50 be computed, taking the horizontal resolution and a vertical scal‐
51 ing factor (if the value is smaller than 10) resp. the vertical
52 resolution (otherwise) from the command line, ignoring the
53 nmb_fonts parameter of the configuration file. The last two char‐
54 acters (which are interpreted as the subfont number) are stripped
55 to get the name for the configuration file (which must end with
56 ‘.cfg’). No job file will be created. If option -p is set, no PL
57 file is created. If -g is set, no GF file is created. The exten‐
58 sion can be controlled with -n; if set, the extension is ‘.gf’,
59 otherwise ‘.<resolution>gf’. -q makes hbf2gf quiet.
60 hbf2gf -t [-q] subfont-name
62 This mode is intended for use with scripts like mktexpk; it tests
64 whether the specified subfont name leads to an hbf2gf configura‐
65 tion file. It returns 0 on success and prints out the name of
66 that configuration file (provided the -q switch isn't set). This
67 test isn't a thorough one; it only removes the last two characters
68 and checks whether a configuration file with that name exists.
69 See the next section for more details about configuration files.
71 Specifying the option --version returns the current version of hbf2gf
73 and the used file search library (e.g. kpathsea). Usage information is
74 shown with the --help parameter.
75
77 Here a sample configuration file (gsfs14.cfg) for a 56×56 Chinese font
78 in GB encoding; note that all information about the font is in the
79 jfs56.hbf file. See the FILE SEARCHING section how HBF fonts and
80 hbf2gf configuration files are found. See the AVAILABILITY section
81 where to get CJK fonts together with its HBF files:
82 hbf_header jfs56.hbf
84 mag_x 1
85 threshold 128
86 comment jianti fansongti 56x56 pixel font
87 design_size 14.4
89 y_offset -13
91 nmb_files -1
93 output_name gsfs14
95 checksum 123456789
97 dpi_x 300
99 pk_files no
101 tfm_files yes
102 coding codingscheme GuoBiao encoded TeX text
104 pk_directory $HBF_TARGET/pk/modeless/gb2312/gsfs14/
106 tfm_directory $HBF_TARGET/tfm/gb2312/gsfs14/
107 A configuration file is a plain text file consisting of keywords and
109 its arguments. A keyword must start a line, otherwise the whole line
110 will be ignored. If the word starting a line is not a keyword, the
111 line will be ignored too. Empty lines will also be skipped. The
112 search for keywords is case insensitive; in contrast, the arguments
113 will be taken exactly as given (except ‘yes’ and ‘no’ which can be
114 written with uppercase or lowercase letters). Each keyword has one ar‐
115 gument which must be separated by whitespace (blanks or tabs) from the
116 keyword and must be on the same line. Each line must not be longer
117 than 256 characters.
118 You can use environment variables in the configuration file. The es‐
120 cape character starting an environment variable in the configuration
121 file is always ‘$’, even for operating systems like DOS which has other
122 conventions. hbf2gf recognizes only environment variable names which
123 start with a letter or an underscore, followed by alphanumeric charac‐
124 ters or underscores. You can surround the variable with braces to in‐
125 dicate where the variable name ends, for example ${FOO}. To get a dol‐
126 lar sign you must write ‘$$’. The expansion of environment variables
127 in hbf2gf itself (without the help of either kpathsea, emtexdir, or
128 MiKTeX searching routines) is very limited; this feature has been car‐
129 ried over from previous versions. It can't expand variables set in
130 texmf.cnf; it also can't handle more than one directory as the vari‐
131 able's value. Don't use it except for the ‘pk_directory’ and ‘tfm_di‐
132 rectory’ parameters!
133 This is the list of all necessary keywords:
135 hbf_header
137 The HBF header file name of the input font(s). hbf2gf uses the
138 given searching mechanism (kpathsea, emtexdir, or MiKTeX) to lo‐
139 cate this file.
140 output_name
142 The name stem of the output files. A running two digit decimal
143 number starting with ‘01’ will be appended. For Unicode fonts
144 see the keyword unicode below. This value is in almost all cas‐
145 es identical to the name of the configuration file.
146 And now all optional keywords:
148 x_offset
150 Increases the character width. Will be applied on both sides;
151 default for non-rotated glyphs is the value given in the HBF
152 header (HBF_BITMAP_BOUNDING_BOX) scaled to design_size (in pix‐
153 els).
154 y_offset
156 Shifts all characters up or down; default for non-rotated glyphs
157 is the value given in the HBF header (HBF_BITMAP_BOUNDING_BOX)
158 scaled to design_size (in pixels).
159 design_size
161 The design size (in points) of the font. x_offset and y_offset
162 refer to this size. Default is 10.0.
163 slant The slant of the font (given as Delta_x / Delta_y). Only values
165 in the range 0 ≤ slant ≤ 1 are allowed. Default is 0.0.
166 rotation
168 If set to ‘yes’, all glyphs will be rotated 90 degrees counter-
169 clockwise. The default offsets as given in the HBF header will
170 be ignored (and set to 0). Default is ‘no’.
171 mag_x
173 mag_y Scaling values of the characters to reach design size. If only
174 one magnification is given, x and y values are assumed to be
175 equal. Default is mag_x = mag_y = 1.0.
176 threshold
178 A value between 1 and 254 defining a threshold for converting
179 the internal graymap into the output bitmap; lower values cut
180 more pixels. Default value is 128.
181 comment
183 A comment describing the font; default is none.
184 nmb_fonts
186 The number of subfonts to create. Default value is -1 for cre‐
187 ating all fonts.
188 unicode
190 If ‘yes’, a two digit hexadecimal number will be used as a run‐
191 ning number, starting with the value of the first byte of the
192 first code range. Default is ‘no’.
193 min_char
195 The minimum value of the encoding. You should set this value to
196 get correct subfile offsets if it is not identical to the lowest
197 character code in the HBF file.
198 dpi_x
200 dpi_y The horizontal and vertical resolution (in dpi) of the printer.
201 If only one resolution is given, x and y values are assumed to
202 be equal. Default is 300.
203 checksum
205 A checksum to identify the GF files with the appropriate TFM
206 files. The default value of this unsigned 32bit integer is 0.
207 coding A comment describing the coding scheme; default is none.
209 pk_directory
211 The destination directory of the PK files; default: none. At‐
212 tention! The batch file will not check whether this directory
213 exists.
214 tfm_directory
216 The destination directory of the TFM files; default: none. At‐
217 tention! The batch file will not check whether this directory
218 exists.
219 pk_files
221 Whether to create PK files or not; default is ‘yes’.
222 tfm_files
224 Whether to create TFM files or not; default is ‘yes’.
225 ofm_file
227 Whether to create an OPL file or not; default is ‘no’. The
228 batch file will then use ovp2ovf of the Omega distribution to
229 convert it into an OFM and an OVF file. The OPL file simply
230 maps all subfonts back to a single Omega font.
231 long_extension
233 If ‘yes’, PK files will include the resolution in the extension
234 (e.g. gsso1201.300pk). This affects the batch file only (de‐
235 fault is ‘yes’).
236 rm_command
238 The shell command to remove files; default: ‘rm’.
239 cp_command
241 The shell command to copy files; default: ‘cp’.
242 job_extension
244 The extension of the batch file which calls gftopk and pltotf to
245 convert the GF and the PL files into PK and TFM files respec‐
246 tively; default is none.
247
249 hbf2gf uses either the kpathsea, emtexdir, or MiKTeX library for
250 searching files (emtexdir will work only on operating systems which
251 have an MS-DOSish background, i.e., MS-DOS, OS/2, Windows; MiKTeX is
252 for Win32 systems).
253 kpathsea
255 Please note that older versions of kpathsea (<3.2) have no special
256 means to seach for program related files. Additionally, versions older
257 than 3.3 have no default path for miscellaneous fonts, thus we use the
258 paths for PostScript related stuff if necessary for fonts resp. config‐
259 uration files. The actual version of kpathsea is displayed on screen
260 if you call hbf2gf --version.
261 Here is a table of the file type and the corresponding kpathsea vari‐
263 ables.
264 Version 3.3 and newer (this won't change again in the future!):
266 .hbf MISCFONTS
268 .cfg HBF2GFINPUTS
269 Version 3.2:
271 .hbf T1FONTS
273 .cfg HBF2GFINPUTS
274 And here the same for pre-3.2-versions of kpathsea:
276 .hbf T1FONTS
278 .cfg TEXCONFIG
279 Finally, the same for versions ≤2.6:
281 .hbf DVIPSHEADERS
283 .cfg TEXCONFIG
284 Please consult the info files of kpathsea for details on these vari‐
286 ables. The decision which naming scheme to use for variables will be
287 done during compilation.
288 You should set the TEXMFCNF variable to the directory where your
290 texmf.cnf configuration file resides.
291 Here is the proper command to find out to which value a kpathsea vari‐
293 able is set (we use MISCFONTS as an example). This is especially use‐
294 ful if a variable isn't set in texmf.cnf or in the environment, thus
295 pointing to the default value which is hard-coded into the kpathsea li‐
296 brary.
297 kpsewhich -progname=hbf2gf -expand-var='$MISCFONTS'
299 We select the program name also since it is possible to specify vari‐
301 ables which are searched only for a certain program -- in our example
302 it would be MISCFONTS.hbf2gf.
303 A similar but not identical method is to say
305 kpsewhich -progname=hbf2gf -show-path='misc fonts'
307 [A full list of format types can be obtained by saying ‘kpsewhich
309 --help’ on the command line prompt.] This is exactly the how hbf2gf
310 searches for files; the disadvantage is that all variables are expanded
311 which can cause very long strings.
312 emtexdir
314 Here the list of suffixes and its related environment variables to be
315 set in autoexec.bat (resp. in config.sys for OS/2):
316 .hbf HBFONTS
318 .cfg HBFCFG
319 If one of the variables isn't set, a warning message is emitted. The
321 current directory will always be searched. As usual, one exclamation
322 mark appended to a directory path causes subdirectories one level deep
323 to be searched, two exclamation marks causes all subdirectories to be
324 searched. Example:
325 HBFONTS=c:\fonts\hbf!!;d:\myfonts\hbf!
327 Constructions like ‘c:\fonts!!\hbf’ aren't possible.
329 MikTeX
331 Please consult the documentation files of MiKTeX for more details.
332
334 The x and y output size must not exceed MAX_CHAR_SIZE, which is defined
335 at compile time; its default value is 1023 (pixel).
336
338 ttf2pk(1)
339 hbf2gf.w: this is the source code written in CWEB which can be convert‐
341 ed into a pretty-printed TeX document using cweave. The CJK
342 package also contains a preformatted hbf2gf.dvi file.
343 the CJK documentation files (hbf2gf.txt).
345 the Hanzi Bitmap File (HBF) standard version 1.3; available at ftp.ifc‐
347 ss.org
348 the Omega documentation available at ftp.ens.fr and the CTAN hosts and
350 mirrors.
351
353 *.cfg The hbf2gf configuration scripts
354 *.hbf HBF header files which describe fixed-width bitmap fonts. Note
356 that the bitmap font name(s) themselves as specified in the
357 header files are irrelevant for hbf2gf.
358
360 hbf2gf is part of the CJK macro package for LaTeX 2e available at the
361 CTAN hosts and its mirrors.
362 CJK fonts together with HBF header files can be found at ftp.ifcss.org
364 and its mirrors.
365
367 Werner Lemberg <wl@gnu.org>
368 Ross Paterson (the HBF API) <ross@soi.city.ac.uk>
369CJK Version 4.7.0 17-Oct-2006 HBF2GF(1)