1 \input texinfo @c -*-texinfo-*-
3 @setfilename README.info
4 @settitle mftrace - Scalable Fonts for MetaFont
9 Copyright (c) 1999--2006 by the authors
11 Permission is granted to copy, distribute and/or modify this document
12 under the terms of the GNU General Public License.
14 You should have received a copy of the GNU General Public License
15 along with this program; if not, write to the Free Software
17 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
26 @chapter mftrace - Scalable PostScript Fonts for MetaFont
30 @code{mftrace} is a small Python program that lets you trace a @TeX{}
31 bitmap font into a PFA or PFB font (A PostScript Type1 Scalable Font)
32 or TTF (TrueType) font. It is licensed under the GNU GPL.
34 Scalable fonts offer many advantages over bitmaps, as they allow
35 documents to render correctly at many printer resolutions. Moreover,
36 Ghostscript can generate much better PDF, if given scalable PostScript
39 Versions prior to 1.0.5 were called `pktrace'.
44 @item @uref{http://www.xs4all.nl/~hanwen/mftrace/mftrace-@MFTVERSION@.tar.gz}
45 @item Anonymous CVS at
46 @code{anoncvs@@subversions.gnu.org:/cvsroot/lilypond}, module
53 @file{mftrace} is a thin Python wrapper around some other programs that
54 do the real work: a tracing program and t1asm. To run mftrace you need:
56 @item A tracing program:
57 autotrace >= 0.30 (see @uref{http://autotrace.sourceforge.net}
58 or potrace (see @uref{http://potrace.sourceforge.net}).
60 Potrace is recommended as it runs quicker than autotrace.
62 @item Python--2.1 or later. See @uref{http://www.python.org/}
63 @item t1utils. See @uref{http://www.lcdf.org/~eddietwo/type/}
64 @item TeX--your tex installation should include
74 @item A recent version (040215 or newer) of
75 @uref{http://fontforge.sourceforge.net,FontForge}. Some of @code{mftrace}
76 functionality requires FontForge to be present on user's system. This
77 includes rounding to integer, simplifying and autohinting font outlines,
78 as well as generating any output formats except PFA, PFB and AFM. You
79 should not request any of these features using @code{mftrace} options if
80 you don't like your font to be run through FontForge (note that in this
81 case you also have to explicitly specify @code{--noround} to disable
84 @item Alternatively, you need GhostScript with its @file{printafm}
85 utility, available somethere in your PATH. @code{mftrace} uses
86 @file{printafm} to generate AFM files in case there is no need to
87 process the font with FontForge.
93 A RPM may be built by issuing
96 rpm -tb mftrace-@var{version}.tar.gz
102 @section Debian GNU/Linux
104 Users of Debian unstable (and Debian 3.0 when it is released) can
105 install all requirements by running (as root):
108 apt-get install mftrace
111 If you wish to also install the FontForge package to simplify and
112 autohint the font, then run the command
115 apt-get install fontforge
122 Install the prerequite packages. Then run
129 in the mftrace directory. Run as follows:
136 @section Invoking mftrace.
138 Command line options:
141 A comma-separated list of formats to generate. Choices include: AFM,
142 PFA, PFB, TTF and SVG. Default is to generate a PFA file. Note that
143 @file{fontforge} (formerly called @file{pfaedit}) needs to be installed
144 in order to generate any format except PFA or PFB. For generating AFM
145 you need either @file{fontforge} or @file{ghostscript}.
146 @item -e,--encoding=@var{enc}
147 Use encoding file @var{enc}. Encoding files used by @code{mftrace} are
148 basically in the GhostScript/dvips format, but you may use a special
149 @code{.notavail} glyph name in order to tell mftrace not to process
150 a specific glyph. If this option is not specified, mftrace will try to
151 determine the encoding file automatically, from the encoding specified
153 @item --glyphs=@var{list}
154 Only process glyphs in @var{list}, which is a comma-delimited list of
155 decimal numbers or ranges.
157 --glyphs 1-10,50,55,90-100
159 @item --gffile=@var{name}
160 = Take glyphs from file @var{name}.
161 @item --grid @var{gridsize}
162 Set reciprocal grid size in em units multiplied by ratio magnification/1000.
163 For example @code{--grid 10 --magnification 1000} will round
164 coordinates of control points to 1/10 of em unit. Useful simultaneously
165 with @code{--noround} option. Default @var{gridsize} value is 1, i. e. round to integer.
169 Retain all temporary files in the directory @file{mftrace.dir/}. This
170 is useful for debugging problems.
172 Try to continue if external programs called by mftrace fail. If METAFONT
173 crashes with overflow errors, but nevertheless outputs a GF file, try to
174 process its output as is (useful for some buggy fonts, see below). If
175 potrace/autotrace fails to trace a specific character, first try it with
176 a less smoothed curve, and if that fails, skip the character.
178 By default mftrace outputs @file{trace-bug-FONTNAME-NUMBER.pbm} and
179 stops the process with a request to file a bugreport.
180 @item --magnification
181 The magnification to use for the PFA file. The default is 1000. The
182 larger the more precise the PFA file will be. However, when
183 magnification is too large METAFONT can crash with overflow errors.
185 Sadly, many MF fonts contain resolution checks
187 if dots_per_inch * design_size > 1500:
190 This check is susceptible to overflow errors. Such code should be
191 reported as a bug, and changed to
193 if dots_per_inch > (1500 / design_size):
198 Don't round coordinates of control points to integer
199 values. Useful simultaneously with
200 @code{--grid} option. Disabled by default.
202 @item -o,--output-base=FILE
203 Output to FILE.pfa or FILE.pfb.
205 Pass the font through FontForge for automatic simplification and hinting.
207 Use @var{file} for the TFM file. This file is needed to determine at
208 what resolution to run MetaFont.
210 Be verbose: print all commands as they are invoked. This is useful
215 Try to kludge up the paths coming from MikTeX for a cygwin
216 environment. If this doesn't work, specify @code{--tfmfile} and
217 @code{--encoding} manually.
219 show warranty and copyright
221 use Potrace (default).
225 @item -D,--define=@var{symbol}=@var{value}
226 Set the font info @var{symbol} to the given @var{value}. For example
227 @code{-DFamilyName=Foo} sets the font family name to @code{Foo}.
229 Mftrace tries to fill in sensible values for the FontName, FamilyName,
230 FullName and Weight fields. It does so by guessing values for the CM font
231 series. For other fonts, it tries to read an AFM file (which is not likely
232 to exist). Suggestions for a more generic way to handle this are welcome.
236 Mftrace uses kpathsea for finding fonts, so any kpathsea variable can
237 be used to fine-tune which files should be loaded. For example, you
238 can set @code{MFINPUTS} to specify which paths to search for
241 Additional options may be passed to the backend program (potrace or autotrace)
242 with the @code{MFTRACE_BACKEND_OPTIONS} environment variable.
247 Why use @code{mftrace} over
248 @uref{http://textrace.sourceforge.net,textrace}? Textrace and mftrace
249 are functionally similar. However, mftrace is quicker, more cleanly
250 written and can be installed using standard methods. Additionally,
251 textrace requires perl, ghostscript and dvips.
253 How about @uref{http://www.truetex.com,MetaFog}? MetaFog operates
254 directly on the curves that generate the bitmap font, its outlines will
255 probably be smaller and better. However, MetaFog is a proprietary
256 product: its source code is not available, and it will only run on a
257 limited number of platforms.
259 How about @uref{ftp://bop.eps.gda.pl/pub/metatype1/,MetaType1}?
260 MetaType1 is an approach that puts severe constraints on what may be
261 done in a font program. It does not work for fonts containing overlaps
264 How about @uref{http://fontforge.sourceforge.net/,FontForge} itself?
265 FontForge is an interactive editor, but it can be scripted. Since it
266 supports bitmap tracing and @TeX{} bitmap fonts, it is possible to
267 duplicate the functionality of mftrace. However, out of the box,
268 FontForge does not recognize TeX encodings.
271 @section Bugs and todo
274 @item Discuss fonts & copyright.
275 @item Submit @file{tfm.py} to www.python.org. @file{tfm.py} is a python
276 module to parse Tex Font Metric file.
279 Should you encounter any bug or problem, then please send a bugreport
280 to @email{hanwen@@xs4all.nl,Han-Wen Nienhuys}.
284 @email{hanwen@@xs4all.nl,Han-Wen Nienhuys}
289 Gf2pbm, the utility to convert a MetaFont GF file to a PBM file was
290 based on Paul Vojta's Xdvi. The license notice is reproduced below.
292 Thanks to all bughunters and contributors: Andrey V. Panov, Geoffrey
293 Alan Washburn, @uref{http://www.maths.qmul.ac.uk/~jdg/,Julian Gilbey}
294 G@"{u}nther Spahlinger, Richard Mahoney, Stanislav Brabec, and Thomas
299 Copyright (c) 1990-1999 Paul Vojta
301 Permission is hereby granted, free of charge, to any person obtaining a copy
302 of this software and associated documentation files (the "Software"), to
303 deal in the Software without restriction, including without limitation the
304 rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
305 sell copies of the Software, and to permit persons to whom the Software is
306 furnished to do so, subject to the following conditions:
308 The above copyright notice and this permission notice shall be included in
309 all copies or substantial portions of the Software.
311 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
312 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
313 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
314 PAUL VOJTA BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
315 IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
316 CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
319 The rest of the package mftrace script itself is licensed under the
320 @uref{http://www.gnu.org/licenses/gpl.txt,GNU General Public License}.
327 @item @uref{http://partners.adobe.com/asn/developer/pdfs/tn/T1Format.pdf,Type1
329 @item @uref{http://partners.adobe.com/asn/developer/pdfs/tn/5015.Type1_Supp.pdf,Supplement
330 to the Type1 specification}.