diff options
| -rw-r--r-- | .hgignore | 1 | ||||
| -rw-r--r-- | mod/doc/context/third/rst/documentation.rst | 124 |
2 files changed, 72 insertions, 53 deletions
@@ -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 |