Re: [Docutils-develop] DocBook writer in sandbox

[David G. <go...@us...>]

Richard Jones wrote:
> An alternative to the "role" concept, where all text marked up in
> `backquotes` is assigned a particular role, would be to extend the
> parser to handle `index me`i or similar, to make the index tagging
> explicit.

That's what `index me`:i: does (could do).  There's more syntax, but
it's there on purpose, to emphasize the role.  Without any extra
syntax it looks like a typo, and may be too subtle to notice.

The implicit role idea is that in any particular application, there's
going to be one interpreted text role that is used more than any
other.  For that one role, no explicit :role: markup is required, just
the `interpreted text` alone.  A convenience feature, but significant.
 Any other roles used will need explicit markup.

For docstrings in Python source, the implicit role will be "look up
this text as a Python identifier in the current namespace, and
automatically link to the definition of that identifier; the role
itself is determined from context: the type of the identifier."  For
Aahz's book, it might be "mark this text as an index entry".

The syntax for explicit interpreted text roles has yet to be tested in
the real world; it's still just an idea that I'm not dead-set on.  I'm
open to alternatives.  There's no real difference between `this`:role:
and  `this`<role> and `this`{role}; I chose :colons: because they're
also used for field lists, <angle> brackets are too strongly
associated with XML/SGML/HTML tags (and we'll probably see a lot of
documents *featuring* such tags as subject matter), and {braces} are
used in TeX and in ordinary text (especially technical text).  For
details of these and other alternatives considered, see
http://docutils.sf.net/spec/rst/alternatives.html#interpreted-text-roles.

-- 
David Goodger  <go...@us...>  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/