path: root/support/mf2pt1/mf2pt1.texi

\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename mf2pt1.info
@settitle mf2pt1
@setchapternewpage off
@dircategory TeX
@direntry
* mf2pt1: (mf2pt1).   PostScript Type 1 fonts from Metafont source.
@end direntry
@finalout
@c %**end of header

@copying
Copyright @copyright{} 2005--2024 Scott Pakin

@sp 2

This program may be distributed and/or modified under the conditions
of the @LaTeX{} Project Public License, either version 1.3c of this
license or (at your option) any later version.

@sp 1

The latest version of this license is in:
@sp 1
@center @uref{https://www.latex-project.org/lppl.txt}
@sp 1
and version 1.3c or later is part of all distributions of @LaTeX{}
version 2006/05/20 or later.

@end copying

@set VERSION 2.8
@set DATE 6 July 2024

@c Define some fonts we intend to use.
@iftex
@tex
@global@font@tenlogo=logo10 % font used for the METAFONT logo
@global@font@eightrm=cmr8   % needed for the "A" in "LaTeX"
@end tex
@end iftex

@c Define a macro for the Metafont logo.
@iftex
@macro MF {}
@tex
@tenlogo @leavevmode@hbox{METAFONT}@unskip
@end tex
@end macro
@end iftex
@ifnottex
@macro MF {}
Metafont
@end macro
@end ifnottex

@macro copt {option}
@w{@code{--\option\}}
@end macro

@c %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

@iftex
@tex
% If we're using pdfTeX in PDF-generating mode then include some
% document metadata.
\ifx\pdfoutput\undefined
\else
  \ifx\pdfoutput\relax
  \else
    \ifcase\pdfoutput
    \else
      \pdfinfo {
        /Title    (mf2pt1)
        /Subject  (Produce PostScript Type 1 fonts from Metafont source)
        /Author   (Scott Pakin <scott+mf@@pakin.org>)
        /Keywords (PostScript Type 1 fonts, Metafont, MetaPost, FontForge)
      }
    \fi
  \fi
\fi
@end tex
@end iftex

@titlepage
@title mf2pt1
@subtitle Produce PostScript @w{Type 1} fonts from Metafont source
@author Scott Pakin, @email{scott+mf@@pakin.org}

@page

@vskip 0pt plus 2filll

This file documents @command{mf2pt1} version @value{VERSION}, dated
@value{DATE}.

@vskip 0pt plus 1filll

@insertcopying

@contents

@end titlepage

@ifnottex
@node Top, Introduction, (dir), (dir)
@top mf2pt1

@command{mf2pt1} is a tool that lets font designers design PostScript
@w{Type 1} fonts using the @MF{} language.  The same source file can be
used to produce both @w{Type 1} (@file{.pfb}) and bitmap (@file{.pk})
fonts.
@end ifnottex

@menu
* Introduction::                Introduction to mf2pt1
* Usage::                       How to use mf2pt1
* Future Work::                 Features I may one day add to mf2pt1
* Acknowledgments::             People who helped with mf2pt1
@end menu


@node Introduction, Usage, Top, Top
@chapter Introduction

@MF{} is a high-level, mathematically oriented language for producing
fonts.  The @MF{} interpreter produces device-dependent bitmaps, which
render well at the target resolution on the target device, but poorly
at other resolutions or on other devices.  Adobe's PostScript @w{Type 1}
font format is the de facto font standard for printers these days.  It
is a vector format, which implies that it scales better than bitmaps,
and it delegates the device- and resolution-dependent tweaking from
the font source to the target device's PostScript renderer.  However,
@w{Type 1} fonts are extremely difficult to code by hand.  Usually, one
uses a @acronym{WYSIWYG} program to design a @w{Type 1} font.  @MF{}, with
its font-specific programming language, is an elegant alternative.  A
font designer can write reusable subroutines for repeated features,
such as serifs and accents.  He can define a font in terms of
arbitrary parameters, such as ``boldness'' or ``italicness'', making
it trivial to produce entire families of fonts from a single source
(hence the ``meta'' in the name ``@MF{}'').  Ideally, we would like to
design a font using the @MF{} language, but produce PostScript @w{Type 1}
output instead of bitmaps.

@command{mf2pt1} helps bridge the gap between @MF{} and @w{Type 1} fonts.
@command{mf2pt1} facilitates producing PostScript @w{Type 1} fonts from a
@MF{} source file.  It is @emph{not}, as the name may imply, an
automatic converter of arbitrary @MF{} fonts to @w{Type 1} format.
@command{mf2pt1} imposes a number of restrictions on the @MF{} input.
If these restrictions are met, @command{mf2pt1} will produce valid
@w{Type 1} output.

@menu
* Requirements::                Pre-installation checklist
* Installation::                How to install mf2pt1
@end menu


@node Requirements, Installation, Introduction, Introduction
@section Requirements

Before using @command{mf2pt1}, you will need to install the following
programs:

@table @asis
@item Perl
@command{mf2pt1} is written in Perl.  You will need a Perl interpreter
to run it.

@item MetaPost
@command{mf2pt1} actually uses MetaPost, not @MF{}, to produce
PostScript output.  Specifically, you will need the @command{mpost}
executable and the @file{mfplain.mp} base file.

@item @w{Type 1} Utilities
Producing properly encoded @w{Type 1} fonts is tricky.
@command{mf2pt1} delegates the effort to the @w{Type 1} Utilities,
specifically, to the @command{t1asm} program within that suite.

@item FontForge (optional)
FontForge is a @acronym{WYSIWYG}, but scriptable, @w{Type 1}
font-editing program.  Although FontForge is not strictly required for
@command{mf2pt1} to produce a @w{Type 1} font, @command{mf2pt1} uses
FontForge when available to autohint the generated @w{Type 1} font,
thereby making it look better especially at lower resolutions.
@end table

Perl is available from @uref{https://www.cpan.org, the Comprehensive
Perl Archive Network}; MetaPost and the @w{Type 1} utilities are
available from @uref{https://www.ctan.org, the Comprehensive @TeX{}
Archive Network}; and FontForge is available from
@uref{https://fontforge.sourceforge.net/}.  In addition, MetaPost's
home page is @uref{https://tug.org/metapost.html}, and the @w{Type 1}
utilities' home page is @uref{https://www.lcdf.org/type/}.

Besides being useful for autohinting fonts, FontForge enables a font
designer to hint fonts manually for additional fine-tuning and to
convert among a variety of font formats, such as PostScript, TrueType,
and @w{X Window} fonts.  FontForge is strongly recommended as a
complement to @command{mf2pt1}.


@node Installation,  , Requirements, Introduction
@section Installation

To install @command{mf2pt1}, move the @file{mf2pt1} executable
someplace where your operating system can find it.  If you're running
Microsoft Windows, you should rename the program to @file{mf2pt1.pl},
so that Windows knows it's a Perl script.  (Alternatively, if you have
@command{pl2bat}, use that to produce a @file{mf2pt1.bat} file, which
you can run as simply @file{mf2pt1}.)

The next step is to produce a @file{mf2pt1.mem} file from the supplied
@file{mf2pt1.mp}.  The command to do this differs from system to
system but is usually something like the following:

@example
mpost -progname=mpost -ini mf2pt1 \\dump
@end example

Move the resulting @file{mf2pt1.mem} file someplace where MetaPost can
find it.

@sp 1

The @command{mf2pt1} documentation (what you're reading now) is written
in Texinfo and can therefore easily be converted to a variety of
formats:

@table @asis
@item PDF (@file{mf2pt1.pdf})
@example
texi2pdf mf2pt1.texi
@end example

@item PostScript (@file{mf2pt1.ps})
@example
texi2dvi mf2pt1.texi
dvips mf2pt1.dvi -o mf2pt1.ps
@end example

@item HTML (@file{mf2pt1.html})
@example
makeinfo --html mf2pt1.texi
@end example

@item Info (@file{mf2pt1.info})
@example
makeinfo mf2pt1.texi
@end example
@end table

@noindent
N.B@.  The @command{install-info} command is a convenient way to install
@file{mf2pt1.info} on your system.

@sp 1

On Unix, you may also want to generate an @command{mf2pt1} man page.
The man page is embedded within the @file{mf2pt1} Perl script and can be
extracted with @command{pod2man}:

@example
pod2man --center="User Commands" --date="@value{DATE}" \
  --release="v@value{VERSION}" mf2pt1 > mf2pt1.1
@end example

@noindent
You can then move @file{mf2pt1.1} into @file{/usr/man/man1} or any other
man page directory.  Note that the @command{mf2pt1} man page is fairly
rudimentary.  It is primarily a list of the command-line options
(@pxref{Font information}) and a pointer to the document that you're
reading now.


@node Usage, Future Work, Introduction, Top
@chapter Usage

@command{mf2pt1} is fairly straightforward to use.  To process a
@MF{} source file, merely specify the filename:

@example
mf2pt1 myfont.mf
@end example

@noindent
That simple command automatically performs all of the following
operations:

@enumerate
@item
Read @file{myfont.mf}.

@item
Use @command{mpost} to convert each character to a separate
Encapsulated PostScript (@acronym{EPS}) file named
@file{myfont.@var{num}}.

@item
Process and merge the @acronym{EPS} files into a single
``disassembled'' @w{Type 1} font called @file{myfont.pt1}.

@item
Run @command{t1asm} from the @w{Type 1} Utilities to convert the
disassembled font into a true, binary @w{Type 1} font called
@file{myfont.pfb}.

@item
Invoke @command{fontforge} to apply rendering hints to
@file{myfont.pfb} and to attempt to remove overlapping paths.
@end enumerate

The external programs launched by @command{mf2pt1}---@command{mpost},
@command{t1asm}, and @command{fontforge}---can be overridden by
setting the eponymous, uppercase environment variable.  For example,
invoking FontForge's predecessor, PfaEdit, instead of FontForge is
simply a matter of setting the @samp{FONTFORGE} environment variable
to @samp{pfaedit} before invoking @command{mf2pt1}.  As a corollary,
you can inhibit an @command{mf2pt1} external program from running by
setting the corresponding environment variable to the name of a
nonexistent program.  Arguments can be included in the environment
variable's value.  Hence, defining @samp{MPOST} to @samp{mpost
-recorder}, for instance, instructs @command{mf2pt1} to run
@command{mpost} with the @samp{-recorder} option.

@menu
* Restrictions::                Restrictions imposed on the font source code
* Font information::            Specifying PostScript font characteristics
* Additional command-line options::  Options unrelated to font characteristics
* Custom font encodings::       Altering the mapping from character name to number
* Restoring mfplain defaults::  Using the original (un)filldraw and pencircle
@end menu


@node Restrictions, Font information, Usage, Usage
@section Restrictions

If @command{mf2pt1} sounds too good to be true, it is---somewhat.
@command{mf2pt1} is not a general-purpose @MF{}-to-@w{Type 1}
converter.  Rather, it can convert only certain @MF{} constructs.
This is not a showstopper for new fonts designed with @command{mf2pt1}
in mind, but it is unlikely that @command{mf2pt1} will work on an
arbitrary @MF{} source file.

@command{mf2pt1}'s biggest restriction is that each glyph must be
drawn entirely from closed paths, using @MF{}'s @strong{fill} and
@strong{unfill} commands.  (@command{mf2pt1} has limited support for
@strong{draw} and @strong{undraw}, but their use is currently
discouraged.  @strong{filldraw} and @strong{unfilldraw} issue a
warning message and invoke @strong{draw} and @strong{undraw},
respectively.)  The @w{Type 1} format requires that these paths be
nonoverlapping.  The following are some of the alternatives for
removing path overlaps:

@enumerate
@item
Install FontForge.  As part of its final step in producing a @w{Type
1} font, @command{mf2pt1} instructs FontForge to replace overlapping
paths with nonoverlapping paths.

@item
Remove overlaps using @MF{} code within the font program itself.  A
@file{.zip} file attachment to
@uref{https://tug.org/pipermail/metapost/2005-January/000080.html,
a @w{6 January} 2005 article} by
@iftex
@tex
Bogus\l{}aw
@end tex
@end iftex
@ifnottex
Boguslaw
@end ifnottex
Jackowski on the MetaPost mailing list (subject: ``Re: all
intersections between two paths'') includes a MetaPost library which
assists with that task.  The library provides a @strong{find_outlines}
command which can be used to define a path as the union of two other
paths.  A number of MetaPost example programs are also included in the
@file{.zip} file.

@item
Design your fonts from the beginning without using overlapping paths.
@end enumerate

A secondary restriction is that @command{mf2pt1} redefines a number of
Plain @MF{} commands, such as @strong{beginchar}, @strong{fill}, and
@strong{unfill}.  @MF{} font programs which redefine or bypass these
(using @MF{} primitives) will not be convertible with
@command{mf2pt1}.

A far less severe restriction is due to @command{mf2pt1}'s utilizing
MetaPost's @MF{} interface instead of @MF{} itself.  The implication
is that commands not defined by MetaPost's @file{mfplain.mp} cannot be
handled by @command{mf2pt1}, either.  Very few fonts will have a
problem with this restriction but see the MetaPost manual for more
information.


@node Font information, Additional command-line options, Restrictions, Usage
@section Specifying font information

@iftex
@tex
@leavevmode
@end tex
@end iftex
@MF{} fonts normally specify a set of @strong{fontdimen}s which
provide information about a particular font that cannot otherwise be
inferred.  These include features such as the font's x-height, quad
width, interword stretchability and shrinkability, and other design
characteristics that @TeX{} makes use of.  PostScript fonts utilize a
largely different set of font parameters, such as the underline
position and thickness, font family name, and copyright notice.
@command{mf2pt1} provides @MF{} commands to define the PostScript font
parameters in the generated @w{Type 1} font.  These parameters should
appear in the @MF{} source file as follows:

@display
@b{if} known @i{ps_output}:
  @dots{}
@b{fi}
@end display

@noindent
@code{ps_output} is defined by @command{mf2pt1} but not by Plain
@MF{}.  Checking if it is known is the recommended way to determine if
the font is being built under @command{mf2pt1}.

@ifnottex
@menu
* Parameters::                  Font-information commands available to Metafont
* Command-line equivalents::    Specifying font features on the command line
* Default values::              Types and default values of each parameter
* Parameter example::           Metafont example which specifies all parameters
@end menu


@node Parameters, Command-line equivalents, Font information, Font information
@subsection Parameters
@end ifnottex

The following list presents all of the font-information commands
provided by @command{mf2pt1} and describes what each command means.
Commands marked with an asterisk are also defined by Plain @MF{} and
therefore do not need to be enveloped within a test for
@code{ps_output}.

@table @strong
@item font_coding_scheme
The mapping between character numbers and PostScript names.  If this
is the name of a file, @command{mf2pt1} expects it to contain
PostScript code defining a font-encoding vector.  @xref{Custom font
encodings}, for an example of such a file.  If
@strong{font_coding_scheme} is not the name of a file,
@command{mf2pt1} expects it to be one of the literal strings
@code{standard} (Adobe standard encoding), @code{isolatin1} (ISO Latin
1 encoding), @code{ot1} (@TeX{} 7-bit encoding), @code{t1} (@TeX{}
8-bit encoding), or @code{asis} (encoding integrated with the
character programs using the @strong{glyph_name} command as described
in @ref{Custom font encodings}).  Anything else will generate a
warning message and cause @command{mf2pt1} to use @code{standard}
instead.

@item font_comment
A textual comment that will appear within the generated font.  This is
often used for copyright notices.

@item font_family
The family that this font belongs to.  For example, ``Utopia Bold
Italic'' belongs to the @code{Utopia} family.

@item font_fixed_pitch
Whether the font is monospaced (if @strong{true}) or or proportionally
spaced (if @strong{false}).

@item font_identifier (*)
The full name of the font, e.g., @code{Utopia Bold Italic}.

@item font_name
The symbolic font name, used to load the font from a PostScript
document.  Spaces are forbidden.  Generally, the font name is of the
form @code{@var{family}-@var{modifiers}}.  For example, the font name
of Utopia Bold Italic would be @code{Utopia-BoldItalic}.

@item font_size (*)
The font design size.  This is specified in ``sharped'' units within
@MF{} code or as a point size on the command line.

@item font_slant (*)
When specified with @strong{font_slant}, the amount of slant per
point.  When specified with @copt{italicangle}, the angle in
counterclockwise degrees from the vertical (i.e., zero for an upright
font, negative for a right-slanting italic font).

@item font_underline_position
The vertical position at which an underline should lie, specified in
``sharped'' units within @MF{} code or as a number of points on the
command line.

@item font_underline_thickness
The thickness of an underline, specified in ``sharped'' units within
@MF{} code or as a number of points on the command line.

@item font_unique_id
The unique ID for this font.  The ID should be between 0 and
16,777,215, with the ``open'' range being 4,000,000-4,999,999.  All
IDs not in that range are allocated by contacting Adobe's UniqueID
Coordinator.  (I don't believe a fee is involved, but I don't know for
sure.)  If a unique ID is not specified, @command{mf2pt1} will not
write a unique ID to the file.  Note that Adobe no longer recommends
including unique IDs in fonts.

@item font_version
The version number of the font.  This should be of the form
@code{@var{MMM}.@var{mmm}}, where @var{MMM} is the major version
number and @var{mmm} is the minor version number.

@item font_weight
The font weight.  For example, the font weight of Utopia Bold Italic
is @code{Bold}.
@end table


@ifnottex
@node Command-line equivalents, Default values, Parameters, Font information
@subsection Command-line equivalents
@end ifnottex

Each of the
@iftex
preceding font-information commands
@end iftex
@ifnottex
font-information commands listed in @ref{Parameters}
@end ifnottex
has a command-line equivalent.  Their use is discouraged but they are
listed here for completeness:

@multitable {@strong{font_underline_thickness}} {@copt{fontversion}}
@item
@strong{font_coding_scheme}
@tab @copt{encoding}

@item
@strong{font_comment}
@tab @copt{comment}

@item
@strong{font_family}
@tab @copt{family}

@item
@strong{font_fixed_pitch}
@tab @copt{fixedpitch}

@item
@strong{font_identifier}
@tab @copt{fullname}

@item
@strong{font_name}
@tab @copt{name}

@item
@strong{font_size}
@tab @copt{designsize}

@item
@strong{font_slant}
@tab @copt{italicangle}

@item
@strong{font_underline_position}
@tab @copt{underpos}

@item
@strong{font_underline_thickness}
@tab @copt{underthick}

@item
@strong{font_unique_id}
@tab @copt{uniqueid}

@item
@strong{font_version}
@tab @copt{fontversion}

@item
@strong{font_weight}
@tab @copt{weight}
@end multitable

A special case is @copt{fixedpitch} which does not take an argument.
Rather, you should use @copt{fixedpitch} as the equivalent of
@samp{font_fixed_pitch true} and @copt{nofixedpitch} as the equivalent
of @samp{font_fixed_pitch false}.


@ifnottex
@node Default values, Parameter example, Command-line equivalents, Font information
@subsection Default values
@end ifnottex

The next table lists the @MF{} type and default value of each of the
parameters listed in
@ifnottex
@ref{Parameters}.
@end ifnottex
@ifnotinfo
the previous table.
@end ifnotinfo

@multitable {@strong{font_underline_thickness}} {@strong{numeric}} {MMMMMMMMMMMMMMMMMMMMMMMMM}
@item @strong{font_coding_scheme}
@tab  @strong{string}
@tab  @code{"standard"}

@item @strong{font_comment}
@tab  @strong{string}
@tab  @code{"Font converted to @w{Type 1} by mf2pt1, written by Scott Pakin."}

@item @strong{font_family}
@tab  @strong{string}
@tab  (The value of @strong{font_identifier})

@item @strong{font_fixed_pitch}
@tab  @strong{boolean}
@tab  @strong{false}

@item @strong{font_identifier}
@tab  @strong{string}
@tab  (The input filename, minus @file{.mf})

@item @strong{font_name}
@tab  @strong{string}
@tab  (The value of @strong{font_family}, plus an underscore, plus the
      value of @strong{font_weight}, with all spaces removed)

@item @strong{font_size}
@tab  @strong{numeric}
@tab  (Must be specified or @command{mf2pt1} will abort with an error message)

@item @strong{font_slant}
@tab  @strong{numeric}
@tab  0

@item @strong{font_underline_position}
@tab  @strong{numeric}
@tab  -1

@item @strong{font_underline_thickness}
@tab  @strong{numeric}
@tab  0.5

@item @strong{font_unique_id}
@tab  @strong{string}
@tab  (Randomly generated in the range 4000000-4999999)

@item @strong{font_version}
@tab  @strong{string}
@tab  @code{"001.000"}

@item @strong{font_weight}
@tab  @strong{string}
@tab  @code{"Medium"}
@end multitable

@sp 1


@ifnottex
@node Parameter example,  , Default values, Font information
@subsection Parameter example
@end ifnottex

As an example, the following @MF{} code shows the usage of all of the
parameters that @command{mf2pt1} accepts:

@noindent
@b{if} known @i{ps_output}:
@multitable {@b{if}} {@b{font_underline_thickness}} {@t{"Copyright (C) 2005-2024 Scott Pakin.";}}
@item @tab @b{font_coding_scheme}       @tab @t{"ot1"};
@item @tab @b{font_comment}             @tab @t{"Copyright (C) 2005-2024 Scott Pakin."};
@item @tab @b{font_family}              @tab @t{"Kerplotz"};
@item @tab @b{font_fixed_pitch}         @tab @b{false};
@item @tab @b{font_identifier}          @tab @t{"Kerplotz Light Oblique"};
@item @tab @b{font_name}                @tab @t{"Kerplotz-LightOblique"};
@item @tab @b{font_size}                @tab 10@i{pt}#; @ @ @ @ @ % Important to include this.
@item @tab @b{font_slant}               @tab 1/6;
@item @tab @b{font_underline_position}  @tab -1@i{pt}#;
@item @tab @b{font_underline_thickness} @tab 1/2@i{pt}#;
@item @tab @b{font_unique_id}           @tab @t{"4112233"}; @ @ @ @ @ % Better to omit this.
@item @tab @b{font_version}             @tab @t{"002.005"};
@item @tab @b{font_weight}              @tab @t{"Light"};
@end multitable
@noindent
@b{fi}

@noindent
In the above, the @strong{font_fixed_pitch} call could have been
omitted, as it defaults to @strong{false}.  Also, unless you've
requested a unique ID from Adobe, it's generally better not to assign
@strong{font_unique_id}; let @command{mf2pt1} choose a random value
itself.

The same parameters can also be specified on the command line as
follows:

@example
mf2pt1 --encoding=ot1 --comment="Copyright (C) 2005-2024 Scott Pakin."
  --family=Kerplotz --nofixedpitch --fullname="Kerplotz Light Oblique"
  --name=Kerplotz-LightOblique --designsize=10 --italicangle=-9.5
  --underpos=-100 --underthick=50 --uniqueid=4112233 --version=002.005
  --weight=Light kerplotz.mf
@end example

@noindent
Note that a @MF{} font slant of 1/6 is equal to a PostScript italic
angle of approximately -9.5.  The conversion formula is
@iftex
@tex
$s = -@tan @theta$, in which $s$ is the slant and $@theta$ is the
italic angle.
@end tex
@end iftex
@ifnottex
slant = -tan(angle).
@end ifnottex
In addition, the underline position and thickness must be multiplied by
1000/@strong{font_size} to convert from the @MF{} units that are used
within the @file{.mf} file to the PostScript units that are used on the
command line.


@node Additional command-line options, Custom font encodings, Font information, Usage
@section Additional command-line options

In addition to the command-line options for setting font parameters
that were presented in
@iftex
@ref{Font information},
@end iftex
@ifnottex
@ref{Parameters},
@end ifnottex
@command{mf2pt1} supports a @copt{rounding} option.  While
@command{mf2pt1} normally rounds all font coordinates to the nearest
integer, @copt{rounding} increases coordinate precision by
instructing @command{mf2pt1} to round instead to the nearest multiple
of a given fractional number.  For example, @samp{--rounding=0.25}
rounds the coordinate @math{(7.4, 10.3)} to @math{(7.5, 10.25)} while
it would otherwise be rounded to the less-precise @math{(7, 10)}.

Large glyphs can be problematic in MetaPost and therefore in
@command{mf2pt1}.  Unlike @MF{}, MetaPost does not honor @samp{mag}
for magnifying dimensions.  Rather, the number of PostScript
(a.k.a. ``big'') points per pixel---@samp{bpppix}---is hardwired @w{to
0.02} and all other dimensions (@samp{mm}, @samp{in}, @samp{pt},
etc.@:) are expressed in terms of that.  Consequently, glyphs that
multiply a large number of font units by a dimension are likely to
exceed 4096, the largest value that MetaPost can represent in its
fixed-point format.  If numerical overflow becomes a problem you can
use the @copt{bpppix} option to @command{mf2pt1} to change the value
of @samp{bpppix}.  For example, specifying @samp{--bpppix=0.2} enables
a tenfold increase in maximum glyph size (with a corresponding
decrease in precision).

After generating a @w{Type 1} font, @command{mf2pt1} runs it through
FontForge to add hinting information, remove overlaps, and otherwise
clean up the generated font.  The @copt{ffscript} option specifies
the filename of a FontForge script to use instead of the default
script, which is listed below:

@example
Open($1);
SelectAll();
RemoveOverlap();
AddExtrema();
Simplify(0, 2);
CorrectDirection();
Simplify(0, 2);
RoundToInt();
AutoHint();
Generate($1);
Quit(0);
@end example

@noindent
See the FontForge documentation for an explanation of each of those
commands and a description of other commands made available to
FontForge scripts.  @command{mf2pt1} runs the script with one argument
(@code{$1}), which is the name of the generated @file{.pfb} file.

@command{mf2pt1} also supports a @copt{help} option which summarizes
all of the program's command-line options.

@c Improve formatting by keeping the large cartouche on the same
@c page as the text that introduces it.
@page

@node Custom font encodings, Restoring mfplain defaults, Additional command-line options, Usage
@section Custom font encodings

@iftex
@ref{Font information},
@end iftex
@ifnottex
@ref{Parameters},
@end ifnottex
lists the font encodings currently supported by @command{mf2pt1} and
mentions that an alternate encoding can be specified by providing the
name of an encoding file.  To elaborate, the following example
represents the contents of an encoding file which defines a---largely
useless nowadays---@acronym{EBCDIC} font encoding:

@cartouche
@quotation
@code{% Sample encoding vector: @acronym{EBCDIC}@*
@*
% The encoding vector must have a name and be defined as a PostScript array.@*
/ebcdic_encoding [@*
/_a0 /_a1 /_a2 /_a3 /_a4 /_a5 /_a6 /_a7 /_a8 /_a9 /_a10 /_a11 /_a12
/_a13 /_a14 /_a15 /_a16 /_a17 /_a18 /_a19 /_a20 /_a21 /_a22 /_a23
/_a24 /_a25 /_a26 /_a27 /_a28 /_a29 /_a30 /_a31 /_a32 /_a33 /_a34
/_a35 /_a36 /_a37 /_a38 /_a39 /_a40 /_a41 /_a42 /_a43 /_a44 /_a45
/_a46 /_a47 /_a48 /_a49 /_a50 /_a51 /_a52 /_a53 /_a54 /_a55 /_a56
/_a57 /_a58 /_a59 /_a60 /_a61 /_a62 /_a63 /space /_a65 /_a66 /_a67
/_a68 /_a69 /_a70 /_a71 /_a72 /_a73 /bracketleft /period /less
/parenleft /plus /exclam /ampersand /_a81 /_a82 /_a83 /_a84 /_a85
/_a86 /_a87 /_a88 /_a89 /bracketright /dollar /asterisk /parenright
/semicolon /asciicircum /hyphen /slash /_a98 /_a99 /_a100 /_a101
/_a102 /_a103 /_a104 /_a105 /bar /comma /percent /underscore /greater
/question /_a112 /_a113 /_a114 /_a115 /_a116 /_a117 /_a118 /_a119
/_a120 /_a121 /colon /numbersign /at /quoteright /equal /quotedbl
/_a128 /a /b /c /d /e /f /g /h /i /_a138 /_a139 /_a140 /_a141 /_a142
/_a143 /_a144 /j /k /l /m /n /o /p /q /r /_a154 /_a155 /_a156 /_a157
/_a158 /_a159 /_a160 /asciitilde /s /t /u /v /w /x /y /z /_a170 /_a171
/_a172 /_a173 /_a174 /_a175 /_a176 /_a177 /_a178 /_a179 /_a180 /_a181
/_a182 /_a183 /_a184 /quoteleft /_a186 /_a187 /_a188 /_a189 /_a190
/_a191 /braceleft /A /B /C /D /E /F /G /H /I /_a202 /_a203 /_a204
/_a205 /_a206 /_a207 /braceright /J /K /L /M /N /O /P /Q /R /_a218
/_a219 /_a220 /_a221 /_a222 /_a223 /backslash /_a225 /S /T /U /V /W /X
/Y /Z /_a234 /_a235 /_a236 /_a237 /_a238 /_a239 /zero /one /two /three
/four /five /six /seven /eight /nine /_a250 /_a251 /_a252 /_a253
/_a254 /_a255@*
% Don't forget to end the array.@*
] def}
@end quotation
@end cartouche

All entries in the encoding vector are PostScript ``names'' and
therefore must be prefixed with a slash.  Unnamed characters such as
control characters are commonly named @samp{_a@var{number}}, where
@var{number} is the decimal offset into the character table.
Undefined characters are indicated by @samp{.notdef}.  In the
@acronym{EBCDIC} example, the character at @w{position 0} in the font
will be named @samp{a0}; the character at @w{position 1} will be named
@samp{a1}; the character at @w{position 74} will be named
@samp{bracketleft}; the character at @w{position 129} will be named
@samp{a}; and so forth.

Individual characters can be mapped to an encoding either numerically
or by executing a @strong{glyph_name} command within a character
definition.  For example, the following code overrides the character
position passed to @strong{beginchar} @w{(i.e., 123)} with whatever
character position the current encoding has designated for the
@samp{ohungarumlaut} glyph:

@display
@b{beginchar} (123, cap_height#-1/2pt#, cap_height#, 0);
  @b{if} known @i{ps_output}:
    @i{glyph_name} @t{"ohungarumlaut"};
  @b{fi}
  @dots{}
@b{endchar};
@end display


@node Restoring mfplain defaults,  , Custom font encodings, Usage
@section Restoring @file{mfplain} defaults

@command{mf2pt1} normally redefines @strong{filldraw} as @strong{fill}
and @strong{unfilldraw} as @strong{unfill} because @w{Type 1} fonts
don't allow overlapping curves.  Similarly, @command{mf2pt1} redefines
@strong{pencircle} as a 20-gon to coerce MetaPost into drawing it
using a filled instead of a stroked PostScript path.

If you know you'll be postprocessing your fonts using FontForge, which
can automatically convert overlapping paths to nonoverlapping paths,
then you can restore the original @file{mfplain.mp} definitions of
@strong{filldraw}, @strong{unfilldraw}, and @strong{pencircle} as
follows:

@display
@b{if} known @i{ps_output}:
  @b{pencircle} := @i{mfplain_pencircle};
  @b{let filldraw} := @i{mfplain_filldraw};
  @b{let unfilldraw} := @i{mfplain_unfilldraw};
@b{fi}
@end display


@node Future Work, Acknowledgments, Usage, Top
@chapter Future Work

One avenue for future work is to enable the font designer to specify
@w{Type 1} font hints directly in the @MF{} font program.  Hinting is
a way for a font designer to specify how a font should be rendered at
low resolutions, for example, at typical monitor resolutions.  In
@MF{}, this is done by controlling the way that points are mapped to
pixel locations, using commands such as
@strong{define_corrected_pixels}, @strong{define_blacker_pixels}, and
@strong{lowres_fix}.  @w{Type 1} fonts are hinted in a completely
different manner.  @w{Type 1} hints distinguish key character
features, such as stems and dots, from decorations which can be
discarded at low resolutions.  The PostScript interpreter uses that
information to determine how to map points to pixels.  Although
@command{mf2pt1} employs FontForge to autohint the fonts it generates,
the approach is mechanical and unlikely to hint as well as a human can
do manually.  It would be convenient for @command{mf2pt1} one day to
provide @MF{} commands for @strong{hstem}, @strong{vstem},
@strong{dotsection}, and the other @w{Type 1} hints.  That way, hints
will no longer need to be re-added manually every time
@command{mf2pt1} regenerates a @w{Type 1} font.

Another future addition to @command{mf2pt1} is the addition of more
font encodings.  The following are the encodings that @command{mf2pt1}
will most likely accept:

@table @code
@item TeXMathItalicEncoding
Upper- and lowercase Greek and Latin letters, old-style digits, and a
few symbols and accents.

@item TeXMathSymbolEncoding
A variety of symbols, as well as calligraphic Latin majuscules.

@item TeXMathExtensionEncoding
Variable-sized symbols, such as braces, integrals, and radicals.

@item AdobeExpert
Small caps, currency symbols, old-style digits, and various superior and
inferior letters and digits.
@end table


@node Acknowledgments,  , Future Work, Top
@unnumbered Acknowledgments

Many thanks are owed to Werner Lemberg for writing the code underlying
the @copt{rounding} option; for introducing the @strong{glyph_name}
command and @code{asis} encoding vector; for providing the default
FontForge script listed in @ref{Additional command-line options}; for
fixing some code-generation bugs in @command{mf2pt1}; for finding a
more robust way to dump @file{mf2pt1.mem}; for directing me to the
overlap-removal code mentioned in @ref{Restrictions}; for supplying
the @emph{crossproduct}, @emph{makeline}, and @emph{is_clockwise}
functions used by @file{mf2pt1.mp}; for proposing the @copt{bpppix}
command-line option; and for suggesting numerous features and
improvements to @command{mf2pt1}.  Thanks also go to Werner Lemberg
and
@iftex
@tex
Bogus\l{}aw
@end tex
@end iftex
@ifnottex
Boguslaw
@end ifnottex
Jackowski for updating the @strong{is_clockwise} function in
@file{mf2pt1.mp} to work around a bug in MetaPost which relates to the
@strong{turningnumber} command.  Finally, thanks go to Ralf Stubner
for providing the T1 encoding vector and for pointing out a typo in
the generated font programs; to Michael Zedler for alerting me to
problems with @copt{encoding} and suggesting I modify that option to
accept PostScript @file{.enc} files; and to Michael Ummels for fixing
a couple of bugs that made character widths in the generated fonts
slightly too large.

@bye