summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/context/third/rst/documentation.rst
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/context/third/rst/documentation.rst')
-rw-r--r--Master/texmf-dist/doc/context/third/rst/documentation.rst94
1 files changed, 69 insertions, 25 deletions
diff --git a/Master/texmf-dist/doc/context/third/rst/documentation.rst b/Master/texmf-dist/doc/context/third/rst/documentation.rst
index a460a2928c3..90168a3fa1a 100644
--- a/Master/texmf-dist/doc/context/third/rst/documentation.rst
+++ b/Master/texmf-dist/doc/context/third/rst/documentation.rst
@@ -20,16 +20,6 @@ Should you find yourself in desparate need of tables or whatever
structures inside footnotes then I might agree to find a solution
if you ask.
-Tabs
-****
-The |rst| specification requests that tabs (ASCII no 9) be
-treated as spaces_. Although the matching patterns should be
-neutral with respect to tabs, I never tested them, neither do I
-guarantee that they will work anywhere. Converting your tabs to
-spaces might be a good preparation for an |rstcontext| run.
-
-.. _spaces: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#whitespace
-
Hyperlinks
**********
The hyperlink implementation should be fine in general use if you
@@ -55,18 +45,17 @@ 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
-it uses. Therefore, |rstcontext| might not run at all on other
+|rstcontext| is integrated into the ``mtxrun`` command as a
+script, which relies, naturally, on the Lua interpreter of
+|LUATEX|. Therefore, |rstcontext| might not run at all on other
Lua installations, at least not without modification of the
source. Fortunately, every |CONTEXT| user is equipped with
|LUATEX| nowadays so this dependency should be trivial.
To generate |CONTEXT| code from a |rst| document named
-``infile.rst``, call ``rst_parser.lua`` through ``texlua``: ::
+``infile.rst``, call ``mtxrun``: ::
- $texlua rst_parser.lua infile.rst outfile.tex
+ $mtxrun --script rst --if=infile.rst --of=outfile.tex
You should now have a file ``outfile.tex`` that is ready to be
run by |CONTEXT|. With some exceptions the generated code is
@@ -99,17 +88,16 @@ 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 .
+ $mkdir tmp; cd tmp
+ $ln -s ../mod/doc/context/third/rst/documentation.rst .
Now run |rstcontext| on the main documentation file as follows: ::
- texlua rst_parser.lua documentation.rst doc.tex
+ $mtxrun --script rst --if=documentation.rst --of=doc.tex
Now run |CONTEXT| on the layout file: ::
- context ../mod/doc/context/third/rst/manual.tex
+ $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
@@ -152,18 +140,53 @@ 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
+``\\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. ::
+tree, i.e. if the minimals reside in ``~/context/``, you would
+issue the following line: ::
- cp -r ./mod/* ~/context/tex/texmf-local/
+ $cp -r ./mod/* ~/context/tex/texmf-local/
Then rebuild the filename database running ``context
--generate``. The module should be ready for use now.
+RST projects
+************
+
+In addition to the simple command ``\\typesetRSTfile`` the module
+also provides means for handling multiple |rst| input files. This
+is achieved by so-called *inclusions*. An inclusion has to be
+defined first, using the macro ``\\defineRSTinclusion``, which
+receives up to three arguments in brackets. The first one
+specifies the *identifier* by which the inclusion will be
+referred to afterwards (cf. |CONTEXT|’s ``\\useURL`` command). The
+second argument, which is mandatory as well, takes the file to be
+associated with an inclusion. Finally, optional setups can be
+passed to the parser via the third argument (cf. the section on
+`Tabs`_). E.g.: ::
+
+ \usemodule[rst]
+ \defineRSTinclusion [first][inc-first.rst]
+ \defineRSTinclusion[second][inc-second.rst][expandtab=true,shiftwidth=8]
+ \defineRSTinclusion [third][inc-third.rst]
+
+Those inclusions are afterwards accessible *within* the
+``\\[start|stop]project`` environment, and can be dereferenced by
+``\\RSTinclusion``, which takes the identifier as a single
+argument in brackets: ::
+
+ \startRSTproject
+ \RSTinclusion [first]
+ \RSTinclusion[second]
+ \RSTinclusion [third]
+ \stopRSTproject
+
+Within the project environment, |rstcontext| allows for arbitrary
+|CONTEXT| markup.
+
=========
Examples
=========
@@ -501,6 +524,27 @@ can keep whatever directory structure you prefer. (Speaking for
myself, bib data usually resides in its own subdirectory, so I’d
use symlinks, too.)
+****
+Tabs
+****
+The |rst| specification requests that tabs (ASCII no 9) be
+treated as spaces_. Converting your tabs to spaces might be a
+good preparation for an |rstcontext| run. However, as of version
+123 |rstcontext| comes with built-in tab expansion. It can be
+enabled by supplying an optional argument to the
+``typesetRSTfile`` command: ::
+
+ \usemodule[rst]
+ \typesetRSTfile[expandtab=true,shiftwidth=4]{myfile.rst}
+
+The argument ``expandtab`` triggers a prepocessing step which
+expands all tabulation characters (``\t`` and ``\v``) into the
+correct amount of spaces. Optionally, the tab stop distance can
+be configured using the ``shiftwidth`` parameter, which defaults
+to 4.
+
+.. _spaces: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#whitespace
+
===================
About this software
===================