From 5e3872117c632287f3401511174ce152f936eb6c Mon Sep 17 00:00:00 2001
From: Peter Hinch <peter@hinch.me.uk>
Date: Mon, 20 Aug 2018 11:54:36 +0100
Subject: [PATCH] font_to_py.py Update docs.

---
 FONT_TO_PY.md     |  2 +-
 writer/DRIVERS.md | 33 +++++++++++++++++++++++----------
 2 files changed, 24 insertions(+), 11 deletions(-)

diff --git a/FONT_TO_PY.md b/FONT_TO_PY.md
index aa36dfe..dcb9979 100644
--- a/FONT_TO_PY.md
+++ b/FONT_TO_PY.md
@@ -63,7 +63,7 @@ bytecode this will not reduce RAM usage but it will conserve flash. An example
 usage for a digital clock font:
 
 ```shell
-font_to_py.py Arial.ttf 20 arial_clock.py -c 1234567890:
+$ font_to_py.py Arial.ttf 20 arial_clock.py -c 1234567890:
 ```
 If a character set is specified, `--smallest` and `--largest` should not be
 specified: these values are computed from the charcater set.
diff --git a/writer/DRIVERS.md b/writer/DRIVERS.md
index 297e54c..57b3b90 100644
--- a/writer/DRIVERS.md
+++ b/writer/DRIVERS.md
@@ -68,15 +68,15 @@ Assume the user has run the utility to produce a file `myfont.py` This then
 has the following outline definition (in practice the bytes objects are large):
 
 ```python
- # Code generated by font-to-py.py.
- # Font: FreeSerif.ttf
-version = '0.2'
+# Code generated by font-to-py.py.
+# Font: Arial.ttf
+version = '0.25'
 
 def height():
-    return 21
+    return 20
 
 def max_width():
-    return 22
+    return 20
 
 def hmap():
     return False
@@ -94,15 +94,14 @@ def max_ch():
     return 126
 
 _font =\
-b'\x06\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00'\
-b'\x00\x00\x00\x00\x08\x00\xfe\xc7\x00\x7e\xc0\x00\x00\x00\x00\x00'\
+b'\x0b\x00\x18\x00\x00\x1c\x00\x00\x0e\x00\x00\x06\xce\x00\x06\xcf'\
+b'\x00\x86\x03\x00\xce\x01\x00\xfc\x00\x00\x38\x00\x00\x00\x00\x00'\
 
 _index =\
-b'\x00\x00\x14\x00\x2e\x00\x4b\x00\x71\x00\x97\x00\xd2\x00\x0a\x01'\
-b'\x1b\x01\x35\x01\x4f\x01\x75\x01\x9e\x01\xb2\x01\xcc\x01\xe0\x01'\
+b'\x00\x00\x23\x00\x23\x00\x37\x00\x37\x00\x4b\x00\x4b\x00\x62\x00'\
+b'\x62\x00\x85\x00\x85\x00\xa8\x00\xa8\x00\xe0\x00\xe0\x00\x09\x01'\
 
 _mvfont = memoryview(_font)
-    # Boilerplate code omitted
 
 def get_ch(ch):
     # validate ch, if out of range use '?'
@@ -124,6 +123,20 @@ character check.
 and contains all the bytes required to render the character including trailing
 space.
 
+The `_font` bytearray holds the glyphs corresponding to every character in the
+font. Entry 0 is the default glyph, used if an attempt is made to render a
+nonexistent character.
+
+The index holds two integers (each occupying 2 bytes) per character. The index
+has an entry for every character in the specified range, whether or not that
+character exists.
+
+Index entries are offsets into the `_font` bytearray represnting the start and
+end of the glyph. If the font comprises a set of characters which is not
+contiguous, missing characters have an index entry which points to the first
+glyph in the `_font` bytearray. This ensures that the default glyph is
+rendered.
+
 ## Fixed width fonts
 
 If a Python font file is created with the `-f` argument, all characters will