summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/context
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2011-10-04 23:14:25 +0000
committerKarl Berry <karl@freefriends.org>2011-10-04 23:14:25 +0000
commit4f68b0c5d5f831d436030b16a89144bd43c1bd42 (patch)
treefcc6886d2d14a0b8d51bcdf079e42447b99cc7c4 /Master/texmf-dist/doc/context
parent9eca32c15f6dbc09ab0bfd2f7aa3b6cce8fd3754 (diff)
context-rst (4oct11)
git-svn-id: svn://tug.org/texlive/trunk@24199 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/context')
-rw-r--r--Master/texmf-dist/doc/context/third/rst/COPYING22
-rw-r--r--Master/texmf-dist/doc/context/third/rst/README.rst27
-rw-r--r--Master/texmf-dist/doc/context/third/rst/documentation.rst94
-rw-r--r--Master/texmf-dist/doc/context/third/rst/inc-first.rst14
-rw-r--r--Master/texmf-dist/doc/context/third/rst/inc-second.rst9
-rw-r--r--Master/texmf-dist/doc/context/third/rst/inc-third.rst14
-rw-r--r--Master/texmf-dist/doc/context/third/rst/inc.tex11
-rw-r--r--Master/texmf-dist/doc/context/third/rst/manual.bib10
-rw-r--r--Master/texmf-dist/doc/context/third/rst/manual.pdfbin0 -> 112951 bytes
9 files changed, 165 insertions, 36 deletions
diff --git a/Master/texmf-dist/doc/context/third/rst/COPYING b/Master/texmf-dist/doc/context/third/rst/COPYING
new file mode 100644
index 00000000000..05f08de1457
--- /dev/null
+++ b/Master/texmf-dist/doc/context/third/rst/COPYING
@@ -0,0 +1,22 @@
+Copyright 2010-2011 Philipp Gesang. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+ 1. Redistributions of source code must retain the above copyright notice,
+ this list of conditions and the following disclaimer.
+
+ 2. Redistributions in binary form must reproduce the above copyright
+ notice, this list of conditions and the following disclaimer in the
+ documentation and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER ``AS IS'' AND ANY EXPRESS OR
+IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
+EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
+INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
+OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
diff --git a/Master/texmf-dist/doc/context/third/rst/README.rst b/Master/texmf-dist/doc/context/third/rst/README.rst
index 7bb11909b56..1ab41ce94e8 100644
--- a/Master/texmf-dist/doc/context/third/rst/README.rst
+++ b/Master/texmf-dist/doc/context/third/rst/README.rst
@@ -8,6 +8,19 @@ Read the section *Features Not Implemented* in the manual first.
below just mean that *their* implementation doesn’t understand TeX directives.
Don’t worry, |rstcontext| does.
+============
+Installation
+============
+
+In order to install |rstcontext|, copy everything under the ``mod/``
+subdirectory into your local |CONTEXT| tree and update the filename database,
+i.e.: ::
+
+ cp -r mod/* ~/context/tex/texmf-local/
+ context --generate
+
+if the |CONTEXT| minimal distribution happens to be installed at
+``~/context/``.
=====
Usage
@@ -19,8 +32,7 @@ file and the output file. The following will demonstrate the main usage in a
separate directory: ::
mkdir tmp; cd tmp
- ln -s ../mod/tex/context/third/rst/*.lua .
- texlua rst_parser.lua ../mod/doc/context/third/rst/documentation.rst doc.tex
+ mtxrun --script rst --if=../mod/doc/context/third/rst/documentation.rst --of=doc.tex
context ../mod/doc/context/third/rst/manual.tex
This should have gotten you the manual converted to a file ``doc.tex`` which was
@@ -29,15 +41,8 @@ will find extended instructions on how to build the manual with some cosmetic
improvements in the section *Usage* of the manual itself.
There is also a small module ``t-rst.mkiv`` which permits direct typesetting of
-reST markup with |CONTEXT| MkIV. To install the module, simply copy anything
-under the ``mod`` directory to your local |CONTEXT| tree. For instance, if
-|CONTEXT| happens to be installed at ``~/context``, the installation would be
-achieved this way: ::
-
- cp -r mod/* ~/context/tex/texmf-local/
-
-For usage examples see the files ``hybridtest.tex`` and ``moduletest.tex`` in
-the ``doc`` subdirectory.
+reST markup with |CONTEXT| MkIV. For usage examples see the files
+``hybridtest.tex`` and ``moduletest.tex`` in the ``doc`` subdirectory.
=======
License
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
===================
diff --git a/Master/texmf-dist/doc/context/third/rst/inc-first.rst b/Master/texmf-dist/doc/context/third/rst/inc-first.rst
new file mode 100644
index 00000000000..392649f5566
--- /dev/null
+++ b/Master/texmf-dist/doc/context/third/rst/inc-first.rst
@@ -0,0 +1,14 @@
+=============
+First Chapter
+=============
+
+Mountaineer? *Mountaineer* where the devil are they, mound, mount... mountain...
+a mountaineer: ‘two men skilled in climbing mountains’. Jolly good, well you’re
+in. Congratulations, both of you.
+
+We’ll be leaving on January 22nd and taking the following routes. The A23s
+through Purleys down on the main roads near Purbrights avoiding Leatherheads and
+then taking the A231s entering Rottingdeans from the North. From Rottingdeans we
+go through Africa to Nairobis. We take the South road out of Nairobis for about
+twelve miles and then ask.
+
diff --git a/Master/texmf-dist/doc/context/third/rst/inc-second.rst b/Master/texmf-dist/doc/context/third/rst/inc-second.rst
new file mode 100644
index 00000000000..eff120e2d2f
--- /dev/null
+++ b/Master/texmf-dist/doc/context/third/rst/inc-second.rst
@@ -0,0 +1,9 @@
+==============
+Second Chapter
+==============
+Well Bruce, I heard the Prime Minister use it. S’hot enough to boil a monkey’s
+bum in ’ere, your Majesty, he said and she smiled quietly to herself.
+
+Now, Bruce teaches classical philosophy, Bruce teaches Hegelian philosophy, and
+Bruce here teaches logical positivism, and is also in charge of the sheepdip.
+
diff --git a/Master/texmf-dist/doc/context/third/rst/inc-third.rst b/Master/texmf-dist/doc/context/third/rst/inc-third.rst
new file mode 100644
index 00000000000..67e6d5a2a8c
--- /dev/null
+++ b/Master/texmf-dist/doc/context/third/rst/inc-third.rst
@@ -0,0 +1,14 @@
+=============
+Third Chapter
+=============
+You are hereby charged that on the 28th day of May 1970, you did wilfully,
+unlawfully, and with malice aforethought publish an alleged English-Hungarian
+phrasebook with intent to cause a breach of the peace. How do you plead?
+
+Not guilty.
+
+I quote an example. The Hungarian phrase meaning ‘Can you direct me to the
+station?’ is translated by the English phrase, ‘Please fondle my bum’.
+
+I wish to plead incompetence.
+
diff --git a/Master/texmf-dist/doc/context/third/rst/inc.tex b/Master/texmf-dist/doc/context/third/rst/inc.tex
new file mode 100644
index 00000000000..7703fae0818
--- /dev/null
+++ b/Master/texmf-dist/doc/context/third/rst/inc.tex
@@ -0,0 +1,11 @@
+\usemodule[rst]
+
+\defineRSTinclusion [first][inc-first.rst]
+\defineRSTinclusion[second][inc-second.rst]
+\defineRSTinclusion [third][inc-third.rst]
+
+\startRSTproject
+\RSTinclusion [first]
+\RSTinclusion[second]
+\RSTinclusion [third]
+\stopRSTproject
diff --git a/Master/texmf-dist/doc/context/third/rst/manual.bib b/Master/texmf-dist/doc/context/third/rst/manual.bib
new file mode 100644
index 00000000000..638ed807700
--- /dev/null
+++ b/Master/texmf-dist/doc/context/third/rst/manual.bib
@@ -0,0 +1,10 @@
+@BOOK{texbook,
+ author = {Donald E. Knuth},
+ title = {The \TEX book},
+ year = {1984},
+ address = {Reading, Mass. et. al.},
+ location = {Reading, Mass. et. al.},
+ series = {Computers and typesetting vol. 1},
+ keywords = {all}
+}
+
diff --git a/Master/texmf-dist/doc/context/third/rst/manual.pdf b/Master/texmf-dist/doc/context/third/rst/manual.pdf
new file mode 100644
index 00000000000..de331b5fed5
--- /dev/null
+++ b/Master/texmf-dist/doc/context/third/rst/manual.pdf
Binary files differ