[Doc-SIG] reStructuredText: What a cool idea!!
Stefan Merten
smerten@oekonux.de
Mon, 24 Feb 2003 23:57:56 +0100
-----BEGIN PGP SIGNED MESSAGE-----
Hi hackers and others,
first of all I'd like to apologize if this is off-topic on this list.
If so it would be nice if someone could tell me, where this belongs
to.
I don't know whether you already know, but reStructuredText is
mentioned on
http://www.ibm.com/developerworks/library/x-matters24/
I saw it there, read the specification and some more - and I'm
absolutely delighted :-) !!
First, I'd like to tell you a bit about my background.
I love the Perl idea of embedding documentation in the source code
using POD. To me it became a habit documenting everything while or
often even before coding something. I guess that was, what Larry had
in mind when inventing POD :-) .
Another nice aspect of POD is, that it's ASCII based and thus it is
useful to use CVS on it and/or the miracles of the Emacs' ediff
package. And of course you do not need any special editor to work with
this format. Instead every editor supporting plain ASCII works. And
nonetheless you can produce lots of output formats. By a simple `make'
call if you like. All in all POD allowed for a lot of nice features
with a high degree if automatization, versioning and so on.
So I started to write all my documents in POD. However, POD is a
rather limited markup format. If you want to write something
different from a manual page you'll immediately run into a number of
limitations. So I looked for an alternative.
I found SDF [http://search.cpan.org/author/IANC/sdf-2.001/, the
original site doesn't exist any more but it is embedded in the
package]. SDF is a rather great tool very much in the spirit of
reStructuredText. One feature I particularly like is, that it is
possible to embed (Perl) code in your text document to do some very
specific job. Anyway it is easy to combine SDF with Perl to create
really great stuff. The most elaborated thing I did with SDF were some
filters which take a high level interface description for an API and
produce include files for C, C++, Sicstus Prolog, and Java.
Well, since I discovered SDF I'm using SDF for nearly everything. In
particular the web sites I'm maintaining are all created by SDF and
`make'.
However, SDF has a number of drawbacks:
* The code is based on Perl 4 (before references were invented in
Perl) and it's - ummm - somewhat ugly. I thought about rewriting it
from scratch but I've got no time for such a task.
* There is a great number of nice ideas but there is not much of an
overall concept.
* No community developed - at least no community visible to me. This
may be partly because the maintainer Ian Clatworthy (thanks Ian for
all of your efforts) seemingly gave up the project shortly after I
discovered it (in 1999). (I never contacted him, so I could not have
been the reason ;-) .)
* It did not reach a wide distribution and thus virtually nobody is
used to using it.
So though personally I'm rather happy with SDF I don't like the
thought of being trapped in a evolutionary dead end.
And now I found reStructuredText. I read the specification and though
today reStructuredText misses some things of what SDF has, I see that
there is a potential for reStructuredText for being a very powerful
tool - much more than SDF ever was. Particularly because there seems
to be an active maintainer (thanks David Goodger and all for the
*great* web site, I particularly like that the discussion of
alternatives is listed) and seemingly a very interested community.
Personally I think it would be a great gift to the world to establish
a text format which is easy to write but yet powerful. In short: I
fully support all the goals listed for reStructuredText. I think over
time I'll reformat all my sources to use reStructuredText. Ahmm - as
you may have noted I'm coming from the Perl community and I don't know
Python yet and at the moment I'm not planning to change that. But when
talking about a format this is of little importance of course.
Well, now you know why I'm here :-) .
Now for the question part of this mail. Indeed I have a number of
questions about reStructuredText and it's implementation. I'm sorry if
any of these questions is already answered on one some web page. I did
not read all of the pages yet.
* Is there a Perl implementation already? Does anybody plan such a
beast?
Admittedly I thought of doing it - but my time is *very* limited
:-( . However, that's a itch I'd like to scratch.
* Is there a Emacs mode already? Particularly it there `font-lock'
support for reStructuredText documents available?
Personally I got used so much to font-locking I find it an
unbearable pain to read text containing formal syntax without
appropriate coloring.
If no such thing is available I could give it a try.
* Are there transformation tools from OpenOffice format to
reStructuredText?
This question may need some explanation.
I have the problem, that sometimes I receive M$ `.doc's and `.ppt's
or `.rtf's I'd like to transform to SDF to embed them in a web site.
Before OpenOffice and it's XML based document format this was a
difficult task needing a lot of unautomatable work. I wrote a tool
for RTF but Powerpoint was beyond automatization.
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. In effect by (ab)using
the input filters of OpenOffice I now have a whole lot of formats I
can transform to SDF with reasonable effort.
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.
* 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?
If so the Docutils Document Tree could be used as an XML based
representation and all the nice things of XML are available.
For instance one could write an XSLT transformation from an
OpenOffice format to Docutils Document Tree format and
transformations in all thinkable directions are possible.
* Are there plans to support embedded code in reStructuredText
documents?
The embedded code needs access to the embedding document of course.
May be this is similar to JavaScript embedded in HTML pages.
Of course I'd prefer support for Perl ;-) .
* Are there writers for plain text and/or manual pages?
Finally I'd like to draw your attention to
http://template-toolkit.org/
It's a very cool tool which allows for a wide range of automation. It
virtually adds a powerful macro language to every ASCII based format.
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. However, as SDF is usually not available this feature is of
limited use if you're going to share your source with others :-( .
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
[http://savannah.nongnu.org/cgi-bin/viewcvs/mamo/mamo/lib/perl5/Mamo/Temp=
late/Plugin/Gather.pm].
Thinking reStructuredText and Docutils it might qualify as the input
part of a reader.
Mit Freien Gr=FC=DFen
Stefan
-----BEGIN PGP SIGNATURE-----
Version: 2.6.3in
Charset: noconv
Comment: Processed by Mailcrypt 3.5.7, an Emacs/PGP interface
iQCVAwUBPlqjdAnTZgC3zSk5AQGjVgQArL3NYg0OThGf7Xi++LJPUgKnS0HyRfT6
bek6sjLiYOSfDLQPFAfWjeVhRKaMt4P+nKhIqVPuT/Jfe3nj/LgxTOMdWspjE7gU
CT6VA2qKNpuAAvoIc9BoW9nL4bQE3fgnETENtdZROlg4kiQLwGKzTr1VWs+uLvqt
nSzPi3EddpI=3D
=3DalwL
-----END PGP SIGNATURE-----