[PATCH v2 0/3] doc: introducing synopsis para

Following several issues with the way the formatting of synopsis is done in the manpages that were recently reworked, this patch series introduces the processing of a new custom paragraph attribute 'synopsis'.

This extension is added to asciidoc and asciidoctor and lets write the synopsis of the commands without any typeset. The git-init and git-clone manpages are converted to this new system.

Changes since V1:

 * switch to sed for asciidoc filter and refine the regex for support under
   macOS

Jean-Noël Avila (3):
  doc: introduce a synopsis custom paragraph attribute
  doc: update the guidelines to reflect the current formatting rules
  doc: apply synopsis simplification on git-clone and git-init

 Documentation/CodingGuidelines          | 34 ++++++++++++++-----------
 Documentation/asciidoc.conf             | 12 +++++++++
 Documentation/asciidoctor-extensions.rb | 17 +++++++++++++
 Documentation/git-clone.txt             | 20 +++++++--------
 Documentation/git-init.txt              | 12 ++++-----
 t/t0450-txt-doc-vs-help.sh              | 11 +++-----
 6 files changed, 68 insertions(+), 38 deletions(-)

base-commit: ad57f148c6b5f8735b62238dda8f571c582e0e54
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1766%2Fjnavila%2Fdoc_synopsis_para-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1766/jnavila/doc_synopsis_para-v2
Pull-Request: https://github.com/gitgitgadget/git/pull/1766

Range-diff vs v1:

 1:  704f0333ef1 ! 1:  aba144f4ff3 doc: introduce a synopsis custom paragraph attribute
     @@ Documentation/asciidoc.conf: git-relative-html-prefix=
      +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"
     ++synopsis-style=template="verseparagraph",filter="sed -E 's!([\[ |()>]|^|\])([-=a-zA-Z0-9:+.]+)!\\1<literal>\\2</literal>!g;s!&lt;[-a-zA-Z0-9.]+&gt;!<emphasis>\\0</emphasis>!g'"
      +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'"
     ++synopsis-style=template="verseparagraph",filter="sed -E 's!([\[ |()>]|^|\])([-=a-zA-Z0-9:+.]+)!\\1<code>\\2</code>!g;s!&lt;[-a-zA-Z0-9.]+&gt;!<em>\\0</em>!g'"
      +endif::backend-xhtml11[]
      
       ## Documentation/asciidoctor-extensions.rb ##
     @@ Documentation/asciidoctor-extensions.rb: module Git
      +
      +      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__')
     ++          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
     @@ Documentation/asciidoctor-extensions.rb: module Git
         postprocessor Git::Documentation::DocumentPostProcessor
       end
      
     - ## Documentation/git-clone.txt ##
     -@@ Documentation/git-clone.txt: 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
     - -----------
     -
     - ## Documentation/git-init.txt ##
     -@@ Documentation/git-init.txt: 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
     -
       ## t/t0450-txt-doc-vs-help.sh ##
      @@ t/t0450-txt-doc-vs-help.sh: txt_to_synopsis () {
       	fi &&
       	b2t="$(builtin_to_txt "$builtin")" &&
       	sed -n \
      -		-e '/^\[verse\]$/,/^$/ {
     -+		-e '/^\[\(verse\|synopsis\)\]$/,/^$/ {
     ++		-E '/^\[(verse|synopsis)\]$/,/^$/ {
       			/^$/d;
      -			/^\[verse\]$/d;
      -			s/_//g;
      -			s/++//g;
      -			s/`//g;
     -+			/^\[\(verse\|synopsis\)\]$/d;
     - 			s/{litdd}/--/g;
     - 			s/'\''\(git[ a-z-]*\)'\''/\1/g;
     +-			s/{litdd}/--/g;
     +-			s/'\''\(git[ a-z-]*\)'\''/\1/g;
     ++			/^\[(verse|synopsis)\]$/d;
     ++			s/\{litdd\}/--/g;
     ++			s/'\''(git[ a-z-]*)'\''/\1/g;
       
     + 			p;
     + 		}' \
 2:  b0547422e5c = 2:  b6387bef40d doc: update the guidelines to reflect the current formatting rules
 3:  3bcbe455747 ! 3:  2a61e0945de doc: apply synopsis simplification on git-clone and git-init
     @@ Documentation/git-clone.txt: git-clone - Clone a repository into a new directory
      -	  [`-l`] [`-s`] [`--no-hardlinks`] [`-q`] [`-n`] [`--bare`] [`--mirror`]
      -	  [`-o` _<name>_] [`-b` _<name>_] [`-u` _<upload-pack>_] [`--reference` _<repository>_]
      -	  [`--dissociate`] [`--separate-git-dir` _<git-dir>_]
     --	  [`--depth` _<depth>_] [`--`[`no-`]`single-branch`] [`--no-tags`]
     --	  [++--recurse-submodules++[++=++__<pathspec>__]] [`--`[`no-`]`shallow-submodules`]
     --	  [`--`[`no-`]`remote-submodules`] [`--jobs` _<n>_] [`--sparse`] [`--`[`no-`]`reject-shallow`]
     +-	  [`--depth` _<depth>_] [`--`[`no-`]{empty}`single-branch`] [`--no-tags`]
     +-	  [++--recurse-submodules++[++=++__<pathspec>__]] [++--++[++no-++]{empty}++shallow-submodules++]
     +-	  [`--`[`no-`]{empty}`remote-submodules`] [`--jobs` _<n>_] [`--sparse`] [`--`[`no-`]{empty}`reject-shallow`]
      -	  [++--filter=++__<filter-spec>__] [`--also-filter-submodules`]] [`--`] _<repository>_
     --	  [__<directory>__]
     +-	  [_<directory>_]
      +[synopsis]
      +git clone [--template=<template-directory>]
      +	  [-l] [-s] [--no-hardlinks] [-q] [-n] [--bare] [--mirror]
     @@ Documentation/git-init.txt: git-init - Create an empty Git repository or reiniti
      -	  [`--separate-git-dir` _<git-dir>_] [++--object-format=++__<format>__]
      -	  [++--ref-format=++__<format>__]
      -	  [`-b` _<branch-name>_ | ++--initial-branch=++__<branch-name>__]
     --	  [`--shared`[++=++__<permissions>__]] [__<directory>__]
     +-	  [++--shared++[++=++__<permissions>__]] [_<directory>_]
      +[synopsis]
      +git init [-q | --quiet] [--bare] [--template=<template-directory>]
      +	 [--separate-git-dir <git-dir>] [--object-format=<format>]