Debian Codegraph @

documentation/source/developer.md

raw
1 ---
2 title: Awami Nastaliq - Developer information
3 fontversion: 3.200
4 ---
5
6 ## Welcome font developers!
7
8 We welcome other developers who wish to get involved in supporting and enhancing these fonts or who want to modify them.
9
10 ## Permissions granted by the OFL
11
12 SIL’s fonts are licensed according to the terms of the [SIL Open Font License](https://scripts.sil.org/OFL). 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.
13
14 ## Building the fonts from source code
15
16 Font sources are published in a [Github project](https://github.com/silnrsi/font-awami). The build process requires [smith](https://github.com/silnrsi/smith) and project build parameters are set in the [wscript](https://github.com/silnrsi/smith/blob/master/wscript).
17
18 Font sources are in the [UFO3](http://unifiedfontobject.org/versions/ufo3/) format with font family structures defined using [designspace](https://github.com/fonttools/fonttools/tree/master/Doc/source/designspaceLib). There is no OpenType code in this font, but the font does use the Graphite smart font technology.
19
20 The fonts are built using a completely free and open source workflow using industry-standard tools ([fonttools](https://github.com/fonttools/fonttools)), a package of custom python scripts ([pysilfont](https://github.com/silnrsi/pysilfont)), and a build and packaging system ([smith](https://github.com/silnrsi/smith)). The whole toolchain is available as a Docker container.
21
22 Full instructions for setting up the tools and building SIL fonts are available on a dedicated web site: [SIL Font Development Guide](https://silnrsi.github.io/silfontdev/).
23
24 ### Building
25
26 The Awami Nastliq project can be built from source using [smith](https://github.com/silnrsi/smith). This is done via the sequence:
27 ```
28 smith distclean
29 smith configure
30 smith build -v -j1
31 ```
32
33 Because of the complex kerning and collision avoidance logic, builds can take up to 15 minutes or longer, depending on hardware.
34
35 #### Some useful `smith build` options
36
37 `-v` makes the output slightly more verbose, specifically including the "runner" information showing the actual commands smith is executing.
38
39 `-j` controls parallel processing. Depending on your machine's memory, `smith build` sometimes fails due to the intense computation requirements of the Awami build. If this occurs, `-j1` or `-j2` can be used to restrict parallel processing, although this slows the build process somewhat. The number after the `-j` indicates the number of tasks smith will try to do in parallel.
40
41 `-d` should normally be omitted when building the fonts. However, when developing/debugging a font using Graide, the `-d` must be used to prevent some optimizations that are incompatible with Graide.
42
43 `--regOnly` causes smith to build the Regular weight only. This is useful during development and debugging.
44
45 ## Modifying the font
46
47 ### Project documentation
48
49 A good deal of developer documentation for the Awami Nastaliq font can be found at the [Awami GitHub repository](https://github.com/silnrsi/font-awami/documentation/developer).
50
51 ### Adding characters
52
53 Like most Nastaliq fonts, Awami takes a "decomposition" approach, where initial, medial, and final forms are constructed at rendering time from separate base glyphs and nuqtas and other inherent parts of characters. This means that adding a new character will likely require only adding the isolate form along with its USV encoding.
54
55 After adding new glyphs to the font, the shaping logic will need to be extended to handle them. The bulk of the code is found in:
56 - `nastaliq_classes.gdh`
57 - `nastaliq_cntxlClasses.gdh`
58 - `nastaliq_shaping.gdh`
59 - `nastaliq_rules.gdh`.
60
61 A helpful approach is to do a global search through the code for a character with similar behavior and add glyphs for the new character in all the corresponding places.
62
63 In addition, the following will need to be updated:
64 - `glyph_data.csv` -- should include all glyphs in the font; it is used to set glyph order in the built font.
65 - `nastaliq_complexShapes.gdh` -- needs to include any glyphs who shapes cannot be approximated by a simple polygon for the purposes of kerning, particularly those with concave portions.
66 - "Octabox" data will need to be updated for all the weights of the font; see below.
67 - `ftml_test_gen.py` -- should include the new character in order for it to be included in the automatically generated test files.
68
69 ### Generating octaboxes
70
71 "Octaboxes" are polygons that approximate the shape of the glyphs; these are used for kerning and fixing collisions. There is an octabox JSON file for each font weight. Whenever new glyphs are added or glyph shapes are signficantly modified, the octaboxes should be regenerated.
72
73 Before any octabox can be updated, the ttf file for the corresponding font must be in the `results/` folder, so you first need to build the fonts (see above). Then the command to update a single octabox is:
74 ```
75 octalap -j 0 -q -o source/graphite/octabox_AwamiNastaliq-WEIGHT.json results/AwamiNastaliq-WEIGHT.ttf
76 ```
77
78 where WEIGHT is Regular, Bold, etc. As given above, the command must be run from the root of the project. The command must be executed for each weight, and each will take several minutes to execute.
79
80 Alternatively, there is a script in the `tools/` folder called `run_octalap` which, if run from the `tools/` folder, will update all the octaboxes:
81 ```
82 cd tools
83 ./run_octalap
84 ```
85
86 In order to use the newly generated octaboxes the font must then be rebuilt.
87
88 ### Auto-generated test files
89
90 The project includes a Python program `tools/scripts/ftml_test_gen.py` that can generates test data in a form of XML called FTML (see below). A variety of test files can be built, covering various combinations of base characters and diacritics:
91 - `basicforms` - only one character of each shape class is included, no diacritics
92 - `allbasechars` - all base characters, no diacritics
93 - `basic_somediac` - only one character of each shape class with one lower and one upper diacritics
94 - `basic_alldiac` - only one character of each shape class with all diacritics
95 - `allbasecharforms` - all characters and diacritics are included (this creates a huge file!)
96
97 The test file builder is called as follows:
98 ```
99 python3 tools/scripts/ftml_test_gen.py
100 ```
101 which generates files for all five modes, or
102 ```
103 python3 tools/scripts/ftml_test_gen.py -m MODE
104 ```
105
106 These files are not automatically generated by the build.
107
108 #### Modifying `ftml_test_gen.py`
109
110 When new characters are added to the font, they should be added to `ftml_test_gen.py`.
111 - Assign the character a short code and associated it with the USV the `_char_name_to_usv()` function.
112 - Add details about the character to the `_group_name_format()` or `_diac_group_name_format()` function.
113 - Add the code to the appropriate list in the `expand_sequences()` or `insert_diacritics()` function.
114
115
116 `tools/ftml.xsl` can be used to view ftml documents directly in Firefox (which supports both Graphite rendering).
117
118 #### Viewing FTML test files
119
120 The `ftml.xsl` file is used to view the FTML files in Firefox. Firefox is needed to both handle the XSL transforms as well as provide Graphite render.
121
122 However, in order for Firefox to access the .xsl file, you need to relax its "strict URI" policy by going to about:config and
123 setting [security.fileuri.strict_origin_policy](http://kb.mozillazine.org/Security.fileuri.strict_origin_policy) to false.
124
125 Once you have this setting in effect, you can load the FTML documents directly into Firefox and see the built font rendered.
126
127 ## Contributing to the project
128
129 We warmly welcome contributions to the fonts, such as new glyphs, enhanced smart font code, or bug fixes. The [brief overview of contributing changes](https://silnrsi.github.io/silfontdev/en-US/Contributing_Changes.html) 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.
130
131 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 **SIL International Contributor License Agreement for Font Software (v1.0)** prior to sending us your contribution. To read more about this requirement and find out how to submit the required form, please visit the [CLA information page](https://software.sil.org/fontcla).