[Doc-SIG] verse construct (was Re: [Docutils-develop] Parsing
Thu, 09 May 2002 00:07:30 -0400
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
> 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
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 <email@example.com> 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/