This is fontu.info, produced by makeinfo version 4.0 from fontu.texi.

  This file documents the GNU font utilities.

  Copyright (C) 1992, 2000 Free Software Foundation, Inc.

  Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

  Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
sections entitled "Freedom" and "GNU General Public License" are
included exactly as in the original, and provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

  Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that the sections entitled "Freedom" and "GNU General
Public License" may be included in a translation approved by the Free
Software Foundation instead of in the original English.


File: fontu.info,  Node: Top,  Next: Introduction,  Prev: (dir),  Up: (dir)

Introduction
************

  This manual documents how to install and run the GNU font utilities.
It corresponds to version 0.7 (released in March 2000).

  The introduction briefly describes the purpose and philosophy of the
font utilities.  The overview gives details on their general usage,
especially how they interact, and describes various things which are
common to all or most of the programs.

  The first part of this master menu lists the major nodes in this Info
document, including the index.  The rest of the menu lists all the
lower level nodes in the document.

* Menu:

* Introduction::                A brief introduction.
* Installation::                How to compile and install the font utilities.
* Overview::                    Commonalities to the programs,
                                  a roadmap to how they fit together,
                                  and examples of using them in concert.
* Bugs::                        How, why, and where to report bugs.
* File formats::                These programs read and write many files.
* Imageto::                     Extracting a font from a scanned image.
* IMGrotate::                   Rotating an image.
* Fontconvert::                 Manipulation of bitmap fonts.
* Charspace::                   Adding character metrics to a font.
* Limn::                        Making outlines from bitmaps.
* BZRto::                       Converting generic outlines to other formats.
* BPLtoBZR::                    Converting plain text to binary BZR fonts.
* XBfe::                        Hand editor for bitmap fonts under X11.
* BZRedit::                     Hand editor for outline fonts under Emacs.
* GSrenderfont::                Rasterize PostScript fonts.
* Enhancements::                Future projects.
* Copying::                     Copying and sharing the font utilities.
* Freedom::                     Regain your programming freedom.
* Index::                       General index.

 --- The Detailed Node Listing ---

Installation

* configure::                   Options and frills for the `configure' script.
* Prereqs::                     What's needed before installation.
* Problems::                    Known trouble.

Prerequisites

* Archives::                    Where to find programs.

Overview

* Picture::                     A pictorial overview.
* Creating fonts::              How to use the programs together.
* Command-line options::        Many aspects of the command line are
                                  common to all programs.
* Font searching::              How fonts and other files are looked for.
* Font naming::                 How to name fonts.

Creating fonts

* Font creation example::       A real-life example.

Command-line options

* Main input file::             Each program operates on a ``main'' font.
* Options: Common options.      Some options are accepted by all programs.
* Specifying character codes::  Ways of specifying single characters.
* Values: Common option values.  Some options need more information.

Specifying character codes

* Named character codes::       Character names are looked up in the encoding.
* Numeric character codes::     Decimal, octal, hex, or ASCII.

Bugs

* Bug criteria::                Have you found a bug?
* Bug reporting::               How to effectively report a bug.

Bug reporting

* Necessary information::       What you need to send.
* Unnecessary information::     What you don't need to send.
* Documentation bugs::          Report the bugs in the manual, too.

File formats

* File format abbreviations::   The alphabet soup of font formats.
* Common file syntax::          Some elements of auxiliary files are constant.
* Encoding files::              The character code-to-shape mapping.
* Coding scheme map file::      The coding scheme string-to-filename mapping.

Encoding files

* Character names::             How to write character names.
* Ligature definitions::        How to define ligatures.
* GNU encodings::               Why we invented new encodings for GNU.

Imageto

* Imageto usage::               Process for extracting fonts from an image.
* IFI files::                   IFI files supply extra information.
* Invoking Imageto::            Command-line options.

Imageto usage

* Viewing an image::            Seeing what's in an image.
* Image to font conversion::    Extracting a font.
* Dirty images::                Handling scanning artifacts or other noise.

IMGrotate

* IMGrotate usage::             Doing the image rotation.
* Invoking IMGrotate::          Command-line options.

IMGrotate usage

* Clockwise rotation::          Rotating clockwise.
* Flip rotation::               FLipping end-for-end.

Fontconvert

* Invoking Fontconvert::        Command-line options.

Invoking Fontconvert

* Fontconvert output options::  Specifying the output format(s).
* Character selection options::  What characters to operate on.
* Character manipulation options::  Changing characters' appearance.
* Fontwide information options::  Changing global information in a font.
* Miscellaneous options::       Other options.

Charspace

* Charspace usage::             Details on improving the character metrics.
* CMI files::                   You specify the metrics in a separate file.
* Invoking Charspace::          Command-line options.

CMI files

* CMI tokens::                  The building blocks of CMI files.
* char command::                Defining a character's side bearings.
* char-width command::          Defining side bearings via the set width.
* define command::              Introducing a new identifier.
* kern command::                Defining a kerning pair.
* codingscheme command::        Specifying the font encoding.
* fontdimen command::           Defining additional font parameters.
* CMI processing::              How Charspace reads CMI files.

`fontdimen' command

* TFM fontdimens::              All the valid fontdimens.

Limn

* Limn algorithm::              How Limn fits outlines to bitmaps.
* Invoking Limn::               Command-line options.

Limn algorithm

* Finding pixel outlines::      Extracting the edges from the bitmap.
* Finding corners::             Finding subsections of each outline.
* Removing knees::              Removing extraneous points.
* Filtering curves::            Smoothing the outlines.
* Fitting the bitmap curve::    Doing the fitting.
* Changing splines to lines::   Use straight lines where possible.
* Changing lines to splines::   Sometimes it isn't possible.
* Aligning endpoints::          If points are close enough, line them out.
* Displaying fitting online::   Seeing the results as Limn runs.

Fitting the bitmap curve

* Initializing t::              Initializing the parameter values.
* Finding tangents::            Computing the direction of the curve at
                                  the endpoints.
* Finding the spline::          Where are the control points?
* Reparameterization::          Changing the parameter values.
* Subdivision::                 Splitting the curve into pieces.

BZRto

* Metafont and BZRto::          Output as a Metafont program.
* Type 1 and BZRto::            Output as a Type 1 PostScript font.
* Type 3 and BZRto::            Output as a Type 3 PostScript font.
* CCC files::                   Creating additional characters.
* Invoking BZRto::              Command-line options.
* BZR files::                   The technical definition of BZR format.

Metafont and BZRto

* Metafont output at any size::  Making larger or smaller fonts.
* Proofing with Metafont::      Metafont can help with debugging fonts.

CCC files

* setchar: CCC setchar.         Statements for including a character.
* move: CCC move.               Statements for moving to a new position.

BZR files

* Intro: BZR format introduction.  General concepts and definitions.
* Preamble: BZR preamble.       The beginning.
* Chars: BZR characters.        The middle.
* Postamble: BZR postamble.     The end.

BZR characters

* BOC: BZR character beginnings.  Giving character metrics.
* Shape: BZR character shapes.  Defining the outline(s).

BPLtoBZR

* BPL files::                   Bezier property list file format.
* Invoking BPLtoBZR::           Command-line options.

BPL files

* Preamble: BPL preamble.       The beginning.
* Characters: BPL characters.   The middle.
* Postamble: BPL postamble.     The end.

BPL characters

* BPL outlines::                Representation of character outlines.

XBfe

* XBfe usage::                  How to edit fonts.
* Invoking XBfe::               Command-line options.

XBfe usage

* Controlling XBfe ::           Controlling XBfe
* Shape: XBfe shape editing.    Changing the pixels.
* Metrics: XBfe metrics editing.  Changing the side bearings.

XBfe shape editing

* Selections::                  Marking pixel regions for later operations.
* Enlarging the bitmap::        Give yourself more room at the edges.

BZRedit

* BZRedit usage::               Operating the editor.

BZRedit usage

* BZRedit installation::        Additional installation is needed.
* BZR: Editing BZR files.       Editing files in the binary format.
* BPL: Editing BPL files.       Editing files in the textual format.

Editing BPL files

* BZRedit and Ghostscript::     Customizing the use of Ghostscript.

GSrenderfont

* GSrenderfont usage::          Making bitmap fonts from PostScript.
* Invoking GSrenderfont::       Command-line options.

GSrenderfont usage

* Names: GSrenderfont font names.  Supplying PostScript names and filenames.
* Size: GSrenderfont output size.  Specifying the size and resolution.
* Encoding: GSrenderfont encoding.  Specifying the output encoding.

Enhancements

* Additional fonts::            GNU needs more fonts.
* Program features::            These programs can be improved.
* Portability::                 Assumptions about the programming environment.
* Implementation::              Conventions we used in the sources.

Additional fonts

* Legal issues::                Legality (and illegality) differ by country.

Regain your programming freedom

* Software patents::            Algorithm monopolies.
* User interface copyright::    Forbidding upward-compatibility.
* What to do?::                 What to do?


File: fontu.info,  Node: Introduction,  Next: Installation,  Prev: Top,  Up: Top

Introduction
************

  This manual corresponds to version 0.7 of the GNU font utilities.

  You can manipulate fonts in various ways using the utilities:
conversion of a scanned image to a bitmap font, hand-editing of
bitmaps, conversion of a bitmap font to an outline font, and more.
More generally, you can start with a scanned image of artwork and work
your way through to a finished font with side bearings, accented
characters, ligatures, and so on.

  The font formats recognized by these programs are primarily those used
by the (freely available) TeX typesetting system developed by Donald E.
Knuth from 1977-1990.  The filenames, font searching, and other aspects
of their usage are also based on TeX.  They also support output of
PostScript Type 1 fonts.

  Some of this software was originally written as part of the research
program in digital typography at the University of Massachusetts at
Boston, directed by Robert A. Morris.  The staff at UMB, Rick Martin in
particular, has been kind enough to let us to continue to use their
computers, despite our completing the Master's program there in 1989.


File: fontu.info,  Node: Installation,  Next: Overview,  Prev: Introduction,  Up: Top

Installation
************

  *Note Prereqs::, for what you need to have installed before you can
compile these programs.

  After that, here's what to do:

   * Run `sh configure' in the top-level directory.  This tries to
     figure out system dependencies and the installation prefix.  *Note
     configure::, for options and other information about the
     `configure' script.

   * If necessary, edit the paths or other definitions in the top-level
     `GNUmakefile' and in `include/c-auto.h'.

   * Run GNU make.  For example, if it's installed as `make', just type
     `make' in the top-level directory.  If all goes well, this will
     compile all the programs.

   * Install the programs and supporting data files with `make install'.


  If you encounter problems anywhere along the line, let us know.  Known
problems are listed below (*note Problems::).  *Note Bugs::, for
details on how to submit a useful bug report.

* Menu:

* configure::                   Options and frills for the `configure' script.
* Prereqs::                     What's needed before installation.
* Problems::                    Known trouble.


File: fontu.info,  Node: configure,  Next: Prereqs,  Up: Installation

The `configure' script
======================

  (This section is largely from the Autoconf manual, by David MacKenzie.
*Note Running `configure' scripts: (autoconf)Running configure Scripts.)

  The `configure' script that comes with the font utilities is
generated automatically by the Autoconf program.  You can regenerate
`configure' by rerunning Autoconf (for example, if a new version of
Autoconf is released); you must arrange for Autoconf to use the macros
in `./aclocal.m4' (*note Generating `configure': (autoconf)Generating
configure.).

  The purpose of `configure' is to adapt the source code to your
system: for example, the name of the directory header file (`dirent.h'
or `sys/dir.h'), whether an `install' program is available, and so on.

  Normally, you do not need to give any options to `configure'; you
`cd' to the directory with the source code and type `configure'.
Exceptions: if `.' is not in your `PATH', you must type `./configure';
if you are using a non-Bourne-compatible shell on some old systems, you
must samp `sh configure'.

  Running `configure' takes a minute or two.  While it is running, it
prints some messages that tell what it is doing.  If you don't want to
see the messages, run `configure' with its standard output redirected
to `/dev/null'; for example, `configure >/dev/null'.

  To compile the package in a different directory from the one
containing the source code, you must use a variant of Make that
supports the `VPATH' variable, such as GNU Make.  `cd' to the directory
where you want the object files and executables to go and run
`configure' with the option `--srcdir=DIR', where DIR is the directory
that contains the source code.  Using this option is unnecessary if the
source code is in the parent directory of the one in which you are
compiling; `configure' automatically checks for the source code in `..'
if it does not find it in `.'.

  `configure' guesses the default installation prefix (we'll call it
`$(prefix)') by looking for the directory which contains the command
`gcc', and using its parent.  For example, if `gcc' is installed as
`/usr/local/gnu/bin/gcc', `$(prefix)' will be set to `/usr/local/gnu'.

  You can override this default guess for the installation prefix by
giving `configure' the option `--prefix=PATH'.  You can also specify
separate installation prefixes for architecture-specific files and
architecture-independent files by giving `configure' the option
`--exec_prefix=XPATH'. Then XPATH will be the prefix for installing
programs and libraries.  Data files and documentation will still use
the regular prefix.  Normally, all files are installed using the
regular prefix.

  You can tell `configure' to figure out the configuration for your
system, and record it in `config.status', without actually configuring
the package.  To do this, give `configure' the `--no-create' option.
Later, you can run `./config.status' to actually configure the package.
This option is useful mainly in `Makefile' rules for updating
`config.status' and the `Makefile' itself.  You can also give
`config.status' the `--recheck' option, which makes it rerun
`configure' with the same arguments you used before.  This is useful if
you change `configure'.

  `configure' ignores any other arguments that you give it.

  On systems that require unusual options for compilation or linking
that the package's `configure' script does not know about, you can give
`configure' initial values for variables by setting them in the
environment.  In Bourne-compatible shells, you can do that on the
command line like this:

     CC='gcc -traditional' LIBS=-lposix sh configure

  The Make variables that you might want to override with environment
variables when running `configure' are:

  (For these variables, any value given in the environment overrides the
value that `configure' would choose.)

`CC'
     The C compiler program.  The default is `gcc' if that is in your
     `PATH', `cc' otherwise.

`INSTALL'
     The program to use to install files.  The default is `install' if
     you have it, `cp' otherwise.

  (For these variables, any value given in the environment is added to
the value that `configure' chooses.)

`DEFS'
     Configuration options, in the form `-Dfoo -Dbar...'.  Packages
     that use the Autoconf macro `AC_CONFIG_HEADER' (including the file
     utilities) do not use this variable.

`LIBS'
     Libraries to link with, in the form `-lfoo -lbar...'.

  Of course, problems requiring manual intervention (e.g., setting these
variables) should ideally be fixed by updating either the Autoconf
macros or the `configure.in' file for that package.


File: fontu.info,  Node: Prereqs,  Next: Problems,  Prev: configure,  Up: Installation

Prerequisites
=============

  To compile and use these programs, the following are necessary:

   * The GNU C compiler, version 1.40 or newer.

   * GNU Make; probably any version newer than 3.50 or so will do.

   * X11R4 or R5 unshared libraries and headers.  These are only
     necessary to run XBfe (*note XBfe::) or for Limn (*note Limn::) to
     display its results online.  (You also need an X11 server,
     naturally.)  You might be able to compile using the X11 shared
     libraries, but we haven't tried that.

   * To make any substantial use of the fonts you create, you will
     probably need TeX, Metafont, and their friends, especially
     `PLtoTF' and `GFtoPK'.

   * Ghostscript, version 2.4 or newer.  You only need this if you want
     to use GSrenderfont or BZRedit.

   * The GNU Awk program, `gawk'.  This is only needed if you want to
     use GSrenderfont.


  See the section below for information on how to get all these
programs.

* Menu:

* Archives::                    Where to find programs.


File: fontu.info,  Node: Archives,  Up: Prereqs

Archives
--------

  The canonical source for all GNU software, including the GNU C
compiler, GNU make, and Ghostscript, is `prep.ai.mit.edu
[18.71.0.38]:pub/gnu'.  That directory is replicated at many other sites
around the world, including:

United States:
            wuarchive.wustl.edu   gatekeeper.dec.com:pub/GNU
            uxc.cso.uiuc.edu      ftp.uu.net:packages/gnu

Europe:
            archive.eu.net        src.doc.ic.ac.uk:gnu    ftp.funet.fi
            nic.funet.fi:pub/gnu  ugle.unit.no            isy.liu.se
            ftp.diku.dk

elsewhere:
            ftp.cs.titech.ac.jp   utsun.s.u-tokyo.ac.jp:ftpsync/prep
            archie.au:gnu

  You can also order tapes with GNU software from the Free Software
Foundation (thereby supporting the development of the font utilities and
the rest of the GNU project); send mail to `gnu@prep.ai.mit.edu' for
the latest prices and ordering information, or retrieve the file
`DISTRIB' from a GNU archive.

  The canonical source for the X window system is
`export.lcs.mit.edu:pub/R5'.  That directory is also shadowed at many
other sites, including `gatekeeper.dec.com'.  The FSF also sells X
distribution tapes.

  TeX is more scattered.  A complete Unix TeX distribution is available
for ftp on the machine `byron.u.washington.edu', or by ordering a tape
from the University of Washington (send email to
`elisabet@u.washington.edu'.  What is on `byron' for ftp is often
out-of-date, though.

  The canonical sources for just Web2C--the port of just TeX, Metafont,
and friends to Unix, without DVI processors, fonts, macro packages,
etc.--are:

     ftp.cs.umb.edu [192.12.26.23]:pub/tex/                  (Boston)
     ics.uci.edu [128.195.1.1]:TeX/                          (California)
     ftp.th-darmstadt.de [130.83.55.75]:pub/tex/src/web2c/   (Germany)

  At all these sites, the files to retrieve are `web.tar.Z' and
`web2c.tar.Z'.

  The DVI-to-PostScript driver we recommend is Tom Rokicki's Dvips, and
the X window system driver we recommend is Paul Vojta's XDvi.  These
programs are available from, respectively,
     labrea.stanford.edu:pub/dvips*
     export.lcs.mit.edu:contrib/xdvi.tar.Z

  We have modified XDvi and Dvips to use the same path searching code as
the current distribution of TeX and these font utilities; the modified
versions are available from `ftp.cs.umb.edu:pub/tex'.

  To use Metafont, you must have a file defining output devices.
(*Note Metafont and BZRto::.)  We recommend you obtain `modes.mf' from
     ftp.cs.umb.edu:pub/tex/modes.mf

  You can retrieve the document describing all the details of the naming
scheme for TeX fonts from

     ftp.cs.umb.edu [192.12.26.23]:pub/tex/fontname.tar.Z


File: fontu.info,  Node: Problems,  Prev: Prereqs,  Up: Installation

Problems
========

  This section lists some things which have caused trouble during
installation.  If you encounter other problems, please send a bug
report.  *Note Bugs::, for how to submit a useful bug report.

   * You may get a warning from the compiler about `-static' being an
     unrecognized option.  Ignore it.  (This has already been reported
     to `bug-gcc'.)

   * Under SunOS 4.x, the programs which use X (XBfe and Limn) cannot be
     dynamically linked, because (apparently) `/bin/ld' pulls in the
     entire `.sa' file, and the Form, Label, and Viewport widgets are
     multiply defined.  (To us, this seems to defeat the whole purpose
     of having libraries.  It also seems bizarre to us that X was
     written so that these multibyte functions are always needed (via
     `__Xsi...'), and furthermore that the multibyte functions need to
     specifically call the dynamic linking functions.)

     The file `lib/dlsym.c' (from the MIT X distribution) defines the
     `dlsym', `dlclose', and `dlopen' symbols, so static linking should
     work now.

     If the current setup fails, it might work to change `-lXaw' in the
     definition of `X_libraries' in `lib/defs.make' to the full
     pathname of the Xaw library.

   * On many machines (Sun 3 or Sun 4 running SunOS 4.1, Sun386i running
     4.0.2, 386 running ISC 2.2), GCC 1.40 gets a fatal error compiling
     `imageto/main.c' with `-O'.  Just use `-g' for that file, or use a
     newer version of GCC.

   * On a 386 running Interactive UNIX 2.2, `<math.h>' declares the
     wrong prototype for `fmod': the routine takes two doubles, not one.
     We simply corrected our system include file.

     You may get compiler warnings for the file `widgets/Bitmap.c' at
     the lines which use the Xt function `XtIsRealized' on systems which
     define `NULL' as `(void *) 0'.  The reason is that macro
     definition of `XtIsRealized' in `<X11/IntrinsicP.h>' incorrectly
     compares the result of `XtWindowOfObject' to `NULL', instead of
     `0'.  If the warnings bother you, fix `IntrinsicP.h'.

   * The application resource files `limn/Limn' and `xbfe/XBfe' must be
     installed in a directory where your X server can find them.  This
     directory varies according to how X was installed; in the default X
     distribution, it is `/usr/lib/X11/app-defaults'.  If you cannot (or
     do not want to) write in the default directory, you can install
     them elsewhere and set the `XAPPLRESDIR' environment variable to
     that directory.  See the tutorial on resources that comes with the
     MIT X distribution (`mit/doc/tutorial/resources.txt') for more
     information.


  Good luck.


File: fontu.info,  Node: Overview,  Next: Bugs,  Prev: Installation,  Up: Top

Overview
********

  This chapter gives an overview of what you do to create fonts using
these programs.  It also describes some things which are common to all
the programs.

  Throughout this document, we refer to various source files in the
implementation.  If you can read C programs, you may find these
references useful as points of entry into the source when you are
confused about some program's behavior, or are just curious.

* Menu:

* Picture::                     A pictorial overview.
* Creating fonts::              How to use the programs together.
* Command-line options::        Many aspects of the command line are
  				  common to all programs.
* Font searching::              How fonts and other files are looked for.
* Font naming::                 How to name fonts.


File: fontu.info,  Node: Picture,  Next: Creating fonts,  Up: Overview

Picture
=======

  Following is a pictorial representation of the typical order in which
these programs are used, as well as their input and output.

  GSrenderfont is not in the picture since it is intended for an
entirely separate purpose (namely, making bitmaps from PostScript
outlines).  Fontconvert also has many functions which are not needed
for the basic task of font creation from scanned images.

                                              ---------------
                                              | fontconvert |
                                            / ---------------
                                  /--------/         ^
     scanned                     /                   |
     image                      /                    v
     and IFI   -----------    GF   -------------  TFM, GF   --------  BZR
     ========> | imageto | ======> | charspace | =========> | limn | ======...
       ^       -----------         -------------     ^      --------
       |                         /                   |               (continued)
       v                       CMI                   v
     -------------                               --------
     | imgrotate |                               | xbfe |
     -------------                               --------
     
     
     
                                       Metafont source    ------  GF, TFM
                                  |=====================> | mf | =========
      (continued)                 |                       ------
                                  |
           BZR   ---------  TFM,  |   PostScript Type 1 (gsf)
     ... ======> | bzrto |========|=======================
                 ---------        |
               /                  |
             CCC                  |   PostScript Type 3 (pf3)
                                  |======================
                                  |
                                  |
                                  |    BPL    ------------  BZR
                                  |=========> | bpltobzr | =====
                                              ------------

  *Note File formats::, for more information on these file formats.


File: fontu.info,  Node: Creating fonts,  Next: Command-line options,  Prev: Picture,  Up: Overview

Creating fonts
==============

  The previous section described pictorially the usual order in which
these programs are used.  This section will do the same in words.

  Naturally, you may not need to go through all the steps described
here.  For example, if you are not starting with a scanned image, but
already have a bitmap font, then the first step--running Imageto--is
irrelevant.

  Here is a description of the usual font creation process, starting
with a scanned image of a type specimen and ending with fonts which can
be used by Ghostscript, TeX, etc.

  1. To see what an image I consists of, run Imageto with the `-strips'
     option.  This produces a bitmap font `Isp' in which each character
     is simply a constant number of scanlines from the image.

  2. Run Fontconvert (*note Fontconvert::) on `Isp' with the `-tfm'
     option, to produce a TFM file.  This is because of the next step:

  3. Run TeX on `imageto/strips.tex', telling TeX to use the font
     `Isp'.  This produces a DVI file which you can print or preview as
     you usually do with TeX documents.  (If you don't know how to do
     this, you'll have to ask someone knowledgeable at your site, or
     otherwise investigate.)  This will (finally) show you what is in
     the image.

     An alternative to the above steps is to run Imageto with the
     `-epsf' option.  This outputs an Encapsulated PostScript file with
     the image given as a simple PostScript bitmap.  Then you can use
     Ghostscript or some other PostScript interpreter to look at the
     EPS file.  This method is simpler, but has the disadvantage of
     using much more disk space, and needing a PostScript interpreter.

  4. If the original was not scanned in the normal orientation, the
     image must be rotated 90 degrees in some direction and/or flipped
     end for end.  (Sometimes we have not scanned in the normal
     orientation because the physical construction of the book we were
     scanning made it difficult or impossible.)  In this case, you must
     rotate the image to be upright.  The program IMGrotate does this,
     given the `-flip' or `rotate-clockwise' option.  Given an image
     RI, this outputs the upright image I.

  5. Once you have an upright image I, you can use Imageto (*note
     Imageto::) to extract the characters from the image and make a
     bitmap font `I.DPIgf', where DPI is the resolution of the image in
     pixels per inch.  (If the image itself does not contain the
     resolution, you must specify it on the command line with `-dpi'.)
     To do this, you must first prepare an IFI file describing the
     image.  *Note IFI files::, for a description of IFI files.

  6. To view the resulting GF file, run Fontconvert to make a TFM file,
     as above.  Then run TeX on `testfont.tex' and use the `\table' or
     `\sample' commands to produce a font table.  Next, print or
     preview the DVI file that TeX outputs, as before.  This will
     probably reveal problems in your IFI file, e.g., that not all the
     characters are present, or that they are not in the right
     positions.  So you need to iterate until the image is correctly
     processed.

     `testfont.tex' should have come with your TeX distribution.  If
     for some reason you do not have it, you can use the one
     distributed in the `data' directory.

  7. Once all the characters have been properly extracted from the
     image, you have a bitmap font.  Unlike the above, the following
     steps all interact with each other, in the sense that fixing
     problems found at one stage may imply changes in an earlier stage.
     As a result, you must expect to iterate them several (billion)
     times.

     At any rate, given a bitmap font F you then run Charspace (*note
     Charspace::) to add side bearings to F, producing a new bitmap
     font, say G, and a corresponding TFM file `G.tfm'.  To do this,
     you must prepare a CMI file specifying the side bearings.  *Note
     CMI files::, for a description of CMI files.

  8. To fit outlines to the characters in a bitmap font, run Limn
     (*note Limn::).  Given the bitmap font G, it produces the BZR
     (*note BZR files::) outline font `G.bzr'.  The side bearings in G
     are carried along.

     Although Limn will (should) always be able to fit some sort of
     outline to the bitmaps, you can get the best results only by
     fiddling with the (unfortunately numerous) parameters.  *Note
     Invoking Limn::.

  9. To convert from the BZR file `G.bzr' that Limn outputs to a font
     format that a typesetting program can use, run BZRto (*note
     BZRto::).  While developing a font, we typically convert it to a
     Metafont program (with the `-metafont' option).

     As you get closer to a finished font, you may want to prepare a
     CCC file (*note CCC files::) to tell BZRto how construct composite
     characters (pre-accented `A's, for example) to complete the font.

 10. Given the font in Metafont form, you can then either make the font
     at its true size for some device, or make an enlarged version to
     examine the characters closely.  *Note Metafont and BZRto::, for
     the full details.

     Briefly, to do the former, run Metafont with a `mode' of whatever
     device you wish (the mode `localfont' will get you the most common
     local device, if Metafont has been installed properly).  Then you
     can use `testfont.tex' to get a font sample, as described above.

     To do the latter, run Metafont with no assignment to `mode'.  This
     should get you `proof' mode.  You can then use GFtoDVI to get a DVI
     file with one character per page, showing you the control points
     Limn chose for the outlines.

 11. Problems can arise at any stage.  For example, the character
     spacing might look wrong; in that case, you should fix the CMI
     files and rerun Charspace (and all subsequent programs,
     naturally).  Or the outlines might not match the bitmaps very
     well; then you can change the parameters to Limn, or use XBfe
     (*note XBfe::) to hand-edit the bitmaps so Limn will do a better
     job.  (To eliminate some of tedium of fixing digitization problems
     in the scanned image, you might want to use the filtering options
     in Fontconvert before hand-editing; see *Note Character
     manipulation options::.)

     Inevitably, as one problem gets fixed you notice new ones ...


* Menu:

* Font creation example::       A real-life example.


File: fontu.info,  Node: Font creation example,  Up: Creating fonts

Font creation example
---------------------

  This section gives a real-life example of font creation for the
Garamond roman typeface, which we worked on concomitantly with
developing the programs.  We started from a scanned type specimen of 30
point Monotype Garamond, scanned using a Xerox 9700 scanner loaned to
us from Interleaf, Inc.  (Thanks to Paul English and others at
Interleaf for this loan.)

     To begin, we used Imageto as follows to look at the image file we
     had scanned (*note Viewing an image::).  Each line is a separate
     command.
          imageto -strips ggmr.img
          fontconvert -tfm ggmrsp.1200
          echo ggmrsp | tex strips.tex
          xdvi -p 1200 -s 10 strips.dvi

  1. Next, we created the file `ggmr.ifi' (distributed in the `data'
     directory), listing the characters in the order they appeared in
     the image, guessing at baseline offsets and (if necessary)
     including bounding box counts.  Then we ran Imageto again, this
     time to get information about the baselines and spurious blotches
     in the image.  We use the `-encoding' option since some of the
     characters in the image are not in the default `ASCII' encoding.
          imageto -print-guidelines -print-clean-info -encoding=gnulatin ggmr.img

  2. Based on the information gleaned from that run, we decided on the
     final baselines, adjusted the bounding box counts for broken-up
     characters, and extracted the font (*note Image to font
     conversion::).  (In truth, this took several iterations.)  The
     design size of the original image was stated in the book to be
     30pt.  We noticed several blotches in the image we needed to
     ignore, and so we added `.notdef' lines to `ggmr.ifi' as
     appropriate.
          imageto -verbose -baselines=121,130,120 \
            -designsize=30 -encoding=gnulatin ggmr.img

  3. To smooth some of the rough edges caused by the scanner's
     rasterization errors, we filtered the bitmaps with Fontconvert
     (*note Fontconvert::).
          fontconvert -verbose -gf -tfm -filter-passes=3 -filter-size=3 \
            ggmr30.1200 -output=ggmr30a

  4. For a first attempt at intercharacter and interword spacing, we
     created `ggmr.1200cmi' (also distributed in the `data' directory)
     and ran Charspace (*note Charspace::), producing `ggmr30b.1200gf'
     and `ggmr30b.tfm'.  To see the results, we ran `ggmr30b' through
     `testfont.tex', modified the CMI file, reran Charspace, etc., until
     the output was somewhat reasonable.  We didn't try to fine-tune the
     spacing here, since we knew the following steps would affect the
     character shapes, which in turn would affect the spacing.
          charspace -verbose -cmi=ggmr.1200cmi ggmr30a.1200 -output=ggmr30b

  5. Next we ran `ggmr30b.1200gf', created by Charspace, through Limn to
     produce the outline font in BZR form, `ggmr30b.bzr'.  We couldn't
     know what the best values of all the fitting parameters were the
     first time, so we just increased the ones which are relative to the
     resolution.
          limn -verbose -corner-surround=4 -filter-surround=6 \
            -filter-alternative-surround=3 -subdivide-surround=6 \
            -tangent-surround=6 ggmr30b.1200

  6. Then we converted `ggmr30b.bzr' to a Metafont program using BZRto
     (*note BZRto::), and then ran Metafont to create TFM and GF files
     we could typeset with (*note Metafont and BZRto::).  In order to
     keep the Metafont-generated files distinct from the original TFM
     and GF files, we use the output stem `ggmr30B'.  To see the
     results at the usual 10pt, we then ran the Metafont output through
     `sample.tex' (a one-line wrapper for `testfont.tex': `\input
     testfont \sample \end').
          bzrto -verbose -metafont ggmr30b -output=ggmr30B
          mf '\mode:=localfont; input ggmr30B'
          echo ggmr30B | tex sample
          dvips sample

  7. This 10pt output looked too small to us.  So we changed the design
     size to 26pt (finding the value took several iterations) with
     Fontconvert (*note Fontconvert::), then reran Charspace, Limn,
     BZRto, Metafont, etc., as above.  We only show the Fontconvert
     step here; the others have only the filenames changed from the
     invocations above.
          fontconvert -verbose -gf -tfm -designsize=26 ggmr30b.1200 -output=ggmr26c

  8. After this, the real work begins.  We ran the Metafont program
     `ggmr26D.mf' in `proof' mode, followed by GFtoDVI, so we could see
     how well Limn did at choosing the control points for the outlines.
     *Note Proofing with Metafont::.  (The `nodisplays' tells Metafont
     not to bother displaying each character in a window online.)
          mf '\mode:=proof; nodisplays; input ggmr26D'
          gftodvi ggmr26D.3656gf

  9. From this, we went and hand-edited the font `ggmr26d.1200gf' with
     XBfe (*note XBfe::), and/or tinkered with the options to Limn,
     trying to make the outlines reasonable.  We still haven't finished
     ...


File: fontu.info,  Node: Command-line options,  Next: Font searching,  Prev: Creating fonts,  Up: Overview

Command-line options
====================

  Since these programs do not have counterparts on historical Unix
systems, they need not conform to an existing interface.  We chose to
have all the programs use the GNU function `getopt_long_only' to parse
command lines.

  As a result, you can give the options in any order, interspersed as
you wish with non-option arguments; you can use `-' or `--' to start an
option; you can use any unambiguous abbreviation for an option name;
you can separate option names and values with either `=' or one or more
spaces; and you can use filenames that would otherwise look like
options by putting them after an option `--'.

  By convention, all the programs accept only one non-option argument,
which is taken to be the name of the main input file.

  If a particular option with a value is given more than once, it is the
last value which is used.

  For example, the following command line specifies the options `foo',
`bar', and `verbose'; gives the value `abc' to the `baz' option, and
the value `xyz' to the `quux' option; and specifies the filename
`-myfile-'.

     -foo --bar -verb -abc=baz -quux karl -quux xyz -- -myfile-

* Menu:

* Main input file::             Each program operates on a ``main'' font.
* Options: Common options.      Some options are accepted by all programs.
* Specifying character codes::  Ways of specifying single characters.
* Values: Common option values.  Some options need more information.


File: fontu.info,  Node: Main input file,  Next: Common options,  Up: Command-line options

The main input file
-------------------

  By convention, all the programs accept only one non-option argument,
which they take to be the name of the main input file.

  Usually this is the name of a bitmap font.  By their nature, bitmap
fonts are for a particular resolution.  You can specify the resolution
in two ways: with the `-dpi' option (see the next section), or by
giving an extension to the font name on the command line.

  For example, you could specify the font `foo' at a resolution of
300dpi to the program PROGRAM in either of these two ways (`$ ' being
the shell prompt):
     $ PROGRAM foo.300
     $ PROGRAM -dpi=300 foo

  You can also say, e.g., `PROGRAM foo.300gf', but the `gf' is ignored.
These programs always look for a given font in PK format before
looking for it in GF format, under the assumption that if both fonts
exist, and have the same stem, they are the same.

  If the filename is absolute or explicitly relative, i.e., starts with
`/' or `./' or `../', then the programs do not use search paths to look
for it, as described in *Note Font searching::.  Instead, the fonts are
simply searched for in the given directory.


File: fontu.info,  Node: Common options,  Next: Specifying character codes,  Prev: Main input file,  Up: Command-line options

Common options
--------------

  Certain options are available in all or most of the programs.  Rather
than writing identical descriptions in the chapters for each of the
programs, they are described here.

  This first table lists common options which do not convey anything
about the input.  They merely direct the program to print additional
output.

`-help'
     Prints a usage message listing all available options on standard
     error.  The program exits after doing so.

`-log'
     Write information about everything the program is doing to the file
     `FOO.log', where FOO is the root part of the main input file.

`-verbose'
     Prints brief status reports as the program runs, typically the
     character code of each character as it is processed.  This usually
     goes to standard output; but if the program is outputting other
     information there, it goes to standard error.

`-version'
     Prints the version number of the program on standard output.  If a
     main input file is supplied, processing continues; otherwise, the
     program exits normally.

  This second table lists common options which change the program's
behavior in more substantive ways.

`-dpi DPI'
     Look for the main input font at a resolution of DPI pixels per
     inch.  The default is to infer the information from the main input
     filename (*note Main input file::).

`-output-file FNAME'
     Write the main output of the program to FNAME.  If FNAME has a
     suffix, it is used unchanged; otherwise, it is extended with some
     standard suffix, such as `RESOLUTIONgf'.  Unless FNAME is an
     absolute or explicitly relative pathname, the file is written in
     the current directory.

`-range `START-END''
     Only look at the characters between the character codes START and
     END, inclusive.  The default is to look at all characters in the
     font.  *Note Specifying character codes::, for the precise syntax
     of character codes.


File: fontu.info,  Node: Specifying character codes,  Next: Common option values,  Prev: Common options,  Up: Command-line options

Specifying character codes
--------------------------

  Most of the programs allow you to specify character codes for various
purposes.  Character codes are always parsed in the same way (using the
routines in `lib/charcode.c' and `lib/charspec.c').

  You can specify the character code directly, as a numeric value, or
indirectly, as a character name to be looked up in an encoding vector.

* Menu:

* Named character codes::       Character names are looked up in the encoding.
* Numeric character codes::     Decimal, octal, hex, or ASCII.


File: fontu.info,  Node: Named character codes,  Next: Numeric character codes,  Up: Specifying character codes

Named character codes
.....................

  If a string being parsed as a character code is more than one
character long, or starts with a non-digit, it is always looked up as a
name in an encoding vector before being considered as a numeric code.
We do this because you can always specify a particular value in one of
the numeric formats, if that's what you want.

  The encoding vector used varies with the program; you can always
define an explicit encoding vector with the `-encoding' option.  If you
don't specify one explicitly, programs which must have an encoding
vector use a default; programs which can proceed without one do not.
*Note Encoding files::, for more details on encoding vectors.

  As a practical matter, the only character names which have length one
are the 52 letters, `A'-`Z', `a'-`z'.  In virtually all common cases,
the encoding vector and the underlying character set both have these in
their ASCII positions.  (The exception is machines that use the EBCDIC
encoding.)


File: fontu.info,  Node: Numeric character codes,  Prev: Named character codes,  Up: Specifying character codes

Numeric character codes
.......................

  The following variations for numeric character codes are allowed.  The
examples all assume the character set is ASCII.

   * Octal numerals preceded by a zero are taken to be an octal number.
     For example, `0113' also means decimal 75.  If a would-be
     character code starts with a zero but contains any characters
     other than the digits `0' through `7', it is invalid.

   * Hexadecimal "digits" preceded by `0x' or `0X' are taken to be a
     hexadecimal number.  Case is irrelevant.  For example, `0x4b',
     `0X4b', `0x4B', and `0X4B' all mean decimal 75.  As with octal, a
     would-be character code starting with `0x' and containing any
     characters other than `0'-`9', `a'-`f', and `A'-`F' is invalid.

   * A decimal number (consisting of more than one numeral) is itself.
     For example, `75' means the character code decimal 75.  As before,
     a would-be character code starting with `1'-`9' and containing any
     characters other than `0'-`9' is invalid.

   * A single digit, or a single character not in the encoding vector
     as a name, is taken to represent its value in the underlying
     character set.  For example, `K' means the character code decimal
     75, and `0' (the numeral zero) means the character code decimal 48
     (if the machine uses ASCII).

   * If the string being parsed as a character code starts with a
     digit, the appropriate one of the previous cases is applied.  If
     it starts with any other character, the string is first looked up
     as a name.


  Character codes must be between zero and 255 (decimal), inclusive.


File: fontu.info,  Node: Common option values,  Prev: Specifying character codes,  Up: Command-line options

Common option values
--------------------

  The programs have a few common conventions for how to specify option
values that are more complicated than simple numbers or strings.

  Some options take not a single value, but a list.  In this case, the
individual values are separated by commas or whitespace, as in
`-omit=1,2,3' or `-omit="1 2 3"'.  Although using whitespace to
separate the values is less convenient when typing them interactively,
it is useful when you have a list that is so long you want to put it in
the file.  Then you can use `cat' in conjunction with shell quoting to
get the value: `-omit="`cat file`"'.

  Other options take a list of values, but each value is a keyword and
a corresponding quantity, as in `-fontdimens NAME:REAL,NAME,REAL'.

  Finally, a few options take percentages, which you specify as an
integer between 0 and 100, inclusive.

