Re: commit r9245 Use literal syntax in HISTORY

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 <[email protected]>
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




_______________________________________________
Docutils-develop mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/docutils-develop

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