Man Linux: Main Page and Category List

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.   Dont  use  it  except  for  thepk_directoryandtfm_directoryparameters!

       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
       Please  note  that  older  versions  of 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 hbf2gf --version.

       Here is a table  of  the  file  type  and  the  corresponding  kpathsea
       variables.

       Version 3.3 and newer (this won’t change again in the future!):

           .hbf                MISCFONTS
           .cfg                HBF2GFINPUTS

       Version 3.2:

           .hbf                T1FONTS
           .cfg                HBF2GFINPUTS

       And here the same for pre-3.2-versions of kpathsea:

           .hbf                T1FONTS
           .cfg                TEXCONFIG

       Finally, the same for versions ≤2.6:

           .hbf                DVIPSHEADERS
           .cfg                TEXCONFIG

       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>