From ca39cfc363db7adc07e21057cf77b14871554e09 Mon Sep 17 00:00:00 2001
From: Philipp Gesang <pgesang@ix.urz.uni-heidelberg.de>
Date: Sun, 28 Aug 2011 13:39:49 +0200
Subject: updated manual
---
mod/doc/context/third/rst/documentation.rst | 56 +++++++++++++++++------------
1 file changed, 33 insertions(+), 23 deletions(-)
(limited to 'mod/doc/context/third')
diff --git a/mod/doc/context/third/rst/documentation.rst b/mod/doc/context/third/rst/documentation.rst
index a460a29..c5f83c3 100644
--- a/mod/doc/context/third/rst/documentation.rst
+++ b/mod/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
@@ -157,9 +145,10 @@ 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.
@@ -501,6 +490,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
===================
--
cgit v1.2.3