[Doc-SIG] The Use of Roles

[David Priest]

> 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 
class="rolename"> elements, 
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.