cleanup; rewrite directives; update manual

2 files changed, 66 insertions, 11 deletions

diff --git a/mod/doc/context/third/rst/documentation.rst b/mod/doc/context/third/rst/documentation.rst
index 924aa7a..83bf609 100644
--- a/mod/doc/context/third/rst/documentation.rst
+++ b/mod/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*).
 
@@ -413,6 +414,60 @@ caption text of the image.
 .. _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/mod/doc/context/third/rst/manual.tex b/mod/doc/context/third/rst/manual.tex
index cbb0382..b3d63db 100644
--- a/mod/doc/context/third/rst/manual.tex
+++ b/mod/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