[PATCH 0/3] doc: introducing synopsis para

[PATCH 0/3] doc: introducing synopsis para

[Jean-Noël Avila via GitGitGadget]

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.

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             | 14 ++++++++++
 Documentation/asciidoctor-extensions.rb | 17 +++++++++++++
 Documentation/git-clone.txt             | 20 +++++++--------
 Documentation/git-init.txt              | 12 ++++-----
 t/t0450-txt-doc-vs-help.sh              |  7 ++---
 6 files changed, 68 insertions(+), 36 deletions(-)


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

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

[Jean-Noël Avila via GitGitGadget]

From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>

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 <jn.avila@free.fr>
---
 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(-)

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;
 
-- 
gitgitgadget

[PATCH 2/3] doc: update the guidelines to reflect the current formatting rules

[Jean-Noël Avila via GitGitGadget]

From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>

Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
---
 Documentation/CodingGuidelines | 34 +++++++++++++++++++---------------
 1 file changed, 19 insertions(+), 15 deletions(-)

diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index 1d92b2da03e8..4d59e8f89ec8 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -760,56 +760,60 @@ Markup:
 
 Synopsis Syntax
 
- Syntax grammar is formatted neither as literal nor as placeholder.
+ The synopsis (a paragraph with [synopsis] attribute) is automatically
+ formatted by the toolchain and does not need typesetting.
 
  A few commented examples follow to provide reference when writing or
  modifying command usage strings and synopsis sections in the manual
  pages:
 
  Possibility of multiple occurrences is indicated by three dots:
-   _<file>_...
+   <file>...
    (One or more of <file>.)
 
  Optional parts are enclosed in square brackets:
-   [_<file>_...]
+   [<file>...]
    (Zero or more of <file>.)
 
-   ++--exec-path++[++=++__<path>__]
+ An optional parameter needs to be typeset with unconstrained pairs
+   [<repository>]
+
+   --exec-path[=<path>]
    (Option with an optional argument.  Note that the "=" is inside the
    brackets.)
 
-   [_<patch>_...]
+   [<patch>...]
    (Zero or more of <patch>.  Note that the dots are inside, not
    outside the brackets.)
 
  Multiple alternatives are indicated with vertical bars:
-   [`-q` | `--quiet`]
-   [`--utf8` | `--no-utf8`]
+   [-q | --quiet]
+   [--utf8 | --no-utf8]
 
  Use spacing around "|" token(s), but not immediately after opening or
  before closing a [] or () pair:
-   Do: [`-q` | `--quiet`]
-   Don't: [`-q`|`--quiet`]
+   Do: [-q | --quiet]
+   Don't: [-q|--quiet]
 
  Don't use spacing around "|" tokens when they're used to separate the
  alternate arguments of an option:
-    Do: ++--track++[++=++(`direct`|`inherit`)]`
-    Don't: ++--track++[++=++(`direct` | `inherit`)]
+    Do: --track[=(direct|inherit)]
+    Don't: --track[=(direct | inherit)]
 
  Parentheses are used for grouping:
-   [(_<rev>_ | _<range>_)...]
+   [(<rev>|<range>)...]
    (Any number of either <rev> or <range>.  Parens are needed to make
    it clear that "..." pertains to both <rev> and <range>.)
 
-   [(`-p` _<parent>_)...]
+   [(-p <parent>)...]
    (Any number of option -p, each with one <parent> argument.)
 
-   `git remote set-head` _<name>_ (`-a` | `-d` | _<branch>_)
+   git remote set-head <name> (-a|-d|<branch>)
    (One and only one of "-a", "-d" or "<branch>" _must_ (no square
    brackets) be provided.)
 
  And a somewhat more contrived example:
-   `--diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]`
+   --diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]
    Here "=" is outside the brackets, because "--diff-filter=" is a
    valid usage.  "*" has its own pair of brackets, because it can
    (optionally) be specified only when one or more of the letters is
-- 
gitgitgadget

[PATCH 3/3] doc: apply synopsis simplification on git-clone and git-init

[Jean-Noël Avila via GitGitGadget]

From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>

With the new synopsis formatting backend, no special asciidoc markup
is needed.

Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
---
 Documentation/git-clone.txt | 20 ++++++++++----------
 Documentation/git-init.txt  | 12 ++++++------
 2 files changed, 16 insertions(+), 16 deletions(-)

diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
index 70a3f0331f83..53b1c3e23f75 100644
--- a/Documentation/git-clone.txt
+++ b/Documentation/git-clone.txt
@@ -8,16 +8,16 @@ git-clone - Clone a repository into a new directory
 
 SYNOPSIS
 --------
-[verse]
-`git clone` [++--template=++__<template-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`]
-	  [++--filter=++__<filter-spec>__] [`--also-filter-submodules`]] [`--`] _<repository>_
-	  [__<directory>__]
+[synopsis]
+git clone [--template=<template-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]
+	  [--filter=<filter-spec>] [--also-filter-submodules]] [--] <repository>
+	  [<directory>]
 
 DESCRIPTION
 -----------
diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt
index 7cdc693e1c68..eba67fdde83f 100644
--- a/Documentation/git-init.txt
+++ b/Documentation/git-init.txt
@@ -8,12 +8,12 @@ git-init - Create an empty Git repository or reinitialize an existing one
 
 SYNOPSIS
 --------
-[verse]
-`git init` [`-q` | `--quiet`] [`--bare`] [++--template=++__<template-directory>__]
-	  [`--separate-git-dir` _<git-dir>_] [++--object-format=++__<format>__]
-	  [++--ref-format=++__<format>__]
-	  [`-b` _<branch-name>_ | ++--initial-branch=++__<branch-name>__]
-	  [`--shared`[++=++__<permissions>__]] [__<directory>__]
+[synopsis]
+git init [-q | --quiet] [--bare] [--template=<template-directory>]
+	 [--separate-git-dir <git-dir>] [--object-format=<format>]
+	 [--ref-format=<format>]
+	 [-b <branch-name> | --initial-branch=<branch-name>]
+	 [--shared[=<permissions>]] [<directory>]
 
 
 DESCRIPTION
-- 
gitgitgadget

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

[Jean-Noël AVILA]

Sorry for the noise: this patch series does not work on macOS.

BR

Jean-Noël

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

[Junio C Hamano]

"Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com> 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.

Re: [PATCH 2/3] doc: update the guidelines to reflect the current formatting rules

[Junio C Hamano]

"Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>
>
> Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
> ---
>  Documentation/CodingGuidelines | 34 +++++++++++++++++++---------------
>  1 file changed, 19 insertions(+), 15 deletions(-)
>
> diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
> index 1d92b2da03e8..4d59e8f89ec8 100644
> --- a/Documentation/CodingGuidelines
> +++ b/Documentation/CodingGuidelines
> @@ -760,56 +760,60 @@ Markup:
>  
>  Synopsis Syntax
>  
> - Syntax grammar is formatted neither as literal nor as placeholder.
> + The synopsis (a paragraph with [synopsis] attribute) is automatically
> + formatted by the toolchain and does not need typesetting.

How pleasant ;-)

>   And a somewhat more contrived example:
> -   `--diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]`
> +   --diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]
>     Here "=" is outside the brackets, because "--diff-filter=" is a
>     valid usage.  "*" has its own pair of brackets, because it can
>     (optionally) be specified only when one or more of the letters is

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

[Jean-Noël Avila via GitGitGadget]

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>]

-- 
gitgitgadget

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

[Jean-Noël Avila via GitGitGadget]

From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>

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 <jn.avila@free.fr>
---
 Documentation/asciidoc.conf             | 12 ++++++++++++
 Documentation/asciidoctor-extensions.rb | 17 +++++++++++++++++
 t/t0450-txt-doc-vs-help.sh              | 11 ++++-------
 3 files changed, 33 insertions(+), 7 deletions(-)

diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf
index 60f76f43edab..08111e98ab33 100644
--- a/Documentation/asciidoc.conf
+++ b/Documentation/asciidoc.conf
@@ -57,3 +57,15 @@ 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!([\[ |()>]|^|\])([-=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="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[]
diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb
index d906a008039c..8c7612743504 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/t/t0450-txt-doc-vs-help.sh b/t/t0450-txt-doc-vs-help.sh
index 69917d7b8459..f99a69ae1b74 100755
--- a/t/t0450-txt-doc-vs-help.sh
+++ b/t/t0450-txt-doc-vs-help.sh
@@ -56,14 +56,11 @@ 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;
-			s/{litdd}/--/g;
-			s/'\''\(git[ a-z-]*\)'\''/\1/g;
+			/^\[(verse|synopsis)\]$/d;
+			s/\{litdd\}/--/g;
+			s/'\''(git[ a-z-]*)'\''/\1/g;
 
 			p;
 		}' \
-- 
gitgitgadget

[PATCH v2 2/3] doc: update the guidelines to reflect the current formatting rules

[Jean-Noël Avila via GitGitGadget]

From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>

Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
---
 Documentation/CodingGuidelines | 34 +++++++++++++++++++---------------
 1 file changed, 19 insertions(+), 15 deletions(-)

diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index 1d92b2da03e8..4d59e8f89ec8 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -760,56 +760,60 @@ Markup:
 
 Synopsis Syntax
 
- Syntax grammar is formatted neither as literal nor as placeholder.
+ The synopsis (a paragraph with [synopsis] attribute) is automatically
+ formatted by the toolchain and does not need typesetting.
 
  A few commented examples follow to provide reference when writing or
  modifying command usage strings and synopsis sections in the manual
  pages:
 
  Possibility of multiple occurrences is indicated by three dots:
-   _<file>_...
+   <file>...
    (One or more of <file>.)
 
  Optional parts are enclosed in square brackets:
-   [_<file>_...]
+   [<file>...]
    (Zero or more of <file>.)
 
-   ++--exec-path++[++=++__<path>__]
+ An optional parameter needs to be typeset with unconstrained pairs
+   [<repository>]
+
+   --exec-path[=<path>]
    (Option with an optional argument.  Note that the "=" is inside the
    brackets.)
 
-   [_<patch>_...]
+   [<patch>...]
    (Zero or more of <patch>.  Note that the dots are inside, not
    outside the brackets.)
 
  Multiple alternatives are indicated with vertical bars:
-   [`-q` | `--quiet`]
-   [`--utf8` | `--no-utf8`]
+   [-q | --quiet]
+   [--utf8 | --no-utf8]
 
  Use spacing around "|" token(s), but not immediately after opening or
  before closing a [] or () pair:
-   Do: [`-q` | `--quiet`]
-   Don't: [`-q`|`--quiet`]
+   Do: [-q | --quiet]
+   Don't: [-q|--quiet]
 
  Don't use spacing around "|" tokens when they're used to separate the
  alternate arguments of an option:
-    Do: ++--track++[++=++(`direct`|`inherit`)]`
-    Don't: ++--track++[++=++(`direct` | `inherit`)]
+    Do: --track[=(direct|inherit)]
+    Don't: --track[=(direct | inherit)]
 
  Parentheses are used for grouping:
-   [(_<rev>_ | _<range>_)...]
+   [(<rev>|<range>)...]
    (Any number of either <rev> or <range>.  Parens are needed to make
    it clear that "..." pertains to both <rev> and <range>.)
 
-   [(`-p` _<parent>_)...]
+   [(-p <parent>)...]
    (Any number of option -p, each with one <parent> argument.)
 
-   `git remote set-head` _<name>_ (`-a` | `-d` | _<branch>_)
+   git remote set-head <name> (-a|-d|<branch>)
    (One and only one of "-a", "-d" or "<branch>" _must_ (no square
    brackets) be provided.)
 
  And a somewhat more contrived example:
-   `--diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]`
+   --diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]
    Here "=" is outside the brackets, because "--diff-filter=" is a
    valid usage.  "*" has its own pair of brackets, because it can
    (optionally) be specified only when one or more of the letters is
-- 
gitgitgadget

[PATCH v2 3/3] doc: apply synopsis simplification on git-clone and git-init

[Jean-Noël Avila via GitGitGadget]

From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>

With the new synopsis formatting backend, no special asciidoc markup
is needed.

Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
---
 Documentation/git-clone.txt | 20 ++++++++++----------
 Documentation/git-init.txt  | 12 ++++++------
 2 files changed, 16 insertions(+), 16 deletions(-)

diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
index 8e925db7e9c6..53b1c3e23f75 100644
--- a/Documentation/git-clone.txt
+++ b/Documentation/git-clone.txt
@@ -8,16 +8,16 @@ git-clone - Clone a repository into a new directory
 
 SYNOPSIS
 --------
-[verse]
-`git clone` [++--template=++__<template-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-`]{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>_]
+[synopsis]
+git clone [--template=<template-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]
+	  [--filter=<filter-spec>] [--also-filter-submodules]] [--] <repository>
+	  [<directory>]
 
 DESCRIPTION
 -----------
diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt
index daff93bd164b..eba67fdde83f 100644
--- a/Documentation/git-init.txt
+++ b/Documentation/git-init.txt
@@ -8,12 +8,12 @@ git-init - Create an empty Git repository or reinitialize an existing one
 
 SYNOPSIS
 --------
-[verse]
-`git init` [`-q` | `--quiet`] [`--bare`] [++--template=++__<template-directory>__]
-	  [`--separate-git-dir` _<git-dir>_] [++--object-format=++__<format>__]
-	  [++--ref-format=++__<format>__]
-	  [`-b` _<branch-name>_ | ++--initial-branch=++__<branch-name>__]
-	  [++--shared++[++=++__<permissions>__]] [_<directory>_]
+[synopsis]
+git init [-q | --quiet] [--bare] [--template=<template-directory>]
+	 [--separate-git-dir <git-dir>] [--object-format=<format>]
+	 [--ref-format=<format>]
+	 [-b <branch-name> | --initial-branch=<branch-name>]
+	 [--shared[=<permissions>]] [<directory>]
 
 
 DESCRIPTION
-- 
gitgitgadget

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

[Junio C Hamano]

"Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com> writes:

> 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'.

The rendered result looks OK but the source being just like what we
would write in plain text files without any extra mark-up makes it
look quite nice.

I wonder what we want to do with some oddballs, like git-shortlog
that uses "|" not as an alternative but literally a pipe (i.e. "feed
the output of this other command via a pipe to this command"),
though.

    git log --pretty=short | git shortlog [<options>]

There may be also some page that indicates "this command takes its
input from its standard input" by using something like

    git cmd [--foo] [--bar] <input-file

which we may need to think how to handle.  The easiest way out may
be to say "don't do these to indicate/force where the input comes
from".  I dunno.

Thanks.

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

[Jean-Noël AVILA]

On Thursday, 25 July 2024 01:15:48 CEST Junio C Hamano wrote:
> "Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com> writes:
> 
> > 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'.
> 
> The rendered result looks OK but the source being just like what we
> would write in plain text files without any extra mark-up makes it
> look quite nice.
> 
> I wonder what we want to do with some oddballs, like git-shortlog
> that uses "|" not as an alternative but literally a pipe (i.e. "feed
> the output of this other command via a pipe to this command"),
> though.
> 
>     git log --pretty=short | git shortlog [<options>]

I must confess that while reviewing my patch, by switching all [verse] to 
[synopsis] , I looked at this line and understood the pipe as an alternative 
from the grammar, not as a shell pipe. I also noted a few spots where the 
grammar may be misinterpreted e.g. parenthesis in git-grep.

In theory the typesetting should tell the keyword apart from the grammar, but 
for signs such as pipes and parenthesis  the rendering does not change enough.

> 
> There may be also some page that indicates "this command takes its
> input from its standard input" by using something like
> 
>     git cmd [--foo] [--bar] <input-file
> 
> which we may need to think how to handle.  The easiest way out may
> be to say "don't do these to indicate/force where the input comes
> from".  I dunno.
> 

The form 

    git cmd  [--foo] [--bar] < <input-file>

is completely acceptable , would render correctly and would remove the use of 
the pipe. The thing is that this pipe isn't even part of the command. It is 
just an example. Maybe it should not appear in the synopsis at all.

For keyword signs that are already used in expressing the grammar, we could 
quote the sign to indicate that it is a keyword : "(" .

Thanks

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

[Junio C Hamano]

Jean-Noël AVILA <jn.avila@free.fr> writes:

> The form 
>
>     git cmd  [--foo] [--bar] < <input-file>
>
> is completely acceptable , would render correctly and would remove the use of 
> the pipe.

Nice.  I was afraid that it might be interpreted as a placeholder
whose description is "<input-file" ;-)

> The thing is that this pipe isn't even part of the command. It is 
> just an example. Maybe it should not appear in the synopsis at all.

Historically the command was designed to read from "git log" as its
upstream and nothing else, which was where that sample command in
the synopsis originated, but it is unusual to spell out the upstream
(or downstream for that matter) of a pipe even when the command is
often used inside a pipeline in the synopsis section.

> For keyword signs that are already used in expressing the grammar, we could 
> quote the sign to indicate that it is a keyword : "(" .

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

[Jean-Noël Avila via GitGitGadget]

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'. Additionally, as
s macro is introduce to apply the same rules freely in the text.

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

Changes since V2:

 * introduce the s macro to freely apply synopsis styling wherever needed,
   without formatting hassle.

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          | 54 +++++++++---------
 Documentation/asciidoc.conf             | 21 ++++++-
 Documentation/asciidoctor-extensions.rb | 33 +++++++++++
 Documentation/git-clone.txt             | 76 ++++++++++++-------------
 Documentation/git-init.txt              | 33 +++++------
 Documentation/urls.txt                  | 26 ++++-----
 t/t0450-txt-doc-vs-help.sh              | 11 ++--
 7 files changed, 150 insertions(+), 104 deletions(-)


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

Range-diff vs v2:

 1:  aba144f4ff3 ! 1:  0d7c1dd8f26 doc: introduce a synopsis custom paragraph attribute
     @@ Commit message
          created and the backends of asciidoc and asciidoctor take in charge to
          correctly add the required typesetting.
      
     +    additionally, a 's' macro ('s' standing for synopsis) is introduced to
     +    allow writers to freely apply automatic styling whereever required.
     +
          Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
      
       ## Documentation/asciidoc.conf ##
     -@@ Documentation/asciidoc.conf: git-relative-html-prefix=
     +@@
     + 
     + [macros]
     + (?su)[\\]?(?P<name>linkgit):(?P<target>\S*?)\[(?P<attrlist>.*?)\]=
     +-
     ++(?su)[\\]?(?P<name>s):(?P<target>\S*?)\["(?P<attrlist>.*?)"\]=
     + [attributes]
     + asterisk=&#42;
     + plus=&#43;
     +@@ Documentation/asciidoc.conf: ifdef::backend-docbook[]
     + {0#<citerefentry>}
     + {0#<refentrytitle>{target}</refentrytitle><manvolnum>{0}</manvolnum>}
     + {0#</citerefentry>}
     ++
     ++[s-inlinemacro]
     ++{eval:re.sub(r'(&lt;[-a-zA-Z0-9.]+&gt;)', r'<emphasis>\1</emphasis>', re.sub(r'([\[ |()>]|^|\]|&gt;)(\.?[-a-zA-Z0-9:+=~@,\/]+\.?)',r'\1<literal>\2</literal>', '{attrlist}'))}
     + endif::backend-docbook[]
     + 
     + ifdef::backend-docbook[]
     +@@ Documentation/asciidoc.conf: ifdef::backend-xhtml11[]
     + git-relative-html-prefix=
       [linkgit-inlinemacro]
       <a href="{git-relative-html-prefix}{target}.html">{target}{0?({0})}</a>
     - endif::backend-xhtml11[]
     ++
     ++[s-inlinemacro]
     ++{eval:re.sub(r'(&lt;[-a-zA-Z0-9.]+&gt;)', r'<em>\1</em>', re.sub(r'([\[ |()>]|^|\]|&gt;)(\.?[-=a-zA-Z0-9:+,@]+\.?)',r'\1<code>\2</code>', '{attrlist}'))}
     ++
     ++endif::backend-xhtml11[]
      +
      +ifdef::backend-docbook[]
      +ifdef::doctype-manpage[]
      +[paradef-default]
     -+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'"
     ++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="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[]
     ++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
     +       end
     +     end
     + 
     ++    class SynopsisMacroProcessor < Asciidoctor::Extensions::InlineMacroProcessor
     ++      use_dsl
     ++
     ++      named :s
     ++      match(/s:\["(.+?)"\]/)
     ++
     ++      def process(parent, target, attrs)
     ++        l = target.gsub(/([\[\] |()]|^|&gt;)(\.?[-a-zA-Z0-9:+=~@,\/]+\.?)/, '\1{empty}`\2`{empty}')
     ++                  .gsub(/(&lt;[-a-zA-Z0-9.]+&gt;)/, '__\\1__')
     ++                  .gsub(']', ']{empty}')
     ++
     ++        create_inline parent, :quoted, l, attributes: { 'subs' => :normal }
     ++      end
     ++    end
     ++
     +     class DocumentPostProcessor < Asciidoctor::Extensions::Postprocessor
     +       def process document, output
     +         if document.basebackend? 'docbook'
      @@ Documentation/asciidoctor-extensions.rb: module Git
               output
             end
     @@ 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}')
     ++          l.gsub(/([\[\] |()>]|^)([-a-zA-Z0-9:+=]+)/, '\1{empty}`\2`{empty}')
      +           .gsub(/(<[-a-zA-Z0-9.]+>)/, '__\\1__')
      +           .gsub(']', ']{empty}')
      +        end
     @@ Documentation/asciidoctor-extensions.rb: module Git
       
       Asciidoctor::Extensions.register do
         inline_macro Git::Documentation::LinkGitProcessor, :linkgit
     ++  inline_macro Git::Documentation::SynopsisMacroProcessor
      +  block Git::Documentation::SynopsisBlock
         postprocessor Git::Documentation::DocumentPostProcessor
       end
 2:  b6387bef40d ! 2:  92f3121cf4e doc: update the guidelines to reflect the current formatting rules
     @@ Commit message
      
       ## Documentation/CodingGuidelines ##
      @@ Documentation/CodingGuidelines: Markup:
     +    _<key-id>_
     + 
     +  When literal and placeholders are mixed, each markup is applied for
     +- each sub-entity. If they are stuck, a special markup, called
     +- unconstrained formatting is required.
     +- Unconstrained formating for placeholders is __<like-this>__
     +- Unconstrained formatting for literal formatting is ++like this++
     +-   `--jobs` _<n>_
     +-   ++--sort=++__<key>__
     +-   __<directory>__++/.git++
     +-   ++remote.++__<name>__++.mirror++
     +-
     +- caveat: ++ unconstrained format is not verbatim and may expand
     +- content. Use Asciidoc escapes inside them.
     ++ each sub-entity. If the formatting is becoming too hairy, you can use the
     ++ s:["foo"] formatting macro and let it format the groups for you.
     ++   `--jobs` _<n>_ or s:["--jobs <n>"]
     ++   s:["--sort=<key>
     ++   s:["<directory>/.git"]
     ++   s:["remote.<name>.mirror"]
     ++   s:["ssh://[<user>@]<host>[:<port>]/<path-to-git-repo>"]
     ++
     ++Note that the double-quotes are required by the macro.
       
       Synopsis Syntax
       
 3:  2a61e0945de ! 3:  02406b91894 doc: apply synopsis simplification on git-clone and git-init
     @@ Documentation/git-clone.txt: git-clone - Clone a repository into a new directory
       
       DESCRIPTION
       -----------
     +@@ Documentation/git-clone.txt: prevent the unintentional copying of files by dereferencing the symbolic
     + links.
     + +
     + *NOTE*: this operation can race with concurrent modification to the
     +-source repository, similar to running `cp -r src dst` while modifying
     +-`src`.
     ++source repository, similar to running s:["cp -r <src> <dst>"] while modifying
     ++_<src>_.
     + 
     + `--no-hardlinks`::
     + 	Force the cloning process from a repository on a local
     +@@ Documentation/git-clone.txt: If you want to break the dependency of a repository cloned with `--shared` on
     + its source repository, you can simply run `git repack -a` to copy all
     + objects from the source repository into a pack in the cloned repository.
     + 
     +-`--reference`[`-if-able`] _<repository>_::
     ++s:["--reference[-if-able] <repository>"]::
     + 	If the reference _<repository>_ is on the local machine,
     + 	automatically setup `.git/objects/info/alternates` to
     + 	obtain objects from the reference _<repository>_.  Using
     +@@ Documentation/git-clone.txt: objects from the source repository into a pack in the cloned repository.
     + 	is specified. This flag forces progress status even if the
     + 	standard error stream is not directed to a terminal.
     + 
     +-++--server-option=++__<option>__::
     ++s:["--server-option=<option>"]::
     + 	Transmit the given string to the server when communicating using
     + 	protocol version 2.  The given string must not contain a NUL or LF
     + 	character.  The server's handling of server options, including
     + 	unknown ones, is server-specific.
     +-	When multiple ++--server-option=++__<option>__ are given, they are all
     ++	When multiple s:["--server-option=<option>"] are given, they are all
     + 	sent to the other side in the order listed on the command line.
     + 
     + `-n`::
     + `--no-checkout`::
     +-	No checkout of HEAD is performed after the clone is complete.
     ++	No checkout of `HEAD` is performed after the clone is complete.
     + 
     + `--`[`no-`]`reject-shallow`::
     + 	Fail if the source repository is a shallow repository.
     +@@ Documentation/git-clone.txt: objects from the source repository into a pack in the cloned repository.
     + `--bare`::
     + 	Make a 'bare' Git repository.  That is, instead of
     + 	creating _<directory>_ and placing the administrative
     +-	files in _<directory>_`/.git`, make the _<directory>_
     ++	files in s:["<directory>/.git"], make the _<directory>_
     + 	itself the `$GIT_DIR`. This obviously implies the `--no-checkout`
     + 	because there is nowhere to check out the working tree.
     + 	Also the branch heads at the remote are copied directly
     +@@ Documentation/git-clone.txt: objects from the source repository into a pack in the cloned repository.
     + 	linkgit:git-sparse-checkout[1] command can be used to grow the
     + 	working directory as needed.
     + 
     +-++--filter=++__<filter-spec>__::
     ++s:["--filter=<filter-spec>"]::
     + 	Use the partial clone feature and request that the server sends
     + 	a subset of reachable objects according to a given object filter.
     + 	When using `--filter`, the supplied _<filter-spec>_ is used for
     + 	the partial clone filter. For example, `--filter=blob:none` will
     + 	filter out all blobs (file contents) until needed by Git. Also,
     +-	++--filter=blob:limit=++__<size>__ will filter out all blobs of size
     ++	s:["--filter=blob:limit=<size>"] will filter out all blobs of size
     + 	at least _<size>_. For more details on filter specifications, see
     + 	the `--filter` option in linkgit:git-rev-list[1].
     + 
     +@@ Documentation/git-clone.txt: objects from the source repository into a pack in the cloned repository.
     + 
     + `-b` _<name>_::
     + `--branch` _<name>_::
     +-	Instead of pointing the newly created HEAD to the branch pointed
     +-	to by the cloned repository's HEAD, point to _<name>_ branch
     ++	Instead of pointing the newly created `HEAD` to the branch pointed
     ++	to by the cloned repository's `HEAD`, point to _<name>_ branch
     + 	instead. In a non-bare repository, this is the branch that will
     + 	be checked out.
     +-	`--branch` can also take tags and detaches the HEAD at that commit
     ++	`--branch` can also take tags and detaches the `HEAD` at that commit
     + 	in the resulting repository.
     + 
     + `-u` _<upload-pack>_::
     +@@ Documentation/git-clone.txt: objects from the source repository into a pack in the cloned repository.
     + 	via ssh, this specifies a non-default path for the command
     + 	run on the other end.
     + 
     +-++--template=++__<template-directory>__::
     ++s:["--template=<template-directory>"]::
     + 	Specify the directory from which templates will be used;
     + 	(See the "TEMPLATE DIRECTORY" section of linkgit:git-init[1].)
     + 
     +-`-c` __<key>__++=++__<value>__::
     +-`--config` __<key>__++=++__<value>__::
     ++`-c` s:["<key>=<value>"]::
     ++`--config` s:["<key>=<value>"]::
     + 	Set a configuration variable in the newly-created repository;
     + 	this takes effect immediately after the repository is
     + 	initialized, but before the remote history is fetched or any
     +@@ Documentation/git-clone.txt: objects from the source repository into a pack in the cloned repository.
     + Due to limitations of the current implementation, some configuration
     + variables do not take effect until after the initial fetch and checkout.
     + Configuration variables known to not take effect are:
     +-++remote.++__<name>__++.mirror++ and ++remote.++__<name>__++.tagOpt++.  Use the
     ++s:["remote.<name>.mirror"] and s:["remote.<name>.tagOpt"].  Use the
     + corresponding `--mirror` and `--no-tags` options instead.
     + 
     +-`--depth` _<depth>_::
     ++s:["--depth <depth>"]::
     + 	Create a 'shallow' clone with a history truncated to the
     + 	specified number of commits. Implies `--single-branch` unless
     + 	`--no-single-branch` is given to fetch the histories near the
     + 	tips of all branches. If you want to clone submodules shallowly,
     + 	also pass `--shallow-submodules`.
     + 
     +-++--shallow-since=++__<date>__::
     ++s:["--shallow-since=<date>"]::
     + 	Create a shallow clone with a history after the specified time.
     + 
     +-++--shallow-exclude=++__<revision>__::
     ++s:["--shallow-exclude=<revision>"]::
     + 	Create a shallow clone with a history, excluding commits
     + 	reachable from a specified remote branch or tag.  This option
     + 	can be specified multiple times.
     + 
     +-`--`[`no-`]`single-branch`::
     ++s:["--[no-]single-branch"]::
     + 	Clone only the history leading to the tip of a single branch,
     + 	either specified by the `--branch` option or the primary
     + 	branch remote's `HEAD` points at.
     +@@ Documentation/git-clone.txt: corresponding `--mirror` and `--no-tags` options instead.
     + 
     + `--no-tags`::
     + 	Don't clone any tags, and set
     +-	`remote.<remote>.tagOpt=--no-tags` in the config, ensuring
     ++	s:["remote.<remote>.tagOpt=--no-tags"] in the config, ensuring
     + 	that future `git pull` and `git fetch` operations won't follow
     + 	any tags. Subsequent explicit tag fetches will still work,
     + 	(see linkgit:git-fetch[1]).
     +@@ Documentation/git-clone.txt: maintain a branch with no references other than a single cloned
     + branch. This is useful e.g. to maintain minimal clones of the default
     + branch of some repository for search indexing.
     + 
     +-`--recurse-submodules`[`=`{empty}__<pathspec>__]::
     ++s:["--recurse-submodules[=<pathspec>]"]::
     + 	After the clone is created, initialize and clone submodules
     + 	within based on the provided _<pathspec>_.  If no _=<pathspec>_ is
     + 	provided, all submodules are initialized and cloned.
     +@@ Documentation/git-clone.txt: branch of some repository for search indexing.
     + +
     + Submodules are initialized and cloned using their default settings. This is
     + equivalent to running
     +-`git submodule update --init --recursive <pathspec>` immediately after
     ++s:["git submodule update --init --recursive <pathspec>"] immediately after
     + the clone is finished. This option is ignored if the cloned repository does
     + not have a worktree/checkout (i.e. if any of `--no-checkout`/`-n`, `--bare`,
     + or `--mirror` is given)
     + 
     +-`--`[`no-`]`shallow-submodules`::
     ++s:["--[no-]shallow-submodules"]::
     + 	All submodules which are cloned will be shallow with a depth of 1.
     + 
     +-`--`[`no-`]`remote-submodules`::
     ++s:["--[no-]remote-submodules"]::
     + 	All submodules which are cloned will use the status of the submodule's
     + 	remote-tracking branch to update the submodule, rather than the
     + 	superproject's recorded SHA-1. Equivalent to passing `--remote` to
     + 	`git submodule update`.
     + 
     +-`--separate-git-dir=`{empty}__<git-dir>__::
     ++s:["--separate-git-dir=<git-dir>"]::
     + 	Instead of placing the cloned repository where it is supposed
     + 	to be, place the cloned repository at the specified directory,
     + 	then make a filesystem-agnostic Git symbolic link to there.
     + 	The result is Git repository can be separated from working
     + 	tree.
     + 
     +-`--ref-format=`{empty}__<ref-format>__::
     ++s:["--ref-format=<ref-format>"]::
     + 
     + Specify the given ref storage format for the repository. The valid values are:
     + +
     +@@ Documentation/git-clone.txt: _<directory>_::
     + 	for `host.xz:foo/.git`).  Cloning into an existing directory
     + 	is only allowed if the directory is empty.
     + 
     +-`--bundle-uri=`{empty}__<uri>__::
     ++s:["--bundle-uri=<uri>"]::
     + 	Before fetching from the remote, fetch a bundle from the given
     + 	_<uri>_ and unbundle the data into the local repository. The refs
     + 	in the bundle will be stored under the hidden `refs/bundle/*`
      
       ## Documentation/git-init.txt ##
      @@ Documentation/git-init.txt: git-init - Create an empty Git repository or reinitialize an existing one
     @@ Documentation/git-init.txt: git-init - Create an empty Git repository or reiniti
       
       
       DESCRIPTION
     +@@ Documentation/git-init.txt: directory with subdirectories for `objects`, `refs/heads`,
     + commits will be created (see the `--initial-branch` option below
     + for its name).
     + 
     +-If the `$GIT_DIR` environment variable is set then it specifies a path
     ++If the `GIT_DIR` environment variable is set then it specifies a path
     + to use instead of `./.git` for the base of the repository.
     + 
     + If the object storage directory is specified via the
     +-`$GIT_OBJECT_DIRECTORY` environment variable then the sha1 directories
     ++`GIT_OBJECT_DIRECTORY` environment variable then the sha1 directories
     + are created underneath; otherwise, the default `$GIT_DIR/objects`
     + directory is used.
     + 
     +@@ Documentation/git-init.txt: Only print error and warning messages; all other output will be suppressed.
     + Create a bare repository. If `GIT_DIR` environment is not set, it is set to the
     + current working directory.
     + 
     +-++--object-format=++__<format>__::
     +-
     ++s:["--object-format=<format>"]::
     + Specify the given object _<format>_ (hash algorithm) for the repository.  The valid
     + values are `sha1` and (if enabled) `sha256`.  `sha1` is the default.
     + +
     + include::object-format-disclaimer.txt[]
     + 
     +-++--ref-format=++__<format>__::
     +-
     ++s:["--ref-format=<format>"]::
     + Specify the given ref storage _<format>_ for the repository. The valid values are:
     + +
     + include::ref-storage-format.txt[]
     + 
     +-++--template=++__<template-directory>__::
     +-
     ++s:["--template=<template-directory>"]::
     + Specify the directory from which templates will be used.  (See the "TEMPLATE
     + DIRECTORY" section below.)
     + 
     +-++--separate-git-dir=++__<git-dir>__::
     +-
     ++s:["--separate-git-dir=<git-dir>"]::
     + Instead of initializing the repository as a directory to either `$GIT_DIR` or
     + `./.git/`, create a text file there containing the path to the actual
     + repository.  This file acts as a filesystem-agnostic Git symbolic link to the
     +@@ Documentation/git-init.txt: repository.
     + If this is a reinitialization, the repository will be moved to the specified path.
     + 
     + `-b` _<branch-name>_::
     +-++--initial-branch=++__<branch-name>__::
     +-
     ++s:["--initial-branch=<branch-name>"]::
     + Use _<branch-name>_ for the initial branch in the newly created
     + repository.  If not specified, fall back to the default name (currently
     + `master`, but this is subject to change in the future; the name can be
     + customized via the `init.defaultBranch` configuration variable).
     + 
     +-++--shared++[++=++(`false`|`true`|`umask`|`group`|`all`|`world`|`everybody`|_<perm>_)]::
     ++s:["--shared[=(false|true|umask|group|all|world|everybody|<perm>)]"]::
     + 
     + Specify that the Git repository is to be shared amongst several users.  This
     + allows users belonging to the same group to push into that
     +
     + ## Documentation/urls.txt ##
     +@@ Documentation/urls.txt: Git supports ssh, git, http, and https protocols (in addition, ftp
     + and ftps can be used for fetching, but this is inefficient and
     + deprecated; do not use them).
     + 
     +-The native transport (i.e. git:// URL) does no authentication and
     ++The native transport (i.e. `git://` URL) does no authentication and
     + should be used with caution on unsecured networks.
     + 
     + The following syntaxes may be used with them:
     + 
     +-- ++ssh://++{startsb}__<user>__++@++{endsb}__<host>__{startsb}++:++__<port>__{endsb}++/++__<path-to-git-repo>__
     +-- ++git://++__<host>__{startsb}:__<port>__{endsb}++/++__<path-to-git-repo>__
     +-- ++http++{startsb}++s++{endsb}++://++__<host>__{startsb}++:++__<port>__{endsb}++/++__<path-to-git-repo>__
     +-- ++ftp++{startsb}++s++{endsb}++://++__<host>__{startsb}++:++__<port>__{endsb}++/++__<path-to-git-repo>__
     ++- s:["ssh://[<user>@]<host>[:<port>]/<path-to-git-repo>"]
     ++- s:["git://<host>[:<port>]/<path-to-git-repo>"]
     ++- s:["http[s]://<host>[:<port>]/<path-to-git-repo>"]
     ++- s:["ftp[s]://<host>[:<port>]/<path-to-git-repo>"]
     + 
     + An alternative scp-like syntax may also be used with the ssh protocol:
     + 
     +-- {startsb}__<user>__++@++{endsb}__<host>__++:/++__<path-to-git-repo>__
     ++- s:["[<user>@]<host>:/<path-to-git-repo>"]
     + 
     + This syntax is only recognized if there are no slashes before the
     + first colon. This helps differentiate a local path that contains a
     +@@ Documentation/urls.txt: colon. For example the local path `foo:bar` could be specified as an
     + absolute path or `./foo:bar` to avoid being misinterpreted as an ssh
     + url.
     + 
     +-The ssh and git protocols additionally support ++~++__<username>__ expansion:
     ++The ssh and git protocols additionally support s:["~<username>"] expansion:
     + 
     +-- ++ssh://++{startsb}__<user>__++@++{endsb}__<host>__{startsb}++:++__<port>__{endsb}++/~++__<user>__++/++__<path-to-git-repo>__
     +-- ++git://++__<host>__{startsb}++:++__<port>__{endsb}++/~++__<user>__++/++__<path-to-git-repo>__
     +-- {startsb}__<user>__++@++{endsb}__<host>__++:~++__<user>__++/++__<path-to-git-repo>__
     ++- s:["ssh://[<user>@]<host>[:<port>]/~<user>/<path-to-git-repo>"]
     ++- s:["git://<host>[:<port>]/~<user>/<path-to-git-repo>"]
     ++- s:["[<user>@]<host>:~<user>/<path-to-git-repo>"]
     + 
     + For local repositories, also supported by Git natively, the following
     + syntaxes may be used:
     + 
     + - `/path/to/repo.git/`
     +-- ++file:///path/to/repo.git/++
     ++- `file:///path/to/repo.git/`
     + 
     + ifndef::git-clone[]
     + These two syntaxes are mostly equivalent, except when cloning, when
     +@@ Documentation/urls.txt: endif::git-clone[]
     + accept a suitable bundle file. See linkgit:git-bundle[1].
     + 
     + When Git doesn't know how to handle a certain transport protocol, it
     +-attempts to use the `remote-`{empty}__<transport>__ remote helper, if one
     ++attempts to use the s:["remote-<transport>"] remote helper, if one
     + exists. To explicitly request a remote helper, the following syntax
     + may be used:
     + 
     +-- _<transport>_::__<address>__
     ++- s:["<transport>::<address>"]
     + 
     + where _<address>_ may be a path, a server and path, or an arbitrary
     + URL-like string recognized by the specific remote helper being

-- 
gitgitgadget

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

[Jean-Noël Avila via GitGitGadget]

From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>

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.

additionally, a 's' macro ('s' standing for synopsis) is introduced to
allow writers to freely apply automatic styling whereever required.

Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
---
 Documentation/asciidoc.conf             | 21 +++++++++++++++-
 Documentation/asciidoctor-extensions.rb | 33 +++++++++++++++++++++++++
 t/t0450-txt-doc-vs-help.sh              | 11 +++------
 3 files changed, 57 insertions(+), 8 deletions(-)

diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf
index 60f76f43eda..04405453415 100644
--- a/Documentation/asciidoc.conf
+++ b/Documentation/asciidoc.conf
@@ -9,7 +9,7 @@
 
 [macros]
 (?su)[\\]?(?P<name>linkgit):(?P<target>\S*?)\[(?P<attrlist>.*?)\]=
-
+(?su)[\\]?(?P<name>s):(?P<target>\S*?)\["(?P<attrlist>.*?)"\]=
 [attributes]
 asterisk=&#42;
 plus=&#43;
@@ -28,6 +28,9 @@ ifdef::backend-docbook[]
 {0#<citerefentry>}
 {0#<refentrytitle>{target}</refentrytitle><manvolnum>{0}</manvolnum>}
 {0#</citerefentry>}
+
+[s-inlinemacro]
+{eval:re.sub(r'(&lt;[-a-zA-Z0-9.]+&gt;)', r'<emphasis>\1</emphasis>', re.sub(r'([\[ |()>]|^|\]|&gt;)(\.?[-a-zA-Z0-9:+=~@,\/]+\.?)',r'\1<literal>\2</literal>', '{attrlist}'))}
 endif::backend-docbook[]
 
 ifdef::backend-docbook[]
@@ -56,4 +59,20 @@ ifdef::backend-xhtml11[]
 git-relative-html-prefix=
 [linkgit-inlinemacro]
 <a href="{git-relative-html-prefix}{target}.html">{target}{0?({0})}</a>
+
+[s-inlinemacro]
+{eval:re.sub(r'(&lt;[-a-zA-Z0-9.]+&gt;)', r'<em>\1</em>', re.sub(r'([\[ |()>]|^|\]|&gt;)(\.?[-=a-zA-Z0-9:+,@]+\.?)',r'\1<code>\2</code>', '{attrlist}'))}
+
+endif::backend-xhtml11[]
+
+ifdef::backend-docbook[]
+ifdef::doctype-manpage[]
+[paradef-default]
+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="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[]
diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb
index d906a008039..46cbbbbfd76 100644
--- a/Documentation/asciidoctor-extensions.rb
+++ b/Documentation/asciidoctor-extensions.rb
@@ -24,6 +24,21 @@ module Git
       end
     end
 
+    class SynopsisMacroProcessor < Asciidoctor::Extensions::InlineMacroProcessor
+      use_dsl
+
+      named :s
+      match(/s:\["(.+?)"\]/)
+
+      def process(parent, target, attrs)
+        l = target.gsub(/([\[\] |()]|^|&gt;)(\.?[-a-zA-Z0-9:+=~@,\/]+\.?)/, '\1{empty}`\2`{empty}')
+                  .gsub(/(&lt;[-a-zA-Z0-9.]+&gt;)/, '__\\1__')
+                  .gsub(']', ']{empty}')
+
+        create_inline parent, :quoted, l, attributes: { 'subs' => :normal }
+      end
+    end
+
     class DocumentPostProcessor < Asciidoctor::Extensions::Postprocessor
       def process document, output
         if document.basebackend? 'docbook'
@@ -39,10 +54,28 @@ 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
+  inline_macro Git::Documentation::SynopsisMacroProcessor
+  block Git::Documentation::SynopsisBlock
   postprocessor Git::Documentation::DocumentPostProcessor
 end
diff --git a/t/t0450-txt-doc-vs-help.sh b/t/t0450-txt-doc-vs-help.sh
index 69917d7b845..f99a69ae1b7 100755
--- a/t/t0450-txt-doc-vs-help.sh
+++ b/t/t0450-txt-doc-vs-help.sh
@@ -56,14 +56,11 @@ 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;
-			s/{litdd}/--/g;
-			s/'\''\(git[ a-z-]*\)'\''/\1/g;
+			/^\[(verse|synopsis)\]$/d;
+			s/\{litdd\}/--/g;
+			s/'\''(git[ a-z-]*)'\''/\1/g;
 
 			p;
 		}' \
-- 
gitgitgadget

[PATCH v3 2/3] doc: update the guidelines to reflect the current formatting rules

[Jean-Noël Avila via GitGitGadget]

From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>

Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
---
 Documentation/CodingGuidelines | 54 ++++++++++++++++++----------------
 1 file changed, 28 insertions(+), 26 deletions(-)

diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index 1d92b2da03e..1c2d2ecbea9 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -746,70 +746,72 @@ Markup:
    _<key-id>_
 
  When literal and placeholders are mixed, each markup is applied for
- each sub-entity. If they are stuck, a special markup, called
- unconstrained formatting is required.
- Unconstrained formating for placeholders is __<like-this>__
- Unconstrained formatting for literal formatting is ++like this++
-   `--jobs` _<n>_
-   ++--sort=++__<key>__
-   __<directory>__++/.git++
-   ++remote.++__<name>__++.mirror++
-
- caveat: ++ unconstrained format is not verbatim and may expand
- content. Use Asciidoc escapes inside them.
+ each sub-entity. If the formatting is becoming too hairy, you can use the
+ s:["foo"] formatting macro and let it format the groups for you.
+   `--jobs` _<n>_ or s:["--jobs <n>"]
+   s:["--sort=<key>
+   s:["<directory>/.git"]
+   s:["remote.<name>.mirror"]
+   s:["ssh://[<user>@]<host>[:<port>]/<path-to-git-repo>"]
+
+Note that the double-quotes are required by the macro.
 
 Synopsis Syntax
 
- Syntax grammar is formatted neither as literal nor as placeholder.
+ The synopsis (a paragraph with [synopsis] attribute) is automatically
+ formatted by the toolchain and does not need typesetting.
 
  A few commented examples follow to provide reference when writing or
  modifying command usage strings and synopsis sections in the manual
  pages:
 
  Possibility of multiple occurrences is indicated by three dots:
-   _<file>_...
+   <file>...
    (One or more of <file>.)
 
  Optional parts are enclosed in square brackets:
-   [_<file>_...]
+   [<file>...]
    (Zero or more of <file>.)
 
-   ++--exec-path++[++=++__<path>__]
+ An optional parameter needs to be typeset with unconstrained pairs
+   [<repository>]
+
+   --exec-path[=<path>]
    (Option with an optional argument.  Note that the "=" is inside the
    brackets.)
 
-   [_<patch>_...]
+   [<patch>...]
    (Zero or more of <patch>.  Note that the dots are inside, not
    outside the brackets.)
 
  Multiple alternatives are indicated with vertical bars:
-   [`-q` | `--quiet`]
-   [`--utf8` | `--no-utf8`]
+   [-q | --quiet]
+   [--utf8 | --no-utf8]
 
  Use spacing around "|" token(s), but not immediately after opening or
  before closing a [] or () pair:
-   Do: [`-q` | `--quiet`]
-   Don't: [`-q`|`--quiet`]
+   Do: [-q | --quiet]
+   Don't: [-q|--quiet]
 
  Don't use spacing around "|" tokens when they're used to separate the
  alternate arguments of an option:
-    Do: ++--track++[++=++(`direct`|`inherit`)]`
-    Don't: ++--track++[++=++(`direct` | `inherit`)]
+    Do: --track[=(direct|inherit)]
+    Don't: --track[=(direct | inherit)]
 
  Parentheses are used for grouping:
-   [(_<rev>_ | _<range>_)...]
+   [(<rev>|<range>)...]
    (Any number of either <rev> or <range>.  Parens are needed to make
    it clear that "..." pertains to both <rev> and <range>.)
 
-   [(`-p` _<parent>_)...]
+   [(-p <parent>)...]
    (Any number of option -p, each with one <parent> argument.)
 
-   `git remote set-head` _<name>_ (`-a` | `-d` | _<branch>_)
+   git remote set-head <name> (-a|-d|<branch>)
    (One and only one of "-a", "-d" or "<branch>" _must_ (no square
    brackets) be provided.)
 
  And a somewhat more contrived example:
-   `--diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]`
+   --diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]
    Here "=" is outside the brackets, because "--diff-filter=" is a
    valid usage.  "*" has its own pair of brackets, because it can
    (optionally) be specified only when one or more of the letters is
-- 
gitgitgadget

[PATCH v3 3/3] doc: apply synopsis simplification on git-clone and git-init

[Jean-Noël Avila via GitGitGadget]

From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>

With the new synopsis formatting backend, no special asciidoc markup
is needed.

Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
---
 Documentation/git-clone.txt | 76 ++++++++++++++++++-------------------
 Documentation/git-init.txt  | 33 +++++++---------
 Documentation/urls.txt      | 26 ++++++-------
 3 files changed, 65 insertions(+), 70 deletions(-)

diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
index 8e925db7e9c..f0d508ebf51 100644
--- a/Documentation/git-clone.txt
+++ b/Documentation/git-clone.txt
@@ -8,16 +8,16 @@ git-clone - Clone a repository into a new directory
 
 SYNOPSIS
 --------
-[verse]
-`git clone` [++--template=++__<template-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-`]{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>_]
+[synopsis]
+git clone [--template=<template-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]
+	  [--filter=<filter-spec>] [--also-filter-submodules]] [--] <repository>
+	  [<directory>]
 
 DESCRIPTION
 -----------
@@ -64,8 +64,8 @@ prevent the unintentional copying of files by dereferencing the symbolic
 links.
 +
 *NOTE*: this operation can race with concurrent modification to the
-source repository, similar to running `cp -r src dst` while modifying
-`src`.
+source repository, similar to running s:["cp -r <src> <dst>"] while modifying
+_<src>_.
 
 `--no-hardlinks`::
 	Force the cloning process from a repository on a local
@@ -101,7 +101,7 @@ If you want to break the dependency of a repository cloned with `--shared` on
 its source repository, you can simply run `git repack -a` to copy all
 objects from the source repository into a pack in the cloned repository.
 
-`--reference`[`-if-able`] _<repository>_::
+s:["--reference[-if-able] <repository>"]::
 	If the reference _<repository>_ is on the local machine,
 	automatically setup `.git/objects/info/alternates` to
 	obtain objects from the reference _<repository>_.  Using
@@ -142,17 +142,17 @@ objects from the source repository into a pack in the cloned repository.
 	is specified. This flag forces progress status even if the
 	standard error stream is not directed to a terminal.
 
-++--server-option=++__<option>__::
+s:["--server-option=<option>"]::
 	Transmit the given string to the server when communicating using
 	protocol version 2.  The given string must not contain a NUL or LF
 	character.  The server's handling of server options, including
 	unknown ones, is server-specific.
-	When multiple ++--server-option=++__<option>__ are given, they are all
+	When multiple s:["--server-option=<option>"] are given, they are all
 	sent to the other side in the order listed on the command line.
 
 `-n`::
 `--no-checkout`::
-	No checkout of HEAD is performed after the clone is complete.
+	No checkout of `HEAD` is performed after the clone is complete.
 
 `--`[`no-`]`reject-shallow`::
 	Fail if the source repository is a shallow repository.
@@ -162,7 +162,7 @@ objects from the source repository into a pack in the cloned repository.
 `--bare`::
 	Make a 'bare' Git repository.  That is, instead of
 	creating _<directory>_ and placing the administrative
-	files in _<directory>_`/.git`, make the _<directory>_
+	files in s:["<directory>/.git"], make the _<directory>_
 	itself the `$GIT_DIR`. This obviously implies the `--no-checkout`
 	because there is nowhere to check out the working tree.
 	Also the branch heads at the remote are copied directly
@@ -177,13 +177,13 @@ objects from the source repository into a pack in the cloned repository.
 	linkgit:git-sparse-checkout[1] command can be used to grow the
 	working directory as needed.
 
-++--filter=++__<filter-spec>__::
+s:["--filter=<filter-spec>"]::
 	Use the partial clone feature and request that the server sends
 	a subset of reachable objects according to a given object filter.
 	When using `--filter`, the supplied _<filter-spec>_ is used for
 	the partial clone filter. For example, `--filter=blob:none` will
 	filter out all blobs (file contents) until needed by Git. Also,
-	++--filter=blob:limit=++__<size>__ will filter out all blobs of size
+	s:["--filter=blob:limit=<size>"] will filter out all blobs of size
 	at least _<size>_. For more details on filter specifications, see
 	the `--filter` option in linkgit:git-rev-list[1].
 
@@ -208,11 +208,11 @@ objects from the source repository into a pack in the cloned repository.
 
 `-b` _<name>_::
 `--branch` _<name>_::
-	Instead of pointing the newly created HEAD to the branch pointed
-	to by the cloned repository's HEAD, point to _<name>_ branch
+	Instead of pointing the newly created `HEAD` to the branch pointed
+	to by the cloned repository's `HEAD`, point to _<name>_ branch
 	instead. In a non-bare repository, this is the branch that will
 	be checked out.
-	`--branch` can also take tags and detaches the HEAD at that commit
+	`--branch` can also take tags and detaches the `HEAD` at that commit
 	in the resulting repository.
 
 `-u` _<upload-pack>_::
@@ -221,12 +221,12 @@ objects from the source repository into a pack in the cloned repository.
 	via ssh, this specifies a non-default path for the command
 	run on the other end.
 
-++--template=++__<template-directory>__::
+s:["--template=<template-directory>"]::
 	Specify the directory from which templates will be used;
 	(See the "TEMPLATE DIRECTORY" section of linkgit:git-init[1].)
 
-`-c` __<key>__++=++__<value>__::
-`--config` __<key>__++=++__<value>__::
+`-c` s:["<key>=<value>"]::
+`--config` s:["<key>=<value>"]::
 	Set a configuration variable in the newly-created repository;
 	this takes effect immediately after the repository is
 	initialized, but before the remote history is fetched or any
@@ -239,25 +239,25 @@ objects from the source repository into a pack in the cloned repository.
 Due to limitations of the current implementation, some configuration
 variables do not take effect until after the initial fetch and checkout.
 Configuration variables known to not take effect are:
-++remote.++__<name>__++.mirror++ and ++remote.++__<name>__++.tagOpt++.  Use the
+s:["remote.<name>.mirror"] and s:["remote.<name>.tagOpt"].  Use the
 corresponding `--mirror` and `--no-tags` options instead.
 
-`--depth` _<depth>_::
+s:["--depth <depth>"]::
 	Create a 'shallow' clone with a history truncated to the
 	specified number of commits. Implies `--single-branch` unless
 	`--no-single-branch` is given to fetch the histories near the
 	tips of all branches. If you want to clone submodules shallowly,
 	also pass `--shallow-submodules`.
 
-++--shallow-since=++__<date>__::
+s:["--shallow-since=<date>"]::
 	Create a shallow clone with a history after the specified time.
 
-++--shallow-exclude=++__<revision>__::
+s:["--shallow-exclude=<revision>"]::
 	Create a shallow clone with a history, excluding commits
 	reachable from a specified remote branch or tag.  This option
 	can be specified multiple times.
 
-`--`[`no-`]`single-branch`::
+s:["--[no-]single-branch"]::
 	Clone only the history leading to the tip of a single branch,
 	either specified by the `--branch` option or the primary
 	branch remote's `HEAD` points at.
@@ -269,7 +269,7 @@ corresponding `--mirror` and `--no-tags` options instead.
 
 `--no-tags`::
 	Don't clone any tags, and set
-	`remote.<remote>.tagOpt=--no-tags` in the config, ensuring
+	s:["remote.<remote>.tagOpt=--no-tags"] in the config, ensuring
 	that future `git pull` and `git fetch` operations won't follow
 	any tags. Subsequent explicit tag fetches will still work,
 	(see linkgit:git-fetch[1]).
@@ -279,7 +279,7 @@ maintain a branch with no references other than a single cloned
 branch. This is useful e.g. to maintain minimal clones of the default
 branch of some repository for search indexing.
 
-`--recurse-submodules`[`=`{empty}__<pathspec>__]::
+s:["--recurse-submodules[=<pathspec>]"]::
 	After the clone is created, initialize and clone submodules
 	within based on the provided _<pathspec>_.  If no _=<pathspec>_ is
 	provided, all submodules are initialized and cloned.
@@ -290,28 +290,28 @@ branch of some repository for search indexing.
 +
 Submodules are initialized and cloned using their default settings. This is
 equivalent to running
-`git submodule update --init --recursive <pathspec>` immediately after
+s:["git submodule update --init --recursive <pathspec>"] immediately after
 the clone is finished. This option is ignored if the cloned repository does
 not have a worktree/checkout (i.e. if any of `--no-checkout`/`-n`, `--bare`,
 or `--mirror` is given)
 
-`--`[`no-`]`shallow-submodules`::
+s:["--[no-]shallow-submodules"]::
 	All submodules which are cloned will be shallow with a depth of 1.
 
-`--`[`no-`]`remote-submodules`::
+s:["--[no-]remote-submodules"]::
 	All submodules which are cloned will use the status of the submodule's
 	remote-tracking branch to update the submodule, rather than the
 	superproject's recorded SHA-1. Equivalent to passing `--remote` to
 	`git submodule update`.
 
-`--separate-git-dir=`{empty}__<git-dir>__::
+s:["--separate-git-dir=<git-dir>"]::
 	Instead of placing the cloned repository where it is supposed
 	to be, place the cloned repository at the specified directory,
 	then make a filesystem-agnostic Git symbolic link to there.
 	The result is Git repository can be separated from working
 	tree.
 
-`--ref-format=`{empty}__<ref-format>__::
+s:["--ref-format=<ref-format>"]::
 
 Specify the given ref storage format for the repository. The valid values are:
 +
@@ -334,7 +334,7 @@ _<directory>_::
 	for `host.xz:foo/.git`).  Cloning into an existing directory
 	is only allowed if the directory is empty.
 
-`--bundle-uri=`{empty}__<uri>__::
+s:["--bundle-uri=<uri>"]::
 	Before fetching from the remote, fetch a bundle from the given
 	_<uri>_ and unbundle the data into the local repository. The refs
 	in the bundle will be stored under the hidden `refs/bundle/*`
diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt
index daff93bd164..fccd21cf3fb 100644
--- a/Documentation/git-init.txt
+++ b/Documentation/git-init.txt
@@ -8,12 +8,12 @@ git-init - Create an empty Git repository or reinitialize an existing one
 
 SYNOPSIS
 --------
-[verse]
-`git init` [`-q` | `--quiet`] [`--bare`] [++--template=++__<template-directory>__]
-	  [`--separate-git-dir` _<git-dir>_] [++--object-format=++__<format>__]
-	  [++--ref-format=++__<format>__]
-	  [`-b` _<branch-name>_ | ++--initial-branch=++__<branch-name>__]
-	  [++--shared++[++=++__<permissions>__]] [_<directory>_]
+[synopsis]
+git init [-q | --quiet] [--bare] [--template=<template-directory>]
+	 [--separate-git-dir <git-dir>] [--object-format=<format>]
+	 [--ref-format=<format>]
+	 [-b <branch-name> | --initial-branch=<branch-name>]
+	 [--shared[=<permissions>]] [<directory>]
 
 
 DESCRIPTION
@@ -25,11 +25,11 @@ directory with subdirectories for `objects`, `refs/heads`,
 commits will be created (see the `--initial-branch` option below
 for its name).
 
-If the `$GIT_DIR` environment variable is set then it specifies a path
+If the `GIT_DIR` environment variable is set then it specifies a path
 to use instead of `./.git` for the base of the repository.
 
 If the object storage directory is specified via the
-`$GIT_OBJECT_DIRECTORY` environment variable then the sha1 directories
+`GIT_OBJECT_DIRECTORY` environment variable then the sha1 directories
 are created underneath; otherwise, the default `$GIT_DIR/objects`
 directory is used.
 
@@ -51,26 +51,22 @@ Only print error and warning messages; all other output will be suppressed.
 Create a bare repository. If `GIT_DIR` environment is not set, it is set to the
 current working directory.
 
-++--object-format=++__<format>__::
-
+s:["--object-format=<format>"]::
 Specify the given object _<format>_ (hash algorithm) for the repository.  The valid
 values are `sha1` and (if enabled) `sha256`.  `sha1` is the default.
 +
 include::object-format-disclaimer.txt[]
 
-++--ref-format=++__<format>__::
-
+s:["--ref-format=<format>"]::
 Specify the given ref storage _<format>_ for the repository. The valid values are:
 +
 include::ref-storage-format.txt[]
 
-++--template=++__<template-directory>__::
-
+s:["--template=<template-directory>"]::
 Specify the directory from which templates will be used.  (See the "TEMPLATE
 DIRECTORY" section below.)
 
-++--separate-git-dir=++__<git-dir>__::
-
+s:["--separate-git-dir=<git-dir>"]::
 Instead of initializing the repository as a directory to either `$GIT_DIR` or
 `./.git/`, create a text file there containing the path to the actual
 repository.  This file acts as a filesystem-agnostic Git symbolic link to the
@@ -79,14 +75,13 @@ repository.
 If this is a reinitialization, the repository will be moved to the specified path.
 
 `-b` _<branch-name>_::
-++--initial-branch=++__<branch-name>__::
-
+s:["--initial-branch=<branch-name>"]::
 Use _<branch-name>_ for the initial branch in the newly created
 repository.  If not specified, fall back to the default name (currently
 `master`, but this is subject to change in the future; the name can be
 customized via the `init.defaultBranch` configuration variable).
 
-++--shared++[++=++(`false`|`true`|`umask`|`group`|`all`|`world`|`everybody`|_<perm>_)]::
+s:["--shared[=(false|true|umask|group|all|world|everybody|<perm>)]"]::
 
 Specify that the Git repository is to be shared amongst several users.  This
 allows users belonging to the same group to push into that
diff --git a/Documentation/urls.txt b/Documentation/urls.txt
index 7cec85aef17..ffeeeb3599f 100644
--- a/Documentation/urls.txt
+++ b/Documentation/urls.txt
@@ -10,19 +10,19 @@ Git supports ssh, git, http, and https protocols (in addition, ftp
 and ftps can be used for fetching, but this is inefficient and
 deprecated; do not use them).
 
-The native transport (i.e. git:// URL) does no authentication and
+The native transport (i.e. `git://` URL) does no authentication and
 should be used with caution on unsecured networks.
 
 The following syntaxes may be used with them:
 
-- ++ssh://++{startsb}__<user>__++@++{endsb}__<host>__{startsb}++:++__<port>__{endsb}++/++__<path-to-git-repo>__
-- ++git://++__<host>__{startsb}:__<port>__{endsb}++/++__<path-to-git-repo>__
-- ++http++{startsb}++s++{endsb}++://++__<host>__{startsb}++:++__<port>__{endsb}++/++__<path-to-git-repo>__
-- ++ftp++{startsb}++s++{endsb}++://++__<host>__{startsb}++:++__<port>__{endsb}++/++__<path-to-git-repo>__
+- s:["ssh://[<user>@]<host>[:<port>]/<path-to-git-repo>"]
+- s:["git://<host>[:<port>]/<path-to-git-repo>"]
+- s:["http[s]://<host>[:<port>]/<path-to-git-repo>"]
+- s:["ftp[s]://<host>[:<port>]/<path-to-git-repo>"]
 
 An alternative scp-like syntax may also be used with the ssh protocol:
 
-- {startsb}__<user>__++@++{endsb}__<host>__++:/++__<path-to-git-repo>__
+- s:["[<user>@]<host>:/<path-to-git-repo>"]
 
 This syntax is only recognized if there are no slashes before the
 first colon. This helps differentiate a local path that contains a
@@ -30,17 +30,17 @@ colon. For example the local path `foo:bar` could be specified as an
 absolute path or `./foo:bar` to avoid being misinterpreted as an ssh
 url.
 
-The ssh and git protocols additionally support ++~++__<username>__ expansion:
+The ssh and git protocols additionally support s:["~<username>"] expansion:
 
-- ++ssh://++{startsb}__<user>__++@++{endsb}__<host>__{startsb}++:++__<port>__{endsb}++/~++__<user>__++/++__<path-to-git-repo>__
-- ++git://++__<host>__{startsb}++:++__<port>__{endsb}++/~++__<user>__++/++__<path-to-git-repo>__
-- {startsb}__<user>__++@++{endsb}__<host>__++:~++__<user>__++/++__<path-to-git-repo>__
+- s:["ssh://[<user>@]<host>[:<port>]/~<user>/<path-to-git-repo>"]
+- s:["git://<host>[:<port>]/~<user>/<path-to-git-repo>"]
+- s:["[<user>@]<host>:~<user>/<path-to-git-repo>"]
 
 For local repositories, also supported by Git natively, the following
 syntaxes may be used:
 
 - `/path/to/repo.git/`
-- ++file:///path/to/repo.git/++
+- `file:///path/to/repo.git/`
 
 ifndef::git-clone[]
 These two syntaxes are mostly equivalent, except when cloning, when
@@ -57,11 +57,11 @@ endif::git-clone[]
 accept a suitable bundle file. See linkgit:git-bundle[1].
 
 When Git doesn't know how to handle a certain transport protocol, it
-attempts to use the `remote-`{empty}__<transport>__ remote helper, if one
+attempts to use the s:["remote-<transport>"] remote helper, if one
 exists. To explicitly request a remote helper, the following syntax
 may be used:
 
-- _<transport>_::__<address>__
+- s:["<transport>::<address>"]
 
 where _<address>_ may be a path, a server and path, or an arbitrary
 URL-like string recognized by the specific remote helper being
-- 
gitgitgadget

Re: [PATCH v3 2/3] doc: update the guidelines to reflect the current formatting rules

[Eric Sunshine]

On Sun, Aug 11, 2024 at 11:20 AM Jean-Noël Avila via GitGitGadget
<gitgitgadget@gmail.com> wrote:
> Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
> ---
> diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
> @@ -746,70 +746,72 @@ Markup:
>   When literal and placeholders are mixed, each markup is applied for
> + each sub-entity. If the formatting is becoming too hairy, you can use the
> + s:["foo"] formatting macro and let it format the groups for you.
> +   `--jobs` _<n>_ or s:["--jobs <n>"]
> +   s:["--sort=<key>
> +   s:["<directory>/.git"]
> +   s:["remote.<name>.mirror"]
> +   s:["ssh://[<user>@]<host>[:<port>]/<path-to-git-repo>"]
> +
> +Note that the double-quotes are required by the macro.

The closing `"]` is missing from the --sort example. Is that intentional?

Re: [PATCH v3 2/3] doc: update the guidelines to reflect the current formatting rules

[Jean-Noël Avila]

[-- Attachment #1: Type: text/plain, Size: 922 bytes --]

Le 12/08/2024 à 01:56, Eric Sunshine a écrit :
> On Sun, Aug 11, 2024 at 11:20 AM Jean-Noël Avila via GitGitGadget
> <gitgitgadget@gmail.com> wrote:
>> Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
>> ---
>> diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
>> @@ -746,70 +746,72 @@ Markup:
>>   When literal and placeholders are mixed, each markup is applied for
>> + each sub-entity. If the formatting is becoming too hairy, you can use the
>> + s:["foo"] formatting macro and let it format the groups for you.
>> +   `--jobs` _<n>_ or s:["--jobs <n>"]
>> +   s:["--sort=<key>
>> +   s:["<directory>/.git"]
>> +   s:["remote.<name>.mirror"]
>> +   s:["ssh://[<user>@]<host>[:<port>]/<path-to-git-repo>"]
>> +
>> +Note that the double-quotes are required by the macro.
> 
> The closing `"]` is missing from the --sort example. Is that intentional?

Not at all. Will fix it.

Thanks


[-- Attachment #2: jean-noel_avila.vcf --]
[-- Type: text/vcard, Size: 464 bytes --]

begin:vcard
fn;quoted-printable:Jean-No=C3=ABl Avila
n;quoted-printable:Avila;Jean-No=C3=ABl
org:Scantech S.A.
adr;quoted-printable:Savoie Technolac BP 244;;B=C3=A2timent Androm=C3=A8de - 108 Avenue du Lac L=C3=A9man ; LA MOTTE SERVOLEX;;73290;France
email;internet:jean-noel.avila@scantech.com
title:Embedded systems manager
tel;work:+33 479 25 54 50
tel;cell:+33 633 04 64 18
x-mozilla-html:FALSE
url:http://www.scantech.com
version:2.1
end:vcard

Re: [PATCH v3 0/3] doc: introducing synopsis para

[Junio C Hamano]

"Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com> writes:

> 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

This topic has become quiet.  I still find s:["someything you really
want to say"] notation a bit annoying to my eyes, but its may be the
best compromise we can come up with.

So unless we have a strong objection, or (even better) an objection
with an alternative that is less yucky, perhaps it is time to
declare that this is the variant of AsciiDoc/Asciidoctor that we'd
adopt for our documentation.  Comments?

Thanks.

Re: [PATCH v3 0/3] doc: introducing synopsis para

[Jean-Noël AVILA]

Le lundi 19 août 2024, 22:08:19 CEST Junio C Hamano a écrit :
> "Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com> writes:
> 
> > 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
> 
> This topic has become quiet.  I still find s:["someything you really
> want to say"] notation a bit annoying to my eyes, but its may be the
> best compromise we can come up with.
> 
> So unless we have a strong objection, or (even better) an objection
> with an alternative that is less yucky, perhaps it is time to
> declare that this is the variant of AsciiDoc/Asciidoctor that we'd
> adopt for our documentation.  Comments?
> 
> Thanks.
> 

I understand that you are reluctant to include a change that, as the 
maintainer, you do not feel comfortable  keeping alive. 

The whole discussion thread tells me that other developers are not ready to go 
down the "full markup" path. Understandably, this makes it more difficult for 
everyone to propose changes and review them, as there's no tool to track such 
formatting errors and we have to rely on careful manual cross-checking.

I would like to thank you for pushing so that the markup can be simplified as 
much as can be. It can be simplified further one step further: it is possible 
both in asciidoc/asciidoctor to override the formatting of inline verbatim 
texts, so that everything that is backquoted is processed as a synopsis 
string. 
This way, strings like

`<commit>`
`diff.statGraphWidth=<width>`
` --dirstat-by-file[=<param>,...]`

are automatically rendered with the expected styles.

However, contrary to the s macro, this is quite disruptive as it forces the 
new processing on all existing manpages. Another drawback is that it is no 
longer genuine asciidoc, but it seems more in line with the critics. I'm 
refining the regexp at the moment to check for side-effects.

Is this proposition more appropriate?

Re: [PATCH v3 0/3] doc: introducing synopsis para

[Junio C Hamano]

Jean-Noël AVILA <jn.avila@free.fr> writes:

> ... It can be simplified further one step further: it is possible 
> both in asciidoc/asciidoctor to override the formatting of inline verbatim 
> texts, so that everything that is backquoted is processed as a synopsis 
> string. 
> This way, strings like
>
> `<commit>`
> `diff.statGraphWidth=<width>`
> ` --dirstat-by-file[=<param>,...]`
>
> are automatically rendered with the expected styles.
>
> However, contrary to the s macro, this is quite disruptive as it forces the 
> new processing on all existing manpages. Another drawback is that it is no 
> longer genuine asciidoc, but it seems more in line with the critics. I'm 
> refining the regexp at the moment to check for side-effects.
>
> Is this proposition more appropriate?

Thanks for thinking these things through.  The fact that such a
"magic" processing will hide the gory details from those whose
primary interest is to describe the commands and their options cuts
both ways.  It is a very welcome thing for developers around here, I
would assume.  At the same time, I can understand that purists would
find it unacceptably ugly, as `backticks` is now much more than a
mark-up that means "this text is typeset in monospace".  Inside it,
<text inside angle brackets>, [optional text], and (choices), all
signal that they have special meaning by being typeset differently.

I do not personally mind that, and I would even dream about a future
in which other projects notice what you did to AsciiDoctor, love it,
adopt it, and eventually it feeds back to improve AsciiDoctor proper.

It is very likely that is because I haven't seen any "side effects"
yet ;-)

Thanks.

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

[Jean-Noël Avila via GitGitGadget]

In the continuation of the simplification of manpage editing, the synopsis
processing that was developed for synopsis paragraph style is also applied
to all inline backquoted texts.

Refining the magic regexp took more time than expected, but this one should
really enhance writers'experience. I had to fight a bit more with
asciidoctor, due to discrepancies between version 2.0 on my laptop and the
1.5.6 used by Github actions.

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

Changes since V2:

 * introduce the s macro to freely apply synopsis styling wherever needed,
   without formatting hassle.

Changes since V3:

 * replace s macro by direct processing of literal text at the level of
   output processors.

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

 Documentation/CodingGuidelines          | 58 +++++++++--------
 Documentation/asciidoc.conf             | 20 ++++++
 Documentation/asciidoctor-extensions.rb | 87 +++++++++++++++++++++++++
 Documentation/git-clone.txt             | 78 +++++++++++-----------
 Documentation/git-init.txt              | 35 +++++-----
 Documentation/urls.txt                  | 26 ++++----
 ci/install-dependencies.sh              |  1 +
 t/t0450-txt-doc-vs-help.sh              | 11 ++--
 8 files changed, 209 insertions(+), 107 deletions(-)


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

Range-diff vs v3:

 1:  0d7c1dd8f26 ! 1:  c09968d7ccb doc: introduce a synopsis custom paragraph attribute
     @@ Metadata
      Author: Jean-Noël Avila <jn.avila@free.fr>
      
       ## Commit message ##
     -    doc: introduce a synopsis custom paragraph attribute
     +    doc: introduce a synopsis typesetting
      
          In order to follow the common manpage usage, the synopsis of the
          commands needs to be heavily typeset. A first try was performed with
     @@ Commit message
      
          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.
     -
     -    additionally, a 's' macro ('s' standing for synopsis) is introduced to
     -    allow writers to freely apply automatic styling whereever required.
     +    created and the processor for backticked text are modified. The
     +    backends of asciidoc and asciidoctor take in charge to correctly add
     +    the required typesetting.
      
          Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
      
       ## Documentation/asciidoc.conf ##
     -@@
     - 
     - [macros]
     - (?su)[\\]?(?P<name>linkgit):(?P<target>\S*?)\[(?P<attrlist>.*?)\]=
     --
     -+(?su)[\\]?(?P<name>s):(?P<target>\S*?)\["(?P<attrlist>.*?)"\]=
     - [attributes]
     - asterisk=&#42;
     - plus=&#43;
      @@ Documentation/asciidoc.conf: ifdef::backend-docbook[]
       {0#<citerefentry>}
       {0#<refentrytitle>{target}</refentrytitle><manvolnum>{0}</manvolnum>}
       {0#</citerefentry>}
      +
     -+[s-inlinemacro]
     -+{eval:re.sub(r'(&lt;[-a-zA-Z0-9.]+&gt;)', r'<emphasis>\1</emphasis>', re.sub(r'([\[ |()>]|^|\]|&gt;)(\.?[-a-zA-Z0-9:+=~@,\/]+\.?)',r'\1<literal>\2</literal>', '{attrlist}'))}
     ++[literal-inlinemacro]
     ++{eval:re.sub(r'(&lt;[-a-zA-Z0-9.]+&gt;)', r'<emphasis>\1</emphasis>', re.sub(r'([\[\s|()>]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@,\/_^\$]+\.?)+)',r'\1<literal>\2</literal>', re.sub(r'(\.\.\.?)([^\]$.])', r'<literal>\1</literal>\2', macros.passthroughs[int(attrs['passtext'][1:-1])] if attrs['passtext'][1:-1].isnumeric() else attrs['passtext'][1:-1])))}
     ++
       endif::backend-docbook[]
       
       ifdef::backend-docbook[]
     @@ Documentation/asciidoc.conf: ifdef::backend-xhtml11[]
       [linkgit-inlinemacro]
       <a href="{git-relative-html-prefix}{target}.html">{target}{0?({0})}</a>
      +
     -+[s-inlinemacro]
     -+{eval:re.sub(r'(&lt;[-a-zA-Z0-9.]+&gt;)', r'<em>\1</em>', re.sub(r'([\[ |()>]|^|\]|&gt;)(\.?[-=a-zA-Z0-9:+,@]+\.?)',r'\1<code>\2</code>', '{attrlist}'))}
     ++[literal-inlinemacro]
     ++{eval:re.sub(r'(&lt;[-a-zA-Z0-9.]+&gt;)', r'<em>\1</em>', re.sub(r'([\[\s|()>]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@,\/_^\$]+\.?)+)',r'\1<code>\2</code>', re.sub(r'(\.\.\.?)([^\]$.])', r'<code>\1</code>\2', macros.passthroughs[int(attrs['passtext'][1:-1])] if attrs['passtext'][1:-1].isnumeric() else attrs['passtext'][1:-1])))}
      +
      +endif::backend-xhtml11[]
      +
      +ifdef::backend-docbook[]
      +ifdef::doctype-manpage[]
      +[paradef-default]
     -+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'"
     ++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="sed -E 's!([\[ |()>]|^|\])(\.?[-=a-zA-Z0-9:+@]+\.?)!\\1<code>\\2</code>!g;s!&lt;[-a-zA-Z0-9.]+&gt;!<em>\\0</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
     -       end
     -     end
     +@@
     + require 'asciidoctor'
     + require 'asciidoctor/extensions'
     ++require 'asciidoctor/converter/docbook5'
     ++require 'asciidoctor/converter/html5'
       
     -+    class SynopsisMacroProcessor < Asciidoctor::Extensions::InlineMacroProcessor
     -+      use_dsl
     -+
     -+      named :s
     -+      match(/s:\["(.+?)"\]/)
     -+
     -+      def process(parent, target, attrs)
     -+        l = target.gsub(/([\[\] |()]|^|&gt;)(\.?[-a-zA-Z0-9:+=~@,\/]+\.?)/, '\1{empty}`\2`{empty}')
     -+                  .gsub(/(&lt;[-a-zA-Z0-9.]+&gt;)/, '__\\1__')
     -+                  .gsub(']', ']{empty}')
     -+
     -+        create_inline parent, :quoted, l, attributes: { 'subs' => :normal }
     -+      end
     -+    end
     -+
     -     class DocumentPostProcessor < Asciidoctor::Extensions::Postprocessor
     -       def process document, output
     -         if document.basebackend? 'docbook'
     + module Git
     +   module Documentation
      @@ Documentation/asciidoctor-extensions.rb: module Git
               output
             end
     @@ 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}')
     ++          l.gsub(/(\.\.\.?)([^\]$.])/, '`\1`\2')
     ++           .gsub(%r{([\[\] |()>]|^)([-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
     ++
     ++    class GitDBConverter < Asciidoctor::Converter::DocBook5Converter
     ++
     ++      extend Asciidoctor::Converter::Config
     ++      register_for 'docbook5'
     ++
     ++      def convert_inline_quoted node
     ++        if (type = node.type) == :asciimath
     ++          # NOTE fop requires jeuclid to process mathml markup
     ++          asciimath_available? ? %(<inlineequation>#{(::AsciiMath.parse node.text).to_mathml 'mml:', 'xmlns:mml' => 'http://www.w3.org/1998/Math/MathML'}</inlineequation>) : %(<inlineequation><mathphrase><![CDATA[#{node.text}]]></mathphrase></inlineequation>)
     ++        elsif type == :latexmath
     ++          # unhandled math; pass source to alt and required mathphrase element; dblatex will process alt as LaTeX math
     ++          %(<inlineequation><alt><![CDATA[#{equation = node.text}]]></alt><mathphrase><![CDATA[#{equation}]]></mathphrase></inlineequation>)
     ++        elsif type == :monospaced
     ++          node.text.gsub(/(\.\.\.?)([^\]$.])/, '<literal>\1</literal>\2')
     ++              .gsub(%r{([\[\s|()>.]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@,/_^\$]+\.{0,2})+)}, '\1<literal>\2</literal>')
     ++              .gsub(/(&lt;[-a-zA-Z0-9.]+&gt;)/, '<emphasis>\1</emphasis>')
     ++        else
     ++          open, close, supports_phrase = QUOTE_TAGS[type]
     ++          text = node.text
     ++          if node.role
     ++            if supports_phrase
     ++              quoted_text = %(#{open}<phrase role="#{node.role}">#{text}</phrase>#{close})
     ++            else
     ++              quoted_text = %(#{open.chop} role="#{node.role}">#{text}#{close})
     ++            end
     ++          else
     ++            quoted_text = %(#{open}#{text}#{close})
     ++          end
     ++          node.id ? %(<anchor#{common_attributes node.id, nil, text}/>#{quoted_text}) : quoted_text
     ++        end
     ++      end
     ++    end
     ++
     ++    # register a html5 converter that takes in charge to convert monospaced text into Git style synopsis
     ++    class GitHTMLConverter < Asciidoctor::Converter::Html5Converter
     ++
     ++      extend Asciidoctor::Converter::Config
     ++      register_for 'html5'
     ++
     ++      def convert_inline_quoted node
     ++        if node.type == :monospaced
     ++          node.text.gsub(/(\.\.\.?)([^\]$.])/, '<code>\1</code>\2')
     ++              .gsub(%r{([\[\s|()>.]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@,/_^\$]+\.{0,2})+)}, '\1<code>\2</code>')
     ++              .gsub(/(&lt;[-a-zA-Z0-9.]+&gt;)/, '<em>\1</em>')
     ++
     ++        else
     ++          open, close, tag = QUOTE_TAGS[node.type]
     ++          if node.id
     ++            class_attr = node.role ? %( class="#{node.role}") : ''
     ++            if tag
     ++              %(#{open.chop} id="#{node.id}"#{class_attr}>#{node.text}#{close})
     ++            else
     ++              %(<span id="#{node.id}"#{class_attr}>#{open}#{node.text}#{close}</span>)
     ++            end
     ++          elsif node.role
     ++            if tag
     ++              %(#{open.chop} class="#{node.role}">#{node.text}#{close})
     ++            else
     ++              %(<span class="#{node.role}">#{open}#{node.text}#{close}</span>)
     ++            end
     ++          else
     ++            %(#{open}#{node.text}#{close})
     ++          end
     ++        end
     ++      end
      +    end
         end
       end
       
       Asciidoctor::Extensions.register do
         inline_macro Git::Documentation::LinkGitProcessor, :linkgit
     -+  inline_macro Git::Documentation::SynopsisMacroProcessor
      +  block Git::Documentation::SynopsisBlock
         postprocessor Git::Documentation::DocumentPostProcessor
       end
      
     + ## ci/install-dependencies.sh ##
     +@@ ci/install-dependencies.sh: Documentation)
     + 
     + 	test -n "$ALREADY_HAVE_ASCIIDOCTOR" ||
     + 	sudo gem install --version 1.5.8 asciidoctor
     ++	sudo gem install concurrent-ruby
     + 	;;
     + esac
     + 
     +
       ## t/t0450-txt-doc-vs-help.sh ##
      @@ t/t0450-txt-doc-vs-help.sh: txt_to_synopsis () {
       	fi &&
 2:  92f3121cf4e ! 2:  c48649ccd63 doc: update the guidelines to reflect the current formatting rules
     @@ Commit message
      
       ## Documentation/CodingGuidelines ##
      @@ Documentation/CodingGuidelines: Markup:
     +    _<new-branch-name>_
     +    _<template-directory>_
     + 
     +- A placeholder is not enclosed in backticks, as it is not a literal.
     +-
     +  When needed, use a distinctive identifier for placeholders, usually
     +  made of a qualification and a type:
     +    _<git-dir>_
          _<key-id>_
       
     -  When literal and placeholders are mixed, each markup is applied for
     +- When literal and placeholders are mixed, each markup is applied for
      - each sub-entity. If they are stuck, a special markup, called
      - unconstrained formatting is required.
      - Unconstrained formating for placeholders is __<like-this>__
     @@ Documentation/CodingGuidelines: Markup:
      -   ++--sort=++__<key>__
      -   __<directory>__++/.git++
      -   ++remote.++__<name>__++.mirror++
     --
     ++ Git's Asciidoc processor has been tailored to treat backticked text
     ++ as complex synopsis. When literal and placeholders are mixed, you can
     ++ use the backtick notation which will take care of correctly typesetting
     ++ the content.
     ++   `--jobs <n>`
     ++   `--sort=<key>`
     ++   `<directory>/.git`
     ++   `remote.<name>.mirror`
     ++   `ssh://[<user>@]<host>[:<port>]/<path-to-git-repo>`
     + 
      - caveat: ++ unconstrained format is not verbatim and may expand
      - content. Use Asciidoc escapes inside them.
     -+ each sub-entity. If the formatting is becoming too hairy, you can use the
     -+ s:["foo"] formatting macro and let it format the groups for you.
     -+   `--jobs` _<n>_ or s:["--jobs <n>"]
     -+   s:["--sort=<key>
     -+   s:["<directory>/.git"]
     -+   s:["remote.<name>.mirror"]
     -+   s:["ssh://[<user>@]<host>[:<port>]/<path-to-git-repo>"]
     -+
     -+Note that the double-quotes are required by the macro.
     ++As a side effect, backquoted placeholders are correctly typeset, but
     ++this style is not recommended.
       
       Synopsis Syntax
       
 3:  02406b91894 ! 3:  719188da711 doc: apply synopsis simplification on git-clone and git-init
     @@ Documentation/git-clone.txt: git-clone - Clone a repository into a new directory
       
       DESCRIPTION
       -----------
     +@@ Documentation/git-clone.txt: OPTIONS
     + 	to save space when possible.
     + +
     + If the repository is specified as a local path (e.g., `/path/to/repo`),
     +-this is the default, and --local is essentially a no-op.  If the
     ++this is the default, and `--local` is essentially a no-op.  If the
     + repository is specified as a URL, then this flag is ignored (and we
     + never use the local optimizations).  Specifying `--no-local` will
     + override the default when `/path/to/repo` is given, using the regular
      @@ Documentation/git-clone.txt: prevent the unintentional copying of files by dereferencing the symbolic
       links.
       +
       *NOTE*: this operation can race with concurrent modification to the
      -source repository, similar to running `cp -r src dst` while modifying
      -`src`.
     -+source repository, similar to running s:["cp -r <src> <dst>"] while modifying
     ++source repository, similar to running `cp -r <src> <dst>` while modifying
      +_<src>_.
       
       `--no-hardlinks`::
     @@ Documentation/git-clone.txt: If you want to break the dependency of a repository
       objects from the source repository into a pack in the cloned repository.
       
      -`--reference`[`-if-able`] _<repository>_::
     -+s:["--reference[-if-able] <repository>"]::
     ++`--reference[-if-able] <repository>`::
       	If the reference _<repository>_ is on the local machine,
       	automatically setup `.git/objects/info/alternates` to
       	obtain objects from the reference _<repository>_.  Using
     @@ Documentation/git-clone.txt: objects from the source repository into a pack in t
       	standard error stream is not directed to a terminal.
       
      -++--server-option=++__<option>__::
     -+s:["--server-option=<option>"]::
     ++`--server-option=<option>`::
       	Transmit the given string to the server when communicating using
       	protocol version 2.  The given string must not contain a NUL or LF
       	character.  The server's handling of server options, including
       	unknown ones, is server-specific.
      -	When multiple ++--server-option=++__<option>__ are given, they are all
     -+	When multiple s:["--server-option=<option>"] are given, they are all
     ++	When multiple `--server-option=<option>` are given, they are all
       	sent to the other side in the order listed on the command line.
       
       `-n`::
     @@ Documentation/git-clone.txt: objects from the source repository into a pack in t
       	Make a 'bare' Git repository.  That is, instead of
       	creating _<directory>_ and placing the administrative
      -	files in _<directory>_`/.git`, make the _<directory>_
     -+	files in s:["<directory>/.git"], make the _<directory>_
     ++	files in `<directory>/.git`, make the _<directory>_
       	itself the `$GIT_DIR`. This obviously implies the `--no-checkout`
       	because there is nowhere to check out the working tree.
       	Also the branch heads at the remote are copied directly
     @@ Documentation/git-clone.txt: objects from the source repository into a pack in t
       	working directory as needed.
       
      -++--filter=++__<filter-spec>__::
     -+s:["--filter=<filter-spec>"]::
     ++`--filter=<filter-spec>`::
       	Use the partial clone feature and request that the server sends
       	a subset of reachable objects according to a given object filter.
       	When using `--filter`, the supplied _<filter-spec>_ is used for
       	the partial clone filter. For example, `--filter=blob:none` will
       	filter out all blobs (file contents) until needed by Git. Also,
      -	++--filter=blob:limit=++__<size>__ will filter out all blobs of size
     -+	s:["--filter=blob:limit=<size>"] will filter out all blobs of size
     ++	`--filter=blob:limit=<size>` will filter out all blobs of size
       	at least _<size>_. For more details on filter specifications, see
       	the `--filter` option in linkgit:git-rev-list[1].
       
     @@ Documentation/git-clone.txt: objects from the source repository into a pack in t
       	run on the other end.
       
      -++--template=++__<template-directory>__::
     -+s:["--template=<template-directory>"]::
     ++`--template=<template-directory>`::
       	Specify the directory from which templates will be used;
       	(See the "TEMPLATE DIRECTORY" section of linkgit:git-init[1].)
       
      -`-c` __<key>__++=++__<value>__::
      -`--config` __<key>__++=++__<value>__::
     -+`-c` s:["<key>=<value>"]::
     -+`--config` s:["<key>=<value>"]::
     ++`-c` `<key>=<value>`::
     ++`--config` `<key>=<value>`::
       	Set a configuration variable in the newly-created repository;
       	this takes effect immediately after the repository is
       	initialized, but before the remote history is fetched or any
     @@ Documentation/git-clone.txt: objects from the source repository into a pack in t
       variables do not take effect until after the initial fetch and checkout.
       Configuration variables known to not take effect are:
      -++remote.++__<name>__++.mirror++ and ++remote.++__<name>__++.tagOpt++.  Use the
     -+s:["remote.<name>.mirror"] and s:["remote.<name>.tagOpt"].  Use the
     ++`remote.<name>.mirror` and `remote.<name>.tagOpt`.  Use the
       corresponding `--mirror` and `--no-tags` options instead.
       
      -`--depth` _<depth>_::
     -+s:["--depth <depth>"]::
     ++`--depth <depth>`::
       	Create a 'shallow' clone with a history truncated to the
       	specified number of commits. Implies `--single-branch` unless
       	`--no-single-branch` is given to fetch the histories near the
     @@ Documentation/git-clone.txt: objects from the source repository into a pack in t
       	also pass `--shallow-submodules`.
       
      -++--shallow-since=++__<date>__::
     -+s:["--shallow-since=<date>"]::
     ++`--shallow-since=<date>`::
       	Create a shallow clone with a history after the specified time.
       
      -++--shallow-exclude=++__<revision>__::
     -+s:["--shallow-exclude=<revision>"]::
     ++`--shallow-exclude=<revision>`::
       	Create a shallow clone with a history, excluding commits
       	reachable from a specified remote branch or tag.  This option
       	can be specified multiple times.
       
      -`--`[`no-`]`single-branch`::
     -+s:["--[no-]single-branch"]::
     ++`--[no-]single-branch`::
       	Clone only the history leading to the tip of a single branch,
       	either specified by the `--branch` option or the primary
       	branch remote's `HEAD` points at.
     -@@ Documentation/git-clone.txt: corresponding `--mirror` and `--no-tags` options instead.
     - 
     - `--no-tags`::
     - 	Don't clone any tags, and set
     --	`remote.<remote>.tagOpt=--no-tags` in the config, ensuring
     -+	s:["remote.<remote>.tagOpt=--no-tags"] in the config, ensuring
     - 	that future `git pull` and `git fetch` operations won't follow
     - 	any tags. Subsequent explicit tag fetches will still work,
     - 	(see linkgit:git-fetch[1]).
      @@ Documentation/git-clone.txt: maintain a branch with no references other than a single cloned
       branch. This is useful e.g. to maintain minimal clones of the default
       branch of some repository for search indexing.
       
      -`--recurse-submodules`[`=`{empty}__<pathspec>__]::
     -+s:["--recurse-submodules[=<pathspec>]"]::
     ++`--recurse-submodules[=<pathspec>]`::
       	After the clone is created, initialize and clone submodules
     - 	within based on the provided _<pathspec>_.  If no _=<pathspec>_ is
     +-	within based on the provided _<pathspec>_.  If no _=<pathspec>_ is
     ++	within based on the provided _<pathspec>_.  If no `=<pathspec>` is
       	provided, all submodules are initialized and cloned.
     -@@ Documentation/git-clone.txt: branch of some repository for search indexing.
     + 	This option can be given multiple times for pathspecs consisting
     + 	of multiple entries.  The resulting clone has `submodule.active` set to
     +-	the provided pathspec, or "." (meaning all submodules) if no
     ++	the provided pathspec, or "`.`" (meaning all submodules) if no
     + 	pathspec is provided.
       +
       Submodules are initialized and cloned using their default settings. This is
     - equivalent to running
     --`git submodule update --init --recursive <pathspec>` immediately after
     -+s:["git submodule update --init --recursive <pathspec>"] immediately after
     - the clone is finished. This option is ignored if the cloned repository does
     +@@ Documentation/git-clone.txt: the clone is finished. This option is ignored if the cloned repository does
       not have a worktree/checkout (i.e. if any of `--no-checkout`/`-n`, `--bare`,
       or `--mirror` is given)
       
      -`--`[`no-`]`shallow-submodules`::
     -+s:["--[no-]shallow-submodules"]::
     ++`--[no-]shallow-submodules`::
       	All submodules which are cloned will be shallow with a depth of 1.
       
      -`--`[`no-`]`remote-submodules`::
     -+s:["--[no-]remote-submodules"]::
     ++`--[no-]remote-submodules`::
       	All submodules which are cloned will use the status of the submodule's
       	remote-tracking branch to update the submodule, rather than the
       	superproject's recorded SHA-1. Equivalent to passing `--remote` to
       	`git submodule update`.
       
      -`--separate-git-dir=`{empty}__<git-dir>__::
     -+s:["--separate-git-dir=<git-dir>"]::
     ++`--separate-git-dir=<git-dir>`::
       	Instead of placing the cloned repository where it is supposed
       	to be, place the cloned repository at the specified directory,
       	then make a filesystem-agnostic Git symbolic link to there.
     @@ Documentation/git-clone.txt: branch of some repository for search indexing.
       	tree.
       
      -`--ref-format=`{empty}__<ref-format>__::
     -+s:["--ref-format=<ref-format>"]::
     ++`--ref-format=<ref-format>`::
       
       Specify the given ref storage format for the repository. The valid values are:
       +
     @@ Documentation/git-clone.txt: _<directory>_::
       	is only allowed if the directory is empty.
       
      -`--bundle-uri=`{empty}__<uri>__::
     -+s:["--bundle-uri=<uri>"]::
     ++`--bundle-uri=<uri>`::
       	Before fetching from the remote, fetch a bundle from the given
       	_<uri>_ and unbundle the data into the local repository. The refs
       	in the bundle will be stored under the hidden `refs/bundle/*`
     @@ Documentation/git-init.txt: Only print error and warning messages; all other out
       
      -++--object-format=++__<format>__::
      -
     -+s:["--object-format=<format>"]::
     ++`--object-format=<format>`::
       Specify the given object _<format>_ (hash algorithm) for the repository.  The valid
       values are `sha1` and (if enabled) `sha256`.  `sha1` is the default.
       +
     @@ Documentation/git-init.txt: Only print error and warning messages; all other out
       
      -++--ref-format=++__<format>__::
      -
     -+s:["--ref-format=<format>"]::
     ++`--ref-format=<format>`::
       Specify the given ref storage _<format>_ for the repository. The valid values are:
       +
       include::ref-storage-format.txt[]
       
      -++--template=++__<template-directory>__::
      -
     -+s:["--template=<template-directory>"]::
     ++`--template=<template-directory>`::
       Specify the directory from which templates will be used.  (See the "TEMPLATE
       DIRECTORY" section below.)
       
      -++--separate-git-dir=++__<git-dir>__::
      -
     -+s:["--separate-git-dir=<git-dir>"]::
     ++`--separate-git-dir=<git-dir>`::
       Instead of initializing the repository as a directory to either `$GIT_DIR` or
       `./.git/`, create a text file there containing the path to the actual
       repository.  This file acts as a filesystem-agnostic Git symbolic link to the
      @@ Documentation/git-init.txt: repository.
     + +
       If this is a reinitialization, the repository will be moved to the specified path.
       
     - `-b` _<branch-name>_::
     +-`-b` _<branch-name>_::
      -++--initial-branch=++__<branch-name>__::
      -
     -+s:["--initial-branch=<branch-name>"]::
     ++`-b <branch-name>`::
     ++`--initial-branch=<branch-name>`::
       Use _<branch-name>_ for the initial branch in the newly created
       repository.  If not specified, fall back to the default name (currently
       `master`, but this is subject to change in the future; the name can be
       customized via the `init.defaultBranch` configuration variable).
       
      -++--shared++[++=++(`false`|`true`|`umask`|`group`|`all`|`world`|`everybody`|_<perm>_)]::
     -+s:["--shared[=(false|true|umask|group|all|world|everybody|<perm>)]"]::
     ++`--shared[=(false|true|umask|group|all|world|everybody|<perm>)]`::
       
       Specify that the Git repository is to be shared amongst several users.  This
       allows users belonging to the same group to push into that
     @@ Documentation/urls.txt: Git supports ssh, git, http, and https protocols (in add
      -- ++git://++__<host>__{startsb}:__<port>__{endsb}++/++__<path-to-git-repo>__
      -- ++http++{startsb}++s++{endsb}++://++__<host>__{startsb}++:++__<port>__{endsb}++/++__<path-to-git-repo>__
      -- ++ftp++{startsb}++s++{endsb}++://++__<host>__{startsb}++:++__<port>__{endsb}++/++__<path-to-git-repo>__
     -+- s:["ssh://[<user>@]<host>[:<port>]/<path-to-git-repo>"]
     -+- s:["git://<host>[:<port>]/<path-to-git-repo>"]
     -+- s:["http[s]://<host>[:<port>]/<path-to-git-repo>"]
     -+- s:["ftp[s]://<host>[:<port>]/<path-to-git-repo>"]
     ++- `ssh://[<user>@]<host>[:<port>]/<path-to-git-repo>`
     ++- `git://<host>[:<port>]/<path-to-git-repo>`
     ++- `http[s]://<host>[:<port>]/<path-to-git-repo>`
     ++- `ftp[s]://<host>[:<port>]/<path-to-git-repo>`
       
       An alternative scp-like syntax may also be used with the ssh protocol:
       
      -- {startsb}__<user>__++@++{endsb}__<host>__++:/++__<path-to-git-repo>__
     -+- s:["[<user>@]<host>:/<path-to-git-repo>"]
     ++- `[<user>@]<host>:/<path-to-git-repo>`
       
       This syntax is only recognized if there are no slashes before the
       first colon. This helps differentiate a local path that contains a
     @@ Documentation/urls.txt: colon. For example the local path `foo:bar` could be spe
       url.
       
      -The ssh and git protocols additionally support ++~++__<username>__ expansion:
     -+The ssh and git protocols additionally support s:["~<username>"] expansion:
     ++The ssh and git protocols additionally support `~<username>` expansion:
       
      -- ++ssh://++{startsb}__<user>__++@++{endsb}__<host>__{startsb}++:++__<port>__{endsb}++/~++__<user>__++/++__<path-to-git-repo>__
      -- ++git://++__<host>__{startsb}++:++__<port>__{endsb}++/~++__<user>__++/++__<path-to-git-repo>__
      -- {startsb}__<user>__++@++{endsb}__<host>__++:~++__<user>__++/++__<path-to-git-repo>__
     -+- s:["ssh://[<user>@]<host>[:<port>]/~<user>/<path-to-git-repo>"]
     -+- s:["git://<host>[:<port>]/~<user>/<path-to-git-repo>"]
     -+- s:["[<user>@]<host>:~<user>/<path-to-git-repo>"]
     ++- `ssh://[<user>@]<host>[:<port>]/~<user>/<path-to-git-repo>`
     ++- `git://<host>[:<port>]/~<user>/<path-to-git-repo>`
     ++- `[<user>@]<host>:~<user>/<path-to-git-repo>`
       
       For local repositories, also supported by Git natively, the following
       syntaxes may be used:
     @@ Documentation/urls.txt: endif::git-clone[]
       
       When Git doesn't know how to handle a certain transport protocol, it
      -attempts to use the `remote-`{empty}__<transport>__ remote helper, if one
     -+attempts to use the s:["remote-<transport>"] remote helper, if one
     ++attempts to use the `remote-<transport>` remote helper, if one
       exists. To explicitly request a remote helper, the following syntax
       may be used:
       
      -- _<transport>_::__<address>__
     -+- s:["<transport>::<address>"]
     ++- `<transport>::<address>`
       
       where _<address>_ may be a path, a server and path, or an arbitrary
       URL-like string recognized by the specific remote helper being

-- 
gitgitgadget

[PATCH v4 1/3] doc: introduce a synopsis typesetting

[Jean-Noël Avila via GitGitGadget]

From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>

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 processor for backticked text are modified. The
backends of asciidoc and asciidoctor take in charge to correctly add
the required typesetting.

Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
---
 Documentation/asciidoc.conf             | 20 ++++++
 Documentation/asciidoctor-extensions.rb | 87 +++++++++++++++++++++++++
 ci/install-dependencies.sh              |  1 +
 t/t0450-txt-doc-vs-help.sh              | 11 ++--
 4 files changed, 112 insertions(+), 7 deletions(-)

diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf
index 60f76f43eda..75ae9f3da92 100644
--- a/Documentation/asciidoc.conf
+++ b/Documentation/asciidoc.conf
@@ -28,6 +28,10 @@ ifdef::backend-docbook[]
 {0#<citerefentry>}
 {0#<refentrytitle>{target}</refentrytitle><manvolnum>{0}</manvolnum>}
 {0#</citerefentry>}
+
+[literal-inlinemacro]
+{eval:re.sub(r'(&lt;[-a-zA-Z0-9.]+&gt;)', r'<emphasis>\1</emphasis>', re.sub(r'([\[\s|()>]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@,\/_^\$]+\.?)+)',r'\1<literal>\2</literal>', re.sub(r'(\.\.\.?)([^\]$.])', r'<literal>\1</literal>\2', macros.passthroughs[int(attrs['passtext'][1:-1])] if attrs['passtext'][1:-1].isnumeric() else attrs['passtext'][1:-1])))}
+
 endif::backend-docbook[]
 
 ifdef::backend-docbook[]
@@ -56,4 +60,20 @@ ifdef::backend-xhtml11[]
 git-relative-html-prefix=
 [linkgit-inlinemacro]
 <a href="{git-relative-html-prefix}{target}.html">{target}{0?({0})}</a>
+
+[literal-inlinemacro]
+{eval:re.sub(r'(&lt;[-a-zA-Z0-9.]+&gt;)', r'<em>\1</em>', re.sub(r'([\[\s|()>]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@,\/_^\$]+\.?)+)',r'\1<code>\2</code>', re.sub(r'(\.\.\.?)([^\]$.])', r'<code>\1</code>\2', macros.passthroughs[int(attrs['passtext'][1:-1])] if attrs['passtext'][1:-1].isnumeric() else attrs['passtext'][1:-1])))}
+
+endif::backend-xhtml11[]
+
+ifdef::backend-docbook[]
+ifdef::doctype-manpage[]
+[paradef-default]
+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="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[]
diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb
index d906a008039..cb24480b63d 100644
--- a/Documentation/asciidoctor-extensions.rb
+++ b/Documentation/asciidoctor-extensions.rb
@@ -1,5 +1,7 @@
 require 'asciidoctor'
 require 'asciidoctor/extensions'
+require 'asciidoctor/converter/docbook5'
+require 'asciidoctor/converter/html5'
 
 module Git
   module Documentation
@@ -39,10 +41,95 @@ 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(/(\.\.\.?)([^\]$.])/, '`\1`\2')
+           .gsub(%r{([\[\] |()>]|^)([-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
+
+    class GitDBConverter < Asciidoctor::Converter::DocBook5Converter
+
+      extend Asciidoctor::Converter::Config
+      register_for 'docbook5'
+
+      def convert_inline_quoted node
+        if (type = node.type) == :asciimath
+          # NOTE fop requires jeuclid to process mathml markup
+          asciimath_available? ? %(<inlineequation>#{(::AsciiMath.parse node.text).to_mathml 'mml:', 'xmlns:mml' => 'http://www.w3.org/1998/Math/MathML'}</inlineequation>) : %(<inlineequation><mathphrase><![CDATA[#{node.text}]]></mathphrase></inlineequation>)
+        elsif type == :latexmath
+          # unhandled math; pass source to alt and required mathphrase element; dblatex will process alt as LaTeX math
+          %(<inlineequation><alt><![CDATA[#{equation = node.text}]]></alt><mathphrase><![CDATA[#{equation}]]></mathphrase></inlineequation>)
+        elsif type == :monospaced
+          node.text.gsub(/(\.\.\.?)([^\]$.])/, '<literal>\1</literal>\2')
+              .gsub(%r{([\[\s|()>.]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@,/_^\$]+\.{0,2})+)}, '\1<literal>\2</literal>')
+              .gsub(/(&lt;[-a-zA-Z0-9.]+&gt;)/, '<emphasis>\1</emphasis>')
+        else
+          open, close, supports_phrase = QUOTE_TAGS[type]
+          text = node.text
+          if node.role
+            if supports_phrase
+              quoted_text = %(#{open}<phrase role="#{node.role}">#{text}</phrase>#{close})
+            else
+              quoted_text = %(#{open.chop} role="#{node.role}">#{text}#{close})
+            end
+          else
+            quoted_text = %(#{open}#{text}#{close})
+          end
+          node.id ? %(<anchor#{common_attributes node.id, nil, text}/>#{quoted_text}) : quoted_text
+        end
+      end
+    end
+
+    # register a html5 converter that takes in charge to convert monospaced text into Git style synopsis
+    class GitHTMLConverter < Asciidoctor::Converter::Html5Converter
+
+      extend Asciidoctor::Converter::Config
+      register_for 'html5'
+
+      def convert_inline_quoted node
+        if node.type == :monospaced
+          node.text.gsub(/(\.\.\.?)([^\]$.])/, '<code>\1</code>\2')
+              .gsub(%r{([\[\s|()>.]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@,/_^\$]+\.{0,2})+)}, '\1<code>\2</code>')
+              .gsub(/(&lt;[-a-zA-Z0-9.]+&gt;)/, '<em>\1</em>')
+
+        else
+          open, close, tag = QUOTE_TAGS[node.type]
+          if node.id
+            class_attr = node.role ? %( class="#{node.role}") : ''
+            if tag
+              %(#{open.chop} id="#{node.id}"#{class_attr}>#{node.text}#{close})
+            else
+              %(<span id="#{node.id}"#{class_attr}>#{open}#{node.text}#{close}</span>)
+            end
+          elsif node.role
+            if tag
+              %(#{open.chop} class="#{node.role}">#{node.text}#{close})
+            else
+              %(<span class="#{node.role}">#{open}#{node.text}#{close}</span>)
+            end
+          else
+            %(#{open}#{node.text}#{close})
+          end
+        end
+      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/ci/install-dependencies.sh b/ci/install-dependencies.sh
index 4781cd20bb0..3e3ae39cbb1 100755
--- a/ci/install-dependencies.sh
+++ b/ci/install-dependencies.sh
@@ -107,6 +107,7 @@ Documentation)
 
 	test -n "$ALREADY_HAVE_ASCIIDOCTOR" ||
 	sudo gem install --version 1.5.8 asciidoctor
+	sudo gem install concurrent-ruby
 	;;
 esac
 
diff --git a/t/t0450-txt-doc-vs-help.sh b/t/t0450-txt-doc-vs-help.sh
index 69917d7b845..f99a69ae1b7 100755
--- a/t/t0450-txt-doc-vs-help.sh
+++ b/t/t0450-txt-doc-vs-help.sh
@@ -56,14 +56,11 @@ 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;
-			s/{litdd}/--/g;
-			s/'\''\(git[ a-z-]*\)'\''/\1/g;
+			/^\[(verse|synopsis)\]$/d;
+			s/\{litdd\}/--/g;
+			s/'\''(git[ a-z-]*)'\''/\1/g;
 
 			p;
 		}' \
-- 
gitgitgadget

[PATCH v4 2/3] doc: update the guidelines to reflect the current formatting rules

[Jean-Noël Avila via GitGitGadget]

From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>

Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
---
 Documentation/CodingGuidelines | 58 ++++++++++++++++++----------------
 1 file changed, 30 insertions(+), 28 deletions(-)

diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index ccaea39752c..13cbcf1d7a5 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -820,78 +820,80 @@ Markup:
    _<new-branch-name>_
    _<template-directory>_
 
- A placeholder is not enclosed in backticks, as it is not a literal.
-
  When needed, use a distinctive identifier for placeholders, usually
  made of a qualification and a type:
    _<git-dir>_
    _<key-id>_
 
- When literal and placeholders are mixed, each markup is applied for
- each sub-entity. If they are stuck, a special markup, called
- unconstrained formatting is required.
- Unconstrained formating for placeholders is __<like-this>__
- Unconstrained formatting for literal formatting is ++like this++
-   `--jobs` _<n>_
-   ++--sort=++__<key>__
-   __<directory>__++/.git++
-   ++remote.++__<name>__++.mirror++
+ Git's Asciidoc processor has been tailored to treat backticked text
+ as complex synopsis. When literal and placeholders are mixed, you can
+ use the backtick notation which will take care of correctly typesetting
+ the content.
+   `--jobs <n>`
+   `--sort=<key>`
+   `<directory>/.git`
+   `remote.<name>.mirror`
+   `ssh://[<user>@]<host>[:<port>]/<path-to-git-repo>`
 
- caveat: ++ unconstrained format is not verbatim and may expand
- content. Use Asciidoc escapes inside them.
+As a side effect, backquoted placeholders are correctly typeset, but
+this style is not recommended.
 
 Synopsis Syntax
 
- Syntax grammar is formatted neither as literal nor as placeholder.
+ The synopsis (a paragraph with [synopsis] attribute) is automatically
+ formatted by the toolchain and does not need typesetting.
 
  A few commented examples follow to provide reference when writing or
  modifying command usage strings and synopsis sections in the manual
  pages:
 
  Possibility of multiple occurrences is indicated by three dots:
-   _<file>_...
+   <file>...
    (One or more of <file>.)
 
  Optional parts are enclosed in square brackets:
-   [_<file>_...]
+   [<file>...]
    (Zero or more of <file>.)
 
-   ++--exec-path++[++=++__<path>__]
+ An optional parameter needs to be typeset with unconstrained pairs
+   [<repository>]
+
+   --exec-path[=<path>]
    (Option with an optional argument.  Note that the "=" is inside the
    brackets.)
 
-   [_<patch>_...]
+   [<patch>...]
    (Zero or more of <patch>.  Note that the dots are inside, not
    outside the brackets.)
 
  Multiple alternatives are indicated with vertical bars:
-   [`-q` | `--quiet`]
-   [`--utf8` | `--no-utf8`]
+   [-q | --quiet]
+   [--utf8 | --no-utf8]
 
  Use spacing around "|" token(s), but not immediately after opening or
  before closing a [] or () pair:
-   Do: [`-q` | `--quiet`]
-   Don't: [`-q`|`--quiet`]
+   Do: [-q | --quiet]
+   Don't: [-q|--quiet]
 
  Don't use spacing around "|" tokens when they're used to separate the
  alternate arguments of an option:
-    Do: ++--track++[++=++(`direct`|`inherit`)]`
-    Don't: ++--track++[++=++(`direct` | `inherit`)]
+    Do: --track[=(direct|inherit)]
+    Don't: --track[=(direct | inherit)]
 
  Parentheses are used for grouping:
-   [(_<rev>_ | _<range>_)...]
+   [(<rev>|<range>)...]
    (Any number of either <rev> or <range>.  Parens are needed to make
    it clear that "..." pertains to both <rev> and <range>.)
 
-   [(`-p` _<parent>_)...]
+   [(-p <parent>)...]
    (Any number of option -p, each with one <parent> argument.)
 
-   `git remote set-head` _<name>_ (`-a` | `-d` | _<branch>_)
+   git remote set-head <name> (-a|-d|<branch>)
    (One and only one of "-a", "-d" or "<branch>" _must_ (no square
    brackets) be provided.)
 
  And a somewhat more contrived example:
-   `--diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]`
+   --diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]
    Here "=" is outside the brackets, because "--diff-filter=" is a
    valid usage.  "*" has its own pair of brackets, because it can
    (optionally) be specified only when one or more of the letters is
-- 
gitgitgadget

[PATCH v4 3/3] doc: apply synopsis simplification on git-clone and git-init

[Jean-Noël Avila via GitGitGadget]

From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>

With the new synopsis formatting backend, no special asciidoc markup
is needed.

Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
---
 Documentation/git-clone.txt | 78 ++++++++++++++++++-------------------
 Documentation/git-init.txt  | 35 +++++++----------
 Documentation/urls.txt      | 26 ++++++-------
 3 files changed, 67 insertions(+), 72 deletions(-)

diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
index 8e925db7e9c..9c13f847da3 100644
--- a/Documentation/git-clone.txt
+++ b/Documentation/git-clone.txt
@@ -8,16 +8,16 @@ git-clone - Clone a repository into a new directory
 
 SYNOPSIS
 --------
-[verse]
-`git clone` [++--template=++__<template-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-`]{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>_]
+[synopsis]
+git clone [--template=<template-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]
+	  [--filter=<filter-spec>] [--also-filter-submodules]] [--] <repository>
+	  [<directory>]
 
 DESCRIPTION
 -----------
@@ -52,7 +52,7 @@ OPTIONS
 	to save space when possible.
 +
 If the repository is specified as a local path (e.g., `/path/to/repo`),
-this is the default, and --local is essentially a no-op.  If the
+this is the default, and `--local` is essentially a no-op.  If the
 repository is specified as a URL, then this flag is ignored (and we
 never use the local optimizations).  Specifying `--no-local` will
 override the default when `/path/to/repo` is given, using the regular
@@ -64,8 +64,8 @@ prevent the unintentional copying of files by dereferencing the symbolic
 links.
 +
 *NOTE*: this operation can race with concurrent modification to the
-source repository, similar to running `cp -r src dst` while modifying
-`src`.
+source repository, similar to running `cp -r <src> <dst>` while modifying
+_<src>_.
 
 `--no-hardlinks`::
 	Force the cloning process from a repository on a local
@@ -101,7 +101,7 @@ If you want to break the dependency of a repository cloned with `--shared` on
 its source repository, you can simply run `git repack -a` to copy all
 objects from the source repository into a pack in the cloned repository.
 
-`--reference`[`-if-able`] _<repository>_::
+`--reference[-if-able] <repository>`::
 	If the reference _<repository>_ is on the local machine,
 	automatically setup `.git/objects/info/alternates` to
 	obtain objects from the reference _<repository>_.  Using
@@ -142,17 +142,17 @@ objects from the source repository into a pack in the cloned repository.
 	is specified. This flag forces progress status even if the
 	standard error stream is not directed to a terminal.
 
-++--server-option=++__<option>__::
+`--server-option=<option>`::
 	Transmit the given string to the server when communicating using
 	protocol version 2.  The given string must not contain a NUL or LF
 	character.  The server's handling of server options, including
 	unknown ones, is server-specific.
-	When multiple ++--server-option=++__<option>__ are given, they are all
+	When multiple `--server-option=<option>` are given, they are all
 	sent to the other side in the order listed on the command line.
 
 `-n`::
 `--no-checkout`::
-	No checkout of HEAD is performed after the clone is complete.
+	No checkout of `HEAD` is performed after the clone is complete.
 
 `--`[`no-`]`reject-shallow`::
 	Fail if the source repository is a shallow repository.
@@ -162,7 +162,7 @@ objects from the source repository into a pack in the cloned repository.
 `--bare`::
 	Make a 'bare' Git repository.  That is, instead of
 	creating _<directory>_ and placing the administrative
-	files in _<directory>_`/.git`, make the _<directory>_
+	files in `<directory>/.git`, make the _<directory>_
 	itself the `$GIT_DIR`. This obviously implies the `--no-checkout`
 	because there is nowhere to check out the working tree.
 	Also the branch heads at the remote are copied directly
@@ -177,13 +177,13 @@ objects from the source repository into a pack in the cloned repository.
 	linkgit:git-sparse-checkout[1] command can be used to grow the
 	working directory as needed.
 
-++--filter=++__<filter-spec>__::
+`--filter=<filter-spec>`::
 	Use the partial clone feature and request that the server sends
 	a subset of reachable objects according to a given object filter.
 	When using `--filter`, the supplied _<filter-spec>_ is used for
 	the partial clone filter. For example, `--filter=blob:none` will
 	filter out all blobs (file contents) until needed by Git. Also,
-	++--filter=blob:limit=++__<size>__ will filter out all blobs of size
+	`--filter=blob:limit=<size>` will filter out all blobs of size
 	at least _<size>_. For more details on filter specifications, see
 	the `--filter` option in linkgit:git-rev-list[1].
 
@@ -208,11 +208,11 @@ objects from the source repository into a pack in the cloned repository.
 
 `-b` _<name>_::
 `--branch` _<name>_::
-	Instead of pointing the newly created HEAD to the branch pointed
-	to by the cloned repository's HEAD, point to _<name>_ branch
+	Instead of pointing the newly created `HEAD` to the branch pointed
+	to by the cloned repository's `HEAD`, point to _<name>_ branch
 	instead. In a non-bare repository, this is the branch that will
 	be checked out.
-	`--branch` can also take tags and detaches the HEAD at that commit
+	`--branch` can also take tags and detaches the `HEAD` at that commit
 	in the resulting repository.
 
 `-u` _<upload-pack>_::
@@ -221,12 +221,12 @@ objects from the source repository into a pack in the cloned repository.
 	via ssh, this specifies a non-default path for the command
 	run on the other end.
 
-++--template=++__<template-directory>__::
+`--template=<template-directory>`::
 	Specify the directory from which templates will be used;
 	(See the "TEMPLATE DIRECTORY" section of linkgit:git-init[1].)
 
-`-c` __<key>__++=++__<value>__::
-`--config` __<key>__++=++__<value>__::
+`-c` `<key>=<value>`::
+`--config` `<key>=<value>`::
 	Set a configuration variable in the newly-created repository;
 	this takes effect immediately after the repository is
 	initialized, but before the remote history is fetched or any
@@ -239,25 +239,25 @@ objects from the source repository into a pack in the cloned repository.
 Due to limitations of the current implementation, some configuration
 variables do not take effect until after the initial fetch and checkout.
 Configuration variables known to not take effect are:
-++remote.++__<name>__++.mirror++ and ++remote.++__<name>__++.tagOpt++.  Use the
+`remote.<name>.mirror` and `remote.<name>.tagOpt`.  Use the
 corresponding `--mirror` and `--no-tags` options instead.
 
-`--depth` _<depth>_::
+`--depth <depth>`::
 	Create a 'shallow' clone with a history truncated to the
 	specified number of commits. Implies `--single-branch` unless
 	`--no-single-branch` is given to fetch the histories near the
 	tips of all branches. If you want to clone submodules shallowly,
 	also pass `--shallow-submodules`.
 
-++--shallow-since=++__<date>__::
+`--shallow-since=<date>`::
 	Create a shallow clone with a history after the specified time.
 
-++--shallow-exclude=++__<revision>__::
+`--shallow-exclude=<revision>`::
 	Create a shallow clone with a history, excluding commits
 	reachable from a specified remote branch or tag.  This option
 	can be specified multiple times.
 
-`--`[`no-`]`single-branch`::
+`--[no-]single-branch`::
 	Clone only the history leading to the tip of a single branch,
 	either specified by the `--branch` option or the primary
 	branch remote's `HEAD` points at.
@@ -279,13 +279,13 @@ maintain a branch with no references other than a single cloned
 branch. This is useful e.g. to maintain minimal clones of the default
 branch of some repository for search indexing.
 
-`--recurse-submodules`[`=`{empty}__<pathspec>__]::
+`--recurse-submodules[=<pathspec>]`::
 	After the clone is created, initialize and clone submodules
-	within based on the provided _<pathspec>_.  If no _=<pathspec>_ is
+	within based on the provided _<pathspec>_.  If no `=<pathspec>` is
 	provided, all submodules are initialized and cloned.
 	This option can be given multiple times for pathspecs consisting
 	of multiple entries.  The resulting clone has `submodule.active` set to
-	the provided pathspec, or "." (meaning all submodules) if no
+	the provided pathspec, or "`.`" (meaning all submodules) if no
 	pathspec is provided.
 +
 Submodules are initialized and cloned using their default settings. This is
@@ -295,23 +295,23 @@ the clone is finished. This option is ignored if the cloned repository does
 not have a worktree/checkout (i.e. if any of `--no-checkout`/`-n`, `--bare`,
 or `--mirror` is given)
 
-`--`[`no-`]`shallow-submodules`::
+`--[no-]shallow-submodules`::
 	All submodules which are cloned will be shallow with a depth of 1.
 
-`--`[`no-`]`remote-submodules`::
+`--[no-]remote-submodules`::
 	All submodules which are cloned will use the status of the submodule's
 	remote-tracking branch to update the submodule, rather than the
 	superproject's recorded SHA-1. Equivalent to passing `--remote` to
 	`git submodule update`.
 
-`--separate-git-dir=`{empty}__<git-dir>__::
+`--separate-git-dir=<git-dir>`::
 	Instead of placing the cloned repository where it is supposed
 	to be, place the cloned repository at the specified directory,
 	then make a filesystem-agnostic Git symbolic link to there.
 	The result is Git repository can be separated from working
 	tree.
 
-`--ref-format=`{empty}__<ref-format>__::
+`--ref-format=<ref-format>`::
 
 Specify the given ref storage format for the repository. The valid values are:
 +
@@ -334,7 +334,7 @@ _<directory>_::
 	for `host.xz:foo/.git`).  Cloning into an existing directory
 	is only allowed if the directory is empty.
 
-`--bundle-uri=`{empty}__<uri>__::
+`--bundle-uri=<uri>`::
 	Before fetching from the remote, fetch a bundle from the given
 	_<uri>_ and unbundle the data into the local repository. The refs
 	in the bundle will be stored under the hidden `refs/bundle/*`
diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt
index daff93bd164..315f7f7530c 100644
--- a/Documentation/git-init.txt
+++ b/Documentation/git-init.txt
@@ -8,12 +8,12 @@ git-init - Create an empty Git repository or reinitialize an existing one
 
 SYNOPSIS
 --------
-[verse]
-`git init` [`-q` | `--quiet`] [`--bare`] [++--template=++__<template-directory>__]
-	  [`--separate-git-dir` _<git-dir>_] [++--object-format=++__<format>__]
-	  [++--ref-format=++__<format>__]
-	  [`-b` _<branch-name>_ | ++--initial-branch=++__<branch-name>__]
-	  [++--shared++[++=++__<permissions>__]] [_<directory>_]
+[synopsis]
+git init [-q | --quiet] [--bare] [--template=<template-directory>]
+	 [--separate-git-dir <git-dir>] [--object-format=<format>]
+	 [--ref-format=<format>]
+	 [-b <branch-name> | --initial-branch=<branch-name>]
+	 [--shared[=<permissions>]] [<directory>]
 
 
 DESCRIPTION
@@ -25,11 +25,11 @@ directory with subdirectories for `objects`, `refs/heads`,
 commits will be created (see the `--initial-branch` option below
 for its name).
 
-If the `$GIT_DIR` environment variable is set then it specifies a path
+If the `GIT_DIR` environment variable is set then it specifies a path
 to use instead of `./.git` for the base of the repository.
 
 If the object storage directory is specified via the
-`$GIT_OBJECT_DIRECTORY` environment variable then the sha1 directories
+`GIT_OBJECT_DIRECTORY` environment variable then the sha1 directories
 are created underneath; otherwise, the default `$GIT_DIR/objects`
 directory is used.
 
@@ -51,26 +51,22 @@ Only print error and warning messages; all other output will be suppressed.
 Create a bare repository. If `GIT_DIR` environment is not set, it is set to the
 current working directory.
 
-++--object-format=++__<format>__::
-
+`--object-format=<format>`::
 Specify the given object _<format>_ (hash algorithm) for the repository.  The valid
 values are `sha1` and (if enabled) `sha256`.  `sha1` is the default.
 +
 include::object-format-disclaimer.txt[]
 
-++--ref-format=++__<format>__::
-
+`--ref-format=<format>`::
 Specify the given ref storage _<format>_ for the repository. The valid values are:
 +
 include::ref-storage-format.txt[]
 
-++--template=++__<template-directory>__::
-
+`--template=<template-directory>`::
 Specify the directory from which templates will be used.  (See the "TEMPLATE
 DIRECTORY" section below.)
 
-++--separate-git-dir=++__<git-dir>__::
-
+`--separate-git-dir=<git-dir>`::
 Instead of initializing the repository as a directory to either `$GIT_DIR` or
 `./.git/`, create a text file there containing the path to the actual
 repository.  This file acts as a filesystem-agnostic Git symbolic link to the
@@ -78,15 +74,14 @@ repository.
 +
 If this is a reinitialization, the repository will be moved to the specified path.
 
-`-b` _<branch-name>_::
-++--initial-branch=++__<branch-name>__::
-
+`-b <branch-name>`::
+`--initial-branch=<branch-name>`::
 Use _<branch-name>_ for the initial branch in the newly created
 repository.  If not specified, fall back to the default name (currently
 `master`, but this is subject to change in the future; the name can be
 customized via the `init.defaultBranch` configuration variable).
 
-++--shared++[++=++(`false`|`true`|`umask`|`group`|`all`|`world`|`everybody`|_<perm>_)]::
+`--shared[=(false|true|umask|group|all|world|everybody|<perm>)]`::
 
 Specify that the Git repository is to be shared amongst several users.  This
 allows users belonging to the same group to push into that
diff --git a/Documentation/urls.txt b/Documentation/urls.txt
index 7cec85aef17..9c871e716a1 100644
--- a/Documentation/urls.txt
+++ b/Documentation/urls.txt
@@ -10,19 +10,19 @@ Git supports ssh, git, http, and https protocols (in addition, ftp
 and ftps can be used for fetching, but this is inefficient and
 deprecated; do not use them).
 
-The native transport (i.e. git:// URL) does no authentication and
+The native transport (i.e. `git://` URL) does no authentication and
 should be used with caution on unsecured networks.
 
 The following syntaxes may be used with them:
 
-- ++ssh://++{startsb}__<user>__++@++{endsb}__<host>__{startsb}++:++__<port>__{endsb}++/++__<path-to-git-repo>__
-- ++git://++__<host>__{startsb}:__<port>__{endsb}++/++__<path-to-git-repo>__
-- ++http++{startsb}++s++{endsb}++://++__<host>__{startsb}++:++__<port>__{endsb}++/++__<path-to-git-repo>__
-- ++ftp++{startsb}++s++{endsb}++://++__<host>__{startsb}++:++__<port>__{endsb}++/++__<path-to-git-repo>__
+- `ssh://[<user>@]<host>[:<port>]/<path-to-git-repo>`
+- `git://<host>[:<port>]/<path-to-git-repo>`
+- `http[s]://<host>[:<port>]/<path-to-git-repo>`
+- `ftp[s]://<host>[:<port>]/<path-to-git-repo>`
 
 An alternative scp-like syntax may also be used with the ssh protocol:
 
-- {startsb}__<user>__++@++{endsb}__<host>__++:/++__<path-to-git-repo>__
+- `[<user>@]<host>:/<path-to-git-repo>`
 
 This syntax is only recognized if there are no slashes before the
 first colon. This helps differentiate a local path that contains a
@@ -30,17 +30,17 @@ colon. For example the local path `foo:bar` could be specified as an
 absolute path or `./foo:bar` to avoid being misinterpreted as an ssh
 url.
 
-The ssh and git protocols additionally support ++~++__<username>__ expansion:
+The ssh and git protocols additionally support `~<username>` expansion:
 
-- ++ssh://++{startsb}__<user>__++@++{endsb}__<host>__{startsb}++:++__<port>__{endsb}++/~++__<user>__++/++__<path-to-git-repo>__
-- ++git://++__<host>__{startsb}++:++__<port>__{endsb}++/~++__<user>__++/++__<path-to-git-repo>__
-- {startsb}__<user>__++@++{endsb}__<host>__++:~++__<user>__++/++__<path-to-git-repo>__
+- `ssh://[<user>@]<host>[:<port>]/~<user>/<path-to-git-repo>`
+- `git://<host>[:<port>]/~<user>/<path-to-git-repo>`
+- `[<user>@]<host>:~<user>/<path-to-git-repo>`
 
 For local repositories, also supported by Git natively, the following
 syntaxes may be used:
 
 - `/path/to/repo.git/`
-- ++file:///path/to/repo.git/++
+- `file:///path/to/repo.git/`
 
 ifndef::git-clone[]
 These two syntaxes are mostly equivalent, except when cloning, when
@@ -57,11 +57,11 @@ endif::git-clone[]
 accept a suitable bundle file. See linkgit:git-bundle[1].
 
 When Git doesn't know how to handle a certain transport protocol, it
-attempts to use the `remote-`{empty}__<transport>__ remote helper, if one
+attempts to use the `remote-<transport>` remote helper, if one
 exists. To explicitly request a remote helper, the following syntax
 may be used:
 
-- _<transport>_::__<address>__
+- `<transport>::<address>`
 
 where _<address>_ may be a path, a server and path, or an arbitrary
 URL-like string recognized by the specific remote helper being
-- 
gitgitgadget

Re: [PATCH v4 0/3] doc: introducing synopsis para

[Junio C Hamano]

"Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com> writes:

> In the continuation of the simplification of manpage editing, the synopsis
> processing that was developed for synopsis paragraph style is also applied
> to all inline backquoted texts.
>
> Refining the magic regexp took more time than expected, but this one should
> really enhance writers'experience. I had to fight a bit more with
> asciidoctor, due to discrepancies between version 2.0 on my laptop and the
> 1.5.6 used by Github actions.
>
> The git-init and git-clone manpages are converted to this new system.

The fact that such a "magic" processing will hide the gory details
from those whose primary interest is to describe the commands and
their options cuts both ways.  While I can understand that purists
would find it ugly, as `backticks` is now much more than a mark-up
that means "this text is typeset in monospace", it is a very welcome
thing for developers around here, who just want to write their
document in a way even whose source is readable without having to
worry about suh gory details.  Maybe this gets popular enough after
other projects notice what you did to AsciiDoctor, love it, adopt
it, and eventually it feeds back to improve AsciiDoctor proper ;-).

So, unless there are objections and people want to discuss it further,
I'll mark the topic for 'next' soonish.

Thanks.

Re: [PATCH v4 0/3] doc: introducing synopsis para

[Josh Steadmon]

On 2024.09.13 11:15, Junio C Hamano wrote:
> "Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com> writes:
> 
> > In the continuation of the simplification of manpage editing, the synopsis
> > processing that was developed for synopsis paragraph style is also applied
> > to all inline backquoted texts.
> >
> > Refining the magic regexp took more time than expected, but this one should
> > really enhance writers'experience. I had to fight a bit more with
> > asciidoctor, due to discrepancies between version 2.0 on my laptop and the
> > 1.5.6 used by Github actions.
> >
> > The git-init and git-clone manpages are converted to this new system.
> 
> The fact that such a "magic" processing will hide the gory details
> from those whose primary interest is to describe the commands and
> their options cuts both ways.  While I can understand that purists
> would find it ugly, as `backticks` is now much more than a mark-up
> that means "this text is typeset in monospace", it is a very welcome
> thing for developers around here, who just want to write their
> document in a way even whose source is readable without having to
> worry about suh gory details.  Maybe this gets popular enough after
> other projects notice what you did to AsciiDoctor, love it, adopt
> it, and eventually it feeds back to improve AsciiDoctor proper ;-).
> 
> So, unless there are objections and people want to discuss it further,
> I'll mark the topic for 'next' soonish.
> 
> Thanks.
> 

This still breaks on MacOS, as `sed` doesn't understand the '-E' option
there.

Re: [PATCH v4 0/3] doc: introducing synopsis para

[Junio C Hamano]

Josh Steadmon <steadmon@google.com> writes:

>> So, unless there are objections and people want to discuss it further,
>> I'll mark the topic for 'next' soonish.
>> 
>> Thanks.
>> 
>
> This still breaks on MacOS, as `sed` doesn't understand the '-E' option
> there.

Thanks for a report.

What is sad is that we are seeing this after the topic gets very
close to 'master' (it has been in 'next' already for a few days).

Perhaps nobody builds documentation on macOS, in which case the
breakage may be totally acceptable?  Is that the message we are
hearing from mac based developers?

Grumpy...

Re: [PATCH v4 0/3] doc: introducing synopsis para

[Junio C Hamano]

Josh Steadmon <steadmon@google.com> writes:

> This still breaks on MacOS, as `sed` doesn't understand the '-E' option
> there.

Can you try to see t6030 also breaks due to lack of ERE in the same
environment?  It seems it uses "sed -E", so it should fail to find
what it is trying to.

Thanks.

Re: [PATCH v4 0/3] doc: introducing synopsis para

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

> Josh Steadmon <steadmon@google.com> writes:
>
>> This still breaks on MacOS, as `sed` doesn't understand the '-E' option
>> there.
>
> Can you try to see t6030 also breaks due to lack of ERE in the same
> environment?  It seems it uses "sed -E", so it should fail to find
> what it is trying to.
>
> Thanks.

The reason why I am curious is because https://ss64.com/mac/sed.html
claims that -E works.

Earlier I wrote somewhere whatever problem it is it would be shared
with BSD implementation of sed.  But apparently BSD's sed also works
with the -E option.  https://man.freebsd.org/cgi/man.cgi?sed(1)

So, I dunno.  Perhaps it is not -E but some specific construct used
in the pattern?

Re: [PATCH v4 0/3] doc: introducing synopsis para

[Chris Torek]

On Fri, Sep 20, 2024 at 11:24 PM Junio C Hamano <gitster@pobox.com> wrote:
> The reason why I am curious is because https://ss64.com/mac/sed.html
> claims that -E works.

It does for me, on my Mac, which is deliberately behind current: I am
still on Big Sur.

Chris

Re: [PATCH v4 0/3] doc: introducing synopsis para

[Junio C Hamano]

Chris Torek <chris.torek@gmail.com> writes:

> On Fri, Sep 20, 2024 at 11:24 PM Junio C Hamano <gitster@pobox.com> wrote:
>> The reason why I am curious is because https://ss64.com/mac/sed.html
>> claims that -E works.
>
> It does for me, on my Mac, which is deliberately behind current: I am
> still on Big Sur.

Thanks, Chris.

Josh, the topic has been cooking in 'next' long enough to graduate
to 'master' without anybody else complaining.  Could you
double-check and if possible see what is different in your
environment from others?

I can hold the topic in 'next' longer but not forever without
progress.  Help from macOS folks (if it is macOS specific issue)
is greatly appreciated.

Thanks.

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

[Jean-Noël Avila via GitGitGadget]

In the continuation of the simplification of manpage editing, the synopsis
processing that was developed for synopsis paragraph style is also applied
to all inline backquoted texts.

Refining the magic regexp took more time than expected, but this one should
really enhance writers'experience. I had to fight a bit more with
asciidoctor, due to discrepancies between version 2.0 on my laptop and the
1.5.6 used by Github actions.

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

Changes since V2:

 * introduce the s macro to freely apply synopsis styling wherever needed,
   without formatting hassle.

Changes since V3:

 * replace s macro by direct processing of literal text at the level of
   output processors.

Changes since V4:

 * used BRE in sed filter
 * rework the processing of three dots

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

 Documentation/CodingGuidelines          | 58 +++++++++--------
 Documentation/asciidoc.conf             | 20 ++++++
 Documentation/asciidoctor-extensions.rb | 87 +++++++++++++++++++++++++
 Documentation/git-clone.txt             | 78 +++++++++++-----------
 Documentation/git-init.txt              | 35 +++++-----
 Documentation/urls.txt                  | 26 ++++----
 ci/install-dependencies.sh              |  1 +
 t/t0450-txt-doc-vs-help.sh              | 11 ++--
 8 files changed, 209 insertions(+), 107 deletions(-)


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

Range-diff vs v4:

 1:  c09968d7ccb ! 1:  2946cc80314 doc: introduce a synopsis typesetting
     @@ Documentation/asciidoc.conf: ifdef::backend-xhtml11[]
      +ifdef::backend-docbook[]
      +ifdef::doctype-manpage[]
      +[paradef-default]
     -+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'"
     ++synopsis-style=template="verseparagraph",filter="sed 's!&#8230;\\(\\]\\|$\\)!<phrase>\\0</phrase>!g;s!\\([\\[ |()]\\|^\\|\\]\\|&gt;\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.]\\+\\|&#8230;\\)!\\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="sed -E 's!([\[ |()>]|^|\])(\.?[-=a-zA-Z0-9:+@,\/_^\$]+\.?)!\\1<code>\\2</code>!g;s!&lt;[-a-zA-Z0-9.]+&gt;!<em>\\0</em>!g'"
     ++synopsis-style=template="verseparagraph",filter="sed 's!&#8230;\\(\\]\\|$\\)!<span>\\0</span>!g;s!\\([\\[ |()]\\|^\\|\\]\\|&gt;\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.]\\+\\|&#8230;\\)!\\1<code>\\2</code>!g;s!&lt;[-a-zA-Z0-9.]\\+&gt;!<em>\\0</em>!g'"
       endif::backend-xhtml11[]
      
       ## Documentation/asciidoctor-extensions.rb ##
 2:  c48649ccd63 = 2:  06b8fff6a57 doc: update the guidelines to reflect the current formatting rules
 3:  719188da711 = 3:  a76998d6443 doc: apply synopsis simplification on git-clone and git-init

-- 
gitgitgadget

[PATCH v5 1/3] doc: introduce a synopsis typesetting

[Jean-Noël Avila via GitGitGadget]

From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>

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 processor for backticked text are modified. The
backends of asciidoc and asciidoctor take in charge to correctly add
the required typesetting.

Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
---
 Documentation/asciidoc.conf             | 20 ++++++
 Documentation/asciidoctor-extensions.rb | 87 +++++++++++++++++++++++++
 ci/install-dependencies.sh              |  1 +
 t/t0450-txt-doc-vs-help.sh              | 11 ++--
 4 files changed, 112 insertions(+), 7 deletions(-)

diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf
index 60f76f43eda..f6da6d1fbd2 100644
--- a/Documentation/asciidoc.conf
+++ b/Documentation/asciidoc.conf
@@ -28,6 +28,10 @@ ifdef::backend-docbook[]
 {0#<citerefentry>}
 {0#<refentrytitle>{target}</refentrytitle><manvolnum>{0}</manvolnum>}
 {0#</citerefentry>}
+
+[literal-inlinemacro]
+{eval:re.sub(r'(&lt;[-a-zA-Z0-9.]+&gt;)', r'<emphasis>\1</emphasis>', re.sub(r'([\[\s|()>]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@,\/_^\$]+\.?)+)',r'\1<literal>\2</literal>', re.sub(r'(\.\.\.?)([^\]$.])', r'<literal>\1</literal>\2', macros.passthroughs[int(attrs['passtext'][1:-1])] if attrs['passtext'][1:-1].isnumeric() else attrs['passtext'][1:-1])))}
+
 endif::backend-docbook[]
 
 ifdef::backend-docbook[]
@@ -56,4 +60,20 @@ ifdef::backend-xhtml11[]
 git-relative-html-prefix=
 [linkgit-inlinemacro]
 <a href="{git-relative-html-prefix}{target}.html">{target}{0?({0})}</a>
+
+[literal-inlinemacro]
+{eval:re.sub(r'(&lt;[-a-zA-Z0-9.]+&gt;)', r'<em>\1</em>', re.sub(r'([\[\s|()>]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@,\/_^\$]+\.?)+)',r'\1<code>\2</code>', re.sub(r'(\.\.\.?)([^\]$.])', r'<code>\1</code>\2', macros.passthroughs[int(attrs['passtext'][1:-1])] if attrs['passtext'][1:-1].isnumeric() else attrs['passtext'][1:-1])))}
+
+endif::backend-xhtml11[]
+
+ifdef::backend-docbook[]
+ifdef::doctype-manpage[]
+[paradef-default]
+synopsis-style=template="verseparagraph",filter="sed 's!&#8230;\\(\\]\\|$\\)!<phrase>\\0</phrase>!g;s!\\([\\[ |()]\\|^\\|\\]\\|&gt;\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.]\\+\\|&#8230;\\)!\\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="sed 's!&#8230;\\(\\]\\|$\\)!<span>\\0</span>!g;s!\\([\\[ |()]\\|^\\|\\]\\|&gt;\\)\\([-=a-zA-Z0-9:+@,\\/_^\\$.]\\+\\|&#8230;\\)!\\1<code>\\2</code>!g;s!&lt;[-a-zA-Z0-9.]\\+&gt;!<em>\\0</em>!g'"
 endif::backend-xhtml11[]
diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb
index d906a008039..cb24480b63d 100644
--- a/Documentation/asciidoctor-extensions.rb
+++ b/Documentation/asciidoctor-extensions.rb
@@ -1,5 +1,7 @@
 require 'asciidoctor'
 require 'asciidoctor/extensions'
+require 'asciidoctor/converter/docbook5'
+require 'asciidoctor/converter/html5'
 
 module Git
   module Documentation
@@ -39,10 +41,95 @@ 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(/(\.\.\.?)([^\]$.])/, '`\1`\2')
+           .gsub(%r{([\[\] |()>]|^)([-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
+
+    class GitDBConverter < Asciidoctor::Converter::DocBook5Converter
+
+      extend Asciidoctor::Converter::Config
+      register_for 'docbook5'
+
+      def convert_inline_quoted node
+        if (type = node.type) == :asciimath
+          # NOTE fop requires jeuclid to process mathml markup
+          asciimath_available? ? %(<inlineequation>#{(::AsciiMath.parse node.text).to_mathml 'mml:', 'xmlns:mml' => 'http://www.w3.org/1998/Math/MathML'}</inlineequation>) : %(<inlineequation><mathphrase><![CDATA[#{node.text}]]></mathphrase></inlineequation>)
+        elsif type == :latexmath
+          # unhandled math; pass source to alt and required mathphrase element; dblatex will process alt as LaTeX math
+          %(<inlineequation><alt><![CDATA[#{equation = node.text}]]></alt><mathphrase><![CDATA[#{equation}]]></mathphrase></inlineequation>)
+        elsif type == :monospaced
+          node.text.gsub(/(\.\.\.?)([^\]$.])/, '<literal>\1</literal>\2')
+              .gsub(%r{([\[\s|()>.]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@,/_^\$]+\.{0,2})+)}, '\1<literal>\2</literal>')
+              .gsub(/(&lt;[-a-zA-Z0-9.]+&gt;)/, '<emphasis>\1</emphasis>')
+        else
+          open, close, supports_phrase = QUOTE_TAGS[type]
+          text = node.text
+          if node.role
+            if supports_phrase
+              quoted_text = %(#{open}<phrase role="#{node.role}">#{text}</phrase>#{close})
+            else
+              quoted_text = %(#{open.chop} role="#{node.role}">#{text}#{close})
+            end
+          else
+            quoted_text = %(#{open}#{text}#{close})
+          end
+          node.id ? %(<anchor#{common_attributes node.id, nil, text}/>#{quoted_text}) : quoted_text
+        end
+      end
+    end
+
+    # register a html5 converter that takes in charge to convert monospaced text into Git style synopsis
+    class GitHTMLConverter < Asciidoctor::Converter::Html5Converter
+
+      extend Asciidoctor::Converter::Config
+      register_for 'html5'
+
+      def convert_inline_quoted node
+        if node.type == :monospaced
+          node.text.gsub(/(\.\.\.?)([^\]$.])/, '<code>\1</code>\2')
+              .gsub(%r{([\[\s|()>.]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@,/_^\$]+\.{0,2})+)}, '\1<code>\2</code>')
+              .gsub(/(&lt;[-a-zA-Z0-9.]+&gt;)/, '<em>\1</em>')
+
+        else
+          open, close, tag = QUOTE_TAGS[node.type]
+          if node.id
+            class_attr = node.role ? %( class="#{node.role}") : ''
+            if tag
+              %(#{open.chop} id="#{node.id}"#{class_attr}>#{node.text}#{close})
+            else
+              %(<span id="#{node.id}"#{class_attr}>#{open}#{node.text}#{close}</span>)
+            end
+          elsif node.role
+            if tag
+              %(#{open.chop} class="#{node.role}">#{node.text}#{close})
+            else
+              %(<span class="#{node.role}">#{open}#{node.text}#{close}</span>)
+            end
+          else
+            %(#{open}#{node.text}#{close})
+          end
+        end
+      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/ci/install-dependencies.sh b/ci/install-dependencies.sh
index 4781cd20bb0..3e3ae39cbb1 100755
--- a/ci/install-dependencies.sh
+++ b/ci/install-dependencies.sh
@@ -107,6 +107,7 @@ Documentation)
 
 	test -n "$ALREADY_HAVE_ASCIIDOCTOR" ||
 	sudo gem install --version 1.5.8 asciidoctor
+	sudo gem install concurrent-ruby
 	;;
 esac
 
diff --git a/t/t0450-txt-doc-vs-help.sh b/t/t0450-txt-doc-vs-help.sh
index 69917d7b845..f99a69ae1b7 100755
--- a/t/t0450-txt-doc-vs-help.sh
+++ b/t/t0450-txt-doc-vs-help.sh
@@ -56,14 +56,11 @@ 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;
-			s/{litdd}/--/g;
-			s/'\''\(git[ a-z-]*\)'\''/\1/g;
+			/^\[(verse|synopsis)\]$/d;
+			s/\{litdd\}/--/g;
+			s/'\''(git[ a-z-]*)'\''/\1/g;
 
 			p;
 		}' \
-- 
gitgitgadget

[PATCH v5 2/3] doc: update the guidelines to reflect the current formatting rules

[Jean-Noël Avila via GitGitGadget]

From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>

Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
---
 Documentation/CodingGuidelines | 58 ++++++++++++++++++----------------
 1 file changed, 30 insertions(+), 28 deletions(-)

diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index ccaea39752c..13cbcf1d7a5 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -820,78 +820,80 @@ Markup:
    _<new-branch-name>_
    _<template-directory>_
 
- A placeholder is not enclosed in backticks, as it is not a literal.
-
  When needed, use a distinctive identifier for placeholders, usually
  made of a qualification and a type:
    _<git-dir>_
    _<key-id>_
 
- When literal and placeholders are mixed, each markup is applied for
- each sub-entity. If they are stuck, a special markup, called
- unconstrained formatting is required.
- Unconstrained formating for placeholders is __<like-this>__
- Unconstrained formatting for literal formatting is ++like this++
-   `--jobs` _<n>_
-   ++--sort=++__<key>__
-   __<directory>__++/.git++
-   ++remote.++__<name>__++.mirror++
+ Git's Asciidoc processor has been tailored to treat backticked text
+ as complex synopsis. When literal and placeholders are mixed, you can
+ use the backtick notation which will take care of correctly typesetting
+ the content.
+   `--jobs <n>`
+   `--sort=<key>`
+   `<directory>/.git`
+   `remote.<name>.mirror`
+   `ssh://[<user>@]<host>[:<port>]/<path-to-git-repo>`
 
- caveat: ++ unconstrained format is not verbatim and may expand
- content. Use Asciidoc escapes inside them.
+As a side effect, backquoted placeholders are correctly typeset, but
+this style is not recommended.
 
 Synopsis Syntax
 
- Syntax grammar is formatted neither as literal nor as placeholder.
+ The synopsis (a paragraph with [synopsis] attribute) is automatically
+ formatted by the toolchain and does not need typesetting.
 
  A few commented examples follow to provide reference when writing or
  modifying command usage strings and synopsis sections in the manual
  pages:
 
  Possibility of multiple occurrences is indicated by three dots:
-   _<file>_...
+   <file>...
    (One or more of <file>.)
 
  Optional parts are enclosed in square brackets:
-   [_<file>_...]
+   [<file>...]
    (Zero or more of <file>.)
 
-   ++--exec-path++[++=++__<path>__]
+ An optional parameter needs to be typeset with unconstrained pairs
+   [<repository>]
+
+   --exec-path[=<path>]
    (Option with an optional argument.  Note that the "=" is inside the
    brackets.)
 
-   [_<patch>_...]
+   [<patch>...]
    (Zero or more of <patch>.  Note that the dots are inside, not
    outside the brackets.)
 
  Multiple alternatives are indicated with vertical bars:
-   [`-q` | `--quiet`]
-   [`--utf8` | `--no-utf8`]
+   [-q | --quiet]
+   [--utf8 | --no-utf8]
 
  Use spacing around "|" token(s), but not immediately after opening or
  before closing a [] or () pair:
-   Do: [`-q` | `--quiet`]
-   Don't: [`-q`|`--quiet`]
+   Do: [-q | --quiet]
+   Don't: [-q|--quiet]
 
  Don't use spacing around "|" tokens when they're used to separate the
  alternate arguments of an option:
-    Do: ++--track++[++=++(`direct`|`inherit`)]`
-    Don't: ++--track++[++=++(`direct` | `inherit`)]
+    Do: --track[=(direct|inherit)]
+    Don't: --track[=(direct | inherit)]
 
  Parentheses are used for grouping:
-   [(_<rev>_ | _<range>_)...]
+   [(<rev>|<range>)...]
    (Any number of either <rev> or <range>.  Parens are needed to make
    it clear that "..." pertains to both <rev> and <range>.)
 
-   [(`-p` _<parent>_)...]
+   [(-p <parent>)...]
    (Any number of option -p, each with one <parent> argument.)
 
-   `git remote set-head` _<name>_ (`-a` | `-d` | _<branch>_)
+   git remote set-head <name> (-a|-d|<branch>)
    (One and only one of "-a", "-d" or "<branch>" _must_ (no square
    brackets) be provided.)
 
  And a somewhat more contrived example:
-   `--diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]`
+   --diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]
    Here "=" is outside the brackets, because "--diff-filter=" is a
    valid usage.  "*" has its own pair of brackets, because it can
    (optionally) be specified only when one or more of the letters is
-- 
gitgitgadget

[PATCH v5 3/3] doc: apply synopsis simplification on git-clone and git-init

[Jean-Noël Avila via GitGitGadget]

From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>

With the new synopsis formatting backend, no special asciidoc markup
is needed.

Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
---
 Documentation/git-clone.txt | 78 ++++++++++++++++++-------------------
 Documentation/git-init.txt  | 35 +++++++----------
 Documentation/urls.txt      | 26 ++++++-------
 3 files changed, 67 insertions(+), 72 deletions(-)

diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
index 8e925db7e9c..9c13f847da3 100644
--- a/Documentation/git-clone.txt
+++ b/Documentation/git-clone.txt
@@ -8,16 +8,16 @@ git-clone - Clone a repository into a new directory
 
 SYNOPSIS
 --------
-[verse]
-`git clone` [++--template=++__<template-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-`]{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>_]
+[synopsis]
+git clone [--template=<template-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]
+	  [--filter=<filter-spec>] [--also-filter-submodules]] [--] <repository>
+	  [<directory>]
 
 DESCRIPTION
 -----------
@@ -52,7 +52,7 @@ OPTIONS
 	to save space when possible.
 +
 If the repository is specified as a local path (e.g., `/path/to/repo`),
-this is the default, and --local is essentially a no-op.  If the
+this is the default, and `--local` is essentially a no-op.  If the
 repository is specified as a URL, then this flag is ignored (and we
 never use the local optimizations).  Specifying `--no-local` will
 override the default when `/path/to/repo` is given, using the regular
@@ -64,8 +64,8 @@ prevent the unintentional copying of files by dereferencing the symbolic
 links.
 +
 *NOTE*: this operation can race with concurrent modification to the
-source repository, similar to running `cp -r src dst` while modifying
-`src`.
+source repository, similar to running `cp -r <src> <dst>` while modifying
+_<src>_.
 
 `--no-hardlinks`::
 	Force the cloning process from a repository on a local
@@ -101,7 +101,7 @@ If you want to break the dependency of a repository cloned with `--shared` on
 its source repository, you can simply run `git repack -a` to copy all
 objects from the source repository into a pack in the cloned repository.
 
-`--reference`[`-if-able`] _<repository>_::
+`--reference[-if-able] <repository>`::
 	If the reference _<repository>_ is on the local machine,
 	automatically setup `.git/objects/info/alternates` to
 	obtain objects from the reference _<repository>_.  Using
@@ -142,17 +142,17 @@ objects from the source repository into a pack in the cloned repository.
 	is specified. This flag forces progress status even if the
 	standard error stream is not directed to a terminal.
 
-++--server-option=++__<option>__::
+`--server-option=<option>`::
 	Transmit the given string to the server when communicating using
 	protocol version 2.  The given string must not contain a NUL or LF
 	character.  The server's handling of server options, including
 	unknown ones, is server-specific.
-	When multiple ++--server-option=++__<option>__ are given, they are all
+	When multiple `--server-option=<option>` are given, they are all
 	sent to the other side in the order listed on the command line.
 
 `-n`::
 `--no-checkout`::
-	No checkout of HEAD is performed after the clone is complete.
+	No checkout of `HEAD` is performed after the clone is complete.
 
 `--`[`no-`]`reject-shallow`::
 	Fail if the source repository is a shallow repository.
@@ -162,7 +162,7 @@ objects from the source repository into a pack in the cloned repository.
 `--bare`::
 	Make a 'bare' Git repository.  That is, instead of
 	creating _<directory>_ and placing the administrative
-	files in _<directory>_`/.git`, make the _<directory>_
+	files in `<directory>/.git`, make the _<directory>_
 	itself the `$GIT_DIR`. This obviously implies the `--no-checkout`
 	because there is nowhere to check out the working tree.
 	Also the branch heads at the remote are copied directly
@@ -177,13 +177,13 @@ objects from the source repository into a pack in the cloned repository.
 	linkgit:git-sparse-checkout[1] command can be used to grow the
 	working directory as needed.
 
-++--filter=++__<filter-spec>__::
+`--filter=<filter-spec>`::
 	Use the partial clone feature and request that the server sends
 	a subset of reachable objects according to a given object filter.
 	When using `--filter`, the supplied _<filter-spec>_ is used for
 	the partial clone filter. For example, `--filter=blob:none` will
 	filter out all blobs (file contents) until needed by Git. Also,
-	++--filter=blob:limit=++__<size>__ will filter out all blobs of size
+	`--filter=blob:limit=<size>` will filter out all blobs of size
 	at least _<size>_. For more details on filter specifications, see
 	the `--filter` option in linkgit:git-rev-list[1].
 
@@ -208,11 +208,11 @@ objects from the source repository into a pack in the cloned repository.
 
 `-b` _<name>_::
 `--branch` _<name>_::
-	Instead of pointing the newly created HEAD to the branch pointed
-	to by the cloned repository's HEAD, point to _<name>_ branch
+	Instead of pointing the newly created `HEAD` to the branch pointed
+	to by the cloned repository's `HEAD`, point to _<name>_ branch
 	instead. In a non-bare repository, this is the branch that will
 	be checked out.
-	`--branch` can also take tags and detaches the HEAD at that commit
+	`--branch` can also take tags and detaches the `HEAD` at that commit
 	in the resulting repository.
 
 `-u` _<upload-pack>_::
@@ -221,12 +221,12 @@ objects from the source repository into a pack in the cloned repository.
 	via ssh, this specifies a non-default path for the command
 	run on the other end.
 
-++--template=++__<template-directory>__::
+`--template=<template-directory>`::
 	Specify the directory from which templates will be used;
 	(See the "TEMPLATE DIRECTORY" section of linkgit:git-init[1].)
 
-`-c` __<key>__++=++__<value>__::
-`--config` __<key>__++=++__<value>__::
+`-c` `<key>=<value>`::
+`--config` `<key>=<value>`::
 	Set a configuration variable in the newly-created repository;
 	this takes effect immediately after the repository is
 	initialized, but before the remote history is fetched or any
@@ -239,25 +239,25 @@ objects from the source repository into a pack in the cloned repository.
 Due to limitations of the current implementation, some configuration
 variables do not take effect until after the initial fetch and checkout.
 Configuration variables known to not take effect are:
-++remote.++__<name>__++.mirror++ and ++remote.++__<name>__++.tagOpt++.  Use the
+`remote.<name>.mirror` and `remote.<name>.tagOpt`.  Use the
 corresponding `--mirror` and `--no-tags` options instead.
 
-`--depth` _<depth>_::
+`--depth <depth>`::
 	Create a 'shallow' clone with a history truncated to the
 	specified number of commits. Implies `--single-branch` unless
 	`--no-single-branch` is given to fetch the histories near the
 	tips of all branches. If you want to clone submodules shallowly,
 	also pass `--shallow-submodules`.
 
-++--shallow-since=++__<date>__::
+`--shallow-since=<date>`::
 	Create a shallow clone with a history after the specified time.
 
-++--shallow-exclude=++__<revision>__::
+`--shallow-exclude=<revision>`::
 	Create a shallow clone with a history, excluding commits
 	reachable from a specified remote branch or tag.  This option
 	can be specified multiple times.
 
-`--`[`no-`]`single-branch`::
+`--[no-]single-branch`::
 	Clone only the history leading to the tip of a single branch,
 	either specified by the `--branch` option or the primary
 	branch remote's `HEAD` points at.
@@ -279,13 +279,13 @@ maintain a branch with no references other than a single cloned
 branch. This is useful e.g. to maintain minimal clones of the default
 branch of some repository for search indexing.
 
-`--recurse-submodules`[`=`{empty}__<pathspec>__]::
+`--recurse-submodules[=<pathspec>]`::
 	After the clone is created, initialize and clone submodules
-	within based on the provided _<pathspec>_.  If no _=<pathspec>_ is
+	within based on the provided _<pathspec>_.  If no `=<pathspec>` is
 	provided, all submodules are initialized and cloned.
 	This option can be given multiple times for pathspecs consisting
 	of multiple entries.  The resulting clone has `submodule.active` set to
-	the provided pathspec, or "." (meaning all submodules) if no
+	the provided pathspec, or "`.`" (meaning all submodules) if no
 	pathspec is provided.
 +
 Submodules are initialized and cloned using their default settings. This is
@@ -295,23 +295,23 @@ the clone is finished. This option is ignored if the cloned repository does
 not have a worktree/checkout (i.e. if any of `--no-checkout`/`-n`, `--bare`,
 or `--mirror` is given)
 
-`--`[`no-`]`shallow-submodules`::
+`--[no-]shallow-submodules`::
 	All submodules which are cloned will be shallow with a depth of 1.
 
-`--`[`no-`]`remote-submodules`::
+`--[no-]remote-submodules`::
 	All submodules which are cloned will use the status of the submodule's
 	remote-tracking branch to update the submodule, rather than the
 	superproject's recorded SHA-1. Equivalent to passing `--remote` to
 	`git submodule update`.
 
-`--separate-git-dir=`{empty}__<git-dir>__::
+`--separate-git-dir=<git-dir>`::
 	Instead of placing the cloned repository where it is supposed
 	to be, place the cloned repository at the specified directory,
 	then make a filesystem-agnostic Git symbolic link to there.
 	The result is Git repository can be separated from working
 	tree.
 
-`--ref-format=`{empty}__<ref-format>__::
+`--ref-format=<ref-format>`::
 
 Specify the given ref storage format for the repository. The valid values are:
 +
@@ -334,7 +334,7 @@ _<directory>_::
 	for `host.xz:foo/.git`).  Cloning into an existing directory
 	is only allowed if the directory is empty.
 
-`--bundle-uri=`{empty}__<uri>__::
+`--bundle-uri=<uri>`::
 	Before fetching from the remote, fetch a bundle from the given
 	_<uri>_ and unbundle the data into the local repository. The refs
 	in the bundle will be stored under the hidden `refs/bundle/*`
diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt
index daff93bd164..315f7f7530c 100644
--- a/Documentation/git-init.txt
+++ b/Documentation/git-init.txt
@@ -8,12 +8,12 @@ git-init - Create an empty Git repository or reinitialize an existing one
 
 SYNOPSIS
 --------
-[verse]
-`git init` [`-q` | `--quiet`] [`--bare`] [++--template=++__<template-directory>__]
-	  [`--separate-git-dir` _<git-dir>_] [++--object-format=++__<format>__]
-	  [++--ref-format=++__<format>__]
-	  [`-b` _<branch-name>_ | ++--initial-branch=++__<branch-name>__]
-	  [++--shared++[++=++__<permissions>__]] [_<directory>_]
+[synopsis]
+git init [-q | --quiet] [--bare] [--template=<template-directory>]
+	 [--separate-git-dir <git-dir>] [--object-format=<format>]
+	 [--ref-format=<format>]
+	 [-b <branch-name> | --initial-branch=<branch-name>]
+	 [--shared[=<permissions>]] [<directory>]
 
 
 DESCRIPTION
@@ -25,11 +25,11 @@ directory with subdirectories for `objects`, `refs/heads`,
 commits will be created (see the `--initial-branch` option below
 for its name).
 
-If the `$GIT_DIR` environment variable is set then it specifies a path
+If the `GIT_DIR` environment variable is set then it specifies a path
 to use instead of `./.git` for the base of the repository.
 
 If the object storage directory is specified via the
-`$GIT_OBJECT_DIRECTORY` environment variable then the sha1 directories
+`GIT_OBJECT_DIRECTORY` environment variable then the sha1 directories
 are created underneath; otherwise, the default `$GIT_DIR/objects`
 directory is used.
 
@@ -51,26 +51,22 @@ Only print error and warning messages; all other output will be suppressed.
 Create a bare repository. If `GIT_DIR` environment is not set, it is set to the
 current working directory.
 
-++--object-format=++__<format>__::
-
+`--object-format=<format>`::
 Specify the given object _<format>_ (hash algorithm) for the repository.  The valid
 values are `sha1` and (if enabled) `sha256`.  `sha1` is the default.
 +
 include::object-format-disclaimer.txt[]
 
-++--ref-format=++__<format>__::
-
+`--ref-format=<format>`::
 Specify the given ref storage _<format>_ for the repository. The valid values are:
 +
 include::ref-storage-format.txt[]
 
-++--template=++__<template-directory>__::
-
+`--template=<template-directory>`::
 Specify the directory from which templates will be used.  (See the "TEMPLATE
 DIRECTORY" section below.)
 
-++--separate-git-dir=++__<git-dir>__::
-
+`--separate-git-dir=<git-dir>`::
 Instead of initializing the repository as a directory to either `$GIT_DIR` or
 `./.git/`, create a text file there containing the path to the actual
 repository.  This file acts as a filesystem-agnostic Git symbolic link to the
@@ -78,15 +74,14 @@ repository.
 +
 If this is a reinitialization, the repository will be moved to the specified path.
 
-`-b` _<branch-name>_::
-++--initial-branch=++__<branch-name>__::
-
+`-b <branch-name>`::
+`--initial-branch=<branch-name>`::
 Use _<branch-name>_ for the initial branch in the newly created
 repository.  If not specified, fall back to the default name (currently
 `master`, but this is subject to change in the future; the name can be
 customized via the `init.defaultBranch` configuration variable).
 
-++--shared++[++=++(`false`|`true`|`umask`|`group`|`all`|`world`|`everybody`|_<perm>_)]::
+`--shared[=(false|true|umask|group|all|world|everybody|<perm>)]`::
 
 Specify that the Git repository is to be shared amongst several users.  This
 allows users belonging to the same group to push into that
diff --git a/Documentation/urls.txt b/Documentation/urls.txt
index 7cec85aef17..9c871e716a1 100644
--- a/Documentation/urls.txt
+++ b/Documentation/urls.txt
@@ -10,19 +10,19 @@ Git supports ssh, git, http, and https protocols (in addition, ftp
 and ftps can be used for fetching, but this is inefficient and
 deprecated; do not use them).
 
-The native transport (i.e. git:// URL) does no authentication and
+The native transport (i.e. `git://` URL) does no authentication and
 should be used with caution on unsecured networks.
 
 The following syntaxes may be used with them:
 
-- ++ssh://++{startsb}__<user>__++@++{endsb}__<host>__{startsb}++:++__<port>__{endsb}++/++__<path-to-git-repo>__
-- ++git://++__<host>__{startsb}:__<port>__{endsb}++/++__<path-to-git-repo>__
-- ++http++{startsb}++s++{endsb}++://++__<host>__{startsb}++:++__<port>__{endsb}++/++__<path-to-git-repo>__
-- ++ftp++{startsb}++s++{endsb}++://++__<host>__{startsb}++:++__<port>__{endsb}++/++__<path-to-git-repo>__
+- `ssh://[<user>@]<host>[:<port>]/<path-to-git-repo>`
+- `git://<host>[:<port>]/<path-to-git-repo>`
+- `http[s]://<host>[:<port>]/<path-to-git-repo>`
+- `ftp[s]://<host>[:<port>]/<path-to-git-repo>`
 
 An alternative scp-like syntax may also be used with the ssh protocol:
 
-- {startsb}__<user>__++@++{endsb}__<host>__++:/++__<path-to-git-repo>__
+- `[<user>@]<host>:/<path-to-git-repo>`
 
 This syntax is only recognized if there are no slashes before the
 first colon. This helps differentiate a local path that contains a
@@ -30,17 +30,17 @@ colon. For example the local path `foo:bar` could be specified as an
 absolute path or `./foo:bar` to avoid being misinterpreted as an ssh
 url.
 
-The ssh and git protocols additionally support ++~++__<username>__ expansion:
+The ssh and git protocols additionally support `~<username>` expansion:
 
-- ++ssh://++{startsb}__<user>__++@++{endsb}__<host>__{startsb}++:++__<port>__{endsb}++/~++__<user>__++/++__<path-to-git-repo>__
-- ++git://++__<host>__{startsb}++:++__<port>__{endsb}++/~++__<user>__++/++__<path-to-git-repo>__
-- {startsb}__<user>__++@++{endsb}__<host>__++:~++__<user>__++/++__<path-to-git-repo>__
+- `ssh://[<user>@]<host>[:<port>]/~<user>/<path-to-git-repo>`
+- `git://<host>[:<port>]/~<user>/<path-to-git-repo>`
+- `[<user>@]<host>:~<user>/<path-to-git-repo>`
 
 For local repositories, also supported by Git natively, the following
 syntaxes may be used:
 
 - `/path/to/repo.git/`
-- ++file:///path/to/repo.git/++
+- `file:///path/to/repo.git/`
 
 ifndef::git-clone[]
 These two syntaxes are mostly equivalent, except when cloning, when
@@ -57,11 +57,11 @@ endif::git-clone[]
 accept a suitable bundle file. See linkgit:git-bundle[1].
 
 When Git doesn't know how to handle a certain transport protocol, it
-attempts to use the `remote-`{empty}__<transport>__ remote helper, if one
+attempts to use the `remote-<transport>` remote helper, if one
 exists. To explicitly request a remote helper, the following syntax
 may be used:
 
-- _<transport>_::__<address>__
+- `<transport>::<address>`
 
 where _<address>_ may be a path, a server and path, or an arbitrary
 URL-like string recognized by the specific remote helper being
-- 
gitgitgadget

Re: [PATCH v5 0/3] doc: introducing synopsis para

[Junio C Hamano]

"Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com> writes:

> Changes since V4:
>
>  * used BRE in sed filter
>  * rework the processing of three dots

The topic has been deep in 'next' already, and I wasn't expecting a
wholesale replacement.  But thanks for updating.

As the patches are more in the technology demonstration phase by
converting only a few pages and making sure other uses of `` outside
the synopsis section in unconverted pages are not broken, we can
declare that the three-patch series will not be in 2.47 and will
keep it in 'next'.  So let me revert the merge of the previous one
out of 'next' and queue this one afresh to 'seen' to see how well it
works.

Josh (or whoever is taking over this week from him at Google), can
you see if the breakage you saw that stopped us merging the topic
before it causes us trouble on 'master' reproduces with this version
(either by running "make doc" on the topic branch by itself, or on
'seen' that merges the topic) in your environment that had trouble
with the previous round?

It would also be highly appreciated if other macOS users try "make
doc" and see the resulting git-init and git-clone documentation
pages are reasonable, both for the previous round that has been
cooking in 'next' and for this latest round.  Inputs from folks on
more mainstream platforms with modern asciidoc/asciidoctor toolchain
would also help.  The more people we have who look at how the new
way the synopsis section is written and how the resulting documents
get rendered, the more fairly we can assess the value of this topic.

Thanks.

Re: [PATCH v5 0/3] doc: introducing synopsis para

[Torsten Bögershausen]

On Tue, Sep 24, 2024 at 10:16:10AM -0700, Junio C Hamano wrote:
> "Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
> > Changes since V4:
> >
> >  * used BRE in sed filter
> >  * rework the processing of three dots
>
> The topic has been deep in 'next' already, and I wasn't expecting a
> wholesale replacement.  But thanks for updating.
>
> As the patches are more in the technology demonstration phase by
> converting only a few pages and making sure other uses of `` outside
> the synopsis section in unconverted pages are not broken, we can
> declare that the three-patch series will not be in 2.47 and will
> keep it in 'next'.  So let me revert the merge of the previous one
> out of 'next' and queue this one afresh to 'seen' to see how well it
> works.
>
> Josh (or whoever is taking over this week from him at Google), can
> you see if the breakage you saw that stopped us merging the topic
> before it causes us trouble on 'master' reproduces with this version
> (either by running "make doc" on the topic branch by itself, or on
> 'seen' that merges the topic) in your environment that had trouble
> with the previous round?
>
> It would also be highly appreciated if other macOS users try "make
> doc" and see the resulting git-init and git-clone documentation
> pages are reasonable, both for the previous round that has been
> cooking in 'next' and for this latest round.  Inputs from folks on
> more mainstream platforms with modern asciidoc/asciidoctor toolchain
> would also help.  The more people we have who look at how the new
> way the synopsis section is written and how the resulting documents
> get rendered, the more fairly we can assess the value of this topic.
>
> Thanks.
>

Here a report from a MacOs user,
asciidoc --version
asciidoc 10.2.0

installed via macports.

No problems seen in the seen branch.

I diffed git-init.html from seen of today against both master and next,
some (minor) improvements (like GIT_OBJECT_DIRECTORY vs $GIT_OBJECT_DIRECTORY)
All in all it looks all sensible.
(and yes, `sed` understands -E)

Re: [PATCH v5 0/3] doc: introducing synopsis para

[Junio C Hamano]

Torsten Bögershausen <tboegi@web.de> writes:

> On Tue, Sep 24, 2024 at 10:16:10AM -0700, Junio C Hamano wrote:
>> "Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com> writes:
>>
>> > Changes since V4:
>> >
>> >  * used BRE in sed filter
>> >  * rework the processing of three dots
>> ...
>> Josh (or whoever is taking over this week from him at Google), can
>> you see if the breakage you saw that stopped us merging the topic
>> before it causes us trouble on 'master' reproduces with this version
>> (either by running "make doc" on the topic branch by itself, or on
>> 'seen' that merges the topic) in your environment that had trouble
>> with the previous round?
>>
>> It would also be highly appreciated if other macOS users try "make
>> doc" and see the resulting git-init and git-clone documentation
>> pages are reasonable, both for the previous round that has been
>> cooking in 'next' and for this latest round.  Inputs from folks on
>> more mainstream platforms with modern asciidoc/asciidoctor toolchain
>> would also help.  The more people we have who look at how the new
>> way the synopsis section is written and how the resulting documents
>> get rendered, the more fairly we can assess the value of this topic.
>>
> Here a report from a MacOs user,
> asciidoc --version
> asciidoc 10.2.0
>
> installed via macports.
>
> No problems seen in the seen branch.
>
> I diffed git-init.html from seen of today against both master and next,
> some (minor) improvements (like GIT_OBJECT_DIRECTORY vs $GIT_OBJECT_DIRECTORY)
> All in all it looks all sensible.
> (and yes, `sed` understands -E)

Since I haven't pushed out the 'seen' branch with latest iteration,
your sucess report is about the previous iteration that Josh said
"still breaks on MacOS" [*].  The plot thickens...

Thanks.


[Reference]

 * https://lore.kernel.org/git/4ww5v253vz2g4i3z2x3dmgkrot7mcn2qm6ckjcxbyky6yvrozy@mr5hnrsfj6sn/

Re: [PATCH v4 0/3] doc: introducing synopsis para

[Josh Steadmon]

On 2024.09.23 14:14, Eric Sunshine wrote:
> On Mon, Sep 23, 2024 at 12:38 PM Junio C Hamano <gitster@pobox.com> wrote:
> > Chris Torek <chris.torek@gmail.com> writes:
> > > On Fri, Sep 20, 2024 at 11:24 PM Junio C Hamano <gitster@pobox.com> wrote:
> > >> The reason why I am curious is because https://ss64.com/mac/sed.html
> > >> claims that -E works.
> > >
> > > It does for me, on my Mac, which is deliberately behind current: I am
> > > still on Big Sur.
> >
> > Josh, the topic has been cooking in 'next' long enough to graduate
> > to 'master' without anybody else complaining.  Could you
> > double-check and if possible see what is different in your
> > environment from others?
> >
> > I can hold the topic in 'next' longer but not forever without
> > progress.  Help from macOS folks (if it is macOS specific issue)
> > is greatly appreciated.
> 
> I checked my High Sierra installation (macOS 10.13) which is even
> older than Big Sur (macOS 11), and High Sierra's "sed" also
> understands -E.

Hi folks, sorry for the false alarm and the delayed response. For some
reason our build environment has a >decade old version of sed. I'm still
tracking down why that is, but please do not hold back this topic any
longer due to our out-of-date-ness. Sorry again!

Re: [PATCH v4 0/3] doc: introducing synopsis para

[Junio C Hamano]

Josh Steadmon <steadmon@google.com> writes:

>> I checked my High Sierra installation (macOS 10.13) which is even
>> older than Big Sur (macOS 11), and High Sierra's "sed" also
>> understands -E.
>
> Hi folks, sorry for the false alarm and the delayed response. For some
> reason our build environment has a >decade old version of sed. I'm still
> tracking down why that is, but please do not hold back this topic any
> longer due to our out-of-date-ness. Sorry again!

Thanks.

I think Jean-Noël's latest rewrote ERE down to BRE but also tweaked
something else around U+2026 …. Please try that version again when
you have a chance.

Re: [PATCH v5 0/3] doc: introducing synopsis para

[Josh Steadmon]

On 2024.09.24 13:33, Junio C Hamano wrote:
> Torsten Bögershausen <tboegi@web.de> writes:
> 
> > On Tue, Sep 24, 2024 at 10:16:10AM -0700, Junio C Hamano wrote:
> >> "Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com> writes:
> >>
> >> > Changes since V4:
> >> >
> >> >  * used BRE in sed filter
> >> >  * rework the processing of three dots
> >> ...
> >> Josh (or whoever is taking over this week from him at Google), can
> >> you see if the breakage you saw that stopped us merging the topic
> >> before it causes us trouble on 'master' reproduces with this version
> >> (either by running "make doc" on the topic branch by itself, or on
> >> 'seen' that merges the topic) in your environment that had trouble
> >> with the previous round?
> >>
> >> It would also be highly appreciated if other macOS users try "make
> >> doc" and see the resulting git-init and git-clone documentation
> >> pages are reasonable, both for the previous round that has been
> >> cooking in 'next' and for this latest round.  Inputs from folks on
> >> more mainstream platforms with modern asciidoc/asciidoctor toolchain
> >> would also help.  The more people we have who look at how the new
> >> way the synopsis section is written and how the resulting documents
> >> get rendered, the more fairly we can assess the value of this topic.
> >>
> > Here a report from a MacOs user,
> > asciidoc --version
> > asciidoc 10.2.0
> >
> > installed via macports.
> >
> > No problems seen in the seen branch.
> >
> > I diffed git-init.html from seen of today against both master and next,
> > some (minor) improvements (like GIT_OBJECT_DIRECTORY vs $GIT_OBJECT_DIRECTORY)
> > All in all it looks all sensible.
> > (and yes, `sed` understands -E)
> 
> Since I haven't pushed out the 'seen' branch with latest iteration,
> your sucess report is about the previous iteration that Josh said
> "still breaks on MacOS" [*].  The plot thickens...
> 
> Thanks.
> 
> 
> [Reference]
> 
>  * https://lore.kernel.org/git/4ww5v253vz2g4i3z2x3dmgkrot7mcn2qm6ckjcxbyky6yvrozy@mr5hnrsfj6sn/

I finally got the chance to test this version on $DAYJOB's build
infrastructure, and I verified that it works (I also got a much more
recent version of sed installed).

Re: [PATCH v5 0/3] doc: introducing synopsis para

[Junio C Hamano]

Josh Steadmon <steadmon@google.com> writes:

> I finally got the chance to test this version on $DAYJOB's build
> infrastructure, and I verified that it works (I also got a much more
> recent version of sed installed).

Thanks for a follow-up.