| 1 |
<!DOCTYPE html> |
| 2 |
<html lang="en-us"> |
| 3 |
<head> |
| 4 |
<meta charset="utf-8"> |
| 5 |
<title>Harmattan - Developer information</title> |
| 6 |
<meta name="author" content="SIL Writing Systems Technology"> |
| 7 |
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes"> |
| 8 |
<link rel="stylesheet" href="./assets/css/theme.css"> |
| 9 |
<link rel="stylesheet" href="./assets/css/webfonts.css"> |
| 10 |
</head> |
| 11 |
<body> |
| 12 |
<div class="container"> |
| 13 |
<article class="article"> |
| 14 |
<header> |
| 15 |
<h1 class="title">Harmattan - Developer information</h1> |
| 16 |
</header> |
| 17 |
<h2 id="welcome-font-developers">Welcome font developers!</h2> |
| 18 |
<p>We welcome other developers who wish to get involved in supporting and enhancing these fonts or who want to modify them.</p> |
| 19 |
<h2 id="permissions-granted-by-the-ofl">Permissions granted by the OFL</h2> |
| 20 |
<p>SIL’s fonts are licensed according to the terms of the <a href="https://scripts.sil.org/OFL">SIL Open Font License</a>. The OFL allows the fonts to be used, studied, modified and redistributed freely as long as they are not sold by themselves. For details see the OFL.txt and OFL-FAQ.txt files in the package.</p> |
| 21 |
<h2 id="building-the-fonts-from-source-code">Building the fonts from source code</h2> |
| 22 |
<p>Font sources are published in a <a href="https://github.com/silnrsi/font-harmattan">Github project</a>. The build process requires <a href="https://github.com/silnrsi/smith">smith</a> and project build parameters are set in the <a href="https://github.com/silnrsi/smith/blob/master/wscript">wscript</a>.</p> |
| 23 |
<p>Font sources are in the <a href="http://unifiedfontobject.org/versions/ufo3/">UFO3</a> format with font family structures defined using <a href="https://github.com/fonttools/fonttools/tree/master/Doc/source/designspaceLib">designspace</a>. OpenType source code is stored in the <a href="https://adobe-type-tools.github.io/afdko/OpenTypeFeatureFileSpecification.html">.fea</a> format in the UFO (features.fea) but is maintained in a separate file using the more efficient and powerful <a href="https://github.com/silnrsi/pysilfont/blob/master/docs/feaextensions.md">.feax</a> format.</p> |
| 24 |
<p>The fonts are built using a completely free and open source workflow using industry-standard tools (<a href="https://github.com/fonttools/fonttools">fonttools</a>), a package of custom python scripts (<a href="https://github.com/silnrsi/pysilfont">pysilfont</a>), and a build and packaging system (<a href="https://github.com/silnrsi/smith">Smith</a>). The whole system is available in a preconfigured virtual machine using VirtualBox and Vagrant.</p> |
| 25 |
<p>Full instructions for setting up the tools and building SIL fonts are available on a dedicated web site: <a href="https://silnrsi.github.io/silfontdev/">SIL Font Development Notes</a>.</p> |
| 26 |
<h2 id="building">Building</h2> |
| 27 |
<p>The Harmattan project can be built from source using <a href="https://github.com/silnrsi/smith">smith</a>. This is done via the sequence:</p> |
| 28 |
<pre><code> smith distclean |
| 29 |
smith configure |
| 30 |
smith build |
| 31 |
smith alltests</code></pre> |
| 32 |
<p>Because of the complex kerning and collision avoidance logic, builds can take up to 15 minutes or longer, depending on hardware. If the complex kerning is <em>not</em> needed (such as for debugging other font logic), the <code>--quick</code> parameter can be supplied:</p> |
| 33 |
<pre><code> smith distclean |
| 34 |
smith configure |
| 35 |
smith build --quick</code></pre> |
| 36 |
<p>The resulting files will not have functional kerning or collision avoidance, but will be otherwise usable.</p> |
| 37 |
<h3 id="adding-characters">Adding characters</h3> |
| 38 |
<p>After base characters to the font, the following files will also need updating: - <code>glyph_data.csv</code> -- used to set glyph orders and psnames in the built font - <code>classes.xml</code> -- used to define classes used by both OpenType and Graphite. Note that some of the classes defined therein are noted to be "automatically generated" -- these will be updated (from glyph_data.csv) the next time <code>./preflight</code> is run. - <code>opentype/*.feax</code> -- modify as needed to add needed OpenType behavior - <code>graphite/*.gd*</code> -- modify as needed to add needed Graphite behavior - <code>tests/*.ftml</code> -- see below</p> |
| 39 |
<p>Additionally the <code>*-octabox.json</code> files will need to be regenerated in order to add optimal octaboxes for the isolate and initial forms of the newly added characters. If unencoded variants of isolate and initial forms have been added, these must be manually added to the <code>cComplexShape</code> class defined in <code>source/graphite/caBasedKerning.gdl</code> so they get optimized as well.</p> |
| 40 |
<h3 id="generated-source-files">Generated source files</h3> |
| 41 |
<p>Five of the source files needed for the build are actually generated files but, because they require compute-intensive tools to create or update, are generated offline and committed to the repo. The files that fall into this category are: - <code>source/kerndata.ftml</code> — contains strings with all possible combinations of reh-like and following initials or isolates. This is used to extract graphite collision-avoidance-based kerning data. - <code>source/*-octabox.json</code> — optimized octaboxes to enable Graphite to do more accurate kerning of reh-like characters to what follows. - <code>source/opentype/caKern-*.fea</code> — contextual kerning rules that approximate the kerning effected by the Graphite collision avoidance.</p> |
| 42 |
<p>If the <em>design</em> of any Arabic glyphs in the font changes, it is important to rebuild the optimized octabox.json files so that Graphite collision-avoidance-based kerning is accurate, and then to rebuild the OpenType kerning rules from the graphite results. A script to do this is in <code>tools/bin/updateKerning.sh</code>. This should be run from the root of the project. Be aware this can take up to 30 minutes or more to complete.</p> |
| 43 |
<p>Important notes: The <code>updateKerning.sh</code> tool requires: - fully functioning <a href="https://github.com/silnrsi/smith"><code>smith</code></a> build system - a Graphite-enabled Harfbuzz library - a Graphite library with tracing enabled. The library provided by default Ubuntu does not include tracing. You'll need to compile the source with -DGRAPHITE2_NTRACING:BOOL=OFF - the <a href="https://scikit-learn.org/">scikit-learn</a> python module. For ubuntu try:</p> |
| 44 |
<pre><code> sudo apt-get install python3-sklearn python3-sklearn-lib</code></pre> |
| 45 |
<h3 id="generated-test-files">Generated test files</h3> |
| 46 |
<p>After adding characters or additional behaviors to the font, test files should be created or enhanced to test the new behaviors. The test files: - <code>tests/AllChars-auto.ftml</code> - <code>tests/ALsorted-auto.ftml</code> - <code>tests/DaggerAlef-auto.ftml</code> - <code>tests/Diac1-auto.ftml</code> - <code>tests/Diac1-short-auto.ftml</code> - <code>tests/Kern-auto.ftml</code> - <code>tests/SubtendingMarks-auto.ftml</code> - <code>tests/Yehbarree-auto.ftml</code></p> |
| 47 |
<p>are generated automatically using <code>tools/bin/genftmlfiles.sh</code>.</p> |
| 48 |
<p><code>tools/ftml.xsl</code> can be used to view ftml documents directly in Firefox (which supports both Graphite and OpenType rendering).</p> |
| 49 |
<h3 id="about-ftml-tests">About ftml tests</h3> |
| 50 |
<p>After a successful build, the results/ folder will contain, along with the built ttf and woff fonts, a number of test files in an xml-based format called FTML. Examples are AllChars-auto.ftml, DiacTest1-auto.ftml. There is an ftml.xsl file that can be used to view these ftml documents directly in Firefox.</p> |
| 51 |
<p>However, in order for Firefox to access the .xsl file, you need to relax its "strict URI" policy by going to about:config and setting <a href="http://kb.mozillazine.org/Security.fileuri.strict_origin_policy">security.fileuri.strict_origin_policy</a> to false.</p> |
| 52 |
<p>Once you have this setting in effect, you can load the FTML documents directly into Firefox and see the built font rendered.</p> |
| 53 |
<h2 id="contributing-to-the-project">Contributing to the project</h2> |
| 54 |
<p>We warmly welcome contributions to the fonts, such as new glyphs, enhanced smart font code, or bug fixes. The <a href="https://silnrsi.github.io/silfontdev/en-US/Contributing_Changes.html">brief overview of contributing changes</a> is a good place to begin. The next step is to contact us by responding to an existing issue or creating an issue in the Github repository and expressing your interest. We can then work together to plan and integrate your contributions.</p> |
| 55 |
<p>To enable us to accept contributions in a way that honors your contribution and respects your copyright while preserving long-term flexibility for open source licensing, you would also need to agree to the <strong>SIL International Contributor License Agreement for Font Software (v1.0)</strong> prior to sending us your contribution. To read more about this requirement and find out how to submit the required form, please visit the <a href="https://software.sil.org/fontcla">CLA information page</a>.</p> |
| 56 |
<footer class="footer"> |
| 57 |
<p>This guide is from the <a href="https://software.sil.org/harmattan/" title="" class="active">Harmattan project</a> version 4.000 and is copyright © 2014-2023 SIL International.</p> |
| 58 |
</footer> |
| 59 |
</article> |
| 60 |
</div> |
| 61 |
</body> |
| 62 |
</html> |