xml interface; extended module documentation

2 files changed, 82 insertions, 25 deletions

diff --git a/mod/tex/context/third/rst/rst_setups.lua b/mod/tex/context/third/rst/rst_setups.lua
index c10a914..102652b 100644
--- a/mod/tex/context/third/rst/rst_setups.lua
+++ b/mod/tex/context/third/rst/rst_setups.lua
@@ -208,6 +208,7 @@ function optional_setups.breaks ()
 % Fancy transitions                                             %
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
+% Get Wolfgang’s module at <https://bitbucket.org/wolfs/fancybreak>.
 \usemodule[fancybreak]
 \setupfancybreak[symbol=star]
 ]]
diff --git a/mod/tex/context/third/rst/t-rst.mkiv b/mod/tex/context/third/rst/t-rst.mkiv
index a332df9..0359335 100644
--- a/mod/tex/context/third/rst/t-rst.mkiv
+++ b/mod/tex/context/third/rst/t-rst.mkiv
@@ -1,6 +1,6 @@
 %D \module [
 %D         file=t-rst,
-%D      version=0.3 ‘How to Recognise Different Types of Trees from Quite a Long Way Away’
+%D      version=0.4 ‘Owl-stretching time’
 %D        title=\CONTEXT\ User Module,
 %D     subtitle=reStructuredText,
 %D       author=Philipp Gesang,
@@ -9,50 +9,74 @@
 %D      license=2-clause BSD,
 %D ]
 
-%M \usemodule[rst]
-%M \loadsetups[t-rst.xml]
+%M \usemodule  [rst]
+%M \usemodule  [int-load]
+%M \loadsetups [t-letterspace.xml]
+
+%C Read the license conditions in the file \type{COPYING}.
+
+%M \definecolor [gutenred] [x=bf221f] % rubrication from digitized Göttingen Gutenberg bible
+%M \setupinteraction [contrastcolor=gutenred,color=gutenred]
+%M
+%M \define\beautifyshowsetups{%
+%M   \unexpanded \def \setupnumfont  {\rm}%
+%M   \unexpanded \def \setuptxtfont  {\rm}%
+%M   \unexpanded \def \setupintfont  {\rm\sc\Word}%
+%M   \unexpanded \def \setupvarfont  {\rm\it}%
+%M   \unexpanded \def \setupoptfont  {\rm\it}%
+%M   \unexpanded \def \setupalwcolor {gutenred}%
+%M   \unexpanded \def \setupoptcolor {gutenred}%
+%M   \defineframedtext [setuptext] [
+%M     frame=off,
+%M     background=color,
+%M     backgroundcolor=gray:2,
+%M     width=\hsize,
+%M     height=fit,
+%M     align=right,
+%M     offset=0.75em,
+%M   ]%
+%M }
+%M 
+%M \let \Oldshowsetup \showsetup
+%M 
+%M \define [1] \showsetup {%
+%M   \bgroup \beautifyshowsetups%
+%M     \Oldshowsetup{#1}%
+%M   \egroup%
+%M }
 
 \writestatus{loading}{ConTeXt User Module / reStructuredText}
+
 \unprotect
 
 \startinterface all
   \setinterfacevariable {RST} {RST}
 \stopinterface
 
-\definenamespace [RST] [
+\definenamespace [\v!RST] [
   type=module,
   comment=reStructuredText module,
-  version=0.3,
-  name=RST,
-  style=no,
-  command=yes,
-  setup=list,
-  parent=RST,
+  version=0.4,
+  name=\v!RST,
+  style=\v!no,
+  command=\v!yes,
+  setup=\v!list,
+  parent=\v!RST,
 ]
 
 %D Loading the reStructuredText parser.
 \ctxloadluafile{rst_parser}
 
+%D Easy way to define a global test setting. Activated
+%D by \type{\usemodule[rst][test=yes]}.
+
 \startmoduletestsection
   \ctxlua{thirddata.rst_helpers.rst_debug = true}
 \stopmoduletestsection
 
-%%% Leaving this here in case we need to revert to locally
-%%% toggling debugging code.
-
-%\def\RST_enable_verbose{%
-  %\doif{\RSTparameter{debug}}\v!yes\ctxlua{thirddata.rst_helpers.rst_debug = true}%
-%}
-%\appendtoks \RST_enable_verbose \to \everysetupRST
-
-%D Setting some globals.
-%\setupRST [debug=no]
-
-%D This command loads and processes the \type{*.rst} file.
-\def\typesetRSTfile#1{\ctxlua{thirddata.rst.do_rst_file("#1")}}
-
 %D To process inline reST markup we’ll have to reset all catcodes
 %D except for grouping, escaping and cs arguments.
+
 \newcatcodetable   \RST_catcodes
 \startcatcodetable \RST_catcodes
   \catcode`\^^I = 12
@@ -73,11 +97,43 @@
   \catcode`\$   = 12
 \stopcatcodetable
 
+%D \section {User-level Commands}
+%D
+%D \subsection{Typesetting reST-Files}
+%D
+%D \macros
+%D    {typesetRSTfile}
+%D
+%D This command loads and processes an \type{*.rst} file.
+%D All necessary setups for the elements to be used (e.g. tables)
+%D have to be specified {\em before} this macro is called.
+%D As \type{\typesetRSTfile} is intended to process a single file
+%D only, it will handle \type{\start|stoptext} automatically.
+%D Thus, the user should never supply any of these manually,
+%D neither before nor after \type{\typesetRSTfile}.
+%D
+%D \showsetup{typesetRSTfile}
+
+\def\typesetRSTfile#1{\ctxlua{thirddata.rst.do_rst_file("#1")}}
+
+%D \subsection{Typesetting Inline Snippets}
+%D
+%D reST markup can be handy in situations where \CONTEXT\ markup
+%D would result in unappropriately verbose source code, e.g. when
+%D typesetting tables with simple layout.
+%D
+%D \macros
+%D    {RST,startRST}
+%D
 %D The environment \type{\[start|stop]RST} and the macro
 %D \type{\RST} allow access to reST-parser from inside a
-%D \CONTEXT-document when the module is loaded.
+%D \CONTEXT\ document when the module is loaded.
+%D
+%D \showsetup{RST}
+%D \showsetup{startRST}
 
 % Wolfgang’s code below.
+
 \unexpanded \def \startRST{%
   \begingroup
   \setcatcodetable \RST_catcodes