Provided by: latex-cjk-common_4.8.4+git20150701-1_amd64 bug

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 format 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.   Only  one  GF  file
            together with a 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 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 ‘.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 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  intended  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 (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 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.

       You can use environment  variables  in  the  configuration  file.   The  escape  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 characters or underscores.  You can surround  the  variable  with  braces  to
       indicate  where the variable name ends, for example ${FOO}.  To get a 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!

       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 locate 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 cases 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 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 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 creating all fonts.

       unicode
              If ‘yes’, 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 ‘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.  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

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

           .hbf                MISCFONTS
           .cfg                HBF2GFINPUTS

       Please  consult  the  info files of kpathsea for details on these variables.  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 variable is set (we use
       MISCFONTS as an example).  This is especially useful 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 library.

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

       We select the program name also since it  is  possible  to  specify  variables  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 converted  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>