From 8d40fbb4fb8d57890cbf02013aa2344b9894c9f2 Mon Sep 17 00:00:00 2001 From: Philipp Gesang Date: Wed, 27 Mar 2013 00:24:28 +0100 Subject: cleanup; rewrite directives; update manual --- mod/doc/context/third/rst/documentation.rst | 75 +++++++++++++++++++++++++---- mod/doc/context/third/rst/manual.tex | 2 +- 2 files changed, 66 insertions(+), 11 deletions(-) (limited to 'mod/doc/context/third/rst') 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 -- cgit v1.2.3