[Doc-SIG] reStructuredText: What a cool idea!!
David Goodger
goodger@python.org
Wed, 26 Feb 2003 23:39:34 -0500
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