From 91881549ff6046186e3f7a4c6ca150f8ea8b0c94 Mon Sep 17 00:00:00 2001
From: Friedrich von Never <friedrich@fornever.me>
Date: Sun, 5 Mar 2017 21:55:06 +0700
Subject: [PATCH 1/2] prepare-font: add docs about XML preparation

---
 docs/prepare-font.md | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)
 create mode 100644 docs/prepare-font.md

diff --git a/docs/prepare-font.md b/docs/prepare-font.md
new file mode 100644
index 00000000..b16fc38a
--- /dev/null
+++ b/docs/prepare-font.md
@@ -0,0 +1,23 @@
+How to prepare XML from TTF
+===========================
+
+1. To gather font metrics:
+   ```console
+   $ ttf2tfm filename.ttf -v filename.vpl
+   $ tftopl filename.tfm > filename.tpl
+   ```
+   That will generate `filename.tfm` (binary) and `filename.vpl`, `filename.tpl`
+   (text).
+
+   `ttf2tfm` and `tftopl` are parts of the standard TeX distribution (at least
+   TeX Live).
+2. May be helpful:
+   ```console
+   $ ttx filename.ttf
+   ```
+
+   That will generate `filename.ttx` (XML).
+
+   [ttx][]
+
+[ttx]: https://github.com/fonttools/fonttools

From 91e568f96b5f0a5ba45b6643a5b66028a9c00083 Mon Sep 17 00:00:00 2001
From: Friedrich von Never <friedrich@fornever.me>
Date: Sat, 27 Jan 2018 16:51:49 +0700
Subject: [PATCH 2/2] Add information about DefaultTexFont.xml (#70)

---
 README.md            |  6 ++++
 docs/prepare-font.md | 85 +++++++++++++++++++++++++++++++++++++++++---
 2 files changed, 87 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 561e455a..a6679440 100644
--- a/README.md
+++ b/README.md
@@ -18,6 +18,11 @@ For a more detailed sample, check out the [example project][example]. It shows t
 
 ![Screenshot of example project](docs/example-screenshot.png)
 
+Documentation
+-------------
+
+- [How to prepare `DefaultTexFont.xml` from the font file][docs-prepare-font]
+
 History
 -------
 
@@ -30,6 +35,7 @@ The project code is licensed under the terms of [MIT license][license]. The orig
 
 The [fonts][] `cmex10.ttf`, `cmmi10.ttf`, `cmr10.ttf`, and `cmsy10.ttf` and `cmtt10.ttf` are under the [Knuth License][knuth-license].
 
+[docs-prepare-font]: docs/prepare-font.md
 [example]: WpfMath.Example/
 [fonts]: src/WpfMath/Fonts/
 [gpl]: docs/JMathTeX-license.txt
diff --git a/docs/prepare-font.md b/docs/prepare-font.md
index b16fc38a..fe4e947e 100644
--- a/docs/prepare-font.md
+++ b/docs/prepare-font.md
@@ -1,5 +1,17 @@
-How to prepare XML from TTF
-===========================
+How to prepare `DefaultTexFont.xml` from the font file
+======================================================
+
+This document describes the correspondence between the font files we use and
+data in `DefaultTexFont.xml`. The conrete approach (i.e. script files to
+regenerate XML data) hasn't been reproduced yet, although we were able to get
+nearly all the required information.
+
+Data in our XML files is often inaccurate and/or seemlingly generated from other
+TTF files than the files in the repository. Be prepared for that. When in doubt,
+refer to [the original TFM files][tfm] (they seem to correspond to our data
+better than the TFM files generated from our TTF files).
+
+There are two helpful toolsets to work with our TTF files:
 
 1. To gather font metrics:
    ```console
@@ -11,13 +23,78 @@ How to prepare XML from TTF
 
    `ttf2tfm` and `tftopl` are parts of the standard TeX distribution (at least
    TeX Live).
-2. May be helpful:
+2. It may be helpful to use the [ttx][] utility to get some additional
+   information about the font (e.g. mapping from characters to codes in the font
+   file):
    ```console
    $ ttx filename.ttf
    ```
 
    That will generate `filename.ttx` (XML).
 
-   [ttx][]
+For example, there's the following in `DefaultTexFont.xml`:
+
+```xml
+<Font name="cmmi10.ttf" id="0" space="0.0" xHeight="0.430555" skewChar="196" quad="1.000003">
+    <Char code="65" width="0.750002" height="0.683332" >
+        <Kern code="196" val="0.138893"/>
+    </Char>
+</Font>
+```
+
+To get these values from the `cmmi10.tpl` file, search for the following:
+
+```
+(FONTDIMEN
+   (SLANT R 0.25)
+   (SPACE R 0.0)
+   (STRETCH R 0.0)
+   (SHRINK R 0.0)
+   (XHEIGHT R 0.430555)
+   (QUAD R 1.000003)
+   )
+
+…
+
+(CHARACTER C A
+   (CHARWD R 0.750002)
+   (CHARHT R 0.683332)
+   (COMMENT
+      (KRN O 177 R 0.138893)
+      )
+   )
+```
+
+Here, `CHARWD` corresponds to `width`, `CHARHT` corresponds to `height`,
+`CHARDP` corresponds to `depth`, and `CHARIC` corresponds to `italic`. Any of
+them could be ommited.
+
+The kerning section can also be reconstructed from the `*.tpl` file.
+
+How can we know that `O 177` is the same as `code="196"`? To do that, first look
+into `cmmi10.vpl` file: there's the following entry:
+
+```
+(CHARACTER O 177 (comment dieresis)
+   (CHARWD R 583)
+   (CHARHT R 705)
+   (CHARIC R 118)
+   (MAP
+      (SETCHAR O 151)
+      )
+   )
+```
+
+That means that `O 177` is named `dieresis`. Then, open [Adobe Glyph
+List][glyphlist] and search for the `dieresis` name:
+
+```
+dieresis;00A8
+```
+
+It means that `O 177` should be character `0xa8` or `168`, not `196`. The reason
+for that inconsistency is currently unknown.
 
+[glyphlist]: https://github.com/adobe-type-tools/agl-aglfn/blob/5de337bfa018e480bf15b77973e27ccdbada8e56/glyphlist.txt
+[tfm]: https://ctan.org/texarchive/fonts/cm/tfm
 [ttx]: https://github.com/fonttools/fonttools