reStructured Text - suitable for non-documentation?
Ben Finney
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?
Who's using it for things other than Python documentation?
How applicable do you think it is for non-documentation text?
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)?
--
\ Q: "I've heard that Linux causes cancer..." Torvalds: "That's |
`\ a filthy lie. Besides, it was only in rats and has not been |
_o__) reproduced in humans." -- Linus Torvalds |
http://bignose.squidly.org/ 9CFE12B0 791A4267 887F520C B7AC2E51 BD41714B
Florian Schulze
I want to do exactly the same. I already started to use it to some extend
and for me it works well. I use rst2html from the docutils sandbox and I
rewrote my own version of ht2html to better suite my needs. The website
isn't online yet, but it looks very promising. If you are interested, I can
send you an example. I have to do one anyway, because I want to show it to
a friend. I also want to include template functionality. The goal is to
move all the things that can be postprocessed to my local machine. Before I
did much stuff in PHP, but that isn't really needed as it's not dynamic.
Florian
David Goodger
> This seems a well thought out scheme, with coverage of most of the
> things I want to do in web pages.
And it's getting more capable all the time, from users' feature requests.
> Who is using reStructured Text actively?
Lots of people. Do a Google search for "generated by docutils from
restructuredtext source" to see a sample (that text can be generated as
a footer). Search for "restructuredtext" (one word) or "restructured
text" (two) to see lots of articles about it as well.
> Who's using it for things other than Python documentation?
People are using it to make web pages, to write books, and more.
> How applicable do you think it is for non-documentation text?
Very (but I'm biased). Let us know what you think.
> Are there non-Python tools for processing it (preferably PHP)?
Mark Nodine is working on a Perl version, but it isn't released yet.
Haven't heard of anything in PHP.
> Am I insane for even thinking of such a thing?
Not at all. Multiple implementations would be welcome. Docutils and
reStructuredText are still very much in development though, evolving as
needs arise.
> Are there better alternatives (i.e. ones specifically designed for
> marking up web page content in plain text)?
I don't know about "better", but there are a number of alternatives out
there with different design philosophies. There's Textile/PyTextile,
which is like an HTML shorthand, which might be suitable for your task.
--
David Goodger http://starship.python.net/~goodger Projects:
* Python Docutils: http://docutils.sourceforge.net/
(includes reStructuredText: http://docutils.sf.net/rst.html)
* The Go Tools Project: http://gotools.sourceforge.net/
Michele Simionato
> 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
Max M
> 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).
Knuth beat you to it. Google for "litterate programming"
--
hilsen/regards Max M Rasmussen, Denmark
http://www.futureport.dk/
Fremtiden, videnskab, skeptiscisme og transhumanisme
Michele Simionato
> Michele Simionato wrote:
>
> > 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).
>
>
> Knuth beat you to it. Google for "litterate programming"
Hey, literate programming is great!!
But if it was invented in 1984, why is it so little
widespread ? I hardly heard about it before today
(except for Leo, the literate programming editor,
which however I never tried).
BTW, I have in mind an integration of documentation+test suite,
not documentation+program (a la Knuth).
Bye,
--
Michele
Niklas Frykholm
I am, both at home and at work.
At home I use it for everything that does not have to be heavily
structured (XML) or heavily formatted (raw HTML, LaTeX, Quark),
such as letters, notes, works of fiction, etc.
At work we use a reST-based Wiki for all our internal documentation
(which is not Python-related).
> Am I insane for even thinking of such a thing?
Certainly not. If I were to rewrite my web pages today I would
write most of it in reST (using Leo :). I would only write the
front page and the graphics intense pages in HTML.
> Are there better alternatives (i.e. ones specifically designed for
> marking up web page content in plain text)?
It all depends on what you want to do and what you mean by better.
If the formatting options provided by reST (headlines, lists,
footnotes, etc..) covers your needs, then I think you will have a
hard time finding a better markup.
If reST provides _almost_ everything you might still want to use
it and try one of the following options
- pre- or post-process your document to add your own markup
- implement your own custom reST directives
- use the .. raw directive to include raw HTML where needed
// Niklas
David Goodger
> At work we use a reST-based Wiki for all our internal documentation
> (which is not Python-related).
Which wiki are you using? If it's not already available, would you
consider contributing your work back to Docutils and/or to the wiki project?
(I wanted to send this privately. Another victim of spam.)
-- David Goodger
Raymond Hettinger
"Michele Simionato" <mi...@pitt.edu> wrote in message
> Hey, literate programming is great!!
>
> But if it was invented in 1984, why is it so little
> widespread ? I hardly heard about it before today
> (except for Leo, the literate programming editor,
> which however I never tried).
It is still around and has many incarnations such as CWEB,
Leo, etc. There a few issues limiting its popularity.
One of the core ideas is write a piece of documentation that
is a cross between a well written essay and concrete detail
documentation. The problem here is that not that many
people write well enough to achieve even the essay and
even fewer can effectively combine that with detail docs.
The writing skills need to augmented by knowledge of
the markup language (usually TeX). And the writer needs
to know the programming language being used. And the
programmer needs to be skillful enough to write a program
in disconnected fragments that still makes sense and can
be debugged after re-assembly.
Donald Knuth is one person who has all of these skills
and can apply them all at the same time. In contrast,
the average Joe is lucky to have even a few of the
skills, much less being able to apply them all at the
same time. It is rarer still to find teams where all of
the programmers can read and write in a literate style.
As some of the python developers can attest, it takes
a while just to get the LaTeX markup correct.
Even if all of the pieces fall into place, there is still a
sense that it takes a lot of work. So, eventhough there
is a certain pleasure to writing literate code, it is something
you tend to save for that special program and then find that
most tasks are too mundane to warrant using your heavy gun.
Also, I find that the process of writing literately collides with
the Test Driven Development process. I'm sure it's possible
to do both at the same time, they just don't seem to fit together
naturally.
> BTW, I have in mind an integration of documentation+test suite,
> not documentation+program (a la Knuth).
+1
Raymond Hettinger
Michele Simionato
I see all of your points and I fully agree. Actually, I think literate
programming is beatiful if you are writing a book on programming, but it
is an heavy weight for any other purpose ;)
> Also, I find that the process of writing literately collides with
> the Test Driven Development process. I'm sure it's possible
> to do both at the same time, they just don't seem to fit together
> naturally.
>
>
> > BTW, I have in mind an integration of documentation+test suite,
> > not documentation+program (a la Knuth).
>
> +1
>
>
> Raymond Hettinger
I see you are already converted, but for sake of programmers still
dubious on the virtues of rst and similar tools, I will add few sentences.
I don't want to document all of my code, as literally programming would
aspire to, it is too much an effort. My idea is to document only the
user interface, by giving examples of usage automatically tested by
doctest. This integrate the documentation of the public interface (i.e.
the user manual) with its testing. The documentation of the internals
and their testing is a different subject and a much bigger work :-(
For instance, I recently took the habit of writing all or my posts
to c.l.p. in reStructuredText. One advantage is that I have a simple
script based on doctest that tests the code before I post it ;)
a second advantage is that I can cut and paste from my postings and
collect them in larger documents. Then, it is trivial to convert them
in html for web publishing or even in latex for printing purposes.
I am really really happy with rst+doctest ;)
Michele