From ab58cc28266fe58eb6293cca6bf08262eb103719 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Sun, 31 Mar 2013 23:44:06 +0000 Subject: context-rst (30mar13) git-svn-id: svn://tug.org/texlive/trunk@29575 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/context/third/rst/COPYING | 2 +- Master/texmf-dist/doc/context/third/rst/README.rst | 96 ++++++++++++--------- .../doc/context/third/rst/documentation.rst | 79 ++++++++++++++--- Master/texmf-dist/doc/context/third/rst/manual.pdf | Bin 120193 -> 122205 bytes Master/texmf-dist/doc/context/third/rst/manual.tex | 2 +- 5 files changed, 124 insertions(+), 55 deletions(-) (limited to 'Master/texmf-dist/doc/context/third') diff --git a/Master/texmf-dist/doc/context/third/rst/COPYING b/Master/texmf-dist/doc/context/third/rst/COPYING index 6d4166538b7..ac0eb7c9fc6 100644 --- a/Master/texmf-dist/doc/context/third/rst/COPYING +++ b/Master/texmf-dist/doc/context/third/rst/COPYING @@ -1,4 +1,4 @@ -Copyright 2010-2012 Philipp Gesang. All rights reserved. +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: diff --git a/Master/texmf-dist/doc/context/third/rst/README.rst b/Master/texmf-dist/doc/context/third/rst/README.rst index 8c0e6fd75db..571b8aec104 100644 --- a/Master/texmf-dist/doc/context/third/rst/README.rst +++ b/Master/texmf-dist/doc/context/third/rst/README.rst @@ -1,20 +1,32 @@ -============== -General Advice -============== +======================================================================= + General Advice +======================================================================= Read the section *Features Not Implemented* in the manual first. -*Note*: if you happen to read this on BitBucket_, the error messages some lines -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.: :: +*Note*: if you happen to read this on BitBucket_, the error messages +some lines below just mean that *their* implementation doesn’t +understand |TeX| directives. Don’t worry, |rstcontext| does. + +======================================================================= + Installation +======================================================================= +With ConTeXt Standalone +*********************** +An up to date version of the module is installed along with the ConTeXt +distribution (*Standalone*, formerly known as *The Minimals*). +The module should be working out of the box if you installed from the +official source_ and provided the parameter ``--modules=all``. + +.. _source: http://wiki.contextgarden.net/ConTeXt_Standalone#Installing_third_party_modules + +Manually +******** +Firstly, get the module source from BitBucket_ (see the *downloads* +section). +In order to install |rstcontext|, copy everything in the ``mod/`` +subdirectory into your local |CONTEXT| tree and update the filename +database, i.e. :: cp -r mod/* ~/context/tex/texmf-local/ context --generate @@ -22,48 +34,50 @@ i.e.: :: if the |CONTEXT| minimal distribution happens to be installed at ``~/context/``. -===== -Usage -===== +======================================================================= + Usage +======================================================================= -As rstConTeXt was developed on *texlua*, you may expect it to run best with this -interpreter. For now the script accepts two command line arguments: the input -file and the output file. The following will demonstrate the main usage in a -separate directory: :: +As rstConTeXt was developed on *texlua*, you may expect it to run best +with this interpreter. For now the script accepts two command line +arguments: the input file and the output file. The following will +demonstrate the main usage in a separate directory: :: mkdir tmp; cd tmp 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 -subsequently run through |CONTEXT| to generate the final ``manual.pdf``. You -will find extended instructions on how to build the manual with some cosmetic -improvements in the section *Usage* of the manual itself. +This should have gotten you the manual converted to a file ``doc.tex`` +which was subsequently run through |CONTEXT| to generate the final +``manual.pdf``. You 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. For usage examples see the files -``hybridtest.tex`` and ``moduletest.tex`` in the ``doc`` subdirectory. +There is also a small module ``t-rst.mkiv`` which permits direct +typesetting of reST markup with |CONTEXT| MkIV. For usage examples see +the files ``hybridtest.tex`` and ``moduletest.tex`` in the ``doc`` +subdirectory. -======= -License -======= +======================================================================= + License +======================================================================= -|rstcontext| is free software and may be redistributed under the terms of the -2-clause BSD license. You should have recieved a copy of this license in a file -named “COPYING” in the source tree. If there is no such file then please contact -the maintainer_ (Contact_). +|rstcontext| is free software and may be redistributed under the terms +of the 2-clause BSD license. You should have recieved a copy of this +license in a file named “COPYING” in the source tree. If there is no +such file then please contact the maintainer_ (Contact_). -======= -Contact -======= +======================================================================= + Contact +======================================================================= -|rstcontext| was written by Philipp Gesang, ``phg42.2a`` at ``gmail`` dot -``com`` (find me on BitBucket_). +|rstcontext| was written by Philipp Gesang, ``phg42.2a`` at ``gmail`` +dot ``com``. .. |rstcontext| ctx:: {{\em rst}\kern.5pt\CONTEXT} .. |TeX| ctx:: {\TEX} .. |CONTEXT| ctx:: {\CONTEXT} .. _Contact: phg42.2a@gmail.com -.. _BitBucket: http://bitbucket.org/phg +.. _BitBucket: http://bitbucket.org/phg/context-rst .. _maintainer: Contact_ diff --git a/Master/texmf-dist/doc/context/third/rst/documentation.rst b/Master/texmf-dist/doc/context/third/rst/documentation.rst index 90168a3fa1a..621528de7d7 100644 --- a/Master/texmf-dist/doc/context/third/rst/documentation.rst +++ b/Master/texmf-dist/doc/context/third/rst/documentation.rst @@ -114,20 +114,20 @@ 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. + 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 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. +- *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 @@ -388,6 +388,7 @@ 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*). @@ -405,14 +406,68 @@ caption text of the image. .. |TEX| ctx:: \TeX .. |PDFTEX| ctx:: \PDFTEX .. |LUATEX| ctx:: \LUATEX -.. |rstcontext| ctx:: {\em rst}\kern.5pt\CONTEXT -.. |rst| ctx:: {\rm re}{\ss Structured}{\rm Text} +.. |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 ======================= @@ -603,7 +658,7 @@ License :: - Copyright 2010-2011 Philipp Gesang. All rights reserved. + 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 diff --git a/Master/texmf-dist/doc/context/third/rst/manual.pdf b/Master/texmf-dist/doc/context/third/rst/manual.pdf index 60e26dd060b..4150a13def1 100644 Binary files a/Master/texmf-dist/doc/context/third/rst/manual.pdf and b/Master/texmf-dist/doc/context/third/rst/manual.pdf differ diff --git a/Master/texmf-dist/doc/context/third/rst/manual.tex b/Master/texmf-dist/doc/context/third/rst/manual.tex index cbb0382d968..b3d63db6989 100644 --- a/Master/texmf-dist/doc/context/third/rst/manual.tex +++ b/Master/texmf-dist/doc/context/third/rst/manual.tex @@ -53,7 +53,7 @@ \vfill \framed [align=right,frame=off,topframe=on] {% \tfxx\ss\setupinterlinespace[small]\noindentation -Copyright 2010--2012 by Philipp Gesang, Heidelberg.\par +Copyright 2010--2013 Philipp Gesang, Radebeul.\par Mail any bug reports, patches or suggestions to\par \type{string.format("%s@%s.com", "phg42.2a", "gmail")}\par or pay a visit to \goto{my BitBucket home}[url(http://bitbucket.org/phg/)].\par -- cgit v1.2.3