[Doc-SIG] The Use of Roles

[David Goodger]

David Priest wrote:
 > I'd have no problem hacking the source, except that it makes it
 > difficult to update when you release the next version...

So send in a patch!  If it's generally useful, we'll polish it
together and it will become part of the next version.

 > If IIRC, the Docutils doctree is a separate idea from the actual
 > Docbook output; ie. it's the responsibility of the output writer to
 > convert doctree to tagging.

Yes, but the Docutils doctree has to make sense.  It has to be
internally consistent and useful for all Writers.

Beni's description is on target.  The decision on how to represent
each proposed role is separate, case-by-case.

 > Should the reader have some idea of what's a valid role, or should
 > it just toss anything it doesn't know about into the class name and
 > let the writers deal with it?

The *Parser* must know *all* valid roles in advance.  Interpreted text
is a parser construct.  Interpreted text roles address a limitation of
the reStructuredText markup.  The writer doesn't know anything about
interpreted text itself.  From the spec:

     Only pre-determined roles are recognized; unknown roles will
     generate errors.  A core set of standard roles is implemented in
     the reference parser; see `reStructuredText Interpreted Text
     Roles`_ for individual descriptions.  In addition, applications
     may support specialized roles.

     -- http://docutils.sf.net/spec/rst/reStructuredText.html
        #interpreted-text

.. _reStructuredText Interpreted Text Roles:
    http://docutils.sf.net/spec/rst/interpreted.html

-- 
David Goodger    http://starship.python.net/~goodger

Programmer/sysadmin for hire: http://starship.python.net/~goodger/cv