From 7d1114cd66025cc18535f3cdab3105e66bbda48d Mon Sep 17 00:00:00 2001 From: Philipp Gesang Date: Sat, 1 Mar 2014 22:47:25 +0100 Subject: adopt more conventional directory structure --- doc/documentation.rst | 691 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 691 insertions(+) create mode 100644 doc/documentation.rst (limited to 'doc/documentation.rst') diff --git a/doc/documentation.rst b/doc/documentation.rst new file mode 100644 index 0000000..621528d --- /dev/null +++ b/doc/documentation.rst @@ -0,0 +1,691 @@ +======================== +Features Not Implemented +======================== +Nesting +******* +Proper nesting. So far only lists support real nested structures. +There's no way you could have real paragraphs or bulleted lists +inside table cells. The problem is that with true nesting some +jobs like the dissection of tables would have to be moved from +the formatter to the parser. If you feel you need thoroughly +nested structures -- e.g. grid tables in footnotes or bullet lists +inside simple tables inside enumerations inside quotations inside +footnotes -- you should consider including |CONTEXT| code as +substitution directives. (OTOH docutils' new and old LaTeX +formatter seems to have problems with tables in footnotes as +well. Not to mention its preference for enclosing random nested +structures in ``quote``-environments.) + +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. + +Hyperlinks +********** +The hyperlink implementation should be fine in general use if you +avoid certain situations. + +- Never ever call your hyperlink targets ``anon_#``, where ``#`` + stands for any integer. Just don't do it, OK? Great. + +- Referencing a structure element like a section heading by means + of an *empty link block* does work. However, if the element in + question requests a page break (e.g. the vanilla + ``\chapter{#1}`` command), the reference will link to the + previous page instead and become useless. You can avoid this + behaviour by referencing the section directly or by targetting + the first paragraph in the section instead. + +- Link chaining does not work with internal references. This is + considered a low-priority bug and will be addressed during the + next big hyperlink overhaul. + +===== +Usage +===== +Invocation from the Command Line +******************************** +|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 ``mtxrun``: :: + + $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 +downward compatible with MkII, thus it does not matter for a +start whether you decide to test it with ``texexec`` or +``context``. + +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 specifying your own setups. +An example for prepended setups can be found in the environment +for this manual (``mod/doc/context/third/rst/manual.tex``). + +.. caution:: + The output of |rstcontext| automatically inserts necessary + setups for the components found in the input. Therefore, the + ``\starttext`` and ``\stoptext`` commands are part of the + output and may not be specified in your setups file. + For now you have to use the |CONTEXT| command + ``\appendtoks \to \starttext`` to add content like + title pages and indices to the result. This mechanism works + reliable as long as you have an eye on the order in which the + tokens are given. Again, have a look at ``manual.tex`` to get + an impression how useful this can be. User hooks for these + and other common constructs are thought of but have yet to be + implemented. + +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/doc/context/third/rst/documentation.rst . + +Now run |rstcontext| on the main documentation file as follows: :: + + $mtxrun --script rst --if=documentation.rst --of=doc.tex + +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, auto-generated code will not 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, and compatibility with + it is not a primary objective for |rstcontext|. + However, an effort has been made to keep the output essentially + MkII clean. Do not expect Unicode 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, i.e. if the minimals reside in ``~/context/``, you would +issue the following line: :: + + $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 +========= + +|rstcontext| was developed for the largest part by going through +the |rst| specification_ step by step and tested against the +examples given both in the spec and in the `quick reference`_. +Therefore you should refer to those examples first (and drop me a +note immediately if any of them stopped working). +All kinds of text blocks and inline markup have been implemented +with the exception of anything mentioned in the section on +`Features Not Implemented`_. +Some of them that I have not found a real-world usage for (such +as *definition lists*) do not yet have a presentable output -- +there is room for improvements that should be supplied by +somebody who actually uses those features. + +.. _specification: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html +.. _quick reference: http://docutils.sourceforge.net/docs/user/rst/quickref.html + +Block Quotes +************ + +The *block quote* syntax is fully supported, including +attributions. For instance, the next snippet: :: + + Some people have made the mistake of seeing Shunt’s work as a + load of rubbish about railway timetables, but clever people + like me, who talk loudly in restaurants, see this as a + deliberate ambiguity, a plea for understanding in a + mechanized world. + + --- Gavin Millarrrrrrrrrr on Neville Shunt + +gets you a neatly indented quotation, typeset in a slightly +smaller font magnitude. + + Some people have made the mistake of seeing Shunt’s work as a + load of rubbish about railway timetables, but clever people + like me, who talk loudly in restaurants, see this as a + deliberate ambiguity, a plea for understanding in a + mechanized world. + + --- Gavin Millarrrrrrrrrr on Neville Shunt + +Don’t forget proper indentation. + +Numbered List +************* + +Save for nesting lists are fully implemented in |rstcontext|. +The following code typesets a triple-nested list with different +kinds of bulleting / numbering: :: + + i First order list, first entry. + + ii First order list, second entry. + + iii First order list, third entry. + + - Second order list, first entry. + + # Third order list, first entry. + + # Third order list, second entry. + + # Third order list, third entry. + Real nesting rules! + + - Second order list, second entry. + + iv First order list, fourth entry. + + v First order list, fifth entry. + +The result looks like this: + +i First order list, first entry. + +ii First order list, second entry. + +iii First order list, third entry. + + - Second order list, first entry. + + # Third order list, first entry. + # Third order list, second entry. + # Third order list, third entry. + Real nesting rules! + + - Second order list, second entry. + +iv First order list, fourth entry. + +v First order list, fifth entry. + +.. caution:: + Don’t forget the blank lines between list items. + +Line Blocks +*********** + +Line blocks are a convenient environment for parts of the text +that need to preserve line breaks and indentation. This makes it +the first choice for most kinds of poems: :: + + | When does a dream begin? + | Does it start with a goodnight kiss? + | Is it conceived or simply achieved? + | When does a dream begin? + | + | When does a dream begin? + | Is it born in a moment of bliss? + | Or is it begun when two hearts are one? + | When does a dream exist? + | + | The vision of you appears somehow + Impossible to resist + | But I'm not imagining seeing you + For who could have dreamed of this? + | + | When does a dream begin? + | When reality is dismissed? + | Or does it commence when we lose all pretence? + | When does a dream begin? + +Indentation, continued lines, etc. should work out without +problems: + +| When does a dream begin? +| Does it start with a goodnight kiss? +| Is it conceived or simply achieved? +| When does a dream begin? +| +| When does a dream begin? +| Is it born in a moment of bliss? +| Or is it begun when two hearts are one? +| When does a dream exist? +| +| The vision of you appears somehow + Impossible to resist +| But I'm not imagining seeing you + For who could have dreamed of this? +| +| When does a dream begin? +| When reality is dismissed? +| Or does it commence when we lose all pretence? +| When does a dream begin? + + +========== +Directives +========== +Admonitions +************ +The following admonition directives have been implemented: + +Caution +------- +The *caution* directive results in the text being prefixed by one +“dangerous bend” symbol in order to resemble the “wizards only” +passages of the TeXbook. +For example, the directive: :: + + .. caution:: White mice do worse in experiments than grey mice. + +will result in the following: + +.. caution:: White mice do worse in experiments than grey mice. + +Danger +------ +Similar to the *caution* directive, the *danger* directive +prefixes the given text with two “dangerous bends” giving it the +look of Knuths’s “esoteric” annotations. + +.. danger:: Be nice to the parser: + Don’t forget to align paragraphs that end a literal + block! + + +Images +****** +Including pictures is easy using the *image* directive: simply +supply it the name of the image file as in ``.. image:: cow``. +If the format is supported by |CONTEXT| the suffix can be +neglected. + +The placement of images can be controlled via a set of optional +arguments, each of which has to be specified on single line in +``key: value`` style: :: + + .. image:: cow + width: hsize + caption: A generic Dutch cow. + +This will place your image somewhere close to the spot where you +defined it. (The placement parameter to ``placefigure`` will be +set to ``here`` by default.) + +.. image:: cow + cow.pdf + width: hsize + alt: A generic Dutch cow (*bos primigenius taurus*). + +The supported parameters are ``width`` +(alias: ``size``), ``caption`` and ``scale``. +The *width* parameter accepts the values ``hsize`` +(alias: ``fit``, ``broad``) or ``normal``. +Alternatively, the *scale* parameter allows for arbitrary +manipulation of the desired magnification; it defaults to ``1`` +(unscaled). +The value passed as *caption* parameter will be used in as the +caption text of the image. + +.. |CONTEXT| ctx:: \CONTEXT +.. |TEX| ctx:: \TeX +.. |PDFTEX| ctx:: \PDFTEX +.. |LUATEX| ctx:: \LUATEX +.. |rstcontext| ctx:: \bgroup\em rst\egroup\kern.5pt\CONTEXT +.. |rst| ctx:: \bgroup\rm re\egroup\bgroup\ss Structured\egroup\bgroup\rm Text\egroup +.. |LATEX| ctx:: \LATEX + +.. _outline: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html +.. _docutils: http://docutils.sourceforge.net/ +.. _Pandoc: http://johnmacfarlane.net/pandoc/ + +Containers +********** + +Upon request |rstcontext| now supports another kind of +directive, namely containers_. +Due to their being defined explicitly in terms of HTML, +*containers* lack a corresponding construct in |CONTEXT| (or +|TEX| for that matter). +Some parts of |CONTEXT| (e. g. ``\\framed``) come quite close with +respect to functionality as well as generality. +However, none of the candidates alone covers the entire spectrum +of functionality that containers_ are supposed to. +For that reason the implementation leaves them essentially +undefined. + +If an explicit name is specified, then the ``container`` +directive maps to the environment of that name. +Anonymous containers are interpreted as a |TEX| group. +Any text block inside the element is treated as ordinary +paragraph. +In below example the content will be handled as if between +``\\startxyzzy`` and ``\\stopxyzzy``, where it is up to the user to +define the *xyzzy* environment:: + + This is a paragraph. + + .. container:: xyzzy + + whatever + + foo **bar** baz + + This is another paragraph. + +The middle part translates to |CONTEXT| as follows:: + + \start[xyzzy]% + whatever + + foo {\sc bar} baz + \stop + +Note that the ``\\start[foo]``/``\\stop``-environment is equivalent +to ``\\startfoo``/``\\stopfoo``, except that the environment +doesn’t actually need to be defined. + +.. caution:: + Support for the *container* directive is considered + experimental. + Suggestions for improving or extending the current + implementation are always welcome. + +.. _containers: http://docutils.sourceforge.net/docs/ref/rst/directives.html#container + +======================= +Substitution Directives +======================= + +There are substitution directives for simple *replacing* and +for insertion of |LUATEX|’s three languages: |mp|, Lua and, +of course, |TEX|. + +.. |mp| replace:: \METAPOST + +Ordinary text replacement is done via the ``replace`` +substitution directive. E.g. in the main text you consistently +use ``|replaceme|`` and have all its occurences substituted by +``I wasn’t in the mood to write out this long sentence.`` +like in the next snippet: + +:: + + .. |replaceme| replace:: + I wasn’t in the mood to write out this long sentence. + +The code insertions work similarly. You have to specify some +phrase that gets substituted by the code you supply. +E.g. this document accesses the fancy logos predefined in the +|CONTEXT| core via substitutions: :: + + .. |CONTEXT| ctx:: \CONTEXT + .. |LUATEX| ctx:: \LUATEX + +Etc. pp. The respective directive names are ``ctx``, ``mp`` and +``lua``. In order to get a |circle| drawn on spot, you would +define a Metapost substitution: + +:: + + .. |circle| mp:: + fill fullcircle scaled(8) withcolor blue; + +================ +Special Features +================ +Text Roles +********** + +The default *role* for interpreted text is *emphasis*. + +The role marker provides explicit access to formatting commands. +The formatting routine for inline literals can be called with the +role marker :literal:`literal`, strong emphasis likewise is +achieved via the role marker :literal:`strong_emphasis`. + +Other roles that lack an equivalent among inline markup are +``bold``, :ss:`ss` (alias :literal:`sans_serif`), +``uppercase``, ``lowercase`` and colors. +Color roles begin with the string ``color_`` (the underscore is +compulsive), followed by either the string ``rgb_`` or a +`valid color name`__. +An rgb vector is specified in decimal. +Its values can be separated by either dashes or underscores. +Thus, ``color_rgb_.3_.5_.8`` is a valid rgb expression, as is +``color_rgb_0-1-0``. +Unforturnately, the colon character ``:`` has to be escaped in +color expressions, e.g. ``color_gray\:5``. + +__ http://wiki.contextgarden.net/Colors#Using_predefined_colors:_.5Csetupcolor + +For example, to give Mr. Neville Shunt’s work an apt +typographic representation you can use these roles instead of +the standard inline markup: :: + + :color_rgb_.9_.2_.7:`Chuff`, chuff, :literal:`chuffwoooooch`, + woooooch! Sssssssss, sssssssss! :uppercase:`Diddledum`, + `diddledum`, diddlealum. :literal:`Toot`, toot. The train + :bold:`now` standing :color_gray\:5:`at` platform :ss:`eight, + tch`, tch, :color_rgb_0-1-0:`tch`, + :color_rgb_.5-.6-.2:`diddledum`, diddledum. + :lowercase:`Chuffff`, :strong_emphasis:`chuffffiTff` + eeeeeeeeeaaaaaaaaa :color_red:`Vooooommmmm`. + +which yields when passed through |rstcontext|: + +:color_rgb_.9_.2_.7:`Chuff`, chuff, :literal:`chuffwoooooch`, +woooooch! Sssssssss, sssssssss! :uppercase:`Diddledum`, +`diddledum`, diddlealum. :literal:`Toot`, toot. The train +:bold:`now` standing :color_gray\:5:`at` platform :ss:`eight, +tch`, tch, :color_rgb_0-1-0:`tch`, +:color_rgb_.5-.6-.2:`diddledum`, diddledum. :lowercase:`Chuffff`, +:strong_emphasis:`chuffffiTff` eeeeeeeeeaaaaaaaaa +:color_red:`Vooooommmmm`. + +************************** +Bibliography and Citations +************************** + +.. caution:: + Not much for now concerning the usage of Taco’s bib system. + It’s just that I use my own bibliography system and never + became sufficiently familiar with the standard |CONTEXT| + approach. *If you feel that the current support should be + improved then feel free to contact me!* I will need somebody + for testing. + +When |rstcontext| first encounters a citation (``[texbook]_``) it +automatically looks up a bibliography in the working directory by +the name of ``\jobname``. E.g. with a main file ``manual.tex`` +bibtex will use the database called ``manual.bib``. Symlinking +your bibliography file in the local tree should suffice and you +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 +=================== + +The docutils_ provide means to translate the extra-convenient +markup language |rst| into various formats like PDF, HTML and +|LATEX|, unfortunately omitting the One True Macro System: +|CONTEXT|. + +As far as I am aware of it, there is some support for |rst| in +Pandoc_ but as it relies on a rather large set of dependencies it +proved very difficult (too difficult for me) to install on my +favourite distribution. +From the `interactive demo`__ I gather that support for |rst|’s +language features is not very extensive and the result did not +even come with proper setups. +Additionally, it’s written in a language I am not familiar with +and that does not make use of one the most awesome features of +all the the extended capabilities |LUATEX| provides: the Lua +interpreter. + +For quite some time I was thinking about how to implement an +|rst| parser in |LUATEX|, until some discussion__ emerged on the +|CONTEXT| mailing list that indicates a broader interest in +convenient markup languages across the community. +As the alternatives mentioned above don’t meet the expectations +of a normal |CONTEXT| user, the initial step to write +|rstcontext| was done. +Handling most of the corner cases and usability features of |rst| +proved in the end not nearly as easy as I imagined. + +__ http://johnmacfarlane.net/pandoc/try +__ http://archive.contextgarden.net/message/20100814.051917.28caafcd.en.html + +.. caution:: + |rstcontext| is experimental software and neither feature + complete nor thoroughly commented. Keep this in mind before you + start using it. Anything might still be subject to change, so + expect breakage *in case you start relying on exceptional + behaviour* (read: bugs) that does not conform to the |rst| + specification. Consider filing a bug report instead and wait for + me (the maintainer) to fix it, because regardless of how much + testing I do myself I alway run into the weirdest issues only + during the actual deployment of the software. Thus, if you notice + that |rstcontext| does not adhere to the outline_ of |rst| + according to the Docutils documentation, very likely you have + discovered a corner case I was not aware of. + +.. |circle| mp:: + fill fullcircle scaled(8) withcolor blue; + + +======= +License +======= + +:: + + Copyright 2010-2013 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. + + +.. vim:tw=65 -- cgit v1.2.3