Re: [Docutils-develop] commit r9245 Use literal syntax in HISTORY

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

On 2022-11-16, Adam Turner wrote:
> Dear Günter,

>> the commit r9245 eliminates the deliberate distinction between Python
>> object names (up to r9244 marked up with the default "title-reference"
>> role, not *emphasis*!) and filenames or code examples (marked up as
>> "inline literal").

> Thank you for the clarification.

> I suggest documenting this in a comment at the start of the HISTORY
> file, as the distinction was entirely lost on me. We might also
> consider using explicit markup for clarity (either ``:title:``, or a
> custom code role ``:py:``).

My main intention is to keep it simple and keep it readable in source
format. 

The `default role`__ should be used for the most common inline text role,
IMV this is `title`__ (alias "title-reference" alias "t").

The "title" role creates a `title_reference`__ element which is written
in HTML as <cite>.
The `MDN documentation`__ says "The <cite> HTML element is used to
describe a reference to a cited creative work, and must include the title
of that work."
Under that assumption that "title" and "name" are synonyms and Python
objects (classes, functions, ...) are a "creative work", using the
default default-role is justifiable.

__ https://docutils.sourceforge.io/docs/ref/rst/directives.html#setting-the-default-interpreted-text-role
__ https://docutils.sourceforge.io/docs/ref/rst/roles.html#title-reference
__ https://docutils.sourceforge.io/docs/ref/doctree.html#title-reference
__ https://developer.mozilla.org/en-US/docs/Web/HTML/Element/cite


> For programme names, such as "pandoc", "flake8", and "2to3", what
> syntax would we use? Following the rule outlined in your note, these
> would use literal syntax, I believe, though I would like to check
> before reverting a reversion.

Computer programs are listed as examples for a "creative work" in the
HTML standard
https://html.spec.whatwg.org/multipage/text-level-semantics.html#the-cite-element
Whether they should use the default "title" or the "literal" role
depends on the context: If referencing the program by its name,
use the "title" role, e.g., "we use `flake8` to check coding style". 

As part of an CLI call (code or kbd), use "literal" (as this is
simpler as "code"), e.g., "check styling with ``flake8 myfile.py``.
(I often used single backticks here as well)

> There are some Python names that were previously using literal syntax
> that should likely be modified, e.g. "HTMLTranslator.topic_classes",
> "use_latex_toc", "split_escaped_whitespace", etc.

> Finally, for expressions in the HISTORY file (e.g. "parts['title']",
> "footnote_backlinks==False", etc), what syntax should we use?

These are rather code snippets than names of creative work, so
`literal`__ is fine (and simpler as ":code:`parts['title']`").

__ https://docutils.sourceforge.io/docs/ref/rst/roles.html#literal


Günter