build: add DOCUMENTATION

Add a format/package documentation so users actually know how mmap-unifont
works.

Signed-off-by: David Herrmann <dh.herrmann@gmail.com>

1 files changed, 129 insertions, 1 deletions

diff --git a/DOCUMENTATION b/DOCUMENTATION
index 1333ed7..cc84848 100644
--- a/DOCUMENTATION
+++ b/DOCUMENTATION
@@ -1 +1,129 @@
-TODO
+mmap-unifont - Documentation
+============================
+
+The mmap-unifont package provides a pre-compiled font based on GNU-Unifont. It
+installs two files into the system, namely:
+    $prefix/lib/pkgconfig/mmap-unifont.pc
+    $prefix/share/mmap-unifont/mmap-unifont.bin
+
+The first file is a pkg-config file to test whether mmap-unifont is installed
+and to retrieve configuration options. It includes the following definition
+(amongst others):
+    pkgdatadir=${datadir}/@PACKAGE@
+
+The second file is the actual pre-compiled font. To access it, you're highly
+recommended to read the 'pkgdatadir' variable from the pkg-config file. The font
+file can then be accessed via:
+    $pkgdatadir/mmap-unifont.bin
+
+The usual way to access the file is:
+    fd = open(PATH, O_RDONLY | O_CLOEXEC);
+    fstat(fd, &st);
+    p = mmap(NULL, st.st_size, PROT_READ, MAP_PRIVATE, fd, 0);
+
+
+Binary Format
+-------------
+
+The mmap-unifont.bin file provides all glyphs plus metadata in a simple
+binary-format, easily accessible from C programs. See ./test/test-glyphs.c for
+an example how to render arbitrary glyphs.
+
+The font-file has the following structure:
+    +--------------------+
+    |     HEADER SIZE    |  4 bytes
+    +--------------------+
+    |       HEADER       |  n bytes
+    ~                    ~
+    ~                    ~
+    +--------------------+
+    |       GLYPHS       |  x bytes
+    ~                    ~
+    ~                    ~
+    +--------------------+
+
+A few global rules exist:
+  - all multi-byte integers are in little-endian format
+  - no alignment is enforced
+  - the format is fully backwards- and forwards-compatible
+
+The first 4 bytes of the file contain a 4-byte unsigned integer which defines
+the size of the header-block (excluding the 4 initial bytes of the header-size
+field) in bytes.
+Following the header-size is the full header. It's length is defined by the
+header-size field. No alignment is enforced. If new header-fields are added, the
+header-size is simply increased. You're therefore supposed to skip the full
+header including any unknown fields to access the glyphs.
+
+After the header, an array of glyphs is appended. All glyphs occupy the same
+number of bytes. This allows direct access to any glyph in the array.
+
+  Header
+  ------
+
+    The header can have any size, it may be empty or it may be bigger than
+    required. Its size can be inquired by reading the preceding header-size
+    field.
+    The header consists of a list of fields in a well-defined order. If the
+    header-size is to small to contain a specific field, the caller has to
+    assume it's set to the default value as specified below. For instance, if
+    the header has size 3, it's too small to contain the glyph-size field,
+    therefore, glyph-size is 33. But it's also too small to contain any
+    following field (as the field-order is fixed), therefore, all fields get the
+    default value.
+
+    Currently, the header is defined as:
+        +--------------------+
+        |     GLYPH SIZE     |  4 bytes
+        +--------------------+
+        |      UNKNOWN       |  x bytes
+        ~                    ~
+        ~                    ~
+        +--------------------+
+
+    Defined fields are:
+      glyph-size: 4byte unsigned integer which defines the size of each glyph
+                  in bytes.
+
+    No other fields are defined and any following bytes are undefined.
+
+
+  Glyphs
+  ------
+
+    After the header, the file contains an array of glyphs. Each glyph has the
+    size as defined in the glyph-size field in the header. This size is not
+    restricted by any alignment. So the array is packed.
+
+    The array is ordered by Unicode codepoints. Therefore, the n-th entry is the
+    glyph for the n-th Unicode codepoint.
+
+    A glyph itself has the following format:
+        +--------------------+
+        |     GLYPH WIDTH    |  1 byte
+        +--------------------+
+        |        DATA        |  16*n bytes
+        ~                    ~
+        +--------------------+
+        |      UNKNOWN       |  x bytes
+        ~                    ~
+        ~                    ~
+        +--------------------+
+
+    Thus, a glyph occupies at least 17bytes. Any following bytes have to be
+    ignored. The glyph-width is a 1byte unsigned integer that defines the
+    character-width of the glyph. Normal ASCII characters have a width of 1,
+    wide-characters (eg., CJK) have a width of 2. More widths might be required
+    for future characters.
+    The data section contains the packed glyph representation. 1 bit per pixel
+    is available, which defines whether the pixel should be black or white (on
+    or off, ..). The upper-most / most-significant bit defines the left-most
+    pixel. The lower-most / least-significant bit defines the right-most pixel.
+
+    Every glyph is encoded in "8 * width" horizontal pixels and 16 vertical
+    pixels. A single-width char thus occupies 8x16 pixels, which requires 1 byte
+    per line, thus 16 bytes.
+    A double-width / wide character requires 8 * 2 == 16 horizontal pixels and
+    16 vertical pixels, thus 2 bytes per line and 32 bytes in total.
+
+    Any following bytes have to be ignored.