[Doc-SIG] reStructuredText: What a cool idea!!

[David Goodger]

Stefan Merten wrote:
> first of all I'd like to apologize if this is off-topic on this
> list.

Not really off-topic here, but there are two Docutils-specific lists
also: <http://lists.sourceforge.net/lists/listinfo/docutils-users> for
usage questions, and
<http://lists.sourceforge.net/lists/listinfo/docutils-develop> for
developers.  Recent archives are also available at <http://gmane.org>.
This list is more general and it has a greater readership.

> I don't know whether you already know, but reStructuredText is
> mentioned on
> 
>     http://www.ibm.com/developerworks/library/x-matters24/

Yes, it's a good article.  A few details could be corrected, but
nothing major.

> I saw it there, read the specification and some more - and I'm
> absolutely delighted :-) !!

Glad you like it.

> * Is there a Perl implementation already? Does anybody plan such a
>   beast?

Mark Nodine <nodine@somerset.sps.mot.com> is working on a Perl
implementation of the reStructuredText parser.  He hasn't released any
code yet, though.

> * Is there a Emacs mode already?

Not yet.  There are a few functions in
tools/editors/emacs/restructuredtext.el, available from CVS or the
snapshot (<http://docutils.sf.net/docutils-snapshot.tgz>).

>   Particularly it there `font-lock'
>   support for reStructuredText documents available?

No.  It's an interesting idea, although I'm not sure how it would
work.

>   If no such thing is available I could give it a try.

Please do!

> * Are there transformation tools from OpenOffice format to
>   reStructuredText?

There is work being done on OpenOffice.org XML *writers*, but nothing
to my knowledge the other way.

>   For SDF lately I created a suite of XSLT style sheets which
>   transform the `styles.xml' and `content.xml' contained in `.sxw'
>   and `.sxc' to SDF. Though this involves some post processing by
>   hand it is *much* easier than anything I did before.

Sounds like a good approach.  I've heard of people setting up
semi-automated systems to assist with conversion.

>   Of course I'd like to see this for reStructuredText as well. If
>   no-one did this until know, I could rewrite my XSLT scripts a bit
>   to support reStructuredText.

Such code would be welcome.

> * Is there a transformation for Docutils Document Tree documents in
>   XML to a reStructuredText source form? Or following PEP 258: Is
>   there a writer for reStructuredText?

There has been some discussion about a generic to-reStructuredText
conversion system, perhaps a Docutils "Writer", but no implementation
yet.

> * Are there plans to support embedded code in reStructuredText
>   documents?

I believe Mark Nodine's Perl implementation has it.  There are notes
about at <http://docutils.sf.net/spec/notes.html#misc-exec>.  Such a
feature is inherently dangerous though, and there have to be
safeguards in place to prevent reStructuredText/Docutils being used as
a vector for viruses & trojans.

> * Are there writers for plain text and/or manual pages?

Not that I know of.  I recall some discussion, but nothing concrete.

> Finally I'd like to draw your attention to
> 
>     http://template-toolkit.org/

Looks useful, but templating systems are plentiful.

> One thing I particularly liked with SDF is the feature to embed SDF
> or other stuff in anything which supports comments. This way you
> were able to embed for instance POD documentation in a C++ file. One
> of the nice features is, that it rearranges the embedded code
> allowing you to write your documentation at the place of the
> definition and nonetheless get every piece of documentation at the
> right place in the final document.

Sounds like "literate programming".  Do you have a link to a
description of how SDF accomplishes this rearranging?

> In the free software project I started lately
> [http://savannah.nongnu.org/projects/mamo/] I created a plug-in for
> the Template Toolkit which exactly does this sort of gathering of
> snippets of documentation from an arbitrary source file
...
> Thinking reStructuredText and Docutils it might qualify as the input
> part of a reader.

I don't understand the implications.  Can you describe this for us?

-- David Goodger    http://starship.python.net/~goodger

Programmer/sysadmin for hire: http://starship.python.net/~goodger/cv