Re: [Docutils-users] kbd role

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

On 2017-02-16, Alan Isaac wrote:
> On 2/16/2017 3:05 PM, David Goodger wrote:
>> 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?

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.

...

> 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