[Doc-SIG] The Use of Roles
goodger at python.org
Tue Jun 10 02:20:05 EDT 2003
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
> 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
More information about the Doc-SIG