updated manual

1 files changed, 71 insertions, 53 deletions

diff --git a/mod/doc/context/third/rst/documentation.rst b/mod/doc/context/third/rst/documentation.rst
index 3ce17cd..a460a29 100644
--- a/mod/doc/context/third/rst/documentation.rst
+++ b/mod/doc/context/third/rst/documentation.rst
@@ -50,55 +50,11 @@ avoid certain situations.
   considered a low-priority bug and will be addressed during the
   next big hyperlink overhaul.
 
-Module
-******
-
-A provisional module for MkIV is included (``t-rst.mkiv``).
-Actually, the converter was thought of as a module for direct
-rendering of |rst| input initially but certain objections
-diverted me from this path.
-
--   *Typography*. It’s all about the details. No matter how good your
-    converter is, it still won’t reach |TEX|’s omnipotence and
-    flexibility. |rstcontext| is a tool to generate raw material
-    for your typesetting job, not a typesetting system in itself.
-
--   *Testing*. Never underestimate the insights gained from reading
-    the resulting |CONTEXT| file. Quite some effort has been
-    undertaken to make it human-readable, especially the setups.
-
--   *MkII*. I’m not an MkII user at all save for rapid testing and
-    the occasional check for the sanity of |CONTEXT|’s behaviour.
-    Slow hardware forces me to run |PDFTEX| instead of |LUATEX|
-    whenvever I need some result as quick as possible, so I wanted
-    to keep the code MkII clean. Do not expect Unicode (as  in
-    this document) to work without precautions.
-
-During the development readability of the generated code was
-alway one of the main goals of |rstcontext|. Quite some computing
-effort is made to reflow even simple things as paragraphs into
-a shape understandable by more than only the |TEX| machine.
-If you should at one point decide that your project is
-ripe for the typographical finish and you want to add local
-changes in form of |TEX| code only, you should be able to use the
-output of |rstcontext| as starting point.
-
-However, using the module may have advantages when testing. There
-is a usage example in ``moduletest.tex``.  Another example in
-``hybridtest.tex`` demonstrates the |CONTEXT| command ``\RST`` as
-well as the corresponding environment.
-
-To install the module simply copy the files into your local |TEX|
-tree. ::
-
-    cp -r ./mod/tex/ ~/context/tex/texmf-local/
-
-Then rebuild the filename database running ``context
---generate``. The module should be ready for use now.
-
 =====
 Usage
 =====
+Invocation from the Command Line
+********************************
 At the moment, |rstcontext| needs to be called as a separate
 program. It is written for use with the Lua interpreter of
 |LUATEX|, ``texlua``, whose libraries and extended capabilities
@@ -120,9 +76,9 @@ start whether you decide to test it with ``texexec`` or
 
 The resulting |TEX| file has rather a basic layout, if at all.
 This is intentional as you are expected to include it in a
-document after your own setups.
+document after specifying your own setups.
 An example for prepended setups can be found in the environment
-for this manual (``doc/manual.tex``).
+for this manual (``mod/doc/context/third/rst/manual.tex``).
 
 .. caution::
     The output of |rstcontext| automatically inserts necessary
@@ -138,13 +94,75 @@ for this manual (``doc/manual.tex``).
     and other common constructs are thought of but have yet to be
     implemented.
 
-To build the documentation, first ``cd`` to the root directory of the
-repository. Now run |rstcontext| as follows: ::
+To build the documentation, first create a temporary directory
+somewhere safe. Then copy or symlink the Lua files from
+``mod/tex/context/third/rst/`` and the manual source there as
+well: ::
+
+    mkdir tmp; cd tmp
+    ln -s ../mod/tex/context/third/rst/*.lua .
+    ln -s ../mod/doc/context/third/rst/documentation.rst .
+
+Now run |rstcontext| on the main documentation file as follows: ::
 
-    $texlua rst_parser.lua doc/documentation.rst doc/doc.tex 
+    texlua rst_parser.lua documentation.rst doc.tex
 
-Then change to the ``doc`` directory and run |CONTEXT| on
-``manual.tex``. Voilà, you have successfully built ``manual.pdf``.
+Now run |CONTEXT| on the layout file: ::
+
+    context ../mod/doc/context/third/rst/manual.tex
+
+This will include the generated code after a couple of setups --
+voilà, you have successfully built ``manual.pdf``. (Note that the
+commands you have to issue in each of the steps vary across
+different OS. In the literal form the example might only work on
+Linux or POSIX compliant systems.)
+
+Module
+******
+
+A provisional module for MkIV is included (``t-rst.mkiv``).
+Actually, the converter was thought of as a module for direct
+rendering of |rst| input initially, but certain objections
+diverted me from this path.
+
+-   *Typography*. It’s all about the details. No matter how good your
+    converter is, it still won’t reach |TEX|’s omnipotence and
+    flexibility. |rstcontext| is a tool to generate raw material
+    for your typesetting job, not a typesetting system in itself.
+
+-   *Testing*. Never underestimate the insights gained from reading
+    the resulting |CONTEXT| file. Quite some effort has been
+    undertaken to make it human-readable, especially the setups.
+
+-   *MkII*. I’m not an MkII user at all save for rapid testing and
+    the occasional check for the sanity of |CONTEXT|’s behaviour.
+    Slow hardware forces me to run |PDFTEX| instead of |LUATEX|
+    whenvever I need some result as quick as possible, so I wanted
+    to keep the code MkII clean. Do not expect Unicode (as  in
+    this document) to work without precautions.
+
+During the development readability of the generated code was
+alway one of the main goals of |rstcontext|. Quite some computing
+effort is made to reflow even simple things as paragraphs into
+a shape understandable by more than only the |TEX| machine.
+If you should at one point decide that your project is
+ripe for the typographical finish and you want to add local
+changes in form of |TEX| code only, you should be able to use the
+output of |rstcontext| as starting point.
+
+However, using the module may have advantages when testing. There
+is a usage example in ``moduletest.tex``, introducing the macro
+``\typesetRSTfile``.  Another example in ``hybridtest.tex``
+demonstrates the |CONTEXT| command ``\RST`` as well as the
+corresponding environment.
+
+To install the module simply copy the files into your local |TEX|
+tree. ::
+
+    cp -r ./mod/* ~/context/tex/texmf-local/
+
+Then rebuild the filename database running ``context
+--generate``. The module should be ready for use now.
 
 =========
 Examples