From 032c27025a42a31f2a3361bd6715b3dc2d56d14e Mon Sep 17 00:00:00 2001
From: Michael Orlitzky <michael@orlitzky.com>
Date: Wed, 8 Nov 2023 20:31:59 -0500
Subject: [PATCH] README: start adding substance; in particular, links to my
 articles

---
 README | 59 ++++++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 55 insertions(+), 4 deletions(-)

diff --git a/README b/README
index 7f9775a..4ca1658 100644
--- a/README
+++ b/README
@@ -1,5 +1,50 @@
-Build requirements:
+== Introduction
 
+CharmBypass, or charm-bypass, is a free software project that lets you
+ride mass transit in Maryland for free. (Disclaimer: doing so is not at
+all legal.) It is what powers the site https://charm-bypass.com/
+
+That website consists of a single file, index.html, that it is our
+goal to build. This document discusses only the technical details
+involved. An introduction and security analysis (what is this, how
+does it work) can be found at,
+
+  1. https://michael.orlitzky.com/articles/charmbypass_pt._1%3A_introduction.xhtml
+  2. https://michael.orlitzky.com/articles/charmbypass_pt._2%3A_analysis.xhtml
+
+
+== Design goals
+
+The main design goal is that the entire application should be
+self-contained: it should be downloadable and usable without network
+access. The "usable" part is lacking somewhat at the moment due to the
+limitations present in mobile operating systems, but containment has
+been achieved.
+
+It is also mobile-only. By which I mean that if you view the site on
+a large (desktop-sized) screen, it will look crazy. That's OK.
+
+
+== Build process
+
+The project uses a standard GNU autotools build system that should be
+familiar to UNIX programmers and system administrators. To build it,
+first install the build requirements listed below. Then run,
+
+  $ autoreconf -fi
+  $ ./configure
+  $ make
+
+The first command (re)generates the autotools build system. The second
+and third invoke it. If you're feeling lucky, you can also run
+
+  $ make check
+
+to run a (very) minimal set of tests on the index.html you just built.
+
+=== Build requirements
+
+  0. GNU autotools
   1. The "base64" utility from GNU coreutils.
   2. The "scour" SVG optimizer.
   3. The "fontforge" program.
@@ -7,7 +52,13 @@ Build requirements:
 
 To run the test suite, you'll also need the "tidy-html5" program.
 
-SVG Tricks:
 
-1. To remove a "transform" from a group (like the bus) that was
-   resized together, simply ungroup and regroup the whole thing.
+== Miscellany
+
+=== SVG Tricks
+
+1. To inline a "transform" from a group (like the bus) that was
+   resized or translated, simply ungroup and regroup the whole thing.
+   This is necessary for groups that are animated using the
+   "transform" property, because otherwise, applying a new transform
+   would clobber the existing one.
-- 
2.43.2