README.rst: improve usage and installation docs

Try to separate the "usage" and "installation" instructions. Mention
the SRCS variable, and explain why BIBS and MJOTEX are located at
build time

diff --git a/README.rst b/README.rst
index b656fad55428de94dc91a64852c9e717e4778843..534cbb6c4f01e5a11af0dc9377a55909f05dd630 100644 (file)
--- a/README.rst
+++ b/README.rst
@@ -1,12 +1,40 @@
-Personal LaTeX macros and Beamer theme
+Personal LaTeX macros, Beamer theme, and TeX build system
 
 
 Usage
 =====
 
 There are example projects in the ``examples`` directory that show you
-how to use the macros and beamer theme. The rest of this section is
-focused on getting them usable.
+how to use the macros, BibTeX style, Beamer theme, and build system
+for your own documents. The macros are usable once you include the
+relevant ``mjo-*.tex`` files into your document:
+
+.. code-block:: latex
+
+  \input{mjo-common}
+  \input{mjo-convex}
+  ...
+
+To use the BibTeX style (``mjo.bst``), ask for the "mjo" style prior
+to generating the bibliography. For example,
+
+.. code-block:: latex
+
+  \bibliographystyle{mjo}
+  \bibliography{references}
+
+Finally, the beamer theme files (``beamer*mjo.sty``) are switched on
+when you specify the "mjo" theme in your Beamer document:
+
+.. code-block:: latex
+
+  \documentclass{beamer}
+  \usetheme{mjo}
+  ...
+
+
+Installation
+============
 
 Vanilla
 -------
@@ -23,19 +51,34 @@ by adding (for example)
   export BSTINPUTS="${BSTINPUTS}:/path/to/mjotex.git"
   export TEXINPUTS="${TEXINPUTS}:/path/to/mjotex.git"
 
-to your ``~.bashrc`` or equivalent. That will allow you to use
-commands like
+to your ``~.bashrc`` or equivalent.
+
+GNUmakefile
+-----------
+
+The included build system based on GNU Make is described below. To use
+it (and to use the rest of mjotex from within it) you will need to add
+the mjotex repository to your TeX path. For multiple projects, the
+easiest way is to add something like
+
+.. code-block:: shell
+
+  export BSTINPUTS="${BSTINPUTS}:/path/to/mjotex.git"
+  export TEXINPUTS="${TEXINPUTS}:/path/to/mjotex.git"
+
+to your ``~/.bashrc`` or equivalent.
+
+For one-offs, or if you would simply prefer to keep everything local,
+you can do the same thing at the top of your copy of ``GNUmakefile``:
 
 .. code-block:: make
 
-  \input{mjo-common}
-  \input{mjo-convex}
-  \bibliographystyle{mjo}
+  export TEXINPUTS := $(TEXINPUTS):/path/to/mjotex.git
+  export BSTINPUTS := $(BSTINPUTS):/path/to/mjotex.git
 
-in your documents.
 
-GNUmakefile
------------
+Build system
+============
 
 The included build system involves a ``GNUmakefile.mjo`` that has evolved
 from the one described in my `Makeing LaTeX
@@ -56,33 +99,29 @@ These variables are as follows:
   extension). Defaults to the name of the parent directory.
 ``BIBS``
   The names of any BibTeX bibliography (``*.bib``) used in your
-  document. Default unset.
+  document. Their full paths are looked up at build time. 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.
+  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 ``*.tex`` or ``*.sty`` files you use from this
-  repository. Default unset.
+  repository. Their full paths are looked up at build time. Default
+  unset.
+``SRCS``
+  Any additional source files that should trigger a rebuild of your
+  document. Unlike the entries in ``MJOTEX`` and ``BIBS``, these are
+  *not* located at build time; they must resolve relative to your
+  project. 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
-
-  export BSTINPUTS="${BSTINPUTS}:/path/to/mjotex.git"
-  export TEXINPUTS="${TEXINPUTS}:/path/to/mjotex.git"
-
-in your ``~/.bashrc``. Or if you would prefer to keep everything
-localized, you can do the same thing at the top of your copy of
-``GNUmakefile``:
-
-.. code-block:: make
-
-  export TEXINPUTS := $(TEXINPUTS):/path/to/mjotex.git
-  export BSTINPUTS := $(BSTINPUTS):/path/to/mjotex.git
+must live on your TeX path. See the "Installation" section for that.
+(This makes it possible to maintain one copy of the mjotex repository
+and/or one bibliography database, independent of your papers and
+presentations.)