[Doc-SIG] The Use of Roles
priest at sfu.ca
Tue Jun 10 09:07:46 EDT 2003
> The interpreted-text role-handling mechanism could be ripped out of
> the parser proper and made into a subpackage similar to directives.
> Honestly, I hadn't thought of it, probably because nobody had
> suggested it, and personally I have no problem hacking the Docutils
> source. ;-)
I'd have no problem hacking the
source, except that it makes it
difficult to update when you release
the next version...
> The issue I have is, should these roles generate unique new elements
> in the Docutils doctree, or should they generate <inline
> class="something"> elements? (The <inline> element didn't exist in
> March, so there has been some progress!) If the latter, the ideas in
> the to-do list may cover it (see link below). If the former, I try to
> be cautious before adding new elements to the doctree. We need to
> spec out these roles and their semantics fully.
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.
In which case, it seems to me to be
appropriate to generate <inline
which in DocBook would be output
as proper tags (<guilabel>, etc); in
HTML would be output as <span
class="rolename"> (assuming CSS
styling; output as <B> if not using
CSS); in TeX would be output as
whatever TeX uses.
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? I can see
arguments either way.
More information about the Doc-SIG