summaryrefslogtreecommitdiff
path: root/language/chinese/CJK/cjk-4.8.4/doc/man/txt/hbf2gf.txt
blob: 3f77fc6eaf5c0a1d7cfdc3d6a9af8ee8955efbcc (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
HBF2GF(1)                   General Commands Manual                  HBF2GF(1)



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

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
       CJK  bitmap fonts can't be directly used with TeX because the number of
       characters in such fonts exceeds 256, the limit of a TeX 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 for-
       mat  of  the X Window System which describes the bitmap font files: the
       encoding, the size, etc.  The produced GF files can then  be  converted
       with gftopk into standard PK files.

       hbf2gf can be called in three modes:

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

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

            If ofm_file is set to `yes' in the configuration file, OFM and OVF
            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.  On-
            ly  one GF file together with a PL file for the given subfont will
            be computed, taking the horizontal resolution and a vertical scal-
            ing  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 char-
            acters (which are interpreted as the subfont number) are  stripped
            to  get  the  name for the configuration file (which must end with
            `.cfg').  No job file will be created.  If option -p is set, no PL
            file is created.  If -g is set, no GF file is created.  The exten-
            sion 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 intended for use with scripts like mktexpk; it tests
            whether the specified subfont name leads to an  hbf2gf  configura-
            tion  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. kpathsea).  Usage information is
       shown with the --help parameter.

CONFIGURATION FILE
       Here a sample configuration file (gsfs14.cfg) for a 56×56 Chinese  font
       in  GB  encoding;  note  that  all information about the font is in the
       jfs56.hbf 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 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 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 ar-
       gument  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 es-
       cape character starting an environment variable  in  the  configuration
       file is always `$', 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 charac-
       ters or underscores.  You can surround the variable with braces to  in-
       dicate where the variable name ends, for example ${FOO}.  To get a dol-
       lar 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  car-
       ried  over  from  previous  versions.  It can't expand variables set in
       texmf.cnf; it also can't handle more than one directory  as  the  vari-
       able's  value.  Don't use it except for the `pk_directory' and `tfm_di-
       rectory' 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 lo-
              cate this file.

       output_name
              The name stem of the output files.  A running two digit  decimal
              number  starting  with `01' will be appended.  For Unicode fonts
              see the keyword unicode below.  This value is in almost all cas-
              es 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 pix-
              els).

       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 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  cre-
              ating all fonts.

       unicode
              If  `yes', a two digit hexadecimal number will be used as a run-
              ning 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 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.   At-
              tention!   The  batch file will not check whether this directory
              exists.

       tfm_directory
              The destination directory of the TFM files; default: none.   At-
              tention!   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  (de-
              fault 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  respec-
              tively; default is none.

FILE SEARCHING
       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
       The actual version of kpathsea is  displayed  on  screen  if  you  call
       hbf2gf --version.

       Here  is  a table of the file type and the corresponding kpathsea vari-
       ables.

           .hbf                MISCFONTS
           .cfg                HBF2GFINPUTS

       Please consult the info files of kpathsea for details  on  these  vari-
       ables.   The  decision which naming scheme to use for variables will be
       done during compilation.

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

       Here  is the proper command to find out to which value a kpathsea vari-
       able is set (we use MISCFONTS as an example).  This is especially  use-
       ful  if  a  variable isn't set in texmf.cnf or in the environment, thus
       pointing to the default value which is hard-coded into the kpathsea li-
       brary.

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

       We  select  the program name also since it is possible to specify vari-
       ables which are searched only for a certain program - in our example it
       would be MISCFONTS.hbf2gf.

       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 is that all variables are expanded
       which can cause very long strings.

   emtexdir
       Here the list of suffixes and its related environment variables  to  be
       set in autoexec.bat (resp. in config.sys for OS/2):

           .hbf                HBFONTS
           .cfg                HBFCFG

       If  one  of the variables isn't set, a warning message is emitted.  The
       current directory will always be searched.  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.

   MikTeX
       Please consult the documentation files of MiKTeX for more details.

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).

SEE ALSO
       ttf2pk(1)

       hbf2gf.w: this is the source code written in CWEB which can be convert-
                 ed  into a pretty-printed TeX document using cweave.  The CJK
                 package also contains a preformatted hbf2gf.pdf file.

       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.

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.

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



CJK Version 4.8.4                 18-Apr-2015                        HBF2GF(1)