README.rst: rewrite, I just changed the way everything works

diff --git a/README.rst b/README.rst
index 56252d082eb89e603bb5595f780cf5e8de5d238b..4c93247281dabcb5c319281cc5ce8e26d8a6a9d1 100644 (file)
--- a/README.rst
+++ b/README.rst
@@ -4,8 +4,9 @@ My personal library of LaTeX macros and operators
 Usage
 =====
 
-The included ``examples.tex`` shows you how to use the macros; the
-rest of this section is focused on getting them usable.
+There is an example project in the ``examples`` directory that shows
+you how to use the macros; the rest of this section is focused on
+getting them usable.
 
 Vanilla
 -------
@@ -36,25 +37,41 @@ in your documents.
 GNUmakefile
 -----------
 
-The included build system involves a ``GNUmakefile`` that has evolved
+The included build system involves a ``GNUmakefile.mjo`` that has evolved
 from the one described in my `Makeing LaTeX
 <https://michael.orlitzky.com/articles/makeing_latex.xhtml>`_ article.
-To use it, copy the provided ``GNUmakefile`` to your own project and
-then edit the copy.
-
-If you are using this build system, you should edit your copy of
-``GNUmakefile`` to list the files in the repository that you use. For
-example,
-
-.. code-block:: make
-
-  MJOTEX  = mjo-common.tex mjo-cone.tex mjo-font.tex mjo-calculus.tex
-  MJOTEX += mjo-theorem.tex mjo.bst
-
-The absolute paths to those files will be determined at build time
-using ``kpsewhich`` from the `kpathsea suite
-<https://tug.org/texinfohtml/kpathsea.html>`_, but for that to work,
-they must live on your TeX path. If you are using Bash, you might set
+It is not meant to be invoked directly; instead, you should create
+your own ``GNUmakefile`` (in your own project) based on the one in
+``examples/GNUmakefile``. This does several things:
+
+#. Adds this repository to the TeX path.
+#. Declares a few relevant variables.
+#. Includes ``GNUmakefile.mjo`` from the repository, which can now
+   be found on the TeX path.
+
+These variables are as follows:
+
+``PN``
+  The name of the main document (your TeX file, without the ``.tex``
+  extension). Defaults to the name of the parent directory.
+``BIBS``
+  The names of any BibTeX bibliography (``*.bib``) used in your
+  document. Default unset.
+``INDICES``
+  The name of your index, if your document has an index. Will typically
+  be set to ``$(PN)`` in that case. Default unset.
+``SAGE_LISTINGS``
+  The names of any Sage code listing files. These are automatically
+  converted to python files and doctested with ``make check-sage``.
+  Default unset.
+``MJOTEX``
+  The names of any ``mjo-*.tex`` files you use from this repository.
+  Default unset.
+
+The absolute paths to the ``BIBS`` and ``MJOTEX`` entries are
+determined at build time using ``kpsewhich`` from the `kpathsea suite
+<https://tug.org/texinfohtml/kpathsea.html>`_. For that to work, they
+must live on your TeX path. If you are using Bash, you might set
 
 .. code-block:: shell
 
@@ -69,21 +86,3 @@ localized, you can do the same thing at the top of your copy of
 
   export TEXINPUTS := $(TEXINPUTS):/path/to/mjotex.git
   export BSTINPUTS := $(BSTINPUTS):/path/to/mjotex.git
-
-If you're not planning on publishing your document, you can save some
-time by referencing the full package file ``mjotex.sty`` rather than
-the individual ``mjo-*.tex`` files:
-
-.. code-block:: make
-
-  MJOTEX = mjotex.sty mjo.bst
-
-The package can be then be loaded all at once in your document, with
-
-.. code-block:: make
-
-  \usepackage{mjotex}
-
-This will cause the build system to ignore (not rebuild due to)
-changes in the ``mjo-*.tex`` files, but it absolves you of the need to
-track which ones you use.