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: Font searching,  Next: Font naming,  Prev: Command-line options,  Up: Overview

Font searching
==============

  These programs use the same environment variables and algorithms for
finding font files as does (the Unix port of) TeX and its friends.

  You specify the default paths in the top-level Makefile.  The
environment variables `TEXFONTS', `PKFONTS', `TEXPKS', and `GFFONTS'
override those paths.  Both the default paths and the environment
variable values should consist of a colon-separated list of directories.

  Specifically, a TFM file is looked for along the path specified by
`TEXFONTS'; a GF file along `GFFONTS', then `TEXFONTS'; a PK file along
`PKFONTS', then `TEXPKS', then `TEXFONTS'.

  A leading or trailing colon in an environment variable value is
replaced by the default path.

  A leading `~' or `~USER' in a path component is replaced by the
current home directory or USER's home directory, respectively.

  If a directory in a path does not exist, it is simply ignored.

  In either the default value or the environment variable value, if a
component directory D ends with two slashes, all subdirectories of D
are searched: first those subdirectories directly under D, then the
subsubdirectories under those, and so on.  At each level, the order in
which the directories are searched is unspecified.

  The subdirectory searching has one known deficiency, for which we know
of no good solution.  If a directory D being searched for
subdirectories contains plain files and symbolic links to other
directories, but no real subdirectories, D will be considered a leaf
directory, i.e., the symbolic links will not be followed.  The only way
we know of to fix this is to invoke `stat' (an expensive system call)
on every directory entry.  Since font directories often contain
hundreds of files, this would make the startup time unacceptably slow.

  A directory D explicitly named with two trailing slashes, however, is
always searched for subdirectories, even if it is a "leaf".  We do this
since presumably you would not have asked D to be searched for
subdirectories if you didn't want it to be, and therefore you don't
have hundreds of files in D.

  For example, the following value for an environment variable says to
search the following: all subdirectories of the current user's `fonts'
directory in his or her home directory, then the directory `fonts' in
the user `karl's home directory, and finally the system default
directories specified at compilation time.

     ~/fonts//:~karl/fonts:


File: fontu.info,  Node: Font naming,  Prev: Font searching,  Up: Overview

Font naming
===========

  Naming font files has always been a difficult proposition at best.  On
the one hand, the names should be as portable as possible, so the fonts
themselves can be used on almost any platform.  On the other hand, the
names should be as descriptive and comprehensive as possible.  The best
compromise we have been able to work out is described in a separate
document: *Note Introduction: (fontname)Top.  *Note Archives::, for
where to obtain.

  Filenames for GNU project fonts should start with `g', for the
"source" abbreviation of "GNU".

  Aside from a general font naming scheme, when _developing_ fonts you
must keep the different versions straight.  We do this by appending a
"version letter" `a', `b', ... to the main bitmap filename.  For
example, the original Garamond roman font we scanned was a 30 point
size, so the main filename was `ggmr30' (`g' for GNU, `gm' for
Garamond, `r' for roman).  As we ran the font through the various
programs, we named the output `ggmr30b', `ggmr30c', and so on.

  Since the outline fonts produced by BZRto are scalable, we do not
include the design size in their names.  (BZRto removes a trailing
number from the input name by default.)


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

Bugs
****

  (This chapter is adapted from the analogous one in the GCC manual,
written by Richard Stallman.)

  Your bug reports are essential in making these programs reliable.

  Reporting a bug may help you by bringing a solution to your problem,
or it may not.  (If it does not, look in the service directory, which is
part of the GNU CC and GNU Emacs distributions.)  In any case, the
principal function of a bug report is to help the entire community by
making the next release work better.

  Send bug reports for the GNU font utilities, or for their
documentation, to the address `bug-gnu-utils@prep.ai.mit.edu'.  We also
welcome suggestions for improvements, no matter how small.

  In order for a bug report to serve its purpose, you must include the
information that makes for fixing the bug, as described below.

  Thanks (in advance)!

* Menu:

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


File: fontu.info,  Node: Bug criteria,  Next: Bug reporting,  Up: Bugs

Bug criteria
============

  If you are not sure whether you have found a bug, here are some
guidelines:

   * If a program gets a fatal signal, for any input whatsoever, that
     is a bug.  Reliable programs never crash.

   * If a program produces an invalid font, for any input whatsoever,
     that is a bug--unless the program reported a fatal error that
     forced it to quit prematurely.  For example, if Metafont gives
     errors reading the output of `bzrto -mf', that is a bug.  You can
     run the TeX utility programs GFtype and TFtoPL to check the
     validity of a GF or TFM file.

   * If a program gives an error message for valid input, that is a bug.
     Similarly, if a program gives a fatal error when it could continue
     processing, that is a bug.  It is sometimes hard to tell if these
     conditions obtain; you must use your best judgement.

   * If a program does not give an error message for invalid input,
     that is a bug.



File: fontu.info,  Node: Bug reporting,  Prev: Bug criteria,  Up: Bugs

Bug reporting
=============

  The purpose of a bug report is to enable someone to fix the bug if it
is not known.  It isn't important what happens if the bug is already
known.  Therefore, always write your bug reports on the assumption that
the bug is not known.

  Sometimes people give a few sketchy facts and ask, "Does this ring a
bell?" or "Should this be happening?"  This cannot help us fix a bug,
so it is basically useless.  We can only respond by asking for the
details below, so we can investigate.  You might as well expedite
matters by sending them to begin with.

  Try to make your bug report self-contained.  If we ask you for more
information, it is best if you include all the original information in
your response, as well as the new information.  We might have discarded
the previous message, or even if we haven't, it takes us time to search
for it.  Similarly, if you've reported bugs before, it is still best to
send all the information; we can't possibly remember what environment
everyone uses!

* Menu:

* 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: fontu.info,  Node: Necessary information,  Next: Unnecessary information,  Up: Bug reporting

Necessary information
---------------------

  To enable us to fix a bug, please include all the information below.
If the bug was in compilation or installation, as opposed to in actually
running one of the programs, the last two items are irrelevant.  But in
that case, please also make sure it is not a known problem before
reporting it.  *Note Problems::.

  You should include all of the following in your bug report:

   * The version number of the program.  You can get this from the
     top-level files `ChangeLog' or `GNUmakefile.in', or from the
     `-version' option which all the programs have.

   * The type of machine you are using, and the operating system name
     and version number.

   * A description of the bug.  For example, "The program gets a fatal
     signal," or "The baselines in the generated font are too high."

   * All the command-line arguments you gave the program.

   * The relevant input files.  Since fonts and images are typically
     binary files, be sure to use `uuencode' or `btoa' before mailing
     them.  Be sure to include the TFM file as well as the bitmap (GF or
     PK) or BZR file, if the program needs both as input.

     Bugs typically apply to a single character in a font; you can find
     out what character is being processed with the `-verbose' option.
     It should then be straightforward to cut that single character out
     of the font with either the `-range' option and/or the
     `fontconvert' program, to make a new (very small) font.  It is
     easier for us to deal with small files.

     But if you don't want to take the time to break up the font,
     please send in the bug report anyway (with the entire font).  We
     much prefer that to you not reporting the bug at all!


  In other words, we need enough information so that we can run the
offending program under the debugger, so we can find out what's
happening.  Without all the command-line arguments, or the input file in
question, we cannot do this.  Since you must have found the bug by
running the program with a particular set of options and on a particular
input file, you already have this information; all you need to do is
send it!


File: fontu.info,  Node: Unnecessary information,  Next: Documentation bugs,  Prev: Necessary information,  Up: Bug reporting

Unnecessary information
-----------------------

  Here are some things that are not necessary to include in a bug
report.

   * A description of the envelope of the bug.

     Often people who encounter a bug spend a lot of time investigating
     which changes to the input file or command-line options will make
     the bug go away and which changes will not affect it.

     This is often time consuming and not very useful, because the way
     we will find the bug is by running a single example under the
     debugger with breakpoints, not by pure deduction from a series of
     examples.  You might as well save your time for something else.

   * A patch for the bug.

     A patch for the bug is useful if it is a good one.  But don't omit
     the necessary information, such as the test case, on the
     assumption that a patch is all we need.  We might see problems
     with your patch and decide to fix the problem another way, or we
     might not understand the patch at all.  Without an example, we
     won't be able to verify that the bug is fixed.

     Also, if we can't understand what bug you are trying to fix, or
     why your patch should be an improvement, we won't install it.  A
     test case will help us to understand.

     *Note Sending Patches for GNU CC: (gcc)Sending Patches, for more
     details on the best way to write changes.

   * Sometimes people send just a backtrace, but that is not useful by
     itself.  It is usually the values of local or global variables
     which matter, sometimes very far away from the location where you
     noticed the bug.  We need to be able to run the debugger ourselves
     to investigate.

   * A guess about what the bug is or what it depends on.

     Such guesses are not useful, and often wrong.  It is impossible to
     guess correctly without using the debugger to find the facts, so
     you might as well save your imagination for other things!



File: fontu.info,  Node: Documentation bugs,  Prev: Unnecessary information,  Up: Bug reporting

Documentation bugs
------------------

  It is just as important to report bugs in the documentation as in the
programs.  If you want to do something using these programs, and reading
the manual doesn't tell you how, that is probably a bug.  In fact, the
best way to report it is something like: "I want to do X; I looked in
the manual in sections A and B, but they didn't explain it."

  If your bug report makes it clear that you've actually made an attempt
to find the answers using the manual, we will be much more likely to
take action (since we won't have to search the manual ourselves).


File: fontu.info,  Node: File formats,  Next: Imageto,  Prev: Bugs,  Up: Top

File formats
************

  These programs use various data files to specify font encodings,
auxliary information for a font, and other things.  Some of these data
files are distributed in the directory `data'; others must be
constructed on a font-by-font basis.

  If the environment variable `FONTUTIL_LIB' is set, data files are
looked up along the path it specifies, using the same algorithm as is
used for font searching (*note Font searching::).  Otherwise, the
default path is set in the top-level Makefile.

  The following sections (in other chapters of the manual) also describe
file formats:

   * *Note BZR files::.

   * *Note CCC files::.

   * *Note CMI files::.

   * *Note IFI files::.


* Menu:

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


File: fontu.info,  Node: File format abbreviations,  Next: Common file syntax,  Up: File formats

File format abbreviations
=========================

  For the sake of brevity, we do not spell out every abbreviation
(typically of file format names) in the manual every time we use it.
This section collects and defines all the common abbreviations we use.

BPL
     The `Bezier property list' format output by BZRto and read by
     BPLtoBZR.  This is a transliteration of the binary BZR format into
     human-readable (and -editable) text.  *Note BPL files::.

BZR
     The `Bezier' outline format output by Limn and read by BZRto.  We
     invented this format ourselves.  *Note BZR files::.

CCC
     The `cookie-cutter character' (er, `composite character
     construction') files read by BZRto to add pre-accented and other
     such characters to a font.  *Note CCC files::.

CMI
     The `character metric information' files read by Charspace to add
     side bearings to a font.  *Note CMI files::.

GF
     The `generic font' bitmap format output by Metafont (and by most of
     these programs).  See the sources for Metafont or one of the other
     TeX font utility programs (GFtoPK, etc.) for the definition.

DVI
     The `device independent' format output by TeX, GFtoDVI, etc.  Many
     "DVI driver" programs have been written to translate DVI format to
     something that can actually be printed or previewed.  See sources
     for TeX or DVItype for the definition.

EPS
     The `Encapsulated PostScript' format output by many programs,
     including Imageto (*note Viewing an image::) and Fontconvert
     (*note Fontconvert output options::).  An EPS file differs from a
     plain PostScript file in that it contains information about the
     PostScript image it produces: its bounding box, for example.
     (This information is contained in comments, since PostScript has
     no good way to express such information directly.)

IFI
     The `image font information' files read by Imageto when making a
     font from an image.  *Note IFI files::.

GSF
     The `Ghostscript font' format output by BZRto and the `bdftops'
     program in the Ghostscript distribution.  This is nothing more
     than the Adobe Type 1 font format, unencrypted.  The Adobe Type 1
     format is defined in a book published by Adobe.  (Many PostScript
     interpreters cannot read unencrypted Type 1 fonts, despite the
     fact that the definition says encryption is not required.
     Ghostscript can read both encrypted and unencrypted Type 1 fonts.)

IMG
     The `image' format used by some GEM (a window system sometimes used
     under DOS) programs; specifically, by the program which drives our
     scanner.

MF
     The `Meta-Font' programming language for designing typefaces
     invented by Donald Knuth.  His `Metafontbook' is the only manual
     written to date (that we know of).

PBM
     The `portable bitmap' format used by the PBMplus programs,
     Ghostscript, Imageto, etc.  It was invented by Jef Poskanzer (we
     believe), the author of PBMplus.

PFA
     The `printer font ASCII' format in which Type 1 PostScript fonts
     are sometimes distributed.  This format uses the ASCII hexadecimal
     characters `0' to `9' and `a' to `f' (and/or `A' to `F') to
     represent an `eexec'-encrypted Type 1 font.

PFB
     The `printer font binary' format in which Type 1 PostScript fonts
     are sometimes distributed.  This format is most commonly used on
     DOS systems.  (Personally, we find the existence of this format
     truly despicable, as one of the major advantages of PostScript is
     its being defined entirely in terms of plain text files (in Level
     1 PostScript, anyway).  Having an unportable binary font format
     completely defeats this.)

PK
     The `packed font' bitmap format output by GFtoPK.  PK format has
     (for all practical purposes) the same information as GF format,
     and does a better job of packing: typically a font in PK format
     will be one-half to two-thirds of the size of the same font in GF
     format.  It was invented by Tom Rokicki as part of the TeX
     project.  See the GFtoPK source for the definition.

PL
     The `property list' format output by TFtoPL.  This is a
     transliteration of the binary TFM format into human-readable (and
     -editable) text.  Some of these programs output a PL file and call
     PLtoTF to make a TFM from it.  (For technical reasons it is easier
     to do this than to output a TFM file directly.)  See the PLtoTF
     source for the details.

TFM
     The `TeX font metric' format output by Metafont, PLtoTF, and other
     programs, and read by TeX.  TFM files include only character
     dimension information (widths, heights, depths, and italic
     corrections), kerns, ligatures, and font parameters; in
     particular, there is no information about the character shapes.
     See the TeX or Metafont source for the definition.


File: fontu.info,  Node: Common file syntax,  Next: Encoding files,  Prev: File format abbreviations,  Up: File formats

Common file syntax
==================

  Data files read by these programs are text files that share certain
syntax elements:

   * Comments begin with a `%' character and continue to the end of the
     line.  The content of comments is entirely ignored.

   * Blank lines are allowed, and ignored.  Whitespace characters (as
     defined by the C facility `isspace') are ignored at the beginning
     of a line.

   * Any character except ASCII NUL--character zero--is acceptable in
     data files.  (We would allow NULs, too, at the expense of
     complicating the code, if we knew of any useful purpose for them.)


  A line can be as long as you want.


File: fontu.info,  Node: Encoding files,  Next: Coding scheme map file,  Prev: Common file syntax,  Up: File formats

Encoding files
==============

  The "encoding" of a font specifies the mapping from character codes
(an integer, typically between zero and 255) to the characters
themselves; e.g., does a character with code 92 wind up printing as a
backslash (as it does under the ASCII encoding) or as a double left
quote (as it does under the most common TeX font encoding)?  Put
another way, the encoding is the arrangement of the characters in the
font.

  It is sad but true that no single encoding has been widely adopted,
even for basic text fonts.  (Text fonts and, say, math fonts or symbol
fonts will clearly have different encodings.)  Every typesetting program
and/or font source seems to come up with a new encoding; GNU is no
exception (see below).  Therefore, when you decide on the encoding for
the fonts you create, you should choose whatever is most convenient for
the typesetting programs you intend to run it with.  (Decent typesetting
systems would make it trivial to set font encodings; unfortunately,
almost nothing is decent in that regard!)

  The "encoding file" format we invented is a font-format-independent
representation of an encoding.  Encoding files are "data files" which
have the basic syntax elements described above (*note Common file
syntax::).  They are usually named with the extension `.enc'.

  The first nonblank non-comment line in an encoding file is a string to
put into TFM files as the "coding scheme" to describe the encoding;
some common coding schemes are `TeX text', `TeX math symbol', `Adobe
standard'.  Case is irrelevant; that is, any programs which use the
coding scheme should pay no attention to its case.

  Thereafter, each nonblank non-comment line defines the character for
the corresponding code: the first such line defines the character with
code zero, the next with code one, and so on.

  Each character consists of a name, optionally followed by ligature
information.  (All fonts using the same encoding should have the same
ligatures, it seems to us.)

* Menu:

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


File: fontu.info,  Node: Character names,  Next: Ligature definitions,  Up: Encoding files

Character names
---------------

  The "character name" in an encoding file is an arbitrary sequence of
nonblank characters (except it can't include a `%', since that starts a
comment).  Conventionally, it consists of only lowercase letters,
except where an uppercase letter is actually involved.  (For example,
`eacute' is a lowercase `e' with an acute accent; `Eacute' is an
uppercase `E' with an acute accent.

  If a character code has no equivalent character in the font, i.e., the
font table has a "blank spot", you should use the name `.notdef' for
that code.  This is the only name you can usefully give more than once.
If any other name is used more than once, the results are undefined.

  To avoid unnecessary proliferation of character names, you should use
names from existing `.enc' files where possible.  All the `.enc' files
we have created are distributed in the `data' directory.


File: fontu.info,  Node: Ligature definitions,  Next: GNU encodings,  Prev: Character names,  Up: Encoding files

Ligature definitions
--------------------

  The ligature information for a character in an encoding file is
optional.  More than one ligature specification may be given.  Each
specification looks like:

     lig SECOND-CHAR =: LIG-CHAR

  This means that a ligature character LIG-CHAR should be present in
the font for the current character (the one being defined on this line
of the encoding file) followed by SECOND-CHAR.  You give SECOND-CHAR
and LIG-CHAR as character codes (*note Specifying character codes::).
For example, in most text encodings (which involve Latin characters),
some variation on the following line will be present:

     f       lig f =: 013  lig i =: 014  lig l =: 015

  This will produce a ligature in the font such that when a typesetting
program sees the two character sequence `ff' in the input, it replaces
those two characters in the output with the single character at
position octal 13 (presumably the `fi' ligature) of the font; when it
sees `fi', the character at position octal 14 is output; when it sees
`fl', the character at position octal 15 is output.

  Metafont version 2 allows a more general ligature scheme; if there is
a demand for it, it wouldn't be hard to add.


File: fontu.info,  Node: GNU encodings,  Prev: Ligature definitions,  Up: Encoding files

GNU encodings
-------------

  When we started making fonts for the GNU project, we had to decide on
some font encoding.  We hoped to use an existing one, but none that we
found seemed suitable: the TeX font encodings, including the "Cork
encoding" described in TUGboat 11#4, lacked many standard PostScript
characters; conversely, the standard PostScript encodings lacked useful
TeX characters.  Since we knew that Ghostscript and TeX would be the
two main applications using the fonts, we thought it unacceptable to
favor one at the expense of the other.

  Therefore, we invented two new encodings.  The first one, "GNU Latin
text" (distributed in `data/gnulatin.enc'), is based on ISO Latin 1,
and is close to a superset of both the basic TeX text encoding and the
Adobe standard text encoding.  We felt it was best to use ISO Latin 1
as the foundation, since some existing systems actually use ISO Latin 1
instead of ASCII.  We also left the first eight positions open, so
particular fonts could add more ligatures or other unusual characters.

  The second, "GNU Latin text complement" (distributed in
`data/gnulcomp.enc'), includes the remaining pre-accented characters
from the Cork encoding, the PostScript expert encoding, swash
characters, small caps, etc.


File: fontu.info,  Node: Coding scheme map file,  Prev: Encoding files,  Up: File formats

Coding scheme map file
======================

  When a program reads a TFM file, it's given an arbitrary string (at
best) for the coding scheme.  To be useful, it needs to find the
corresponding encoding file.  We couldn't think of any way to name our
`.enc' files that would allow the filename to be guessed automatically.
Therefore, we invented another data file which maps the TFM coding
scheme strings to our `.enc' filenames.

  This file is distributed as `data/encoding.map'.  *Note Common file
syntax::, for a description of the common syntax elements.

  Each nonblank non-comment line in `encoding.map' has two entries: the
first word (contiguous nonblank characters) is the `.enc' filename; the
rest of the line, after ignoring whitespace, is the string in the TFM
file.  This should be the same string that appears on the first line of
the `.enc' file (*note Encoding files::).

  Programs should ignore case when using the coding scheme string.

  Here is the coding scheme map file we distribute:

     adobestd 	Adobe standard
     ascii		ASCII
     dvips		dvips
     dvips		TeX text + adobestandardencoding
     gnulatin	GNU Latin text
     gnulcomp 	GNU Latin text complement
     psymbol 	PostScript Symbol
     texlatin	Extended TeX Latin
     textext		TeX text
     zdingbat	Zapf Dingbats


File: fontu.info,  Node: Imageto,  Next: IMGrotate,  Prev: File formats,  Up: Top

Imageto
*******

  Imageto converts an image file (currently either in portable bitmap
format (PBM) or GEM's IMG format) to either a bitmap font or an
Encapsulated PostScript file (EPSF).  An "image file" is simply a large
bitmap.

  If the output is a font, it can be constructed either by outputting a
constant number of scanlines from the image as each "character" or
(more usually) by extracting the "real" characters from the image.

  The current selection of input formats is rather arbitrary.  We
implemented the IMG format because that is what our scanner outputs, and
the PBM format because Ghostscript can output it (*note GSrenderfont::).
Other formats could easily be added.

* Menu:

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


File: fontu.info,  Node: Imageto usage,  Next: IFI files,  Up: Imageto

Imageto usage
=============

  Usually there are two prerequisites to extracting a usable font from
an image file.  First, looking at the image, so you can see what you've
got.  Second, preparing the IFI file describing the contents of the
image: the character codes to output, any baseline adjustment (as for,
e.g., `j'), and how many pieces each character has.  Each is a separate
invocation of Imageto; the first time with either the `-strips' or
`-epsf' option, the second time with neither.

  In the second step, Imageto considers the input image as a series of
"image rows".  Each image row consists of all the scanlines between a
nonblank scanline and the next entirely blank scanline.  (A "scanline"
is a single horizontal row of pixels in the image.)  Within each image
row, Imageto looks top-to-bottom, left-to-right, for "bounding boxes":
closed contours, i.e., an area whose edge you can trace with a pencil
without lifting it.

  For example, in the following image Imageto would find two image rows,
the first from scanlines 1 to scanline 7, the second consisting of only
scanline 10.  There are six bounding boxes in the first image row, only
one in the second.  (This example also shows some typical problems in
scanned images: the baseline of the `m' is not aligned with those of
the `i', `j', and `l'; a meaningless black line is present; the `i' and
`j' overlap.)

       01234567890123456789
      0
      1       x
      2 x x   x
      3       x
      4 x x   x   xxxxx
      5 x x   x   x x x
      6   x       x x x
      7 xx
      8
      9
     10 xxxxxxxxxxxxxxx

* Menu:

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


File: fontu.info,  Node: Viewing an image,  Next: Image to font conversion,  Up: Imageto usage

Viewing an image
----------------

  Typically, the first step in extracting a font from an image is to see
exactly what is in the image.  (Clearly, this is unnecessary if you
already know what your image file contains.)

  The simplest way to get a look at the image file, if you have
Ghostscript or some other suitable PostScript interpreter, is to convert
the image file into an EPSF file with the `-epsf' option.  Here is a
possible invocation:

     imageto -epsf ggmr.img

  Here we read an input file `ggmr.img'; the output is `ggmr.eps'.  You
can then view the EPS file with

     gs ggmr.eps

(presuming that `gs' invokes your PostScript interpreter).

  If you don't have both a suitable PostScript interpreter and enough
disk space to store the EPS file (it uses approximately twice as much
disk space as the original image), the above won't work.  Instead, to
view the image you must make a font with the `-strips' option:

     imageto -strips ggmr.img

  The output of this will be `ggmrsp.1200gf' (our image having a
resolution of 1200 dpi).  Although the GF font cannot be conveniently
viewed directly, you can use TeX and your favorite DVI processor to
look at it, as follows:

     fontconvert -tfm ggmrsp.1200
     echo ggmrsp | tex strips

  This outputs in `strips.dvi', which you can view with your favorite
DVI driver.  (*Note Archives::, for how to obtain the DVI drivers for
PostScript and X we recommend.)

  `strips.tex' is distributed in the `imageto' directory.


File: fontu.info,  Node: Image to font conversion,  Next: Dirty images,  Prev: Viewing an image,  Up: Imageto usage

Image to font conversion
------------------------

  Once you can see what is in the image, the next step is to prepare the
IFI file (*note IFI files::) corresponding to its characters.  Imageto
relies completely on the IFI files to describe the image; it makes no
attempt at optical character recognition, i.e., guessing what the
characters are from their shapes.

  You must also decide on a few more aspects of the output font, which
you specify with options:

   * The _design size_, which you specify with the `-designsize'
     option.  The default is 10pt.  Even if you know the true design
     size of the original scanned image, you may wish to change it.  For
     example, some of our original specimens were stated to be 30pt,
     but that resulted in the 10pt size being too small to our
     (20th-century) eyes.  So we specified a design size of 26pt.

   * The _baselines_, which you specify with the `-baselines' option.
     You can specify the baseline for each image row (the bottom
     scanline of each image row is numbered zero, with coordinates
     increasing upward).  You can make an adjustment for individual
     characters in the IFI files, but you save yourself at least some
     of this hassle by specifying a general baseline for each row.

     For instance, in the example image in *Note Imageto usage::, it
     would be best to specify `-baselines=2,0'.  The `2' is scanline #5
     in that image.  The `0' is an arbitrary value for scanline #10,
     which we will ignore via the IFI file (*note IFI files::).

     For each character written, the `-print-guidelines' option produces
     output on the terminal that looks like:
          75 (K) 5/315

     This means that character code 75, whose name in the encoding file
     is `K', has its bottom row at row 5, and its top row at row 315;
     i.e., the character has five blank rows above the origin.  This is
     almost certainly wrong (the letter `K' should sit on the
     typesetting baseline), so we would want to adjust it downwards to 0
     via the individual character adjustment (*note IFI files::).


  The final invocation to produce the font might look something like
this:

     imageto -baselines=121,130,120 -designsize=26 ggmr

  The output from this would be `ggmr26.1200gf'.


File: fontu.info,  Node: Dirty images,  Prev: Image to font conversion,  Up: Imageto usage

Dirty images
------------

  Your image may not be completely "clean", i.e., the scanning process
may have introduced artifacts: black lines at the edge of the paper;
blotches where the original had a speck of dirt or ink; broken lines
where the image had a continuous line.  To get a correct output font,
you must correct these problems.

  To remove blotches, you can simply put `.notdef' in the appropriate
place in the IFI file.  You can find the "appropriate place" when you
look at the output font; some character will be nothing but a (possibly
tiny) speck, and all the characters following will be in the wrong
position.

  The `-print-clean-info' option might also help you to diagnose which
bounding boxes are being assigned to which characters, when you are in
doubt.  Here is an example of its output:

     [Cleaning 149x383 bitmap:
       checking (0,99)-(10,152) ... clearing.
       checking (0,203)-(35,263) ... clearing.
       checking (0,99)-(130,382) ... keeping.
       checking (113,0)-(149,37) ... keeping.
     106]

The final `106' is the character code output (ASCII `j').  The size of
the overall bitmap which contains the `j' is 149 pixels wide and 383
pixels high.  The bitmap contained four bounding boxes, the last two of
which belonged to the `j' and were kept, and the first two from the
adjacent character (`i') and were erased.  (As shown in the example
image above, the tail of the `j' often overlaps the `i' in type
specimens.)

  If the image has blobs you have not removed with `.notdef', you will
see a small bounding box in this output.  The numbers shown are in
"bitmap coordinates": (0,0) is the upper left-hand pixel of the bitmap.

  If a blotch appears outside of the row of characters, Imageto will
consider it to be its own (very small) image row.  If you are using
`-baselines', you must specify an arbitrary value corresponding to the
blotch, even though the bounding box in the image will be ignored.  See
the section above for an example.


File: fontu.info,  Node: IFI files,  Next: Invoking Imageto,  Prev: Imageto usage,  Up: Imageto

IFI files
=========

  An "image font information" (IFI) file is a text file which describes
the contents of an image file.  You yourself must create it; as we will
see, the information it contains usually cannot be determined
automatically.

  If your image file is named `FOO.img' (or `FOO.pbm'), it is customary
to name the corresponding IFI file `FOO.ifi'.  That is what Imageto
looks for by default.  If you name it something else, you must specify
the name with the `-ifi-file' option.

  Imageto does not look for an IFI file if either the `-strips' or
`-epsf' options were specified.

  Each nonblank non-comment line in the IFI file represents a a sequence
of bounding boxes in the image, and a corresponding character in the
output font.  *Note Common file syntax::, for a description of syntax
elements common to all data files processed by these programs, including
comments.

  Each line has one to five "entries", separated by spaces and/or tabs.
If a line contains fewer than five entries, suitable defaults (as
described below) are taken for the missing trailing entries.  (It is
impossible to supply a value for entry #3, say, without also supplying
values for entries #1 and #2.)

  Here is the meaning of each entry, in order:

  1. The character name of the output character.  Usually, Imageto
     outputs the bounding boxes from the image as a character in the
     output font, assigning it the character code of the name as
     defined in the encoding vector (*note Invoking Imageto::).
     However, if the character name is `.notdef', or if the character
     name is not specified in the encoding, Imageto just throws away
     the bounding boxes.  *Note Encoding files::, for general
     information on encoding files.

  2. An adjustment to the baseline of the output character, as a
     (possibly signed) decimal number.  The default baseline is either
     the bottom scanline of the image row, or the value you specified
     with the `-baselines' option.  The number given here, in the IFI
     file, is subtracted from that default.  Thus, a positive
     adjustment moves the baseline up (i.e., moves the character down
     relative to the typesetting baseline), a negative one down.  The
     default adjustment is zero.

  3. The number of bounding boxes which comprise this character, as a
     decimal number.  The default is one.  If this number is negative,
     it indicates that the bounding boxes for this character are not
     consecutive in the image; instead, they alternate with the
     following character.  For example, the tail of an italic `j' might
     protrude to the left of the `i'; then Imageto will find the tail
     of the `j' first (so it should come first in the IFI file), but it
     will find the dot of the `i' next.  In this case, the bounding box
     count for both the `i' and the `j' should be `-2'.

  4. The left side bearing (lsb).  Most type specimens unfortunately
     don't include side bearing information, but if you happen to have
     such, you can give it here.  (GSrenderfont (*note GSrenderfont::)
     uses this feature).  The default is zero.

     You can run Charspace (*note Charspace::) to add side bearings to
     a font semi-automatically.  This is usually less work than trying
     to guess at numbers here.

  5. The right side bearing.  As with the lsb, the default is zero.


  Here is a possible IFI file for the image in *Note Imageto usage::.
We throw away the black line that is the second image row.  (Imagine
that it is a scanner artifact.)

     % IFI file for example image.
     i 0 2
     j 0 2
     l
     m 1
     .notdef % Ignore the black line at the bottom.


File: fontu.info,  Node: Invoking Imageto,  Prev: IFI files,  Up: Imageto

Invoking Imageto
================

  This section describes the options that Imageto accepts.  *Note
Command-line options::, for general option syntax.

  The main input filename (*note Main input file::) is called
IMAGE-NAME below.

`-baselines SCANLINE1,SCANLINE2,...'
     Define the baselines for each image row.  The default baseline for
     the characters in the first image row is taken to be SCANLINE1,
     etc.  The SCANLINEs are _not_ cumulative: the top scanline in each
     image row is numbered zero.

`-designsize REAL'
     Set the design size of the output font to REAL; default is 10.0.

`-dpi UNSIGNED'
     The resolution of the input image, in pixels per inch (required
     for PBM input).  *Note Common options::.

`-encoding ENC-FILE'
     The encoding file to read for the mapping between character names
     and character codes.  *Note Encoding files::.  If ENC-FILE has no
     suffix, `.enc' is appended.  Default is to assign successive
     character codes to the character names in the IFI file.

`-epsf'
     Write the image to `IMAGE-NAME.eps' as an Encapsulated PostScript
     file.

`-help'
     Print a usage message.  *Note Common options::.

`-ifi-file FILENAME'
     Set the name of the IFI file to FILENAME (if FILENAME has an
     extension) or `FILENAME.ifi' (if it doesn't).  The default is
     `IMAGE-NAME.ifi'.

`-input-format FORMAT'
     Specify the format of the input image; FORMAT must be one of `pbm'
     or `img'.  The default is taken from IMAGE-NAME, if possible.

`-nchars UNSIGNED'
     Only write the first UNSIGNED (approximately) characters from the
     image to the output font; default is all the characters.

`-output-file FILENAME'
     Write to FILENAME if FILENAME has a suffix.  If it doesn't, then
     if writing strips, write to FILENAMEsp.DPIgf; else write to
     `FILENAME.DPIgf'.  By default, use `IMAGE-NAME DESIGNSIZE' for
     FILENAME.

`-print-clean-info'
     Print the size of each bounding box considered for removal, and
     the size of the containing bitmaps.  This option implies
     `-verbose'.  *Note Dirty images::, for a full explanation of its
     output.

`-print-guidelines'
     Print the numbers of the top and bottom scanlines for each
     character.  This implies `verbose'.  *Note Image to font
     conversion::, for a full explanation of its output.

`-range CHAR1-CHAR2'
     Only output characters with codes between CHAR1 and CHAR2,
     inclusive.  (*Note Common options::, and *Note Specifying
     character codes::.)

`-strips'
     Take a constant number of scanlines from the image as each
     character in the output font, instead of using an IFI file to
     analyze the image.

`-trace-scanlines'
     Show every scanline as we read it as plain text, using `*' and
     space characters.  This is still another way to view the image
     (*note Viewing an image::), but the result takes an enormous
     amount of disk space (over eight times as much as the original
     image) and is quite difficult to look at (because it's so big).
     To be useful at all, we start a giant XTerm window with the
     smallest possible font and look at the resulting file in Emacs.
     This option is primarily for debugging.

`-verbose'
     Output progress reports.  *Note Common options::.  Specifically, a
     `.' is output for every 100 scanlines read, a `+' is output when
     an image row does not end on a character boundary, and the
     character code is output inside brackets.

`-version'
     Print the version number.  *Note Common options::.


File: fontu.info,  Node: IMGrotate,  Next: Fontconvert,  Prev: Imageto,  Up: Top

IMGrotate
*********

  IMGrotate rotates an IMG file, either 90 or 180 degrees clockwise.  We
call the latter--somewhat inaccurately--a "flip".  (We haven't needed
other rotation angles, so we haven't implemented them.)

  The IMG format is an image format output by a few programs, including
the one that drives the scanner we have.  (Again, we haven't needed
other image formats, so we haven't implemented them.)

  Both the input and output are IMG files.

  The current implementation of IMGrotate uses an extremely slow and
stupid algorithm, because it was a quick hack.  It would be useful to
replace it with a better algorithm.  *Note Program features::, for a
reference.

* Menu:

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


File: fontu.info,  Node: IMGrotate usage,  Next: Invoking IMGrotate,  Up: IMGrotate

IMGrotate usage
===============

  The physical construction of a source to be scanned may make it hard
or impossible to end up with an upright image.  But the task of
extracting characters from an image is complicated by allowing for a
rotated image.  Hence this program to turn rotated images upright.

  By default, the name of the output file is the same as the input file;
both are extended with `.img' if necessary.  If this would result in
the output overwriting the input, `x' is prepended to the output name.

* Menu:

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


File: fontu.info,  Node: Clockwise rotation,  Next: Flip rotation,  Up: IMGrotate usage

Clockwise rotation
------------------

  You specify clockwise rotation of an image with the option
`-rotate-clockwise'.  This rotates the input 90 degrees clockwise.  For
example, the following (an `h' on its side):

           *****
          *
          *
     ***********

turns upright.


File: fontu.info,  Node: Flip rotation,  Prev: Clockwise rotation,  Up: IMGrotate usage

Flip rotation
-------------

  You specify "flip" rotation of an image with the option `-flip'.
This flips the input end for end and reverses left and right, i.e., does
a 180 degree rotation.  For example, the following (an `h' upside down
and backwards):

       *  *
       *  *
       *  *
        ***
          *
          *
          *

turns upright.


File: fontu.info,  Node: Invoking IMGrotate,  Prev: IMGrotate usage,  Up: IMGrotate

Invoking IMGrotate
==================

  This section describes the options that IMGrotate accepts.  *Note
Command-line options::, for general option syntax.

  The name of the main input file (*note Main input file::) is called
IMAGE-NAME below.

`-flip'
     Rotate the input 180 degrees, i.e., flip it end for end and left to
     right.  *Note Flip rotation::.

`-help'
     Print a usage message.  *Note Common options::.

`-output-file FILENAME'
     Write to FILENAME if FILENAME has a suffix.  If it doesn't, write
     to `FILENAME.img', unless that would overwrite the input, in which
     case write to `xFILENAME.img'.  By default, use IMAGE-NAME for
     FILENAME.

`-rotate-clockwise'
     Rotate the input 90 degrees clockwise.  *Note Clockwise rotation::.

`-verbose'
     Output progress reports.  *Note Common options::.

`-version'
     Print the version number.  *Note Common options::.


File: fontu.info,  Node: Fontconvert,  Next: Charspace,  Prev: IMGrotate,  Up: Top

Fontconvert
***********

  Fontconvert performs manipulations on bitmap fonts: conversion to
other formats, merging multiple fonts, adjusting individual characters,
moving characters around within a font, ...

  The input is either a GF or a PK bitmap font, and in some
circumstances, a TFM file.  (*Note File format abbreviations::.)  The
output varies according to the options specified.

* Menu:

* Invoking Fontconvert::        Command-line options.


File: fontu.info,  Node: Invoking Fontconvert,  Up: Fontconvert

Invoking Fontconvert
====================

  In the following sections we describe all the options Fontconvert
accepts, grouped according to general function.

* Menu:

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


File: fontu.info,  Node: Fontconvert output options,  Next: Character selection options,  Up: Invoking Fontconvert

Fontconvert output options
--------------------------

  The following table describes the options which affect the output
file(s) Fontconvert writes.  You can specify as many as you like.  If
you don't specify any, the default is to write nothing at all.

  In the following, FONT-NAME stands for the root part of the main
input file (*note Main input file::).  The output filenames here are the
defaults; you can override them with the `-output-file' option (*note
Miscellaneous options::).

`-epsf'
     Output each character as an Encapsulated PostScript (EPS) file
     named `FONT-NAME-CODE.eps', where CODE is the character code (in
     decimal).  This may be useful if the input "font" is actually a
     collection of images.

`-gf'
     Output a GF font `FONT-NAME.DPIgf', where DPI is the resolution of
     the input font in dots per inch.  If this would overwrite the
     input file (presumably because it, too, is a GF font), then
     prepend `x' to the output name.

     This is mainly useful in conjunction with options that change the
     characters in the input font in some way.

`-text'
     Write the output in a human-readable plain text form to standard
     output.  The bitmap for each character is shown using `*' and ` '.
     This is an easy way to see what output is being generated, without
     going to the trouble of running TeX and a DVI driver.  (The
     standard TeX programs GFtype and PKtype, which serve a similar
     purpose, do not always write the entire bitmap.)

`-tfm'
     Write a TFM file to `FONT-NAME.tfm'.  If a TFM file
     `FONT-NAME.tfm' can be found, it is read, and an `x' is prepended
     to the output name.

     If an existing TFM file is found, then Fontconvert uses it (by
     default) for the TFM header information, and for the ligature and
     kern information.  Unless the `-baseline-adjust', `-column-split',
     filtering, or randomizing options were specified, Fontconvert also
     uses it for the character dimensions.  (Those options radically
     change the appearance and size of the characters, so using the
     dimensions of the originals would be inappropriate.)

     *Note Fontwide information options::, for how to specify the
     global TFM information yourself, overriding the default.

