README: convert to reStructuredText

This will be nice for Codeberg, and I've taken the opportunity to fix
some typos and elaborate on how to use it.

diff --git a/README b/README
deleted file mode 100644 (file)
index bc88639..0000000
--- a/README
+++ /dev/null
@@ -1,29 +0,0 @@
-== What ==
-
-My personal library of LaTeX functions, macros, operators, whatever.
-
-== How ==
-
-In the makefile of your project, you should list out the pieces of
-mjotex that you use. For example,
-
-  MJOTEX = mjo-fonts mjo-theorems
-
-The absolute paths to those libraries, on your system, can be found
-using "kpsewhich" from the kpathsea suite:
-
-  MJOTEXPATHS = $(shell kpsewhich $(MJOTEX))
-
-Now add those as dependencies of your document:
-
-  example.pdf: example.tex example.bbl ... $(MJOTEXPATHS)
-
-If you're planning on publishing your document, then you probably also
-want to create a "dist" target that will bundle all of your
-nonstandard TeX libraries along with the code for your document.
-
-A full makefile example is provided in the repository.
-
-If you're not planning on publishing your document, then you can save
-yourself some trouble and just \usepackage{mjotex}. That will ignore
-any changes to the mjotex library, but hey, YOLO.

diff --git a/README.rst b/README.rst
new file mode 100644 (file)
index 0000000..56252d0
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,89 @@
+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.
+
+Vanilla
+-------
+
+If you just want to steal some of the macros, the easiest way to do it
+is to copy the relevant files out of the repository and into your
+project.
+
+A slightly cleaner approach is to add the repository to your TeX paths
+by adding (for example)
+
+.. code-block:: shell
+
+  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
+
+.. code-block:: make
+
+  \input{mjo-common}
+  \input{mjo-convex}
+  \bibliographystyle{mjo}
+
+in your documents.
+
+GNUmakefile
+-----------
+
+The included build system involves a ``GNUmakefile`` 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
+
+.. 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
+
+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.