[Doc-SIG] The Use of Roles

[Beni Cherniavsky]

David Priest wrote on 2003-06-10:

> > 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.
>
I think the criterion should be ignorability.  If you strip all
`class` attributes, you should still get acceptable results.  E.g. I
think that a `kbd` role should become a `literal` element with ``kbd``
style.  Ask yourself what's the closest approximations to each
proposed role.  It might be unmarked plain text - then `inline` fits.
It might have no acceptable approximation - then a new element might
be in order.

-- 
Beni Cherniavsky <cben at users.sf.net>