[Doc-SIG] The Use of Roles

[David Goodger]

David Priest wrote:
 > Directives seem to me to address only the mark-up of block text.
 > There's a decent document describing how to implement one's own
 > directives in Docutils.

The spec/howto/rst-directives.txt doc was started by Dethe Elza, who
also pushed for an easier API for directives.

 > Roles seem to me to address the mark-up of inline text.  I can find
 > nothing in the documentation nor the (recent, ie. 2003) archives
 > regarding the implementation of one's own roles in Docutils.

Hasn't been written yet.  You'll have to refer to the code, and ask
questions.  A howto for writing role handlers would be welcome.

 > Why not allow users to add Roles in much the same manner that
 > Directives can be added?  I'd much rather hack an __init__ file and
 > add a .py role- handler, than hack the Docutils source itself.

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. ;-)

 > What I'm looking to do is add :gui:, :key:, and :dic: roles that
 > create <guilabel>, <keycap>, and <glossterm> docbook markup.  At
 > some point I'd probably also like to add :idx: for indexing support.

I remember you suggesting these back in March.  Gotta be a squeaky
wheel to get the grease!  Helps if you supply your own grease too ;-).

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.

 > Have I overlooked an easy add-on capability?

No.  It doesn't exist yet.  Patches welcome!

 > Is there any moral, logical, or political reason for allowing user
 > directives but not user roles?

The functionality just hasn't been implemented yet.

 > Or is there some amount of planning to do this eventually?

There's <http://docutils.sf.net/spec/notes.html#role-bindings> and
other ideas around there.  We're still exploring the conceptual space
around interpreted text.

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

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