Re: [Docutils-develop] New role idea: definition term

[Guenter M. <mi...@us...>]

Dear Michał,

On 2012-09-03, Michał Górny wrote:
> On Mon, 3 Sep 2012 12:56:00 +0000 (UTC)
> Guenter Milde <mi...@us...> wrote:
>> On 2012-09-01, Michał Górny wrote:

>> > I don't see in the docs_ any role suitable for a 'definition term'.
>> > In simplest words, `the defining instance of the enclosed term`
>> > or the HTML dfn_ element. Would it be feasible to add such a role
>> > in rst?

>> > .. _docs: http://docutils.sourceforge.net/docs/ref/rst/roles.html
>> > .. _dfn: http://www.w3.org/TR/html4/struct/text.html#h-9.2.1

>> The usual way to add support for not-readymade roles is to define a
>> custom role, e.g.::

>>   .. role:: dfn

>> (This would map to <span class=dfn> instead of the <dfn> element in
>> HTML.)

> If I wanted to hack it around, I'd just do that and not e-mail
> the list. I just see a potential improvement which could benefit users.

In contrast to roles based on "raw", `custom interpreted text roles`__
are not considered a hack but the canonical way to adapt reStructuredText
to special needs.

__ http://docutils.sourceforge.net/docs/ref/rst/directives.html#role

>> Unless there is a strong indication of real benefits in real use
>> cases, it is unlikely to become a pre-defined role.

> Like scientific papers, articles, tutorials and so on?

I understand that there are cases where semantic markup with a
:definition:`something` role makes sense. 

However:

What is the benefit of a pre-defined role over a custom one?
Does it outwight the added complexity?

How would this translate to other output formats (LaTeX, manpage, ODF, ...)?

IMV, there are more important weaknesses regarding scientific papers
(citation handling, formal tables and images (with numbering and
auto-generated listing of all tables/images), better footnote handling,
...).


Adding a new node class to the DTD_ would require a change to all (also
user-contributed) writers and possibly break applications like Sphinx. (A
backwards compatible way would be to pre-define a "definition" role that
maps to an "inline" element with class="definition" in the document-tree
and to add a special case in the HTML writer's visit_inline() function to
map <inline class="definition"> to <dfn>.)

BTW, I see that ``docutils/parsers/rst/roles.py`` defines the standard
roles "abbreviation" and "acronym" even though these are not documented.

.. _DTD: http://docutils.sourceforge.net/docs/ref/doctree.html


Günter