Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / fonttools / e5ad9c959b6dbd76e83ed627a9e10e74d34b2cc4 / . / Doc / index.html
blob: 1ba8dee1ea63ff8d7d74479c86c916dc40172224 [file] [log] [blame]
Just4977da41999-12-18 18:18:09 +0000[diff] [blame]1<HTML>
2<HEAD>
3
4<TITLE>FontTools</TITLE>
5
6
7</HEAD>
8<BODY bgcolor="#FFFFFF">
9
10<H1>FontTools</H1>
11
Juste5ad9c92000-03-15 20:56:20 +0000[diff] [blame^]12FontTools is a suite of tools and libraries for manipulating fonts. It is written
13in Python and has a Python-style, open-source licence -- see LICENSE.txt.
Just4977da41999-12-18 18:18:09 +0000[diff] [blame]14
15<P>
Juste5ad9c92000-03-15 20:56:20 +0000[diff] [blame^]16It currently reads and writes TrueType font files, reads PostScript Type 1 fonts
17and more. It contains two command line programs to convert TrueType fonts to an
18XML based format (called TTX) and back.
19
20<H3>Scope</H3>
21
22FontTools' functionality is aimed towards font developers and font tool developers.
23It can of course be used to just access fonts (outlines, metrics, etc.) but it is
24not optimized for that. It will be further developed so it can be the core of any
25font editor. And that's exactly what it will be for our upcoming major rewrite of
26<A HREF="http://www.robofog.com/">RoboFog</A>, our (commercial) PythonPowered font
27editor for MacOS.
28
29<H3>Installation</H3>
30
31You need the following software to use FontTools:
32
33<UL>
34<LI>
35 Python 1.5.1 or newer. The latest version 1.5.x is here:
36 <A HREF="http://www.python.org/1.5/">http://www.python.org/1.5/</A>
37
38 <P>Windows: grab the Windows installer, run the full install
39 <BR>Un*x: follow the build instructions
40 <BR>Linux: maybe you already *have* Python: check whether you have
41 version 1.5.1 or newer.
42 <BR>MacOS: grab the installer, run "Easy Install"
43
44<P>
45<LI>
46 The Numeric Python extension (you don't need this under MacOS, since it's
47 included in the MacPython installer).
48
49 <BR>The compiled Win32 version:
50 <A HREF="ftp://ftp-icf.llnl.gov/pub/python/LLNLDistribution11.zip">ftp://ftp-icf.llnl.gov/pub/python/LLNLDistribution11.zip</A>
51
52 <BR>The source distribution is here:
53 <A HREF="ftp://ftp-icf.llnl.gov/pub/python/LLNLDistribution11.tgz">ftp://ftp-icf.llnl.gov/pub/python/LLNLDistribution11.tgz</A>
54
55 <BR>Included in this archive is a directory called "Numeric" (but do unzip
56 the whole archive, it's needed for the install script!).
57 <BR>On Linux or other Unices: follow the build instructions.
58
59 <BR>On Windows & Unix:
60 In the "Numeric" directory there is a script called "installthis.py".
61 If you've installed Python successfully, you can just run it, it will
62 install (copy!) the neccesary stuff to the Python directory all by itself.
63
64 <P><B>Note</B> that the above links are not pointing to the latest version! Newer
65 versions use a different install procedure, which recently still had some problems.
66 If you know what you're doing, you can get the latest Numeric Python at
67 <A HREF="http://numpy.sourceforge.net/">http://numpy.sourceforge.net/</A>.
68
69<P>
70<LI>
71 xmlproc (a Python based XML parser) from:
72 <A HREF="http://www.stud.ifi.uio.no/%7Elarsga/download/python/xml/xmlproc.html">http://www.stud.ifi.uio.no/~larsga/download/python/xml/xmlproc.html</A>
73
74 <BR>I don't know the official install procedure, but the archive should contain
75 a directory called "xml", move that directory to the Python directory and
76 you should be all set. To make sure: start python (python.exe on Win32)
77 and type at the ">>>" prompt:
78 <PRE>>>> import xml.parsers.xmlproc.xmlproc</PRE>
79 followed by a return. If that doesn't cause an error, you're all set.
80
81 <P><B>Note</B> that the default xmlproc distribution depends on Python 1.5.2 (by oversight,
82 not intend) but there is an alternative distribution that does work under Python 1.5.1.
83
84 <P>xmlproc is also part of the xml-sig distribution.
85
86</UL>
87
88
89Now run the "install.py" script from the FontTools archive.
90This will make sure Python knows where to find FontTools. It doesn't copy anything.
91(Note that the "install.py" script has only been lightly tested.)
92
93<P>Additional Mac instructions:
94De-binhex "TTX.rsrc.hqx" by dropping it onto StuffIt expander. (Or use your
95own preferred method)
96The "TTX.py" script included in this archive is the Mac-only main program:
97Drop it onto the "BuildApplet" app inside the Python folder; this will
98produce the TTX applet.
99
100
101<H3>User documentation</H3>
102
103<P>For MacOS there's a small application called TTX. If you drop a TrueType file
104onto it, it will convert it to XML. If you drop an XML file onto it, it will
105convert it back to TrueType. Please read the additional README file in the Mac
106subdirectory, since it behaves quite differently than the command line programs
107described below.
108
109<P>For Unix and DOS I've provided two command line programs:
110<UL>
111 <LI>ttDump.py
112 <LI>ttCompile.py
113</UL>
114They do pretty much what you'd expect. They take several arguments:
115an input file name and optionally an output file name. There are some extra
116options which are explained by the 'usage' text; use the -h option to display
117it.
118
119<P>If you don't provide an output file name, an output file name will be contructed
120from the input file name: foo.ttf becomes foo.ttx in ttDump.py and vice versa
121for ttCompile.py. <B>WARNING</B>: these tools will silently overwrite existing files!
122
123<P>Adam Twardoch contributed a Windows registry script (ttx_shellext_win32.py) which
124makes the two above tools available under the Right Mouse Button. I haven't tested
125these myself, but I'm very interested in hearing about the results!
126
127
128<H3>Note about glyph names and TrueType GlyphID's</H3>
129
130TrueType fonts use glyph indices (GlyphID's) to refer to glyphs in most places.
131While this is fine in binary form, it is really hard to work with for
132humans. Therefore we use names instead.
133
134<P>The names are derived from what is found in the 'post' table. It is
135possible that different glyphs use the same PS name. If this happens, we
136force the names to be unique by appending "#n" to the name (n being an
137integer number). The original PS names will still be maintained by the
138'post' table, so even though we use a different name internally, we are
139still able to write the 'post' table back in original form. If there is
140no proper 'post' table available, names will be derived from a Unicode
141cmap (if available) in conjuction with the Adobe Glyph List (see fontTools/agl.py).
142
143<P>Because the order in which glyphs are stored inside the TT font is
144important, ttLib maintains an ordered list of glyph names in the font.
145
146<H3>Feedback</H3>
147
148Please direct all feedback to <A HREF="mailto:just@letterror.com">just@letterror.com</A>.
149I hope to create a discussion mailing list at some point.
150
151<H3>Anonymous CVS-access</H3>
152
153The FontTools sources are also accessible through CVS:
154<PRE>
155 :pserver:fonttools@rietveld.petr.nl:/usr/local/cvsanon
156 password: fontypython
157 module name: FontTools
158</PRE>
159
160
161<H3>Developer documentation</H3>
162
163Sorry, documentation beyond doc strings in the source code is still on my to-do list...
164Below follows a brief overview of what's there.
165
166
Just4977da41999-12-18 18:18:09 +0000[diff] [blame]167<H3>GUI Tools</H3>
Juste5ad9c92000-03-15 20:56:20 +0000[diff] [blame^]168TTX -- A simple Mac app that converts TrueType (or OpenType) fonts to TTX format and back.
Just4977da41999-12-18 18:18:09 +0000[diff] [blame]169<P>
170<H3>Command line tools</H3>
171
Juste5ad9c92000-03-15 20:56:20 +0000[diff] [blame^]172<UL>
173 <LI>ttDump -- dumps a TrueType (or OpenType) font file to TTX format.
174 <LI>ttCompile -- compiles a TTX file back into a TTF (or OTF) file.
Just4977da41999-12-18 18:18:09 +0000[diff] [blame]175</UL>
176
177<P>
178<H3>The library</H3>
179
180Cross-platform
Juste5ad9c92000-03-15 20:56:20 +0000[diff] [blame^]181<UL>
182 <LI>fontTools.t1Lib -- Provides a Type 1 font reader. Writing is a planned feature.
183 <LI>fontTools.ttLib -- Extensive TrueType tools. Reads and writes. This is the flagship
184 of FontTools, it's by far the most mature component. Contains a completely modular
185 TTF table converter architecture. See ttLib/tables/table_API_readme.txt.
186 <LI>fontTools.afmLib -- And AFM file reader/writer.
187 <LI>fontTools.cffLib -- Reads CFF fonts. Writing is a planned feature.
188 <LI>fontTools.unicode -- A simple (but large) module that translates
189 Unicode values to their descriptive names. Still Unicode 2.0.
190 <LI>fontTools.agl -- Interface to the Adobe Glyph List: maps unicode values
191 to glyph names and back.
Just4977da41999-12-18 18:18:09 +0000[diff] [blame]192</UL>
193
194Mac-specific
Juste5ad9c92000-03-15 20:56:20 +0000[diff] [blame^]195<UL>
196 <LI>fontTools.fondLib -- A reader/writer class for Mac FOND resources.
197 <LI>fontTools.nfntLib -- Reads Mac NFNT bitmap font resources.
Just4977da41999-12-18 18:18:09 +0000[diff] [blame]198</UL>
199
Juste5ad9c92000-03-15 20:56:20 +0000[diff] [blame^]200<H3>The Future</H3>
201
202In /Lib/fontTools/objects you'll find several objects-under-construction which will be
203(and partially are) a generic outline font implementation, offering transparent access
204to various font formats (currently only Type 1 and TTF/OTF). Plans:
205<UL>
206 <LI>Develop this into a complete font compiler for at least Type 1, TrueType and
207 OpenType.
208 <LI>To make the above possible, develop a high level XML-based format to be used
209 as source code for font development. This "language" will be called FDL -- Font
210 Definition Language. For some (rather old) blurb about these ideas, see
211 <A HREF="http://www.letterror.com/fdl/">http://www.letterror.com/fdl/</A>.
212</UL>
213
214<H3>Thank-you's</H3>
215
216(in alphabetical order)
217Erik van Blokland, Petr van Blokland, Jelle Bosma, Vincent Connare,
218Simon Daniels, Hannes Famira, Greg Hitchcock, Jack Jansen, Antoine Leca,
219Werner Lemberg, Peter Lofting, Dave Opstad, Laurence Penney,
220Guido van Rossum, Adam Twardoch.
221
222<H3>Copyrights</H3>
223
224FontTools/TTX -- 1999-2000 Just van Rossum; Letterror (just@letterror.com)
225<BR>Python -- Copyright 1991-1995 by Stichting Mathematisch Centrum, Amsterdam,
226 The Netherlands.
227<BR>Numeric Python -- Copyright (c) 1996. The Regents of the
228 University of California. All rights reserved.
229<BR>xmlproc -- Lars Marius Garshol
Just4977da41999-12-18 18:18:09 +0000[diff] [blame]230
231</BODY>
232</HTML>