texmf -> texmf-dist: doc

git-svn-id: svn://tug.org/texlive/trunk@29714 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 718 insertions, 0 deletions

diff --git a/Master/texmf-dist/doc/man/man1/hbf2gf.1 b/Master/texmf-dist/doc/man/man1/hbf2gf.1
new file mode 100644
index 00000000000..55bfddf57fa
--- /dev/null
+++ b/Master/texmf-dist/doc/man/man1/hbf2gf.1
@@ -0,0 +1,718 @@
+.\" man page for hbf2gf
+.\"
+.\" Copyright (C) 1994-2012  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 07-May-2012 "CJK Version 4.8.3"
+.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
+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
+.in +4m
+.ta 2i
+.br
+.C "\&.hbf	MISCFONTS"
+.br
+.C "\&.cfg	HBF2GFINPUTS"
+.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>