[Doc-SIG] docutils feedback

[David Goodger]

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...

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.

> Main point
> ----------
> ...it's then not hard to envisage a directive that goes something
  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/