[Doc-SIG] docutils feedback

[Simon Hefti]

David,

thanks for your comments. For now, I just a few responses:

> You have to realize, this is a volunteer open source project.

No worries. I'm aware of that. You asked for feedback, though ;)

> > - how to mark-up examples ?
> >
> >   .. example:: would be nice
>
> This could be done.  But what are the semantics?  What is the
> behaviour?  (What should the "example" directive *do*?)

In the end, I will want to write rst, generate docbook out of it, and
use whatever xsl is available/used/prescribed to convert if to the
final format.

So, I would like an example markup with the semantics similar to the
docbook example tag:

- callout (much like your ..note)
- plus numbering/referencing
- plus captions (both much like your .. figure)

> > - literal blocks:
> >   This was one of the main reasons for POD

POD is the perl plain old documentation. My use case is to write
technical documentation, say a SQL cheat sheet. So I want show code
and to explain it. Now, to be sure, I want to try out the code which
is show. This is way I need copy/paste: I test in on some shell, copy
it over to the doc (the rst file in that case), perhaps
beautify/comment it, copy it back to the shell for testing and so
forth. This is where the identation is in the way, and here docs would
be handy.

Simon.

------------------------------------------------------------------------
Simon Hefti                                     simon.hefti@netcetera.ch
Netcetera AG, 8040 Zuerich    phone +41 1 247 79 47  fax +41 1 247 70 75