1HBF2GF(1)                   General Commands Manual                  HBF2GF(1)
2
3
4

NAME

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

SYNOPSIS

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

DESCRIPTION

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
22       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
29       hbf2gf can be called in three modes:
30
31         hbf2gf [-q] configuration-file[.cfg]
32
33            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
40            If ofm_file is set to ‘yes’ in the configuration file, OFM and OVF
41            files will be created too.
42
43            -q makes hbf2gf quiet.
44
45         hbf2gf [-q] [-p] [-g] [-n] subfont-name x-resolution
46                [y-scale | y-resolution]
47
48            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
61         hbf2gf -t [-q] subfont-name
62
63            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
70       See the next section for more details about configuration files.
71
72       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

CONFIGURATION FILE

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
83         hbf_header     jfs56.hbf
84         mag_x          1
85         threshold      128
86         comment        jianti fansongti 56x56 pixel font
87
88         design_size    14.4
89
90         y_offset       -13
91
92         nmb_files      -1
93
94         output_name    gsfs14
95
96         checksum       123456789
97
98         dpi_x          300
99
100         pk_files       no
101         tfm_files      yes
102
103         coding         codingscheme GuoBiao encoded TeX text
104
105         pk_directory   $HBF_TARGET/pk/modeless/gb2312/gsfs14/
106         tfm_directory  $HBF_TARGET/tfm/gb2312/gsfs14/
107
108       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
119       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
134       This is the list of all necessary keywords:
135
136       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
141       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
147       And now all optional keywords:
148
149       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
155       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
160       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
164       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
167       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
172       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
177       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
182       comment
183              A comment describing the font; default is none.
184
185       nmb_fonts
186              The number of subfonts to create.  Default value is -1 for  cre‐
187              ating all fonts.
188
189       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
194       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
199       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
204       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
208       coding A comment describing the coding scheme; default is none.
209
210       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
215       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
220       pk_files
221              Whether to create PK files or not; default is ‘yes’.
222
223       tfm_files
224              Whether to create TFM files or not; default is ‘yes’.
225
226       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
232       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
237       rm_command
238              The shell command to remove files; default: ‘rm’.
239
240       cp_command
241              The shell command to copy files; default: ‘cp’.
242
243       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

FILE SEARCHING

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
254   kpathsea
255       The actual version of kpathsea is  displayed  on  screen  if  you  call
256       hbf2gf --version.
257
258       Here  is  a table of the file type and the corresponding kpathsea vari‐
259       ables.
260
261           .hbf                MISCFONTS
262           .cfg                HBF2GFINPUTS
263
264       Please consult the info files of kpathsea for details  on  these  vari‐
265       ables.   The  decision which naming scheme to use for variables will be
266       done during compilation.
267
268       You should set the  TEXMFCNF  variable  to  the  directory  where  your
269       texmf.cnf configuration file resides.
270
271       Here  is the proper command to find out to which value a kpathsea vari‐
272       able is set (we use MISCFONTS as an example).  This is especially  use‐
273       ful  if  a  variable isn't set in texmf.cnf or in the environment, thus
274       pointing to the default value which is hard-coded into the kpathsea li‐
275       brary.
276
277         kpsewhich -progname=hbf2gf -expand-var='$MISCFONTS'
278
279       We  select  the program name also since it is possible to specify vari‐
280       ables which are searched only for a certain program – in our example it
281       would be MISCFONTS.hbf2gf.
282
283       A similar but not identical method is to say
284
285         kpsewhich -progname=hbf2gf -show-path='misc fonts'
286
287       [A  full  list  of  format  types  can be obtained by saying ‘kpsewhich
288       --help’ on the command  line  prompt.]   This  is  exactly  how  hbf2gf
289       searches for files; the disadvantage is that all variables are expanded
290       which can cause very long strings.
291
292   emtexdir
293       Here the list of suffixes and its related environment variables  to  be
294       set in autoexec.bat (resp. in config.sys for OS/2):
295
296           .hbf                HBFONTS
297           .cfg                HBFCFG
298
299       If  one  of the variables isn't set, a warning message is emitted.  The
300       current directory will always be searched.  As usual,  one  exclamation
301       mark  appended to a directory path causes subdirectories one level deep
302       to be searched, two exclamation marks causes all subdirectories  to  be
303       searched.  Example:
304
305         HBFONTS=c:\fonts\hbf!!;d:\myfonts\hbf!
306
307       Constructions like ‘c:\fonts!!\hbf’ aren't possible.
308
309   MikTeX
310       Please consult the documentation files of MiKTeX for more details.
311

LIMITATIONS

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

SEE ALSO

317       ttf2pk(1)
318
319       hbf2gf.w: this is the source code written in CWEB which can be convert‐
320                 ed  into a pretty-printed TeX document using cweave.  The CJK
321                 package also contains a preformatted hbf2gf.pdf file.
322
323       the CJK documentation files (hbf2gf.txt).
324
325       the  Hanzi  Bitmap  File  (HBF)  standard  version 1.3;  available   at
326       ftp.ifcss.org.
327
328       the  Omega documentation available at ftp.ens.fr and the CTAN hosts and
329       mirrors.
330

FILES

332       *.cfg  The hbf2gf configuration scripts.
333
334       *.hbf  HBF header files which describe fixed-width bitmap fonts.   Note
335              that  the  bitmap  font  name(s)  themselves as specified in the
336              header files are irrelevant for hbf2gf.
337

AVAILABILITY

339       hbf2gf is part of the CJK macro package for LaTeX 2e available  at  the
340       CTAN hosts and its mirrors.
341
342       CJK  fonts together with HBF header files can be found at ftp.ifcss.org
343       and its mirrors.
344

AUTHORS

346       Werner Lemberg <wl@gnu.org>
347       Ross Paterson (the HBF API) <ross@soi.city.ac.uk>
348
349
350
351CJK Version 4.8.5                 16-Oct-2021                        HBF2GF(1)
Impressum