[Doc-SIG] docutils feedback

[David Goodger]

On Thu, Jun 13, 2002, Simon Hefti wrote:
> 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.

Aahz wrote:
> My solution to this problem has been to use an include directive --
> no cut'n'paste required.  I don't know how that will work in the
> reST world, though.

It's on the to-do list, but hasn't been implemented yet:
http://docutils.sf.net/spec/notes#misc-include.  I'm not sure what
semantics/behavior to apply though.  Your solution seems to imply a
context to the "include", such as "include a file, and interpret it as
a literal block", but I'm not sure how best to specify the context.

Worthy ideas; they require thought & discussion.  Comments anyone?

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