[Doc-SIG] verse construct (was Re: [Docutils-develop] Parsing oddness)

[David Goodger]

Moore, Paul wrote:
> Frankly, this seems like overkill to me. I can see what you're
> getting at - there's a gap in the logical model, between completely
> literal blocks, and completely interpreted text - but I don't think
> the gap needs to be filled.

Perhaps you'd feel differently if you needed to use it?

> How often is this construct likely to be used? In what contexts?

Richard Jones wanted a snailmail address in a document.  That's a
significant use case.  I have yet to quote verse in a document (except
to illustrate this construct), but I can see it happening.  Thinking
of every time I've had to use a line break in Word, or <br> in HTML, I
believe the construct has merit.

> If you really, really, feel the need to put it in, make it a
> directive. Don't invent new syntax for it.

I agree.  Syntax can be added later if called for.

> And maybe even just make it a sample directive, not enshrined in the
> spec, but available as an example of how the directive
> infrastructure can be extended.

I think that, similarly to modules in Python's library, directives
that are "standard" will be used, but directives that need to be
separately installed won't.  I'd like to build a rich variety of
standard directives, and document them all in "reStructuredText
Directives":

    http://docutils.sf.net/spec/rst/directives.html

> How does a document which relies on a particular directive, state
> that fact? Just by using it?

Yes.  There's currently no mechanism to explicitly declare required
directives.  Directives are located in the
docutils/parsers/rst/directives directory; there are two lookup tables
linking localized directive name (currently just English) -> canonical
directive name -> (module, function) names.  As long as a directive is
registered properly and located in the right place, the parser will
find it.

If an unknown directive is used in a document, an error is reported.

> we don't want to have to start documents with blurb like::
> 
>     .. using:: image, quote, my-special-directive

No, we probably don't.  (*I* certainly don't!)  Thus the need for a
standard place to put directive 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/