README: convert to reStructuredText

This will look nice on Codeberg, and is not any less human-readable.

diff --git a/README b/README.rst
similarity index 66%
rename from README
rename to README.rst
index 67e54c9a894385533ab38017573404b575449b80..5b6fb86e420a837646fd01815b1510955cb83cbf 100644 (file)
--- a/README
+++ b/README.rst
@@ -1,19 +1,22 @@
-== Introduction
+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 powered the site https://charm-bypass.com/
+ride mass transit in Maryland for free. (Disclaimer: doing so is not
+at all legal.) It is what powered the first `CharmBypass
+<https://charm-bypass.com/>`_ website.
 
 The "app" 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
+#. `CharmBypass pt. 1: introduction <https://michael.orlitzky.com/articles/charmbypass_pt._1%3A_introduction.xhtml>`_
+#. `CharmBypass pt. 2: analysis <https://michael.orlitzky.com/articles/charmbypass_pt._2%3A_analysis.xhtml>`_
 
 
-== Design goals
+Design goals
+============
 
 The main design goal is that the entire application should be
 self-contained: it should be downloadable and usable without network
@@ -25,12 +28,15 @@ 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
+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,
 
+.. code-block:: console
+
   $ autoreconf -fi
   $ ./configure
   $ make
@@ -38,26 +44,31 @@ first install the build requirements listed below. Then run,
 The first command (re)generates the autotools build system. The second
 and third invoke it. If you're feeling lucky, you can also run
 
+.. code-block:: console
+
   $ make check
 
 to run a (very) minimal set of tests on the index.html you just built.
 
-=== Build requirements
+Build requirements
+==================
 
-  0. GNU autotools
-  1. The "base64" utility from GNU coreutils.
-  2. The "scour" SVG optimizer.
-  3. The "fontforge" program, built with woff2 support.
-  4. The "xsltproc" program from libxslt.
+#. GNU autotools
+#. The "base64" utility from GNU coreutils.
+#. The "scour" SVG optimizer.
+#. The "fontforge" program, built with woff2 support.
+#. The "xsltproc" program from libxslt.
 
 To run the test suite, you'll also need the "tidy-html5" program.
 
 
-== Miscellany
+Miscellany
+==========
 
-=== SVG Tricks
+SVG Tricks
+----------
 
-1. To inline a "transform" from a group (like the bus) that was
+#. 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