[Doc-SIG] docutils feedback

[David Goodger]

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