reStructured Text - suitable for non-documentation?

[Michele Simionato]

Ben Finney <bignose-hates-spam at and-zip-does-too.com.au> wrote in message news:<slrnbdle2r.h32.bignose-hates-spam at iris.polar.local>...
> Howdy all,
> 
> I'm engaged on a low-priority, long-term project to "refactor" my web
> pages.  I don't want the content in a database; I'm much more
> comfortable editing text files.  However, I do want content to be
> completely separate from presentation markup or code.
> 
> So I've been investigating the various plain-text markup schemes
> available.  I.e., the ones where the idea is that the source be
> reasonably readable as a plain-text document, and existing plain-text
> "markup" conventions be leveraged as much as possible.  The Wiki
> schemes, the BB schemes, et al are all in this group.  None of them are
> particularly satisfactory though.
> 
> My latest investigation is of reStructured Text, the proposed docutil
> markup scheme:
> 
>   <http://docutils.sourceforge.net/rst.html>
> 
> This seems a well thought out scheme, with coverage of most of the
> things I want to do in web pages.
> 
> So, some questions:
> 
> Who is using reStructured Text actively?

Many programmers.

> Who's using it for things other than Python documentation?

I am using it for everything I write (except my scientific papers
which are in latex).

> How applicable do you think it is for non-documentation text?

Very applicable, if you don't have special requirements. Notice that
rst comes with a latex writer, pretty useful if you want to print
the output. You can mix rst commands and latex commands and tune the 
final output quite well.

Still, keep in mind that rst is intended for SIMPLE documents, if
you have stringent requirements probably it is better to use a
more heavy weight approach.

> Are there non-Python tools for processing it (preferably PHP)?
> Am I insane for even thinking of such a thing?
> Are there better alternatives (i.e. ones specifically designed for
> marking up web page content in plain text)?

I leave these questions to others.

Recently, I have found a nice application for rst in the context of
DDD (Documentation Driven Development, dunno if the acronym already
exists ;)
and I thinks it may be of interest to people here (if not to the OP).

As an experiment, I started a project by writing the documentation
first.
The documentation is in rst and contains several example of usages
(plus
an appendix which is a large test suite); the examples are run by
using the following script:

# doc_test.py

"""Search text files for examples to run via doctest. Example of
usage:

$ doc_test doc1.txt -v doc2.txt doc3.txt

This runs the examples in doc1.txt in silent mode and the
examples in doc2.txt and doc3.txt in verbose mode."""

import sys,doctest

def test(*args):
    t=doctest.Tester(globs={},verbose=0) # default, non-verbose
    for name in args:
        if name=='-v': # verbose option
            t=doctest.Tester(globs={},verbose=1) 
        else: # the argument is assumed to be a filename
            t.runstring(file(name).read(),name)

if __name__=='__main__': # bare bone argument processing
    args=sys.argv[1:]
    if not args: print __doc__
    else: test(*args)

I must say that after having written the documentation and the
examples,
writing the program in such a way to satify the tests has been much
more
effective and fast than I expected, since I had exactly clear in mind
the
required specifications and I didn't wasted time in trying to
implement
more than needed (which is my usual weakness ;)

Also, doctest is *much* easier to use than unittest (that I haven't
studied
well yet...)

HTH,
                                   Michele