reStructured Text - suitable for non-documentation?

[Michele Simionato]

"Raymond Hettinger" <vze4rx4y at verizon.net> wrote in message news:<PbeDa.34724$ca5.29977 at nwrdny02.gnilink.net>...
> "Michele Simionato" <mis6 at 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.
>

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