[Doc-SIG] The Use of Roles
David Goodger
goodger at python.org
Wed Jun 11 12:59:40 EDT 2003
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
More information about the Doc-SIG
mailing list