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
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
|
<?xml version="1.0" encoding="utf-8"?>
<!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="http://sflogo.sourceforge.net/sflogo.php?group_id=159705&type=4" 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="#preparing">Preparing files for merging</a>
<a href="#xgfmerge">How xgfmerge merges files</a>
<a href="#storage">The Storage Area</a>
<a href="#composite">Instructing composite glyphs</a>
<a href="#xinclude">XIncludes from other files</a>
<a href="#multiple">Merging multiple files</a>
<a href="#example">Example</a>
</div>
<div id="content">
<h1>Collaborating with the FontForge auto-instructor</h1>
<p>
<i>The method described here is deprecated, though it does still
work. For a simpler method, click <a href="merge-mode.html">this
link</a>.</i>
</p>
<p>
Recent versions of FontForge do an excellent job of "writing"
instructions for TrueType fonts. You have only to follow these
simple steps:
</p>
<ol>
<li>
Use Hints-->Remove Instr Tables to delete everything relating to
TrueType instructions.
</li>
<li>
Use Element-->Font Info-->PS Private to insert "BlueValues,"
"OtherBlues" and "BlueFuzz."
</li>
<li>
In Font View, type Ctrl-A to select all glyphs.
</li>
<li>
Use Hints-->AutoHint to add hints to the font.
</li>
<li>
With all glyphs still selected, use Hints-->AutoInstr to add
instructions to the font.
</li>
</ol>
<p>
Now, if you generate the font and view it with ftview, you will
see that your font is well "hinted."
</p>
<p>
But auto-instructing may not please you for every glyph. You may
want finer control over the most commonly displayed characters in
your font, or you may want to add deltas and other refinements to
the instructions generated by FontForge. If so, Xgridfit comes
with tools that make it easy to collaborate with the FontForge
auto-instructor. The steps to follow are straightforward:
</p>
<ol>
<li>
Generate an Xgridfit program (call it <tt>file-a.xgf</tt>) from
the auto-instructed font created by FontForge (see <a
href="convert.html">Converting Existing Instructions</a>).
</li>
<li>
Write your own glyph programs (functions, macros and anything
else) in one or more separate files (<tt>file-b.xgf</tt> and
possibly others), and/or copy FontForge glyph programs that you
wish to revise into these files.
</li>
<li>
When you have completed your own programming and revisions,
merge <tt>file-a.xgf</tt> and the other files using
<tt>xgfmerge</tt>, a utility supplied with Xgridfit.
</li>
<li>
Compile the merged file as usual and run the generated
FontForge script to create a font containing a mix of
auto-instruction and custom programming.
</li>
</ol>
<p>
Note that, while the method outlined here was developed with the
FontForge auto-instructor in mind, it should be useful for any
TrueType font that contains instructions, if you wish to maintain
your own added or revised instructions in separate files.
</p>
<p>
Details and complications are described in the following sections.
</p>
<h2 id="preparing">Preparing files for merging</h2>
<p>
The file here called <tt>file-a.xgf</tt> is an Xgridfit program
extracted from a font containing instructions <a
href="convert.html">generated by FontForge</a>. Once you have
created this file you should not edit it, though you may open it
to copy out control values and glyph programs.
</p>
<p>
The other files (we'll pretend there is just one,
<tt>file-b.xgf</tt>) constitute an Xgridfit program that you have
written. There are several restrictions on this file. Any
functions it contains should not have the <tt>num</tt> attribute,
as these are not compatible with the <legacy-functions>
element that <tt>file-a.xgf</tt> almost certainly contains. In
general, it should not already contain legacy programming—that is,
programming taken from an existing font using TTX and
<tt>ttx2xgf</tt>. This is because two <legacy-functions>
elements cannot be merged, and because hard-coded (numerical)
references to control values and functions will break in this file
(but not in <tt>file-a.xgf</tt>) when the two files are merged.
</p>
<p>
If <tt>file-b.xgf</tt> contains only a little legacy programming,
the situation is not hopeless. You can convert numerical
references to control values and functions into symbolic ones
pretty easily. You'll need to search for MIRP and MIAP
instructions and change the <push> elements that precede
them. For example, this sequence:
</p>
<pre>
<push>5 10</push>
<command name="MIRP" modifier="11100"/></pre>
<p>
could become this (remembering that, since control values are
indexed from zero, the <control-value> with index 10 will
actually be the eleventh <control-value> in the list):
</p>
<pre>
<push>5 lc-vert-stem</push>
<command name="MIRP" modifier="11100"/></pre>
<p>
Likewise function numbers in <push> elements can be replaced
with function names.
</p>
<p>
You can use XIncludes and the <no-compile> element in
<tt>file-b.xgf</tt> to import glyph programs and other material
from <tt>file-a.xgf</tt>. These are ignored when xgfmerge runs
(see below for <a href="#xinclude">XIncludes from other
files</a>).
</p>
<h2 id="xgfmerge">How <tt>xgfmerge</tt> merges files</h2>
<p>
When you run <tt>xgfmerge</tt>, it applies these rules in merging
<tt>file-a.xgf</tt> and <tt>file-b.xgf</tt>:
</p>
<ul>
<li>
<glyph-select>, <infile>, <outfile>,
<outfile-base> and <outfile-script-name>
are taken from <tt>file-b.xgf</tt> if available; if not, they
are taken from <tt>file-a.xgf</tt>.
</li>
<li>
<no-compile> is ignored unless you ask for it via the
<tt>-n</tt> option. The <no-compile> element in the
merged file will contain all the <glyph> elements
contained in the <no-compile> elements of all the files
being merged. Duplicate <glyph> elements are omitted.
</li>
<li>
If a <default> element with attribute
<tt>type="legacy-storage"</tt> is present in <tt>file-a.xgf</tt>
(and it probably is), its value is compared with the value of a
<default> element with <tt>type="max-storage"</tt> (if
present) in <tt>file-a.xgf</tt>. The greater of these, which may
be no less than 64, is added to the value of a <default>
element with <tt>type="max-storage"</tt> in <tt>file-b.xgf</tt>
(this is also not permitted to be less than 64). This sum (which
may not be less than 128) becomes the value of a new
<default> element with <tt>type="max-storage"</tt>.
</li>
<li>
The value of a <default> element with
<tt>type="max-stack"</tt> in <tt>file-a.xgf</tt> is compared
with the same element in <tt>file-b.xgf</tt>, and the larger is
used as the value of a new <default> element with
<tt>type="max-stack"</tt>. If either <default> element is
not present the default value of 256 is assumed; if the result
of the comparison is 256, no <default> element is
generated.
</li>
<li>
Other <default> elements are copied from
<tt>file-b.xgf</tt> when available, otherwise from
<tt>file-a.xgf</tt>.
</li>
<li>
Global <constant>, <alias>, <variable> or
<round-state> elements are taken from <tt>file-b.xgf</tt>
when available. Any of these elements in <tt>file-a.xgf</tt>
whose <tt>name</tt> elements do not clash with those in
<tt>file-b.xgf</tt> are also taken.
</li>
<li>
<control-value> elements from <tt>file-a.xgf</tt> are all
retained in their original order. However, if a
<control-value> in <tt>file-b.xgf</tt> has the same name
as one in <tt>file-a.xgf</tt>, its value is used instead of the
one from <tt>file-a.xgf</tt>.
</li>
<li>
<control-value> elements from <tt>file-b.xgf</tt> are all
retained, positioned after the ones from <tt>file-a.xgf</tt>. Any
<control-value> with the same name as one in <tt>file-a.xgf</tt>
is skipped, since that one has already been inserted above.
</li>
<li>
The <legacy-functions> element from <tt>file-a.xgf</tt> is
copied exactly. <tt>file-b.xgf</tt> should not contain
<legacy-functions>.
</li>
<li>
<function> elements from <tt>file-a.xgf</tt> are retained,
though there probably should be none. Any <function> with
the same name as one in <tt>file-b.xgf</tt> is skipped.
</li>
<li>
<function> elements from <tt>file-b.xgf</tt> are retained.
</li>
<li>
<macro> elements are treated like <function> elements.
</li>
<li>
The <pre-program> is constructed by merging programming
from <tt>file-a.xgf</tt> and <tt>file-b.xgf</tt>. First
<alias> and <variable> elements are copied from both
places (though there should be none in <tt>file-a.xgf</tt>),
then programming from <tt>file-a.xgf</tt> is copied, and finally
programming from <tt>file-b.xgf</tt>. If the <tt>-p</tt> option
is present, the <pre-program> from <tt>file-b.xgf</tt> is
substituted for the one in <tt>file-a.xgf</tt>, if available; if
not, the one in <tt>file-a.xgf</tt> is retained.
</li>
<li>
<glyph> elements from <tt>file-a.xgf</tt> are copied, but
any whose <tt>ps-name</tt> attribute matches that of a <glyph>
in <tt>file-b.xgf</tt> is skipped.
</li>
<li>
<glyph> elements from <tt>file-b.xgf</tt> are copied.
</li>
</ul>
<p>
These rules are designed to produce a file in which two basically
independent sets of glyph programs coexist peacefully. If the
programming in <tt>file-b.xgf</tt> has been correctly written
(without hard-coded references to control values, functions and
the storage area), the merger should be invisible to
end-users. Complications, inevitable in such an undertaking as
this, are discussed below.
</p>
<h2 id="storage">The Storage Area</h2>
<p>
Xgridfit and its utilities are extremely cautious about the
TrueType Storage Area, which is where Xgridfit stores information
about the graphics state and the variables you declare. The reason
for this caution is that, when insufficient storage is declared in
an Xgridfit program, strange bugs can appear in areas of the program
apparently unrelated to storage. So the default size of the
Storage Area for Xgridfit programs is 64 (though few Xgridfit
programs need so much), and <tt>ttx2xgf</tt> always reserves at
least 64 storage locations for "legacy storage" in a converted
font, no matter what information it finds in the font itself. The
minimum storage reserved in an Xgridfit program produced by
<tt>xgfmerge</tt> is 128.
</p>
<p>
This is almost certainly more storage than you need, especially
since the FontForge auto-instructor claims to use none at
all. Before generating a production version of your font, you may
wish to experiment with the <default type="legacy-storage">
and <default type="max-storage"> elements in your merged
Xgridfit file. Try commenting out the <default
type="legacy-storage"> element; if the value of <default
type="max-storage"> is 64, see how much you can reduce it
before your programming breaks.
</p>
<h2 id="revising">Revising FontForge's instructions</h2>
<p>
You can revise the instructions generated by FontForge, refining
them or inserting deltas. The recommended method is to copy the
glyph program you want to revise from <tt>file-a.xgf</tt> to
<tt>file-b.xgf</tt> and revise it there (start by deleting the
<tt>init-graphics</tt> attribute if you plan to insert any
Xgridfit programming). Copying the <glyph> will protect it
from being overwritten if you run the auto-instructor again.
</p>
<p>
There is a danger, however, that references to control values and
functions will become obsolete if you re-run the auto-instructor
and regenerate <tt>file-a.xgf</tt>. The best solution, of course,
would be to do this work late enough that it is not necessary to
run the auto-instructor again. If you must, however, you can take
several steps to protect this programming. Here are some tips.
</p>
<ul>
<li>
Use XInclude to import control values from
<tt>file-a.xgf</tt>. The <xi:include> element that does
this must come before any <control-value> elements in
<tt>file-b.xgf</tt>. Insert <alias> elements in
<tt>file-b.xgf</tt> referring to these <control-values>,
and use comments to indicate their original values, e.g.
<pre>
<alias name="ff-cv-ab" target="cv-01"/> <!-- 345 --></pre>
Finally, locate the references to control values in the glyph
program(s) you have copied from <tt>file-a.xgf</tt> and change
them to refer instead to the aliases you've made. You can locate
the places that need revision by searching for MIRP and MIAP
instructions:
<pre>
<push>5 ff-cv-ab</push>
<command name="MIRP" modifier="11111"/></pre>
Now, if you have to re-run the auto-instructor, you only need to
check your list of <aliases> and edit it if necessary.
</li>
<li>
Use XInclude to import <legacy-functions> from
<tt>file-a.xgf</tt>. Use <constant> elements to create
named references to the functions contained in
<legacy-functions>, and revise the <push> elements
that immediately precede CALL and LOOPCALL instructions:
<pre>
<push>1 ff-func-aa</push>
<command name="CALL"/></pre>
If you have to re-run the auto-instructor, you only need to
check these <constant> elements.
</li>
<li>
You may (or may not) find it useful to name some points in the
<glyph> programs you've pasted from
<tt>file-a.xgf</tt>. If so, simply insert <constant>
elements into the glyph programs after you've pasted them.
</li>
</ul>
<p>
You can freely mix Xgridfit programming with the <push> and
<command> elements imported from <tt>file-a.xgf</tt>. You
can substitute high-level Xgridfit elements for these low-level
elements, and you can add <delta> and any other elements you
like.
</p>
<h2 id="composite">Instructing composite glyphs</h2>
<p>
FontForge does not auto-instruct glyphs that are made of
references to other glyphs. Yet it is often desirable to write
some minimal instructions for these, to make sure that accents do
not collide with base characters and are correctly positioned
horizontally. When you instruct glyphs that have been
auto-instructed by FontForge, programming for the accent and base
glyph is likely to be in <tt>file-a.xgf</tt> while programming for
the composite glyphs is in <tt>file-b.xgf</tt>. This raises
special problems—at least if, as recommended, you avoid editing
<tt>file-a.xgf</tt>, which contains only automatically generated
code.
</p>
<p>
The method recommended here is that you use XInclude to import
into <no-compile> the programs for the glyphs that are the
targets of the references in your composite glyph. Then, since you
cannot insert <constant> elements in those target glyph
programs, make some useful <constant> elements: some global
and others in the composite glyph itself, as appropriate. Thus:
</p>
<pre>
<no-compile>
<xi:include href="file-a.xgf#a"/>
<xi:include href="file-a.xgf#macron"/>
</no-compile>
<constant name="a-top" value="34"/>
<constant name="a-total" value="56"/>
<constant name="macron-bottom" value="3"/>
<constant name="macron-left" value="5"/>
<glyph name="amacron">
<constant name="mark-bottom" value="a-total + macron-bottom"/>
<constant name="mark-left" value="a-total + macron-left"/>
<constant name="mark-contour" value="2"/>
<set-vectors axis="y"/>
<call-function name="ensure-diacritic-gap">
<with-param name="char-top" value="a-top"/>
<with-param name="diacritic-bottom" value="mark-bottom"/>
<with-param name="diacritic-contour" value="mark-contour"/>
</call-function>
<set-vectors axis="x"/>
<delta>
<point num="mark-left"/>
<delta-set size=3" distance="8"/>
<delta-set size=5" distance="8"/>
</delta>
<shift>
<reference>
<point num="mark-left"/>
</reference>
<contour num="mark-contour"/>
</shift>
</glyph></pre>
<h2 id="xinclude">XIncludes from other files</h2>
<p>
The sections above assume that all of your XIncludes come from
<tt>file-a.xgf</tt>. It is a minor complication if some of your
XIncludes come from that file and some from elsewhere (e.g. a
library of functions or another font). If this is the case, use
xgfmerge's <tt>-x</tt> option to resolve XIncludes before merging
files:
</p>
<pre>
$ xgfmerge -x file-a.xgf file-b.xgf > new-file.xgf</pre>
<p>
The <tt>-x</tt> option causes xgfmerge to suppress any XIncludes
from <tt>file-a.xgf</tt>; only those from other files are
included. Note, however, that for XIncludes from
<tt>file-a.xgf</tt> to be suppressed, the filename on the command
line must be identical with that in the <tt>href</tt> attribute of
the <xi:include> element. If one of these is, say, the name
of a symlink, or if the form in the <tt>href</tt> attribute is
<tt>file-a.xgf</tt> while that on the command line is
<tt>./file-a.xgf</tt>, then xgfmerge will not recognize that the
two filenames refer to the same file.
</p>
<p>
Xgfmerge does not copy <xi:include> elements literally into
the merged file. It must either resolve them (only in files other
than <tt>file-a.xgf</tt>) or ignore them.
</p>
<h2 id="multiple">Merging multiple files</h2>
<p>
Xgfmerge is happy to merge multiple files with the one
automatically generated file named first on the command
line. Given a command line like this one:
</p>
<pre>
$ xgfmerge -o final.xgf file-a.xgf file-b.xgf file-c.xgf</pre>
<p>
the merge program is first run for <tt>file-a.xgf</tt> and
<tt>file-b.xgf</tt>, and then once more for the result of the
first merge and <tt>file-c.xgf</tt>. You can use wildcard
filenames (e.g. <tt>MyFont*.xgf</tt>) as well as a list.
</p>
<p>
As explained above, the rules for the first file in the list
(<tt>file-a.xgf</tt>) are different from those for the second
(<tt>file-b.xgf</tt>). When you merge multiple files, "file-b"
rules are applied to <i>all</i> files after the first in the list,
and "file-a" rules are applied to all the intermediate
results. It's as if you ran these two commands:
</p>
<pre>
$ xgfmerge -o intermediate.xgf file-a.xgf file-b.xgf
$ xgfmerge -o final.xgf intermediate.xgf file-c.xgf</pre>
<p>
The rules applied by xgfmerge are meant to be friendly to such
multiple merges; and yet the program may at times operate with
unnecessary redundancy, raising the possibility of error. This is
particularly true when the <tt>-x</tt> option is used to bring in
XIncludes. Then, since you are likely to have imported, say,
<control-value> elements into all your files, these will be
merged over and over again. The result should not be duplicate
<control-value> elements, and yet it seems worthwhile to
avoid such redundancy.
</p>
<p>
You can do so if you have routinely used the "compile-globals"
default to suppress compilation of global elements. In general,
<control-value>, <function> and other global elements
should be compiled in only one of the files that constitute the
programming for a single font. This element suppresses it in the
others:
</p>
<pre>
<default type="compile-globals" value="no"/></pre>
<p>
If you include the <tt>-c</tt> option on the <tt>xgfmerge</tt>
command line, the program will look for that <default>
element in each file after the first, and it will ignore those
global elements in any file where it is found. In general, you
should consider using the <tt>-c</tt> option whenever you are
merging multiple files with the <tt>-x</tt> option.
</p>
<h2 id="example">Example</h2>
<p>
For an example, see <a href="tutorial3.html">Tutorial 3</a>.
</p>
</div>
</body>
</html>
|
