[Doc-SIG] Announce: RTX 1.0.0 yet another plain-text-ish markup

[Mark Summerfield]

Hi,

If you're interested in plain text-ish markup you might find RTX of
interest: http://www.ourobourus.com

It is vaguely reminiscent of doxygen since it takes lots of ideas from
qdoc (of which doxygen is a public implementation).

Basically you can write with a minimally intrusive markup and produce
HTML, SGML (docbook), Lout (which generates postscript and PDF) and
plain text. It handles lists and tables as well as 'categorising'
markup, e.g. \key Alt+F. It does not support much 'formatting' markup,
e.g. fonts etc. in the text itself, but you have considerable control
over how the output works in the supported formats (so you can control
fonts, colours etc. globally for consistency by changing simple
configuration files). It is quite easy to subclass to produce your own
format (it's all written in pure Python).

I don't use it to markup Python code, at least not yet, but doing so
should be straightforward. Below are some notes on this possibility
(but extracting marked up text from Python code isn't supported yet --
but hopefully will be soon).


Here's how a fragment of David Goodger's documentation looks using
his reStructuredText:

    def __init__(self, stateclasses, initialstate, debug=0):
        """
        Initialize a `StateMachine` object; add state objects.

        Parameters:

        - `stateclasses`: a list of `State` (sub)classes.
        - `initialstate: a string, the name of the initial state (class 
name).
        - `debug`: a boolean; produce verbose output if true (nonzero).
        """

here's how you'd achieve the same thing using RTX (only I wouldn't do
this; see the final example):

    def __init__(self, stateclasses, initialstate, debug=0):
        """
        Initialize a \class StateMachine object; add state objects.

        Parameters:
	\list
        \e \p stateclasses a list of \class State (sub)classes.
        \e \p initialstate a string, the name of the initial state 
(class name).
        \e \p debug a boolean; produce verbose output if true (nonzero).
	\endlist
        """

The \e is a cell or list element, the \p is a parameter. (If you need
to group a phrase you'd do \b[bold phrase] -- yes bold and italic are
supported even though they aren't categorisation.)

The way I'd have written the thing is like this:

    def __init__(self, stateclasses, initialstate, debug=0):
        '''
        Initialize a \class StateMachine object; add state objects.

	The \p stateclasses is a list of \class State (sub)classes. The
	initial state (which is a class name) is in the \p
	initialstate string. If you want verbose output set \p debug
	to true (its default is false). 
        '''

If you wanted to do this you'd have to extract the text yourself and
then run it through RTX. I will make RTX capable of doing this itself
soon.

BTW I am not keen on defining the presentational structure within the
description itself. For me the presentation is a concern of the output
formatter and what I want to feed into that is categorisation, i.e.
this is a class name, this is a method name, etc.

-- 
Mark.