diff options
Diffstat (limited to 'Master/texmf-dist/doc/context/third/rst')
| -rw-r--r-- | Master/texmf-dist/doc/context/third/rst/COPYING | 22 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/context/third/rst/README.rst | 27 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/context/third/rst/documentation.rst | 94 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/context/third/rst/inc-first.rst | 14 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/context/third/rst/inc-second.rst | 9 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/context/third/rst/inc-third.rst | 14 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/context/third/rst/inc.tex | 11 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/context/third/rst/manual.bib | 10 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/context/third/rst/manual.pdf | bin | 0 -> 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 Binary files differnew file mode 100644 index 00000000000..de331b5fed5 --- /dev/null +++ b/Master/texmf-dist/doc/context/third/rst/manual.pdf |