/usr/share/doc/xgridfit/html/debug.html is in xgridfit-doc 2.3-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<title>Xgridfit</title>
<link rel="stylesheet" href="oeg.css" media="screen" type="text/css" />
<link rel="stylesheet" href="parchment.css" media="screen"
type="text/css" title="parchment" />
<link rel="alternate stylesheet" href="legible.css" media="screen"
type="text/css" title="legible" />
<style type="text/css" media="print"> @import "oeg.print.css"; </style>
<meta name="AUTHOR" content="Peter S. Baker" />
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
</head>
<body>
<div id="jumplist">
<a href="http://sourceforge.net"><img src="" width="125" height="37" border="0" alt="SourceForge.net Logo" /></a>
<a href="http://xgridfit.sourceforge.net/">Home Page</a>
<a href="http://sourceforge.net/projects/xgridfit">Project Page</a>
<a href="http://sourceforge.net/project/showfiles.php?group_id=159705">Download</a>
<a href="http://xgridfit.cvs.sourceforge.net/xgridfit/xgridfit/">CVS repository</a>
</div>
<div id="content">
<h1>Debugging with FontForge</h1>
<p>
Xgridfit has no debugger, and it's pretty safe to predict that it
never will. FontForge, however, has an excellent debugger, which
you can use to step through the TrueType instructions for a glyph
and watch the effect of each instruction on the outline.
</p>
<p>
You may have to compile FontForge from source to enable the
debugger; and if so, you will need the source code for
FreeType. We'll go through the procedure below; but first will
discuss problems and solutions for debugging Xgridfit code.
</p>
<p>
For Xgridfit users, the trouble with the FontForge debugger is
that it knows nothing about Xgridfit. It can be used to debug the
raw TrueType instructions generated by Xgridfit, but it does not
display the Xgridfit code in the debugger window. Without a pretty
thorough knowledge of TrueType and how Xgridfit generates
instructions, it can be difficult to identify an Xgridfit element
that is causing problems.
</p>
<p>
The solution is the Xgridfit debug mode, which, instead of a
FontForge or Python script, generates a file that shows exactly
what TrueType instructions are generated by every Xgridfit
element. If you are using the <tt>xgridfit</tt> command-line tool,
simply include the <tt>-d</tt> parameter:
</p>
<pre>
$ xgridfit -d Junicode-Bold.xgf</pre>
<p>
Now, instead of generating a script <tt>Junicode-Bold.pe</tt> or
<tt>Junicode-Bold.py</tt>, it generates a file
<tt>Junicode-Bold.debug</tt>. This file always contains output
for all functions and the <pre-program>. By default, it
generates output for every <glyph> in your Xgridfit
program. You can save time and generate a smaller file by using
the <tt>-g</tt> (glyph-select) parameter, thus:
</p>
<pre>
$ xgridfit -d -g amacron Junicode-Bold.xgf</pre>
<p>
And now the only glyph Xgridfit generates output for is <glyph
ps-name="amacron">.
</p>
<p>
The output of debug mode consists of the Xgridfit element
(sometimes omitting child elements that do not generate code)
enclosing the TrueType instructions generated from it. For
example, this element:
</p>
<pre>
<move distance="baseline">
<point num="bottom-a"/>
<align>
<point num="bottom-b"/>
</align>
</move></pre>
<p>
generates this output:
</p>
<pre>
<move distance="baseline">
<point num="bottom-a"/>
PUSHB_2
35
0
MIAP[rnd]
<align>
<point num="bottom-b"/>
PUSHB_1
9
ALIGNRP
</align>
</move></pre>
<p>
By comparing this output with the TrueType instructions in the
FontForge debugger, one can quickly locate an Xgridfit element
that is causing problems.
</p>
<p>
A couple of points. First, if you invoke Xgridfit directly using
an XSLT engine rather than the xgridfit script, run in debug mode
by using the XSLT script <tt>xgridfit-debug.xsl</tt> rather than
<tt>xgridfit.xsl</tt>. Second, be aware that you will see some
TrueType instructions in the output that do not belong to Xgridfit
elements. This is because Xgridfit inserts code of its own,
e.g. at the beginnings of glyph programs and at the beginnings and
ends of functions.
</p>
<h2>Activating the FontForge debugger</h2>
<p>
There are general instructions for building FontForge from source
and activating the debugger on the <a
href="http://fontforge.sourceforge.net/source-build.html">FontForge
site</a>. Here are some helpful pointers.
</p>
<p>
You will need the source code for FreeType2. Most Linux
distributions provide a convenient way to obtain it. For example,
in Debian or Ubuntu,
</p>
<pre>
$ apt-get source freetype2</pre>
<p>
should do it. Users of RPM-based distributions can easily obtain a
source RPM for FreeType. Once you have unpacked the source, you
need to find the file <tt>ftoption.h</tt>; it should be in
<tt>include/freetype/config/</tt> (assuming you are in the
FreeType base directory). Open this file with a text editor and
find a line that looks like this:
</p>
<pre>
/* #define TT_CONFIG_OPTION_BYTECODE_INTERPRETER */</pre>
<p>
Uncomment the line by removing the <tt>/*</tt> and <tt>*/</tt> and
save the file. Depending on your system configuration, you may or
may not have to build FreeType from source and install this new
version. On Ubuntu Linux you don't have to. On other systems it
may be necessary. One way to find out is to build FontForge and
see if the debugger works.
</p>
<p>
Note the location of the FreeType base directory (perhaps by
typing <tt>pwd</tt> at the command line) and then go to the
FontForge base directory. Run <tt>configure</tt> with a parameter
pointing out the location of the FreeType source code, e.g.
</p>
<pre>
$ ./configure --with-freetype-src=/path-to-freetype</pre>
<p>
If you don't use the <tt>--with-freetype-src</tt> parameter, the
configure script will <em>probably</em> find the FreeType source,
but will hang for a long time while looking for it.
</p>
<p>
Now do <tt>make</tt> and, if the build finishes successfully,
become root and run <tt>make install</tt>. If all has gone well,
you will be able to use the debugger next time you start
FontForge.
</p>
<p>
Note that Apple Computer Inc. owns several <a
href="http://freetype.sourceforge.net/patents.html">patents</a>
relating to the instructing of TrueType fonts. Strictly speaking,
you should not enable the FreeType bytecode interpreter unless you
have a license from Apple, you live in a country where the patent
does not apply, or you are willing to risk a lawsuit. It is
perhaps worth noting that Apple does not appear to have a history
of suing Open Source font developers.
</p>
</div>
</body>
</html>
|