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