From 196558e9b8866cbe60344298de4ca9a8e7091c1a Mon Sep 17 00:00:00 2001
From: Greg Lueck <gregory.m.lueck@intel.com>
Date: Sat, 27 Jul 2024 14:36:52 -0400
Subject: [PATCH] Generalize synopsis role

Allow "[role=synopsis]" to be used with paragraphs in addition to
"[source]" blocks.  Paragraphs with this role are styled with a
clickable "#" that links to the paragraph, similar to the styling for
"[source]" blocks with this role.

This lays the groundwork for some future reformatting and does not
change any formatting in the current render of the specification.
---
 adoc/config/khronos.css           | 12 ++++++------
 adoc/config/synopsis/extension.rb | 21 ++++++---------------
 2 files changed, 12 insertions(+), 21 deletions(-)

diff --git a/adoc/config/khronos.css b/adoc/config/khronos.css
index 61481f5d..e6635807 100644
--- a/adoc/config/khronos.css
+++ b/adoc/config/khronos.css
@@ -483,20 +483,20 @@ pre.nowrap,pre.nowrap pre{white-space:pre;word-wrap:normal}
 .listingblock.terminal pre .command:not([data-prompt]):before { content: "$"; }
 
 /* Format "[source,role=synopsis]" blocks.  This format overrides "listingblock" above. */
-.synopsis > .content {
+.listingblock.synopsis > .content {
   position: relative;
   display: inline-block;
   border: 1px solid #ddd;
 }
-.synopsis pre, .synopsis pre[class] {
+.listingblock.synopsis pre, .listingblock.synopsis pre[class] {
   padding: 7px 7px 7px 7px;
 }
 
-/* Any "[source,role=synopsis]" blocks with an "id" have an anchor tag inside the
+/* Any "[role=synopsis]" blocks with an "id" have an anchor tag inside the
    block's <div>.  (See the "synopsis" Ruby extension script.)  Style this as a
-   pound sign in the left column that is visible when hovering over the listing
-   block.  This is similar to the way section headers are styled, but with a
-   pound sign instead of a section sign.
+   pound sign in the left column that is visible when hovering over the block.
+   This is similar to the way section headers are styled, but with a pound sign
+   instead of a section sign.
 */
 .synopsis > a {
   position: absolute;
diff --git a/adoc/config/synopsis/extension.rb b/adoc/config/synopsis/extension.rb
index c95b694f..f4648057 100644
--- a/adoc/config/synopsis/extension.rb
+++ b/adoc/config/synopsis/extension.rb
@@ -5,30 +5,21 @@
 
 include ::Asciidoctor
 
-# Add HTML anchors for "[source,role=synopsis,id=X]" blocks, changing the HTML
-# from this:
+# Add HTML anchors for "[role=synopsis,id=X]" blocks, changing the HTML from
+# this:
 #
-# <div id="X" class="listingblock synopsis">
+# <div id="X" class="XX synopsis">
 #
 # to this:
 #
-# <div id="X" class="listingblock synopsis">
+# <div id="X" class="XX synopsis">
 # <a href="#X"></a>
 #
 # Note that this happens only if the block has an "id" attribute.
 #
 # This extension also relies on some custom CSS styling to turn the anchor into
-# into a section marker that you can click on to get the URL of the synopsis
-# block.  See the CSS entries for the class name "synopsis".
-#
-# TODO: It would be nice to create a custom Asciidoc block instead of using the
-# "role=" syntax.  This would allow the Asciidoc source to look like:
-#
-# [synopsis,id=X]
-#
-# However, doing this disables the source code highlighting feature.  I think
-# this is because the rouge highlighter looks only at [source] blocks, and I
-# cannot find a way to tell it to look at a custom block named [synopsis].
+# into a marker that you can click on to get the URL of the synopsis block.  See
+# the CSS entries for the class name "synopsis".
 
 class AddSynopsisAnchors < Extensions::Postprocessor