summaryrefslogtreecommitdiff
path: root/Master/texmf/doc/man/man1/hbf2gf.1
blob: 0ccb6648f56a5d5090995fbccef00bd47b115ea1 (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
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
.\" man page for hbf2gf
.\"
.\" Copyright (C) 1994-2008  Werner Lemberg <wl@gnu.org>
.\"
.\" This program is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 2 of the License, or
.\" (at your option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with this program in doc/COPYING; if not, write to the Free
.\" Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston,
.\" MA 02110-1301 USA
.\"
.
.TH HBF2GF 1 29-Dec-2008 "CJK Version 4.8.2"
.SH NAME
hbf2gf \- convert a CJK bitmap font into subfonts usable by TeX and Omega.
.
.
.SH SYNOPSIS
.na
.nh
.B hbf2gf
.RB [ \-q ]
.IR \%configuration-file [ .cfg ]
.br
.B hbf2gf
'in +\n(.ku
.RB [ \-q ]
.RB [ \-p ]
.RB [ \-g ]
.RB [ \-n ]
.I \%subfont-name \%x-resolution
.RI [ \%y-scale \ | \ \%y-resolution ]
.br
.in
.B hbf2gf
.B \-t
.RB [ \-q ]
.I \%subfont-name
.br
.B "hbf2gf \-\-version"
|
.B \-\-help
.ad
.hy
.
.
.
.\" ====
.\" ==== macro definitions
.\" ====
.
.\" here we define \TeX for troff and nroff
.if t .ds TX \fRT\h'-0.1667m'\v'0.20v'E\v'-0.20v'\h'-0.125m'X\fP
.if n .ds TX TeX
.
.\" and here the same for \LaTeX
.if t \{\
.ie '\*(.T'dvi' \
.ds LX \fRL\h'-0.36m'\v'-0.15v'\s-3A\s0\h'-0.15m'\v'0.15v'\fP\*(TX
.el .ds LX \fRL\h'-0.36m'\v'-0.22v'\s-2A\s0\h'-0.15m'\v'0.22v'\fP\*(TX
.\}
.if n .ds LX LaTeX
.
.\" \LaTeXe
.\" note that we need \vareps for TeX instead of \eps which can only be
.\" accessed with the \N escape sequence (in the Math Italic font)
.if t \{\
.ie '\*(.T'dvi' .ds LE \*(LX\h'0.15m'2\v'0.20v'\f(MI\N'34'\fP\v'-0.20v'
.el .ds LE \*(LX\h'0.15m'2\v'0.20v'\(*e\v'-0.20v'
.\}
.if n .ds LE LaTeX\ 2e
.
.\" a definition for \Delta
.if t .ds DE \(*D
.if n .ds DE Delta_
.
.\" a typewriter font
.if t \{\
.de C
\fC\\$1\fP\\$2
..
.\}
.if n \{\
.de C
\\$1\\$2
..
.\}
.
.\" an addition to .TP to allow two labels for the same item
.de TQ
.br
.ns
.TP
..
.
.\" ====
.\" ==== end of macro definitions
.\" ====
.
.
.
.SH DESCRIPTION
CJK bitmap fonts can't be directly used with \*(TX
because the number of characters in such fonts exceeds\ 256, the limit of a
\*(TX
font.
Thus it is necessary to split these fonts into subfonts, and this is
exactly what
.B hbf2gf
does.
.PP
As the name says,
.B hbf2gf
uses CJK fonts in a certain format which is called
.B Hanzi Bitmap Font
.RB ( 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
.C GF
files can then be converted with
.B gftopk
into standard
.C PK
files.
.PP
.B hbf2gf
can be called in three modes:
.
.PP
.in +2m
.B hbf2gf
.RB [ \-q ]
.IR configuration-file [ .cfg ]
.PP
.in +5m
This call normally creates a set of
.C GF
files, one
.C PL
file, and a batch file which must be executed after
.B hbf2gf
has finished.
This script will then call
.B gftopk
to convert all
.C GF
files into
.C PK
files, and it will call
.B pltotf
to convert the
.C PL
file into a
.C TFM
file.
Finally it will copy the
.C TFM
file so that each
.C PK
file has its
.C TFM
file (which are all identical).
.PP
.in +5m
If
.B ofm_file
is set to \(oqyes\(cq in the configuration file,
.C OFM
and
.C OVF
files will be created too.
.
.PP
.in +5m
.B \-q
makes
.B hbf2gf
quiet.
.PP
.in +2m
.na
.nh
.B hbf2gf
'in +\n(.ku
.RB [ \-q ]
.RB [ \-p ]
.RB [ \-g ]
.RB [ \-n ]
.I \%subfont-name \%x-resolution
.RI [ \%y-scale \ | \ \%y-resolution ]
.ad
.hy
.PP
.in +5m
This mode is intended for use with
.B \%mktexpk
and its derivates.
Only one
.C GF
file together with a 
.C PL
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
.B 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
\(oq\c
.C \&.cfg \(cq).
No job file will be created.
If option
.B \-p
is set, no
.C PL
file is created.
If
.B \-g
is set, no
.C GF
file is created.
The extension can be controlled with
.BR \-n ;
if set, the extension is \(oq\c
.C \&.gf \(cq,
otherwise \(oq\c
.C \&. <\c
.IR resolution >\c
.C gf \(cq.
.B \-q
makes
.B hbf2gf
quiet.
.
.PP
.in +2m
.na
.nh
.B hbf2gf
'in +\n(.ku
.B \-t
.RB [ \-q ]
.I \%subfont-name
.ad
.hy
.PP
.in +5m
This mode is intended for use with scripts like
.BR \%mktexpk ;
it tests whether the specified subfont name leads to an
.B hbf2gf
configuration file.
It returns 0 on success and prints out the name of that configuration file
(provided the
.B \-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.
.PP
See the next section for more details about configuration files.
.PP
Specifying the option
.B \-\-version
returns the current version of
.B hbf2gf
and the used file search library (e.g.\ \c
.BR kpathsea ).
Usage information is shown with the
.B \-\-help
parameter.
.
.
.SH "CONFIGURATION FILE"
Here a sample configuration file (\c
.C gsfs14.cfg )
for a 56\(mu56 Chinese font in GB encoding; note that all information
about the font is in the
.C jfs56.hbf
file.
See the
.B "FILE SEARCHING"
section how HBF fonts and
.B hbf2gf
configuration files are found.
See the
.B AVAILABILITY
section where to get CJK fonts together with its
.C HBF
files:
.PP
.if t \fC
.nf
  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/
.fi
.if t \fP
.PP
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 \(oqyes\(cq and \(oqno\(cq 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.
.PP
You can use environment variables in the configuration file.
The escape character starting an environment variable in the configuration
file is always \(oq\c
.C $ \(cq,
even for operating systems like DOS which has other conventions.
.B 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
.C ${FOO} .
To get a dollar sign you must write \(oq\c
.C $$ \(cq.
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.
.B Don't use it except for the \(oqpk_directory\(cq and \(oqtfm_directory\(cq
.B parameters!
.PP
This is the list of all necessary keywords:
.TP
.B hbf_header
The HBF header file name of the input font(s).
.B hbf2gf
uses the given searching mechanism (kpathsea, emtexdir, or MiKTeX) to locate
this file.
.TP
.B output_name
The name stem of the output files.
A running two digit decimal number starting with \(oq\c
.C 01 \(cq
will be appended.
For Unicode fonts see the keyword
.B unicode
below.
This value is in almost all cases identical to the name of the configuration
file.
.PP
And now all optional keywords:
.TP
.B 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
.RB ( HBF_BITMAP_BOUNDING_BOX )
scaled to
.B design_size
(in pixels).
.TP
.B y_offset
Shifts all characters up or down; default for non-rotated glyphs is the value
given in the HBF header
.RB ( HBF_BITMAP_BOUNDING_BOX )
scaled to
.B design_size
(in pixels).
.TP
.B design_size
The design size (in points) of the font.
.B x_offset
and 
.B y_offset
refer to this size.
Default is\ 10.0.
.TP
.B slant
The slant of the font (given as \*(DEx\ /\ \*(DEy).
Only values in the range 0\ \(<=\ \fBslant\fP\ \(<=\ 1 are allowed.
Default is\ 0.0.
.TP
.B rotation
If set to \(oqyes\(cq, 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 \(oqno\(cq.
.TP
.B mag_x
.TQ
.B 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 \fBmag_x\fP\ =\ \fBmag_y\fP\ =\ 1.0.
.PP
.TP
.B 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.
.PP
.TP
.B comment
A comment describing the font; default is none.
.PP
.TP
.B nmb_fonts
The number of subfonts to create.
Default value is \-1 for creating all fonts.
.TP
.B unicode
If \(oqyes\(cq, 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 \(oqno\(cq.
.TP
.B 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.
.PP
.TP
.B dpi_x
.TQ
.B 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.
.TP
.B checksum
A checksum to identify the 
.C GF
files with the appropriate 
.C TFM
files.
The default value of this unsigned 32bit integer is\ 0.
.TP
.B coding
A comment describing the coding scheme; default is none.
.PP
.TP
.B pk_directory
The destination directory of the
.C PK
files; default: none.
Attention!
The batch file will not check whether this directory exists.
.TP
.B tfm_directory
The destination directory of the
.C TFM
files; default: none.
Attention!
The batch file will not check whether this directory exists.
.TP
.B pk_files
Whether to create
.C PK
files or not; default is \(oqyes\(cq.
.TP
.B tfm_files
Whether to create
.C TFM
files or not; default is \(oqyes\(cq.
.TP
.B ofm_file
Whether to create an
.C OPL
file or not; default is \(oqno\(cq.
The batch file will then use
.B ovp2ovf
of the Omega distribution to convert it into an
.C OFM
and an
.C OVF
file.
The
.C OPL
file simply maps all subfonts back to a single Omega font.
.TP
.B long_extension
If \(oqyes\(cq,
.C PK
files will include the resolution in the extension (e.g.
.C gsso1201.300pk ).
This affects the batch file only (default is \(oqyes\(cq).
.TP
.B rm_command
The shell command to remove files; default: \(oqrm\(cq.
.TP
.B cp_command
The shell command to copy files; default: \(oqcp\(cq.
.TP
.B job_extension
The extension of the batch file which calls
.B gftopk
and
.B pltotf
to convert the
.C GF
and the
.C PL
files into
.C PK
and
.C TFM
files respectively; default is none.
.
.
.SH "FILE SEARCHING"
.B hbf2gf
uses either the
.BR kpathsea ,
.BR emtexdir ,
or
.B MiKTeX
library for searching files 
.RB ( emtexdir
will work only on operating systems which have an MS-DOSish background,
i.e., MS-DOS, OS/2, Windows;
.B MiKTeX
is for Win32 systems).
.
.SS kpathsea
Please note that older versions of
.B kpathsea
(<3.2) have no special means to seach for program related files.
Additionally, versions older than 3.3 have no default path for miscellaneous
fonts, thus we use the paths for PostScript related stuff if necessary for
fonts resp. configuration files.
The actual version of kpathsea is displayed on screen if you call
.B hbf2gf
.BR \-\-version .
.PP
Here is a table of the file type and the corresponding
.B kpathsea
variables.
.PP
Version\ 3.3 and newer (this won't change again in the future!):
.PP
.in +4m
.ta 2i
.br
.C "\&.hbf	MISCFONTS"
.br
.C "\&.cfg	HBF2GFINPUTS"
.PP
Version\ 3.2:
.PP
.in +4m
.ta 2i
.br
.C "\&.hbf	T1FONTS"
.br
.C "\&.cfg	HBF2GFINPUTS"
.PP
And here the same for pre-3.2-versions of
.B kpathsea:
.PP
.in +4m
.ta 2i
.br
.C "\&.hbf	T1FONTS"
.br
.C "\&.cfg	TEXCONFIG"
.PP
Finally, the same for versions\ \(<=2.6:
.PP
.in +4m
.ta 2i
.br
.C "\&.hbf	DVIPSHEADERS"
.br
.C "\&.cfg	TEXCONFIG"
.PP
Please consult the info files of
.B kpathsea
for details on these variables.
The decision which naming scheme to use for variables will be done during
compilation.
.PP
You should set the
.C TEXMFCNF
variable to the directory where your
.C texmf.cnf
configuration file resides.
.PP
Here is the proper command to find out to which value a
.B kpathsea
variable is set (we use
.C MISCFONTS
as an example).
This is especially useful if a variable isn't set in
.C texmf.cnf
or in the environment, thus pointing to the default value which is
hard-coded into the
.B kpathsea
library.
.PP
.in +2m
.C "kpsewhich \-progname=hbf2gf \-expand\-var='$MISCFONTS'"
.PP
We select the program name also since it is possible to specify
variables which are searched only for a certain program \(en in our
example it would be
.C MISCFONTS.hbf2gf .
.PP
A similar but not identical method is to say
.PP
.in +2m
.C "kpsewhich \-progname=hbf2gf \-show\-path='misc fonts'"
.PP
[A full list of format types can be obtained by saying \(oq\c
.C "kpsewhich \-\-help" \(cq
on the command line prompt.]
This is exactly how
.B hbf2gf
searches for files; the disadvantage is that all variables are expanded
which can cause very long strings.
.
.SS emtexdir
.PP
Here the list of suffixes and its related environment variables to be set in
.C autoexec.bat
(resp. in
.C config.sys
for OS/2):
.PP
.in +4m
.ta 2i
.br
.C "\&.hbf	HBFONTS"
.br
.C "\&.cfg	HBFCFG"
.PP
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:
.PP
.in +2m
.C HBFONTS=c:\\\\fonts\\\\hbf!!;d:\\\\myfonts\\\\hbf!
.PP
Constructions like \(oq\c
.C c:\\\\fonts!!\\\\hbf \(cq
aren't possible.
.
.SS MikTeX
.PP
Please consult the documentation files of
.B MiKTeX
for more details.
.
.
.SH LIMITATIONS
The x and y output size must not exceed
.BR MAX_CHAR_SIZE ,
which is defined at compile time; its default value is 1023\ (pixel).
.
.
.SH "SEE ALSO"
.BR ttf2pk (1)
.PP
.C hbf2gf.w :
'in +\n(.ku
this is the source code written in
.B CWEB
which can be converted into a pretty-printed \*(TX
document using
.BR cweave .
The CJK package also contains a preformatted
.C hbf2gf.pdf
file.
.PP
the
.B CJK
documentation files (\c
.C hbf2gf.txt ).
.PP
the
.B Hanzi Bitmap File
.RB ( HBF )
standard version\ 1.3; available at
.C \%ftp.ifcss.org .
.PP
the Omega documentation available at
.C ftp.ens.fr
and the CTAN hosts and mirrors.
.
.
.SH FILES
.TP
.C *.cfg
The
.B hbf2gf
configuration scripts.
.TP
.C *.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
.BR hbf2gf .
.
.
.SH AVAILABILITY
.B hbf2gf
is part of the CJK macro package for \*(LE
available at the CTAN hosts and its mirrors.
.PP
CJK fonts together with HBF header files can be found at
.C ftp.ifcss.org
and its mirrors.
.
.
.SH AUTHORS
Werner Lemberg
.C <wl@gnu.org>
.br
Ross Paterson (the HBF API)
.C <ross@soi.city.ac.uk>