summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--.hgignore1
-rw-r--r--mod/doc/context/third/rst/documentation.rst124
2 files changed, 72 insertions, 53 deletions
diff --git a/.hgignore b/.hgignore
index 4065014..ec1e032 100644
--- a/.hgignore
+++ b/.hgignore
@@ -39,3 +39,4 @@ syntax:glob
./testing/*
./tmp.tex
*–rst_temporary*
+./tmp/*
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