Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / fonttools / da15a425c4226b1548d622c68bdfa106dc23e606 / . / Doc / documentation.html
blob: d3f0a506e8f419b4bca35225a5025a7a3bbec6d7 [file] [log] [blame]
Just4977da41999-12-18 18:18:09 +0000[diff] [blame]1<HTML>
2<HEAD>
3
jvraeed5692002-05-03 19:10:39 +0000[diff] [blame]4<TITLE>TTX/FontTools</TITLE>
Just4977da41999-12-18 18:18:09 +0000[diff] [blame]5
6
7</HEAD>
8<BODY bgcolor="#FFFFFF">
9
jvraeed5692002-05-03 19:10:39 +0000[diff] [blame]10<H1>TTX/FontTools</H1>
Just4977da41999-12-18 18:18:09 +0000[diff] [blame]11
jvraeed5692002-05-03 19:10:39 +0000[diff] [blame]12<A HREF="http://fonttools.sourceforge.net/">TTX/FontTools</A> is a
13suite of tools and libraries for manipulating fonts. It is written in
14Python and has a BSD-style, open-source licence -- see LICENSE.txt.
15It's hosted at <A HREF="http://sourceforge.net/">sourceforge.net</A>.
Just4977da41999-12-18 18:18:09 +0000[diff] [blame]16
17<P>
Juste5ad9c92000-03-15 20:56:20 +0000[diff] [blame]18It currently reads and writes TrueType font files, reads PostScript Type 1 fonts
19and more. It contains two command line programs to convert TrueType fonts to an
20XML based format (called TTX) and back.
21
22<H3>Scope</H3>
23
jvraeed5692002-05-03 19:10:39 +0000[diff] [blame]24TTX/FontTools' functionality is aimed towards font developers and font tool
25developers. It can of course be used to just access fonts (outlines,
26metrics, etc.) but it is not optimized for that. It will be further
27developed so it can be the core of any font editor. And that's exactly
28what it will be for our upcoming major rewrite of <A
29HREF="http://www.robofog.com/">RoboFog</A>, our (commercial)
30PythonPowered font editor for MacOS.
Juste5ad9c92000-03-15 20:56:20 +0000[diff] [blame]31
32<H3>Installation</H3>
33
34You need the following software to use FontTools:
35
36<UL>
37<LI>
jvr8eb99922002-05-02 08:11:37 +0000[diff] [blame]38 <B>Python</B>. The fresh versions as well as older versions (You need 2.0 or higher) can be obtained here:
jvrf5ccb352001-08-10 08:54:14 +0000[diff] [blame]39 <A HREF="http://www.python.org/download/">http://www.python.org/download/</A>
40 or here:
41 <A HREF="http://sourceforge.net/projects/python/">http://sourceforge.net/projects/python/</A>
Juste5ad9c92000-03-15 20:56:20 +0000[diff] [blame]42
jvrf5ccb352001-08-10 08:54:14 +0000[diff] [blame]43 <P>Windows: grab the Windows installer, run the full install.
44 <BR>Un*x: follow the build instructions.
Juste5ad9c92000-03-15 20:56:20 +0000[diff] [blame]45 <BR>MacOS: grab the installer, run "Easy Install"
Juste5ad9c92000-03-15 20:56:20 +0000[diff] [blame]46<P>
47<LI>
jvrf5ccb352001-08-10 08:54:14 +0000[diff] [blame]48 The <B>Numeric Python</B> extension (you don't need this under MacOS, since it's
49 included in the MacPython installer). Get a fresh version from the download page,
50 linked from here:
51 <A HREF="http://sourceforge.net/projects/numpy/">http://sourceforge.net/projects/numpy/</A>
52 <P>Windows: grab the "Numeric-*.exe" archive, it's an installer. Make sure the
53 Python version in the archive name (eg. "2.1") matches the Python version you have.
54 <BR>Linux/Un*x: get a source archive and run this command from the unpacked directory:
jvrec8ca4b2002-05-03 19:02:26 +0000[diff] [blame]55 <BR><TT>python setup.py install</TT>
Juste5ad9c92000-03-15 20:56:20 +0000[diff] [blame]56<P>
57<LI>
jvrf5ccb352001-08-10 08:54:14 +0000[diff] [blame]58 <B>PyXML</B>, a set of XML tools:
59 <A HREF="http://sourceforge.net/projects/pyxml/">http://sourceforge.net/projects/pyxml/</A>
jvrf5ccb352001-08-10 08:54:14 +0000[diff] [blame]60 <BR>Installation should be very similar to installing Numeric Python, see above.
jvr911b33d2002-05-12 12:58:22 +0000[diff] [blame]61 <BR><I>Note:</I> some Python distributions already contain the neccesary XML support.
62 If "import xml.parsers.expat" works at the Python interactive prompt, you don't need to
63 install PyXML.
Juste5ad9c92000-03-15 20:56:20 +0000[diff] [blame]64
65</UL>
66
67
jvrf5ccb352001-08-10 08:54:14 +0000[diff] [blame]68Now run the "setup.py" script from the FontTools archive. This will install
69all the modules in the right places, as well as tries to compile the one (optional)
70C extension contained in FontTools. (XXX: need precompiled Mac and Windows binaries,
71*or* a way to skip compilation when there's no compiler available.)
Juste5ad9c92000-03-15 20:56:20 +0000[diff] [blame]72
73<P>Additional Mac instructions:
74De-binhex "TTX.rsrc.hqx" by dropping it onto StuffIt expander. (Or use your
75own preferred method)
76The "TTX.py" script included in this archive is the Mac-only main program:
77Drop it onto the "BuildApplet" app inside the Python folder; this will
78produce the TTX applet.
79
80
81<H3>User documentation</H3>
82
jvrec8ca4b2002-05-03 19:02:26 +0000[diff] [blame]83<P>For Unix and DOS there are three command line programs:
Juste5ad9c92000-03-15 20:56:20 +0000[diff] [blame]84<UL>
jvrec8ca4b2002-05-03 19:02:26 +0000[diff] [blame]85 <LI>ttdump -- dumps a TrueType (or OpenType) font file to TTX format.
86 <LI>ttcompile -- compiles a TTX file back into a TTF (or OTF) file.
87 <LI>ttlist -- lists minimal info about each table in a font.
Juste5ad9c92000-03-15 20:56:20 +0000[diff] [blame]88</UL>
jvrec8ca4b2002-05-03 19:02:26 +0000[diff] [blame]89They can all work with multiple input files. There are some extra
90options which are explained by the 'usage' text; use the -h option to
91display it. The setup.py script installs them as global tools, the
92source is in the Tools directory.
93
94<P>For MacOS there's a application called TTX. If you drop a TrueType
95file onto it, it will convert it to XML. If you drop an XML file onto
96it, it will convert it back to TrueType. Please read the additional
97README file in the Mac subdirectory, since it behaves quite differently
98than the command line programs described below.
Juste5ad9c92000-03-15 20:56:20 +0000[diff] [blame]99
Juste5ad9c92000-03-15 20:56:20 +0000[diff] [blame]100<P>Adam Twardoch contributed a Windows registry script (ttx_shellext_win32.py) which
101makes the two above tools available under the Right Mouse Button. I haven't tested
102these myself, but I'm very interested in hearing about the results!
103
jvr7de32f22002-05-12 12:48:14 +0000[diff] [blame]104<H3>A note about glyph names and TrueType GlyphID's</H3>
Juste5ad9c92000-03-15 20:56:20 +0000[diff] [blame]105
106TrueType fonts use glyph indices (GlyphID's) to refer to glyphs in most places.
107While this is fine in binary form, it is really hard to work with for
108humans. Therefore we use names instead.
109
jvr7de32f22002-05-12 12:48:14 +0000[diff] [blame]110<P>The glyph names are either extracted from the 'CFF ' table or the 'post' table,
111or are derived from a Unicode 'cmap' table. In the latter case the Adobe Glyph List
112is used to calculate names based on Unicode values. If all of these mthods fail,
113names are invented based on GlyphID (eg. "glyph00142").
114
115<P>It is possible that different glyphs use the same name. If this happens,
116we force the names to be unique by appending "#n" to the name (n being an
117integer number). The original names are being kept, so this has no influence
118on a "round tripped" font.
Juste5ad9c92000-03-15 20:56:20 +0000[diff] [blame]119
120<P>Because the order in which glyphs are stored inside the TT font is
jvr7de32f22002-05-12 12:48:14 +0000[diff] [blame]121important, we maintain an ordered list of glyph names in the font.
Juste5ad9c92000-03-15 20:56:20 +0000[diff] [blame]122
123<H3>Feedback</H3>
124
jvrf5ccb352001-08-10 08:54:14 +0000[diff] [blame]125Please join the fonttools-discussion mailing list at SourceForge. Subscription
126info can be found if you follow the "Mailing Lists" link at the
127<A HREF="http://sourceforge.net/projects/fonttools/">SourceForge project page</A>.
128You can also email me directly at <A HREF="mailto:just@letterror.com">just@letterror.com</A>.
129
130<P>
131If you want to follow the development of FontTools closely, or would like to
132contribute, you can also subscribe to the fonttools-checkins mailing list.
Juste5ad9c92000-03-15 20:56:20 +0000[diff] [blame]133
134<H3>Anonymous CVS-access</H3>
135
jvrf5ccb352001-08-10 08:54:14 +0000[diff] [blame]136The FontTools sources are also accessible through CVS, see the
137the <A HREF="http://sourceforge.net/projects/fonttools/">SourceForge project
138page</A>. Let me know if you'd like to become a co-developer.
Juste5ad9c92000-03-15 20:56:20 +0000[diff] [blame]139
140<H3>Developer documentation</H3>
141
142Sorry, documentation beyond doc strings in the source code is still on my to-do list...
143Below follows a brief overview of what's there.
144
Just4977da41999-12-18 18:18:09 +0000[diff] [blame]145<P>
146<H3>The library</H3>
147
148Cross-platform
Juste5ad9c92000-03-15 20:56:20 +0000[diff] [blame]149<UL>
150 <LI>fontTools.t1Lib -- Provides a Type 1 font reader. Writing is a planned feature.
151 <LI>fontTools.ttLib -- Extensive TrueType tools. Reads and writes. This is the flagship
152 of FontTools, it's by far the most mature component. Contains a completely modular
153 TTF table converter architecture. See ttLib/tables/table_API_readme.txt.
154 <LI>fontTools.afmLib -- And AFM file reader/writer.
155 <LI>fontTools.cffLib -- Reads CFF fonts. Writing is a planned feature.
156 <LI>fontTools.unicode -- A simple (but large) module that translates
157 Unicode values to their descriptive names. Still Unicode 2.0.
158 <LI>fontTools.agl -- Interface to the Adobe Glyph List: maps unicode values
159 to glyph names and back.
Just4977da41999-12-18 18:18:09 +0000[diff] [blame]160</UL>
161
162Mac-specific
Juste5ad9c92000-03-15 20:56:20 +0000[diff] [blame]163<UL>
164 <LI>fontTools.fondLib -- A reader/writer class for Mac FOND resources.
165 <LI>fontTools.nfntLib -- Reads Mac NFNT bitmap font resources.
Just4977da41999-12-18 18:18:09 +0000[diff] [blame]166</UL>
167
Juste5ad9c92000-03-15 20:56:20 +0000[diff] [blame]168<H3>Thank-you's</H3>
169
170(in alphabetical order)
171Erik van Blokland, Petr van Blokland, Jelle Bosma, Vincent Connare,
jvra12cf922002-09-10 11:55:09 +0000[diff] [blame]172Simon Daniels, Hannes Famira, Greg Hitchcock, John Hudson, Jack Jansen,
173Antoine Leca, Werner Lemberg, Peter Lofting, Dave Opstad, Laurence Penney,
Juste5ad9c92000-03-15 20:56:20 +0000[diff] [blame]174Guido van Rossum, Adam Twardoch.
175
176<H3>Copyrights</H3>
177
jvrec8ca4b2002-05-03 19:02:26 +0000[diff] [blame]178FontTools/TTX -- 1999-2002 Just van Rossum; Letterror (just@letterror.com)
Just4977da41999-12-18 18:18:09 +0000[diff] [blame]179
180</BODY>
181</HTML>