summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/context
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2013-03-31 23:44:06 +0000
committerKarl Berry <karl@freefriends.org>2013-03-31 23:44:06 +0000
commitab58cc28266fe58eb6293cca6bf08262eb103719 (patch)
treeb9b458a93269d5d8b40b4ae10cdbc804bce9b56e /Master/texmf-dist/doc/context
parent21d4c66b858e7e5a624693762b51ccd29c7c989e (diff)
context-rst (30mar13)
git-svn-id: svn://tug.org/texlive/trunk@29575 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/context')
-rw-r--r--Master/texmf-dist/doc/context/third/rst/COPYING2
-rw-r--r--Master/texmf-dist/doc/context/third/rst/README.rst96
-rw-r--r--Master/texmf-dist/doc/context/third/rst/documentation.rst79
-rw-r--r--Master/texmf-dist/doc/context/third/rst/manual.pdfbin120193 -> 122205 bytes
-rw-r--r--Master/texmf-dist/doc/context/third/rst/manual.tex2
5 files changed, 124 insertions, 55 deletions
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
--- a/Master/texmf-dist/doc/context/third/rst/manual.pdf
+++ b/Master/texmf-dist/doc/context/third/rst/manual.pdf
Binary files 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