[Docutils-users] kbd role

[Alan Isaac]

Might consideration be given to adding a `kbd` standard role?

I realize I can use a custom role. But I am encountering the
need for this so often that I wonder if it other are in the
same situation, so that there might be support among the
developers for including this as a standard role.
(And if not something this specific, perhaps a simple
`span` role to inherit from?)

I realize that the multiplication of standard roles is not
desirable.

Cheers,
Alan Isaac

------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, SlashDot.org! http://sdm.link/slashdot
_______________________________________________
Docutils-users mailing list
Docutils-***@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/docutils-users

Please use "Reply All" to reply to the list.

[David Goodger]

Post by Alan Isaac
Might consideration be given to adding a `kbd` standard role?

What should :kbd:`text` do?

Post by Alan Isaac
I realize I can use a custom role. But I am encountering the
need for this so often that I wonder if it other are in the
same situation, so that there might be support among the
developers for including this as a standard role.
(And if not something this specific, perhaps a simple
`span` role to inherit from?)

What would :span:`text` do?

Simple interpreted text roles are already equivalent to HTML <span>
tags. Why would we add a "span" role?

I'm really just curious here.

Post by Alan Isaac
I realize that the multiplication of standard roles is not
desirable.

True.

You'll need to provide some rationale for development work beyond
simple convenience. Especially when you can just write:

.. role:: kbd

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

------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, SlashDot.org! http://sdm.link/slashdot
_______________________________________________
Docutils-users mailing list
Docutils-***@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/docutils-users

Please use "Reply All" to reply to the list.

[David Goodger]

Post by David Goodger
What would :span:`text` do?

Sorry; coffee wore off while fingers were typing.

Post by David Goodger
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>

------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, SlashDot.org! http://sdm.link/slashdot
_______________________________________________
Docutils-users mailing list
Docutils-***@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/docutils-users

Please use "Reply All" to reply to the list.

[Alan Isaac]

Post by David Goodger
<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?

It is easy to imagine an argument for adding all of these.
It is also easy to imagine an argument for having none of these.
Since no criterion for inclusion has been offered, it is difficult
to choose between these arguments.

My personal reason for inquiring about `kbd` (but not about
`samp` or `var`) is purely frequency of use. I use a `kbd`
role almost as often as a `code` role (and much more often
than `strong`).

I suppose the best general argument turns on the value of a semantic web.
Here the `kbd` tag seems quite valuable in improving webpage accessibility.
But again, I was not motivated by general arguments, but simply
by my personal frequency of use.

Cheers,
Alan

------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, SlashDot.org! http://sdm.link/slashdot
_______________________________________________
Docutils-users mailing list
Docutils-***@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/docutils-users

Please use "Reply All" to reply to the list.

[Guenter Milde]

Post by Alan Isaac

Post by David Goodger
<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?

http://www.html-5.com/tags/index.html#html-phrase-elements lists some more
phrase tags:

<abbr> <cite> <code> <dfn> <em> <figcaption> <kbd> <mark> <q> <s> <samp>
<strong> <sub> <sup> <time> <u> <var>

plus the change tracking tags <ins> and <del>.

The W3C specification
https://www.w3.org/TR/html5/dom.html#phrasing-content lists even more:

3.2.4.1.5 Phrasing content

Phrasing content is the text of the document, as well as elements that
mark up that text at the intra-paragraph level. Runs of phrasing
content form paragraphs.

a abbr area (if it is a descendant of a map element) audio b bdi bdo br
button canvas cite code data datalist del dfn em embed i iframe img
input ins kbd keygen label map mark math meter noscript object output
progress q ruby s samp script select small span strong sub sup svg
template textarea time u var video wbr Text

(see also
https://www.w3.org/TR/html5/text-level-semantics.html#text-level-semantics).


Not all of them need special support on all "Docutils levels":

a) reSt syntax

*em* and **strong** are supported via special syntax as they are widely
used basic text styles.

:sub: and :sup: are standard roles because of wide use.

:code:`code` is supported because we want syntax highlighting

<figcaption> is the first paragraph of a figure directive content.

The other tags have no corresponding standard roles but can be easily
emulated via custom roles.

b) Docutils doctree

There are elements for <emphasis>, <strong>, <subscript>, <superscript>,
and the <figure>'s <caption> sub-element.

"code" is represented as a <literal> element with class "code".

Others can be represented with special class values to a suitable base
element, too.

c) HTML output

A <pre class="code"> Docutils doctree element is converted to <code>
by the HTML writer.

...

Post by Alan Isaac
My personal reason for inquiring about `kbd` (but not about
`samp` or `var`) is purely frequency of use. I use a `kbd`
role almost as often as a `code` role (and much more often
than `strong`).
I suppose the best general argument turns on the value of a semantic web.

We could consider similar handling for other "obvious" classes like kbd,
abbr, cite, dfn, samp, var, del, or ins. Then the HTML writer would produce,
e.g.,

<cite>Elements of style</cite>

instead of

<span class="cite">Elements of style<span>

for the rst input::

.. role:: cite

:cite:`Elements of style`


Günter


------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, SlashDot.org! http://sdm.link/slashdot
_______________________________________________
Docutils-users mailing list
Docutils-***@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/docutils-users

Please use "Reply All" to reply to th