Simon, could you list Doc-SIG explicitly in the To: or Cc: field of your messages please? Tony's reply to your message didn't make it to the Doc-SIG, probably because he assumed that replying *to* a message which arrived *from* a mailing list would make it *back* to the mailing list. It should, but it didn't because of the non-standard headers in your message. I've quoted Tony's entire reply below for the benefit of the rest of Doc-SIG. [David]

...

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

[Simon]

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

Sure, and it's appreciated. The tone of your message was just a bit... demanding, that's all. I'll add your explanation of an "example" directive to the `to-do list`__. __ http://docutils.sf.net/spec/notes.html#body-example [Simon, re literal blocks and why he doesn't want them indented]

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.

So your motivation is convenience. You want to avoid having to indent the interactive sessions you copy and paste into the docs in order to avoid having to unindent when you re-copy and paste the edited code for test purposes. Does that sum it up? I'm not going to change the syntax for literal blocks; indentation does a fine job IMO. Removing indentation as the delimiter would require block-end delimiters (there is already a block-start delimiter: "::"), which I am loathe to do. A directive like the "here-literal" example I showed seems like the best you'll get (although it's not very good!). But read on; perhaps the idea below will work for your SQL examples? [Tony's reply]

Hmm. There have been previous ideas on how to do this sort of thing.

I think that "indented literal blocks" and "examples" are separate issues. In an "example", you'll still need syntax for the code or interactive session, to distinguish it from the explanatory text.

Minor digression ---------------- First off, we already have a "special case" for Python examples - the support provided for blocks of Python code - for instance::

The following is targeted at doctest:

>>> a = 1 >>> a 1

and can thus be used to test code...

The point being, this syntax does *not* require indentation. The leading ">>> " prompt is sufficient to recognize the construct, and a blank line terminates the block.

(pysource, for instance, has a --doctest switch which allows it to read a text file in and just pass it to doctest - intended for use in writing some sorts of documentation/test script). Obviously this special case is there for incestuous reasons - which is why this is a minor digression. But...

Main point ---------- ...it's then not hard to envisage a directive that goes something

This gives me an idea. Perhaps we could generalize the "doctest block" construct (which is overly Python-centric) to other interactive sessions. "Doctest block" could be renamed to "I/O block" or "interactive block", and each of these could also be recognized as such by the parser: - Shell sessions:: $ cat example1.txt A block beginning with a "$ " prompt is interpreted as a shell session interactive block. As with Doctest blocks, the interactive block ends with the first blank line, and wouldn't have to be indented. - Root shell sessions:: # cat example2.txt A block beginning with a "# " prompt is interpreted as a root shell session (the user is or has to be logged in as root) interactive block. Again, the block ends with a blank line. Other standard (and unambiguous) interactive session prompts could easily be added. like::

.. sqlcheat:: explanation: This is *not* real SQL! sql: FOR fred IN tables DO something;

(apologies for what is doubtless poor directive layout design - David is better at this sort of thing than I) which might:

a. write out the explanation neatly b. write out the SQL code neatly c. *run* the SQL code and present the result

(something similar was discussed at one point as a possible way of allowing the reST quick reference to be written in reST - at the moment it's hand-written in HTML).

This approach has the major advantage of saving you all of that manual cut-and-paste. It also means that if at some stage you want to expand the examples to contrast what two different SQL implementations do with the SQL code, you don't need to change the text by much - just alter the explanation occasionally to reflect that two sets of output are being produced. Instead, it's the directive code that gets changed.

So the advantage is that the running of the test code (embedded in the docs) is automated. All that's needed now is a clear set of requirements, a good design, and running code. ;-) -- David Goodger <goodger@users.sourceforge.net> Open-source projects: - Python Docutils: http://docutils.sourceforge.net/ (includes reStructuredText: http://docutils.sf.net/rst.html) - The Go Tools Project: http://gotools.sourceforge.net/