Re: [Docutils-users] kbd role

[David G. <go...@py...>]

On Wed, Feb 15, 2017 at 9:45 PM, Alan Isaac <ala...@gm...> wrote:
> On 2/15/2017 7:51 PM, David Goodger wrote:
>> What would :span:`text` do?
>
> Sorry; coffee wore off while fingers were typing.
>
>
>> What should :kbd:`text` do?
>
>
> For the HTML5 writer, it would add a `kbd` element,
> just like the `code` role produces a `code` element.

https://www.w3schools.com/tags/tag_kbd.asp lists the following "phrase tags":

<em> Renders as emphasized text
<strong> Defines important text
<code> Defines a piece of computer code
<samp> Defines sample output from a computer program
<kbd> Defines keyboard input
<var> Defines a variable

Currently Docutils outputs <em>, <strong>, and <code>, but not the
other three. If we add <kbd>, must we add the last two? If not, why
not?

I note that HTML doesn't have a generic "literal" tag, but up to 4
variations instead.

> The reasons for preferring this output to a `span` element
> with a `kbd` class is the same set of reasons that have
> led the `kbd` element not to be deprecated in HTML5.

Please provide a summary or a link, because I don't know what these
reasons are/were.

> But  I clearly do not understand the policy for roles.
> What motivated the current set of roles?

It's what made sense to me at the time, along with input from the
community over the years.

> Have the
> criteria for being a standard role been articulated?

No, except for what has been discussed and what is now being discussed
on these mailing lists.

> Is it something other than "convenience" for authors?

There's also the cost of implementation (parser, all writers, tests,
documentation), and the added cost of complexity for users (new roles
make reST bigger). That's balanced against the utility to
users/authors. If that utility is just "I don't want to write a
one-liner, .. role:: kbd, and a style", that's not enough (to me) to
counter the costs.

> Although I used the `code` role for comparison, I can see that
> it will often be subclassed while that would be less common
> with `kbd` role.  For that reason, I see that the the case
> is much weaker for a `kbd` standard role.
>
> I won't say anything more about this.  I just wanted to
> know if there might be developer interest.

Not from me, but maybe from others.

David Goodger
<http://python.net/~goodger>