@c Copyright (C) 1992 Free Software Foundation.
@c This is part of the GNU font utilities manual.
@c For copying conditions, see the file fontutil.texi.

@node XBfe, BZRedit, BPLtoBZR, Top
@chapter XBfe

@pindex xbfe
@cindex bitmap fonts, hand-editing
@cindex hand-editing bitmap fonts
@cindex editing bitmap fonts

XBfe (X Bitmap Font Editor) allows you to hand-edit a bitmap font---both
the shapes (i.e., the pixels) and the metric information (set widths,
side bearings, and kerning tables).

The input is both a bitmap (GF or PK) font and a corresponding TFM file.
If you have only a bitmap font for some reason, you can make a TFM file
with Fontconvert (@pxref{Fontconvert output options}).  XBfe outputs (at
your command) the edited files in the current directory @emph{with the
same name}, thus possibly replacing the input file.

XBfe is intended to edit existing fonts, not create new ones.  For
example, it does not provide a way to create new characters in a font.
(you can add characters to a font using Fontconvert, though;
@pxref{Character selection options}).  In terms of its interaction with
the other font utilities, it is most useful for making character shapes
more amenable to Limn's outline fitting (@pxref{Limn}).

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


@node XBfe usage, Invoking XBfe,  , XBfe
@section XBfe usage

@cindex XBfe usage
@cindex usage of XBfe

XBfe attempts to follow established user interface conventions for X
programs:

@itemize @bullet

@item
The location of the mouse determines where keyboard input goes.

@item
In general, it is the release of a mouse button, and not its being
pressed, that causes action.

@item
When you've finished typing a piece of information in one of the items
in the XBfe window, you must hit @key{RET} to cause action.

@findex AsciiText @r{widget}
@cindex key bindings @r{in XBfe}
@item
The text editing facilities for such information are the defaults for
the @code{AsciiText} widget, which is Emacs-like bindings.

@flindex .Xdefaults
@cindex XBfe resources, customizing
@cindex customizing XBfe resources
@item
You can customize the bindings of all actions described below, the fonts
used, window sizes, and so on, via your resource file @file{.Xdefaults}.
See the documentation in the file

@example
.../mit/doc/tutorials/resources.txt
@end example

@cindex class name of XBfe
@noindent in the X distribution if you aren't familiar with X resources.  The
class name is @code{XBfe}.  The font utilities distribution comes with
an application resource file @file{XBfe} (which must be installed for
the program to function properly); see that file for possibilities of
what you might change.

@end itemize

The sections below describe the specific operations XBfe provides.

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


@node Controlling XBfe , XBfe shape editing,  , XBfe usage
@subsection Controlling XBfe 

This section describes a few operations which do not directly involve
editing, but rather managing of the editing session itself.

@cindex XBfe, exiting
@cindex exiting XBfe
To exit XBfe, click on the @samp{Exit} button.  Any changes made since
the last save are lost.

@cindex XBfe, saving changes
@cindex saving changes in XBfe
@vindex TMPDIR
@flindex /tmp
To save changes, click on the @samp{Save} button.  The new files are
written in the current directory---unless that would overwrite the input
files, in which case they are written to the directory @file{/tmp} (or
the value of the environment variable @code{TMPDIR}, if it's set).  When
you exit XBfe normally, the files are moved from the temporary directory
to your current directory, thus possibly overwriting the input.

@cindex XBfe, reverting characters
@cindex reverting characters in XBfe
@cindex undoing changes in XBfe
To go back to the last saved version of a character you are editing,
click on the @samp{Revert} button.  This is useful when you've made
changes you didn't intend.  If you exit without saving first, all
changes (since the last save) will be lost, as mentioned above.

@cindex XBfe, changing characters
@cindex changing characters in XBfe
@cindex moving between characters in XBfe
@cindex next character, finding in XBfe
@cindex previous character, finding in XBfe
You can move to the previous character in the font, i.e., the one with
the character code next smallest to the current one, by clicking on the
@samp{Prev} button.  Similarly, you can move to the next character by
clicking on the @samp{Next} button.  You can move to a specified
character by typing its character code in the @samp{Char} item and
hitting @key{RET}.  @xref{Specifying character codes}, for the various
possibilities for character codes.


@node XBfe shape editing, XBfe metrics editing, Controlling XBfe , XBfe usage
@subsection XBfe shape editing

@cindex shape editing
@cindex character bitmap hand-editing
@cindex editing character bitmaps
@cindex hand-editing character bitmaps

@cindex changing pixels
@cindex inverting pixels
@cindex pixels, changing
The most basic operation for editing character bitmaps is to change
black pixels to white or the reverse; put another way, inverting the
pixel the mouse is on.  You do this by clicking the third mouse button.

@cindex pen tracks
Technically, this is just a special case of changing more than one
pixel: when you press the third button, the current pixel inverts; then,
as you move the mouse, the pixels it touches change to the @emph{color
the first pixel changed to}.  Thus, if you press the third button on a
white pixel, the mouse effectively becomes a ``black pen'' (until you
release the button).

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


@node Selections, Enlarging the bitmap,  , XBfe shape editing
@subsubsection Selections

@cindex selection of rectangles in bitmaps
@cindex bitmaps, selecting rectangles from
XBfe supports selection, pasting, and filling operations on a
rectangle of pixels, as follows.

To select an arbitrary rectangle, press the left mouse button to
determine the first corner; then move the mouse (with the button still
down) to update the other corner of the rectangle; and release the
button to define the rectangle.  (If you release the button when the mouse
is off the character bitmap, the selection rectangle remains unchanged.)

@cindex pasting selections
@cindex selections, pasting
Once a rectangle has been selected, you can @dfn{paste} it, either
within the same character from which it was selected, or in a different
character.  To do this, press the middle button; this outlines the
region that will be changed; as you move the mouse (with the button
still down), the outline moves accordingly; when you release the
middle button, the selected rectangle is pasted onto the current bitmap,
erasing whatever was in the affected area.

@cindex pasting and flipping or rotating
@cindex flipping and pasting
@cindex rotation and flipping
Pasting has several variations: if you have the @kbd{Alt} (a.k.a.@:
Meta) key down when you release the middle button, the selection is
flipped vertically; if the @kbd{Control} key is down, the selection is
flipped horizontally; and if both are down, the selection is flipped in
both directions.  Here is a minimal example:

@example
@r{original}  @r{vertical}  @r{horizontal}  @r{both}
  **         *         **        *
   *        **         *         **
@end example

@cindex serifs, unifying
@cindex consistent serifs
@noindent This is useful when pasting serifs, since serifs are attached
to the main stems in different orientations.  (Incidentally,
making the serif shapes consist of exactly the same pixels may actually
make the serifs look different, because of surrounding character
features or the difference in orientation.  But it is still a good place
to start.)

@cindex filling rectangles in XBfe
@cindex erasing rectangles in XBfe
@cindex selections, filling in XBfe
@cindex selections, erasing in XBfe
@cindex rectangles, filling in XBfe
@cindex rectangles, erasing in XBfe
You can also fill the selected rectangle, i.e., change it to entirely
black or white, by holding the @key{Alt} key down and pressing the right
mouse button.  The selection is filled with the color of the pixel the
mouse is on.  This is how you entirely erase a portion of the bitmap.


@node Enlarging the bitmap,  , Selections, XBfe shape editing
@subsubsection Enlarging the bitmap

@cindex enlarging bitmaps
@cindex bitmaps, enlarging

You can enlarge the bitmap on all four sides by clicking on the
@samp{Expand} button; i.e., this adds one blank row at the top and
bottom, and one blank column at the left and right.  This is useful when
you need to fill out a truncated curve, lengthen a stem or serif, etc.

XBfe correspondingly changes the side bearings and baseline position so
that the origin of the character does not change.  In other words, the
new row at the bottom is below the baseline, and the new columns are in
what was the side bearing space.  You can change the baselines with
Fontconvert (@pxref{Character manipulation options}, and the side
bearings with Charspace (@pxref{Charspace}).


@node XBfe metrics editing,  , XBfe shape editing, XBfe usage
@subsection XBfe metrics editing

@cindex character metrics, hand-editing
@cindex metrics, hand-editing
@cindex hand-editing character metrics
@cindex editing character metrics

@cindex side bearings, hand-editing
@cindex hand-editing side bearings
@cindex editing side bearings
You can change the left side bearing for the current character by typing
the new value in the @samp{lsb} item (and hitting @key{RET}, as always
for information you type).  Likewise for the right side bearing and the
@samp{rsb} item.  The side bearing values must be integers.

@cindex kerns, hand-editing
@cindex hand-editing kerns
@cindex editing kerns
XBfe shows a box with any kerns for the current character.  Each item in
the kern box looks like @samp{@var{code}: @var{kern}}, where @var{code}
is the character code (in decimal) of the character kerned with, and
@var{kern} is the kern distance (in pixels).  You can edit the kern
distances just as with the side bearings; the values here are real
numbers.

@cindex adding kerns
@cindex kerns, adding
@cindex deleting kerns
@cindex kerns, deleting
You can add new kerns by typing the character code of the new
kerned-with character in the @samp{Add kern} item; then a kern item with
that code is added to the kern box, with a distance of zero (which you
can then change to whatever you want).  Similarly, you can delete a kern
by typing the character code in the @samp{Del kern} item.


@node Invoking XBfe,  , XBfe usage, XBfe
@section Invoking XBfe

@cindex XBfe options
@cindex invocation of XBfe
@cindex options for XBfe

This section describes the options that XBfe accepts.
@xref{Command-line options}, for general option syntax.

@table @samp

@opindex -dpi
@item -dpi @var{unsigned}
The resolution, in pixels per inch.  @xref{Common options}.

@opindex -expansion
@cindex pixel expansion
@cindex expansion pixel display
@cindex displaying pixels
@item -expansion @var{unsigned}
Expand each pixel in the character bitmaps to this many pixels
square on the display; default is 12, i.e., each pixel in the original
bitmap will become a 12 by 12 rectangle.

You can't use `=' here to separate the option name and value.

@flindex .Xdefaults
@cindex resources for X
@cindex X resources
@vindex expansion @r{resource}
You can also set this value by setting the resource @samp{expansion} in
@file{.Xdefaults}.

@opindex -initial-char
@cindex first character displayed
@cindex initial character displayed
@cindex character displayed, first
@item -initial-char @var{charcode}
Initially display the character @var{charcode}; default is the first
character in the font, i.e., the one with the lowest character code.

@opindex -help
@item -help
Print a usage message.  @xref{Common options}.

@opindex -output-file
@item -output-file @var{filename}
Write the output to @file{@var{filename}.@var{dpi}gf} and
@file{@var{filename}.tfm}.  The default is to use the name of the main
input file for @var{filename}.

@opindex -version
@item -version
Print the version number.

@end table

@cindex X toolkit options
@cindex options, X toolkit
@opindex -display
@cindex X server, specifying
In addition to the above options, XBfe also accepts the standard X
toolkit options (and resources), such as @samp{-display} to specify the
X server to use.  See the documentation for any X program for a
description of these options.  Unlike the options above, you cannot use
@samp{--} to start X toolkit options, nor can you use @samp{=} to
separate option names and values; for example, neither @samp{--display
host:0} nor @samp{-display=host:0} are recognized.