macros for inline reST parsing

2 files changed, 45 insertions, 1 deletions

diff --git a/doc/documentation.rst b/doc/documentation.rst
index b561ce9..d2cdc43 100644
--- a/doc/documentation.rst
+++ b/doc/documentation.rst
@@ -84,7 +84,9 @@ changes in form of |TEX| code only, you should be able to use the
 output of |rstcontext| as starting point.
 
 However, using the module may have advantages when testing. There
-is a usage example in ``moduletest.tex``.
+is a usage example in ``moduletest.tex``.  Another example in
+``hybridtest.tex`` demonstrates the |CONTEXT| command ``\RST`` as
+well as the corresponding environment.
 
 To install the module simply copy the files into your local |TEX|
 tree. ::
diff --git a/doc/hybridtest.tex b/doc/hybridtest.tex
new file mode 100644
index 0000000..ba3bed5
--- /dev/null
+++ b/doc/hybridtest.tex
@@ -0,0 +1,42 @@
+\usemodule[rst]
+\setuphead[chapter][page=no,style=bold]
+
+\def\RSTCTX{{\em rst}\kern.5pt\CONTEXT}
+\def\reST{{\rm re}{\ss Structured}{\rm Text}}
+
+\starttext
+
+\chapter{\RSTCTX\ Hybrid Documents}
+
+This example demonstrates the macro \type{\RST} which can be used
+to process \reST\ markup directly in a normal \CONTEXT\ document.
+
+\RST{
+-------------
+This Chapter,
+-------------
+
+… for instance, was given entirely in *reST* markup. Naturally,
+there are some :bold:`drawbacks` to expect when mixing markups:
+directives and hyperlink targets that have already been specified
+somewhere above the current section will *stay* accessible in
+later passages until you redefine them. Also, certain letters
+need to be thoroughly escaped in order to make it through to the
+*reST*-parser, e.g. *\\\{* (<left brace>), and you’ll have to be
+inventive to make a backslash (*\\letterbackslash*) pass through
+the parser.
+
+}
+
+\startRST
+
+-------------
+Alternatively
+-------------
+you may always use the matching environment ``\\[start|stop]RST``
+if you prefer.
+
+\stopRST
+
+
+\stoptext