[Doc-SIG] docutils feedback

Tony J Ibbs (Tibs) tony@lsl.co.uk
Fri, 14 Jun 2002 12:19:25 +0100


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