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/
David Goodger wrote:
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.
Drat - I *do* try to read the headers before hitting "send", but all too often I forget.
(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...
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.
Hmm. I'd be against this, partly because it's multiplying entities ("now, is *this* particular format supported or not..."), partly because (for instance) my prompts don't look anything like the examples given (and your examples are very Unix-operating-system-centric), partly because that "(and unambiguous)" makes me uncomfortable, but mainly because this screams to me of a general solution presenting itself as specific instances, and thus the correct thing to do is to handle the general case. (common prompts I work with: * Unix: "lslsuj:tony > " * NT: "D:\LaserScan\java> " * our GIS product: "LULL> " so obviously, a block beginning with text containing a ">" should be special...) My gut feeling is that the sort of "example" directive I was discussing is probably the way to go for thinking about this sort of thing - and if it's a directive, we can leave it for later discussion as more experience is obtained. Of course, that leaves the ">>>" syntax for Python code as a special instance that could be argued as being out-of-place. Doesn't mean I want it to go away, though (and there is a patchwork-quilter's tradition, originating with the Amish, I believe, that no quilt should be perfect, because only God can make a perfect thing. So this can be our incorrect patch.). After all, it *is* a Python originated product, so some special support for Python might be expected. Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.co.uk/ "How fleeting are all human passions compared with the massive continuity of ducks." - Dorothy L. Sayers, "Gaudy Night" My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)
On Fri, 14 Jun 2002, Tony J Ibbs (Tibs) wrote:
Of course, that leaves the ">>>" syntax for Python code as a special instance that could be argued as being out-of-place. Doesn't mean I want it to go away, though (and there is a patchwork-quilter's tradition, originating with the Amish, I believe, that no quilt should be perfect, because only God can make a perfect thing. So this can be our incorrect patch.). After all, it *is* a Python originated product, so some special support for Python might be expected.
I think this is a myth in regards to Amish patchwork quilting. However, it is true of Persian rugs--they're always made with slight and minor irregularities due to the belief that God is the only ultimate perfect being and we shouldn't be attempting something perfect because that would be like claiming the position of the almighty. That would be bad. I think if we have the choice, I'd rather we didn't explicitly put flaws in the reST syntax for the sole purpose of not insulting the almighty. Course, it's not like creating a readable ascii formatting syntax is as easy as making apple pie. So I don't really think we're in danger of that sort of thing. :) /will
David Goodger wrote:
This gives me an idea. Perhaps we could generalize the "doctest block" construct (which is overly Python-centric) to other interactive sessions.
Tony J Ibbs (Tibs) wrote:
Hmm. I'd be against this,
Tony, ever the voice of restraint ;->. A useful role, actually. Taking your points out of order:
partly because (for instance) my prompts don't look anything like the examples given (and your examples are very Unix-operating-system-centric), ... (common prompts I work with:
* Unix: "lslsuj:tony > " * NT: "D:\LaserScan\java> " * our GIS product: "LULL> "
so obviously, a block beginning with text containing a ">" should be special...)
A "> " WinDOS prompt would be feasible. Your Unix prompt is *decidedly* non-standard though.
partly because that "(and unambiguous)" makes me uncomfortable,
Why?
partly because it's multiplying entities ("now, is *this* particular format supported or not..."), ... but mainly because this screams to me of a general solution presenting itself as specific instances, and thus the correct thing to do is to handle the general case.
I thought it *was* addressing the general case, admittedly with a limited set of examples. The real world is a varied place, and many solutions have to be piecemeal by necessity.
My gut feeling is that the sort of "example" directive I was discussing is probably the way to go for thinking about this sort of thing - and if it's a directive, we can leave it for later discussion as more experience is obtained.
The "interactive block" I proposed wasn't addressing the "example" directive, rather Simon Hefti's objection to indented literal blocks. But I agree that the solution (or even the *need* for a solution) isn't clear. I don't really see the need myself. For now, I've added the "interactive block" idea to the to-do list (with a "?"). It will languish there until a champion claims it. -- 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/
subject should say : code innclusion anyone ever thought about support for literate programming. e.g. -------- to start up the program enter <<sample.script>>= bash @ and then type <<sample.script>>= exit @ to leave. ------ indentation does not mind as one should extract/tangle the code and could cut an paste from the file sample.script (i think it is a no web feature, that top chunks that contain no blanks are written to files). -- engelbert gruber email: engelbert.gruber@ssg.co.at
anyone ever thought about support for literate programming.
For literate programming support, see Leo: http://sourceforge.net/projects/leo/ --Guido van Rossum (home page: http://www.python.org/~guido/)
participants (5)
-
David Goodger -
engelbert gruber -
Guido van Rossum -
Tony J Ibbs (Tibs) -
will