/usr/share/doc/xgridfit/html/low-level.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 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 | <!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>
<hr/>
<a href="#command"><command></a>
<a href="#push"><push></a>
<a href="#to-stack"><to-stack></a>
</div>
<div id="content">
<h1>Low-level elements</h1>
<p>
Though Xgridfit tries to provide as much functionality as
possible in its high-level programming constructs, there may
well be times when you feel you need to write low-level, "raw"
instructions, either because Xgridfit does not meet some
particular need or because a job can be done most efficiently
with low-level instructions. Xgridfit provides three elements to
help you write low-level code.
</p>
<h2 id="command"><command></h2>
<p>
The <command> element will insert any TrueType instruction
into your Xgridfit program. If the command reads values from the
stack or writes to it, it is up to you to manage the stack
yourself. Here is a simple example:
</p>
<pre>
<command name="ALIGNRP"/>
</pre>
<p>
A number of instructions take one or more bits as modifiers. For
example, the MIAP instruction, which positions a point at a grid
coordinate read from the control-value table, takes a single
modifier bit that indicates whether the control-value should be
rounded before the point is positioned. The modifier can be
noted in more than one way, even when entered in FontForge:
</p>
<pre>
MIAP[1]
MIAP[rnd]
</pre>
<p>
There are two ways to insert modifiers in Xgridfit: one is
compact, easy and possibly non-portable, and the other is
verbose but portable. The compact method is to include a
<tt>modifier</tt> attribute containing a string which is to be
copied verbatim into Xgridfit's output code:
</p>
<pre>
<command name="MIAP" modifier="1"/>
<command name="MIRP" modifier="01100"/>
</pre>
<p>
The verbose method is to include one or more <modifier>
elements as children of <command>. Each element defines a
bit:
</p>
<pre>
<command name="MIAP">
<modifier type="round" value="yes"/>
</command>
<command name="MIRP">
<modifier type="set-rp0" value="no"/>
<modifier type="round" value="yes"/>
<modifier type="minimum-distance" value="yes"/>
<modifier type="color" value="gray"/>
</command>
</pre>
<p>
At present there is no advantage, aside from legibility (and who
cares about that?), to using <modifier>. But if Xgridfit
at some future time acquires the ability to produce input for
some font production program other than FontForge, the verbose
method is guaranteed to work while the compact method is not.
</p>
<p>
It is not necessary to provide a <modifier> for every bit
that can accompany an instruction: all modifier types have
defaults. Here are the modifier types, with all possible values,
and with defaults in bold:
</p>
<ul>
<li><tt>set-rp0</tt>: <b>yes</b>, no.</li>
<li><tt>round</tt>: <b>yes</b>, no.</li>
<li><tt>minimum-distance</tt>: <b>yes</b>, no.</li>
<li><tt>color</tt>: <b>gray</b>, black, white.</li>
<li><tt>grid-fitted</tt>: <b>yes</b>, no.</li>
<li><tt>to-line</tt>: <b>parallel</b>, orthogonal.</li>
<li><tt>axis</tt>: <b>x</b>, y.</li>
<li><tt>ref-ptr</tt>: <b>1</b>, 0.</li>
</ul>
<p>
If you are planning to write low-level code, you presumably know
already which instructions have modifier bits and what those
bits do. If you do not, consult the <a
href="http://developer.apple.com/textfonts/TTRefMan/index.html">TrueType
Reference Manual</a>.
</p>
<h2 id="push"><push></h2>
<p>
Many TrueType instructions operate upon values they pop from the
stack; thus you must have have a way to move values onto the
stack. TrueType provides a variety of PUSH instructions,
depending on how the values are stored in the program code (as
bytes or words) and how many values need to be pushed. Xgridfit
reduces this variety to a single element: <push>, which
takes a list of values. These are valid Xgridfit <push>
instructions:
</p>
<pre>
<push>2 5 89 67</push>
<push>
left
right
lc-vertical-stem
-1
</push>
<push> 0.58p 2.0 to-grid </push>
<push>1 (top + 3) 512</push>
<push>minimum-distance</push>
</pre>
<p>
Notice that all expressions containing whitespace must be
enclosed in parentheses.
</p>
<p>
The Xgridfit <push> element may invoke the TrueType PUSHB
and PUSHW instructions, which push number literals onto the
stack; but it can also handle variables and other values that
can be resolved only at run-time. In other words, it is a
general-purpose element for moving numbers of all kinds onto the
stack. The list of values in a single <push> element can
be heterogeneous: some bytes, some words, some variables.
</p>
<p>
Here is an example of the use of <push> in a fragment
of code from a function, in which the point <tt>line-2-a</tt>
and the control-value <tt>cvt</tt> have been passed in as
parameters:
</p>
<pre>
<push>line-2-a cvt</push>
<command name="MIRP">
<modifier type="color" value="black"/>
</command>
</pre>
<p>
This code fragment also shows, incidentally, how a
<command> element can be abbreviated by accepting
defaults. It is functionally the same as this:
</p>
<pre>
<command name="MIRP">
<modifier type="set-rp0" value="yes"/>
<modifier type="minimum-distance" value="yes"/>
<modifier type="round" value="yes"/>
<modifier type="color" value="black"/>
</command>
</pre>
<h2 id="to-stack"><to-stack></h2>
<p>
<to-stack>, an element for moving a single value onto the
stack, is deprecated as of Xgridfit version 1.11, as
<push> can perform the same function.
</p>
</div>
</body>
</html>
|