docutils-develop

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

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

Dear Adam,

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").

Please revert.
If the italic rendering is a problem, this can be solved changing the
default role or the styling of "title-reference" for the affected files.

Günter

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

[Adam T. <aat...@ou...>]

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:``).

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.

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?

Thanks,
Adam

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

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

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

Dear Adam, dear Docutils developers,

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

>> the commit r9245 eliminates the deliberate distinction between Python
>> object names [...] and filenames or code examples (marked up as
>> "inline literal").

> 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:``).

How about the following patch?

Günter


>From bd20669aa778e936dcaeebf56c5dae1e3d32c136 Mon Sep 17 00:00:00 2001
From: milde <mi...@us...>
Date: Tue, 29 Nov 2022 13:10:48 +0100
Subject: [PATCH] Mark up object names in HISTORY with a custom default role.

Define "name" role in HISTORY, make it the default role and use it for
package, module, class, function, method, and attribute names.
The default default role ("title-reference") is still available as
":title:`Title of a creative work`".

Define and use a CSS sheet with a rule for the custom role.

Provisional: name and style of the new role may be adapted.
---
 docutils/HISTORY.txt                     |  3 +++
 docutils/docs/docutils-documentation.css | 24 ++++++++++++++++++++++++
 docutils/docutils.conf                   |  5 +++--
 3 files changed, 30 insertions(+), 2 deletions(-)
 create mode 100644 docutils/docs/docutils-documentation.css

diff --git a/docutils/HISTORY.txt b/docutils/HISTORY.txt
index 5bd4b91e2..63f7bc45c 100644
--- a/docutils/HISTORY.txt
+++ b/docutils/HISTORY.txt
@@ -1,4 +1,7 @@
 .. include:: docs/header0.txt
+.. role:: name
+.. default-role:: name
+
 
 ==================
  Docutils History
diff --git a/docutils/docs/docutils-documentation.css b/docutils/docs/docutils-documentation.css
new file mode 100644
index 000000000..6b1ca93e5
--- /dev/null
+++ b/docutils/docs/docutils-documentation.css
@@ -0,0 +1,24 @@
+/* Style sheet for the HTML5 output of Docutils.                           */
+/*                                                                         */
+/* :Author: Günter Milde                                                   */
+/* :Id: $Id$                                                               */
+/* :Copyright: © 2022 Günter Milde.                                        */
+/* :License: Released under the `2-Clause BSD license`_, in short: 	   */
+/*                                                                         */
+/*    Copying and distribution of this file, with or without modification, */
+/*    are permitted in any medium without royalty provided the copyright   */
+/*    notice and this notice are preserved.                                */
+/*                                                                         */
+/*    This file is offered as-is, without any warranty.                    */
+/*                                                                         */
+/* .. _2-Clause BSD license: http://www.spdx.org/licenses/BSD-2-Clause     */
+
+/* This CSS3 stylesheet defines rules for the Docutils documentation pages */
+
+/* Inline markup for names of classes, functions, modules, and packages. */
+span.name {color: maroon;}
+
+/* More contrasting background for literal text */
+.literal-block, .doctest, span.literal {
+    background-color: #e5f3f3;
+}
diff --git a/docutils/docutils.conf b/docutils/docutils.conf
index b03a39dbc..c1d73baac 100644
--- a/docutils/docutils.conf
+++ b/docutils/docutils.conf
@@ -13,12 +13,13 @@ stylesheet-path: docutils/writers/html4css1/html4css1.css
 field-name-limit: 20
 
 [html5 writer]
-stylesheet-dirs: docutils/writers/html5_polyglot/
-stylesheet-path: minimal.css, responsive.css
+stylesheet-dirs: docutils/writers/html5_polyglot, docs
+stylesheet-path: minimal.css, responsive.css, docutils-documentation.css
 section-self-link: yes
 table-style: colwidths-grid
 
 # Prevent tools/buildhtml.py from processing certain text files.
 [buildhtml application]
+writer: html5
 ignore: GPL2.txt:header.txt:header2.txt:cheatsheet.txt
 prune: .svn:.hg:docs/.svn:docutils:test:tools:licenses:build:dist
-- 
2.30.2