[Doc-SIG] The Use of Roles

David Priest priest at sfu.ca
Mon Jun 9 21:15:12 EDT 2003

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 

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.  I do see a fair bit of 
discussion about what roles to implement &c.

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.

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.

Have I overlooked an easy add-on capability?  Is there any moral, logical, 
or political reason for allowing user directives but not user roles?  Or is 
there some amount of planning to do this eventually?

Curious, et al.
  (another) david

More information about the Doc-SIG mailing list