Restructuring

[lianghai]

Before providing concrete tutorials in appendices, this current draft tries to first introduce a solid theoretical framework. This approach may ensure a reader’s systematic understanding, but greatly limits how many readers can benefit from it, because most readers won’t even be able to finish reading the abstract analyses in the main text.

Therefore, in order to allow as many as possible people to benefit from this effort, I’d like to radically change the document’s structure to let its main text be a brief (as much as possible) tutorial that is immediately actionable, then provide a number of appendices with in-depth (but hopefully still concise and readable) introductions of technical details for whoever is actually interested. Roughly like this:

Introduction

• Still in the form of a README.md, providing high-level introduction and navigation to the documents.

1. General tutorial

• Based on Devanagari but not necessarily focused on Devanagari. All other scripts should be mentioned and their distinct features need to be briefly discussed.
• Slightly more generalized and systematic than per-script tutorials. Avoid being misled by Devanagari’s own peculiars. Aim for useful knowledge for all readers looking for a tutorial.
• Based on our recommended glyph names, reference OTL code, and first-party tools.
• Not to provide the full reference OTL code. Instead, drive a reader to the per-script tutorial for acquiring the complete reference OTL code and other detailed script-specific discussions.

2. Per-script tutorials

• Detailed introduction of how to implement a script with a font.
• Reference glyph set and glyph data, as well as the reference OTL code.
• Provide compatibility workarounds, but leave the in-depth explanation to appendices.
• Orthography-specific requirements.

Start with:

• देवनागरी Devanagari
• தமிழ் Tamil

3. Further reading

• A guide for other relevant reads, including our own appendices and other documents.
• Low priority for now, but is valuable in the long run.

Appendices

A. Graphic analysis for digital typography

• The theoretical foundation of this documentation project.

B. Recommended glyph naming

C. How a reference glyph set is designed

• Among others, the glyph database includes graphical dependency and shaping dependency information.

D. Tooling

• A configurable wrapper around fontmake and ufo2ft.
• Tools that allow configurable and progressive OTL development based on different glyph sets.

E. Unicode text

F. OTL text shaping

G. Known issues of shaping environments and workarounds

---

Apart from the general structure, as Peter pointed out that readers seldom read such long-form documents in order, we’ll need to make sure each one of the long articles (eg, the main tutorial and some long appendices) is easily navigable, preferably by having visuals that quickly illustrate what each section is about.

An appendix shall be spun off into a separate document if it requires its own kind of long-term maintenance, such as the document about known shaping issues of shaping environments.

Btw, I’m gonna be preparing for an IUC talk and record a video for it by 25 Sep. This deadline for the talk is a good push for me to re-examine my new ideas since this current draft took shape.

[lianghai]

cc @jbmorizot