[1/3] doc: introduce a synopsis custom paragraph attribute

Commit Message

Jean-Noël Avila July 23, 2024, 10:44 p.m. UTC

From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <[e-mail]>

In order to follow the common manpage usage, the synopsis of the
commands needs to be heavily typeset. A first try was performed with
using native markup, but it turned out to make the document source
almost unreadable, difficult to write and prone to mistakes with
unwanted Asciidoc's role attributes.

In order to both simplify the writer's task and obtain a consistant
typesetting in the synopsis, a custom 'synopsis' paragraph type is
created and the backends of asciidoc and asciidoctor take in charge to
correctly add the required typesetting.

Signed-off-by: Jean-Noël Avila <[e-mail]>
---
 Documentation/asciidoc.conf             | 14 ++++++++++++++
 Documentation/asciidoctor-extensions.rb | 17 +++++++++++++++++
 Documentation/git-clone.txt             |  2 +-
 Documentation/git-init.txt              |  2 +-
 t/t0450-txt-doc-vs-help.sh              |  7 ++-----
 5 files changed, 35 insertions(+), 7 deletions(-)

Comments

Junio C Hamano July 23, 2024, 11:36 p.m. UTC | #1

"Jean-Noël Avila via GitGitGadget" <[e-mail]> writes:

> +ifdef::backend-docbook[]
> +ifdef::doctype-manpage[]
> +[paradef-default]
> +#synopsis-style=template="verseparagraph",filter="sed -E 's!&lt;[a-z-]+&gt;!<emphasis>\\0</emphasis>!g' -E 's!([a-z-]+)!<literal>\\1</literal>!g'"
> +synopsis-style=template="verseparagraph",filter="perl -pe 's!([\[\] |()>]|^)([=+a-zA-Z0-9-:+=]+)!\\1<literal>\\2</literal>!g;s!(&lt\\;[a-zA-Z0-9-.]+&gt\\;)!<emphasis>\\1</emphasis>!g'"
> +#synopsis-style=template="verseparagraph"

This has three candidate definitions, but two are commented out?

> +endif::doctype-manpage[]
> +endif::backend-docbook[]
> +
> +ifdef::backend-xhtml11[]
> +[paradef-default]
> +synopsis-style=template="verseparagraph",filter="perl -pe 's!([\[\] |()>]|^)([+a-zA-Z0-9-:+=]+)!\\1<code>\\2</code>!g;s!(&lt\\;[a-zA-z0-9-.]+&gt\\;)!<em>\\1</em>!g'"
> +endif::backend-xhtml11[]

With this update, do we now assume that anybody who want to format
the documentation from source must have a minimally working Perl on
their $PATH?  It probably is an OK requirement to have.

Patch

diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf
index 60f76f43edab..cb2a9ca59c65 100644
--- a/Documentation/asciidoc.conf
+++ b/Documentation/asciidoc.conf
@@ -57,3 +57,17 @@  git-relative-html-prefix=
 [linkgit-inlinemacro]
 <a href="{git-relative-html-prefix}{target}.html">{target}{0?({0})}</a>
 endif::backend-xhtml11[]
+
+ifdef::backend-docbook[]
+ifdef::doctype-manpage[]
+[paradef-default]
+#synopsis-style=template="verseparagraph",filter="sed -E 's!&lt;[a-z-]+&gt;!<emphasis>\\0</emphasis>!g' -E 's!([a-z-]+)!<literal>\\1</literal>!g'"
+synopsis-style=template="verseparagraph",filter="perl -pe 's!([\[\] |()>]|^)([=+a-zA-Z0-9-:+=]+)!\\1<literal>\\2</literal>!g;s!(&lt\\;[a-zA-Z0-9-.]+&gt\\;)!<emphasis>\\1</emphasis>!g'"
+#synopsis-style=template="verseparagraph"
+endif::doctype-manpage[]
+endif::backend-docbook[]
+
+ifdef::backend-xhtml11[]
+[paradef-default]
+synopsis-style=template="verseparagraph",filter="perl -pe 's!([\[\] |()>]|^)([+a-zA-Z0-9-:+=]+)!\\1<code>\\2</code>!g;s!(&lt\\;[a-zA-z0-9-.]+&gt\\;)!<em>\\1</em>!g'"
+endif::backend-xhtml11[]
diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb
index d906a008039c..d1568f654627 100644
--- a/Documentation/asciidoctor-extensions.rb
+++ b/Documentation/asciidoctor-extensions.rb
@@ -39,10 +39,27 @@  module Git
         output
       end
     end
+
+    class SynopsisBlock < Asciidoctor::Extensions::BlockProcessor
+
+      use_dsl
+      named :synopsis
+      parse_content_as :simple
+
+      def process parent, reader, attrs
+        outlines = reader.lines.map do |l|
+          l.gsub(/([\[\] |()>]|^)([a-zA-Z0-9\-:+=]+)/, '\\1{empty}`\\2`{empty}')
+           .gsub(/(<[a-zA-Z0-9\-.]+>)/, '__\\1__')
+           .gsub(']', ']{empty}')
+        end
+        create_block parent, :verse, outlines, attrs
+      end
+    end
   end
 end
 
 Asciidoctor::Extensions.register do
   inline_macro Git::Documentation::LinkGitProcessor, :linkgit
+  block Git::Documentation::SynopsisBlock
   postprocessor Git::Documentation::DocumentPostProcessor
 end
diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
index 5de18de2ab83..70a3f0331f83 100644
--- a/Documentation/git-clone.txt
+++ b/Documentation/git-clone.txt
@@ -17,7 +17,7 @@  SYNOPSIS
 	  [++--recurse-submodules++[++=++__<pathspec>__]] [`--`[`no-`]`shallow-submodules`]
 	  [`--`[`no-`]`remote-submodules`] [`--jobs` _<n>_] [`--sparse`] [`--`[`no-`]`reject-shallow`]
 	  [++--filter=++__<filter-spec>__] [`--also-filter-submodules`]] [`--`] _<repository>_
-	  [_<directory>_]
+	  [__<directory>__]
 
 DESCRIPTION
 -----------
diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt
index daff93bd164b..7cdc693e1c68 100644
--- a/Documentation/git-init.txt
+++ b/Documentation/git-init.txt
@@ -13,7 +13,7 @@  SYNOPSIS
 	  [`--separate-git-dir` _<git-dir>_] [++--object-format=++__<format>__]
 	  [++--ref-format=++__<format>__]
 	  [`-b` _<branch-name>_ | ++--initial-branch=++__<branch-name>__]
-	  [++--shared++[++=++__<permissions>__]] [_<directory>_]
+	  [`--shared`[++=++__<permissions>__]] [__<directory>__]
 
 
 DESCRIPTION
diff --git a/t/t0450-txt-doc-vs-help.sh b/t/t0450-txt-doc-vs-help.sh
index 69917d7b8459..f9d89949ece3 100755
--- a/t/t0450-txt-doc-vs-help.sh
+++ b/t/t0450-txt-doc-vs-help.sh
@@ -56,12 +56,9 @@  txt_to_synopsis () {
 	fi &&
 	b2t="$(builtin_to_txt "$builtin")" &&
 	sed -n \
-		-e '/^\[verse\]$/,/^$/ {
+		-e '/^\[\(verse\|synopsis\)\]$/,/^$/ {
 			/^$/d;
-			/^\[verse\]$/d;
-			s/_//g;
-			s/++//g;
-			s/`//g;
+			/^\[\(verse\|synopsis\)\]$/d;
 			s/{litdd}/--/g;
 			s/'\''\(git[ a-z-]*\)'\''/\1/g;