{"thread":{"id":"61831","subject":"[PATCH 0/3] doc: introducing synopsis para","startedAt":"2024-07-23T22:44:44Z","lastAt":"2024-10-02T22:43:10Z","messageCount":45,"participants":["Jean-Noël Avila via GitGitGadget","Jean-Noël AVILA","Junio C Hamano","Eric Sunshine","Jean-Noël Avila","Josh Steadmon","Chris Torek","Torsten Bögershausen"],"isPatch":true,"patchVersion":1,"patchTotal":3},"messages":[{"id":"499204","messageId":"pull.1766.git.1721774680.gitgitgadget@gmail.com","threadId":"61831","inReplyTo":null,"subject":"[PATCH 0/3] doc: introducing synopsis para","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-07-23T22:44:37Z","receivedAt":"2024-07-23T22:44:44Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"Following several issues with the way the formatting of synopsis is done in\nthe manpages that were recently reworked, this patch series introduces the\nprocessing of a new custom paragraph attribute 'synopsis'.\n\nThis extension is added to asciidoc and asciidoctor and lets write the\nsynopsis of the commands without any typeset. The git-init and git-clone\nmanpages are converted to this new system.\n\nJean-Noël Avila (3):\n  doc: introduce a synopsis custom paragraph attribute\n  doc: update the guidelines to reflect the current formatting rules\n  doc: apply synopsis simplification on git-clone and git-init\n\n Documentation/CodingGuidelines          | 34 ++++++++++++++-----------\n Documentation/asciidoc.conf             | 14 ++++++++++\n Documentation/asciidoctor-extensions.rb | 17 +++++++++++++\n Documentation/git-clone.txt             | 20 +++++++--------\n Documentation/git-init.txt              | 12 ++++-----\n t/t0450-txt-doc-vs-help.sh              |  7 ++---\n 6 files changed, 68 insertions(+), 36 deletions(-)\n\n\nbase-commit: a7dae3bdc8b516d36f630b12bb01e853a667e0d9\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-1766%2Fjnavila%2Fdoc_synopsis_para-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1766/jnavila/doc_synopsis_para-v1\nPull-Request: https://github.com/gitgitgadget/git/pull/1766\n-- \ngitgitgadget\n"},{"id":"499205","messageId":"704f0333ef17c0e3596ba7ef7976ba6584345eff.1721774680.git.gitgitgadget@gmail.com","threadId":"61831","inReplyTo":"pull.1766.git.1721774680.gitgitgadget@gmail.com","subject":"[PATCH 1/3] doc: introduce a synopsis custom paragraph attribute","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-07-23T22:44:38Z","receivedAt":"2024-07-23T22:44:44Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n\nIn order to follow the common manpage usage, the synopsis of the\ncommands needs to be heavily typeset. A first try was performed with\nusing native markup, but it turned out to make the document source\nalmost unreadable, difficult to write and prone to mistakes with\nunwanted Asciidoc's role attributes.\n\nIn order to both simplify the writer's task and obtain a consistant\ntypesetting in the synopsis, a custom 'synopsis' paragraph type is\ncreated and the backends of asciidoc and asciidoctor take in charge to\ncorrectly add the required typesetting.\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n Documentation/asciidoc.conf             | 14 ++++++++++++++\n Documentation/asciidoctor-extensions.rb | 17 +++++++++++++++++\n Documentation/git-clone.txt             |  2 +-\n Documentation/git-init.txt              |  2 +-\n t/t0450-txt-doc-vs-help.sh              |  7 ++-----\n 5 files changed, 35 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf\nindex 60f76f43edab..cb2a9ca59c65 100644\n--- a/Documentation/asciidoc.conf\n+++ b/Documentation/asciidoc.conf\n@@ -57,3 +57,17 @@ git-relative-html-prefix=\n [linkgit-inlinemacro]\n <a href=\"{git-relative-html-prefix}{target}.html\">{target}{0?({0})}</a>\n endif::backend-xhtml11[]\n+\n+ifdef::backend-docbook[]\n+ifdef::doctype-manpage[]\n+[paradef-default]\n+#synopsis-style=template=\"verseparagraph\",filter=\"sed -E 's!&lt;[a-z-]+&gt;!<emphasis>\\\\0</emphasis>!g' -E 's!([a-z-]+)!<literal>\\\\1</literal>!g'\"\n+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'\"\n+#synopsis-style=template=\"verseparagraph\"\n+endif::doctype-manpage[]\n+endif::backend-docbook[]\n+\n+ifdef::backend-xhtml11[]\n+[paradef-default]\n+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'\"\n+endif::backend-xhtml11[]\ndiff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb\nindex d906a008039c..d1568f654627 100644\n--- a/Documentation/asciidoctor-extensions.rb\n+++ b/Documentation/asciidoctor-extensions.rb\n@@ -39,10 +39,27 @@ module Git\n         output\n       end\n     end\n+\n+    class SynopsisBlock < Asciidoctor::Extensions::BlockProcessor\n+\n+      use_dsl\n+      named :synopsis\n+      parse_content_as :simple\n+\n+      def process parent, reader, attrs\n+        outlines = reader.lines.map do |l|\n+          l.gsub(/([\\[\\] |()>]|^)([a-zA-Z0-9\\-:+=]+)/, '\\\\1{empty}`\\\\2`{empty}')\n+           .gsub(/(<[a-zA-Z0-9\\-.]+>)/, '__\\\\1__')\n+           .gsub(']', ']{empty}')\n+        end\n+        create_block parent, :verse, outlines, attrs\n+      end\n+    end\n   end\n end\n \n Asciidoctor::Extensions.register do\n   inline_macro Git::Documentation::LinkGitProcessor, :linkgit\n+  block Git::Documentation::SynopsisBlock\n   postprocessor Git::Documentation::DocumentPostProcessor\n end\ndiff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt\nindex 5de18de2ab83..70a3f0331f83 100644\n--- a/Documentation/git-clone.txt\n+++ b/Documentation/git-clone.txt\n@@ -17,7 +17,7 @@ SYNOPSIS\n \t  [++--recurse-submodules++[++=++__<pathspec>__]] [`--`[`no-`]`shallow-submodules`]\n \t  [`--`[`no-`]`remote-submodules`] [`--jobs` _<n>_] [`--sparse`] [`--`[`no-`]`reject-shallow`]\n \t  [++--filter=++__<filter-spec>__] [`--also-filter-submodules`]] [`--`] _<repository>_\n-\t  [_<directory>_]\n+\t  [__<directory>__]\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-init.txt b/Documentation/git-init.txt\nindex daff93bd164b..7cdc693e1c68 100644\n--- a/Documentation/git-init.txt\n+++ b/Documentation/git-init.txt\n@@ -13,7 +13,7 @@ SYNOPSIS\n \t  [`--separate-git-dir` _<git-dir>_] [++--object-format=++__<format>__]\n \t  [++--ref-format=++__<format>__]\n \t  [`-b` _<branch-name>_ | ++--initial-branch=++__<branch-name>__]\n-\t  [++--shared++[++=++__<permissions>__]] [_<directory>_]\n+\t  [`--shared`[++=++__<permissions>__]] [__<directory>__]\n \n \n DESCRIPTION\ndiff --git a/t/t0450-txt-doc-vs-help.sh b/t/t0450-txt-doc-vs-help.sh\nindex 69917d7b8459..f9d89949ece3 100755\n--- a/t/t0450-txt-doc-vs-help.sh\n+++ b/t/t0450-txt-doc-vs-help.sh\n@@ -56,12 +56,9 @@ txt_to_synopsis () {\n \tfi &&\n \tb2t=\"$(builtin_to_txt \"$builtin\")\" &&\n \tsed -n \\\n-\t\t-e '/^\\[verse\\]$/,/^$/ {\n+\t\t-e '/^\\[\\(verse\\|synopsis\\)\\]$/,/^$/ {\n \t\t\t/^$/d;\n-\t\t\t/^\\[verse\\]$/d;\n-\t\t\ts/_//g;\n-\t\t\ts/++//g;\n-\t\t\ts/`//g;\n+\t\t\t/^\\[\\(verse\\|synopsis\\)\\]$/d;\n \t\t\ts/{litdd}/--/g;\n \t\t\ts/'\\''\\(git[ a-z-]*\\)'\\''/\\1/g;\n \n-- \ngitgitgadget\n\n"},{"id":"499206","messageId":"b0547422e5cf31c1141f2b6078a43e5bc60cb652.1721774680.git.gitgitgadget@gmail.com","threadId":"61831","inReplyTo":"pull.1766.git.1721774680.gitgitgadget@gmail.com","subject":"[PATCH 2/3] doc: update the guidelines to reflect the current formatting rules","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-07-23T22:44:39Z","receivedAt":"2024-07-23T22:44:46Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n Documentation/CodingGuidelines | 34 +++++++++++++++++++---------------\n 1 file changed, 19 insertions(+), 15 deletions(-)\n\ndiff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines\nindex 1d92b2da03e8..4d59e8f89ec8 100644\n--- a/Documentation/CodingGuidelines\n+++ b/Documentation/CodingGuidelines\n@@ -760,56 +760,60 @@ Markup:\n \n Synopsis Syntax\n \n- Syntax grammar is formatted neither as literal nor as placeholder.\n+ The synopsis (a paragraph with [synopsis] attribute) is automatically\n+ formatted by the toolchain and does not need typesetting.\n \n  A few commented examples follow to provide reference when writing or\n  modifying command usage strings and synopsis sections in the manual\n  pages:\n \n  Possibility of multiple occurrences is indicated by three dots:\n-   _<file>_...\n+   <file>...\n    (One or more of <file>.)\n \n  Optional parts are enclosed in square brackets:\n-   [_<file>_...]\n+   [<file>...]\n    (Zero or more of <file>.)\n \n-   ++--exec-path++[++=++__<path>__]\n+ An optional parameter needs to be typeset with unconstrained pairs\n+   [<repository>]\n+\n+   --exec-path[=<path>]\n    (Option with an optional argument.  Note that the \"=\" is inside the\n    brackets.)\n \n-   [_<patch>_...]\n+   [<patch>...]\n    (Zero or more of <patch>.  Note that the dots are inside, not\n    outside the brackets.)\n \n  Multiple alternatives are indicated with vertical bars:\n-   [`-q` | `--quiet`]\n-   [`--utf8` | `--no-utf8`]\n+   [-q | --quiet]\n+   [--utf8 | --no-utf8]\n \n  Use spacing around \"|\" token(s), but not immediately after opening or\n  before closing a [] or () pair:\n-   Do: [`-q` | `--quiet`]\n-   Don't: [`-q`|`--quiet`]\n+   Do: [-q | --quiet]\n+   Don't: [-q|--quiet]\n \n  Don't use spacing around \"|\" tokens when they're used to separate the\n  alternate arguments of an option:\n-    Do: ++--track++[++=++(`direct`|`inherit`)]`\n-    Don't: ++--track++[++=++(`direct` | `inherit`)]\n+    Do: --track[=(direct|inherit)]\n+    Don't: --track[=(direct | inherit)]\n \n  Parentheses are used for grouping:\n-   [(_<rev>_ | _<range>_)...]\n+   [(<rev>|<range>)...]\n    (Any number of either <rev> or <range>.  Parens are needed to make\n    it clear that \"...\" pertains to both <rev> and <range>.)\n \n-   [(`-p` _<parent>_)...]\n+   [(-p <parent>)...]\n    (Any number of option -p, each with one <parent> argument.)\n \n-   `git remote set-head` _<name>_ (`-a` | `-d` | _<branch>_)\n+   git remote set-head <name> (-a|-d|<branch>)\n    (One and only one of \"-a\", \"-d\" or \"<branch>\" _must_ (no square\n    brackets) be provided.)\n \n  And a somewhat more contrived example:\n-   `--diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]`\n+   --diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]\n    Here \"=\" is outside the brackets, because \"--diff-filter=\" is a\n    valid usage.  \"*\" has its own pair of brackets, because it can\n    (optionally) be specified only when one or more of the letters is\n-- \ngitgitgadget\n\n"},{"id":"499207","messageId":"3bcbe455747f19621f150b2f692194c7012b019e.1721774680.git.gitgitgadget@gmail.com","threadId":"61831","inReplyTo":"pull.1766.git.1721774680.gitgitgadget@gmail.com","subject":"[PATCH 3/3] doc: apply synopsis simplification on git-clone and git-init","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-07-23T22:44:40Z","receivedAt":"2024-07-23T22:44:46Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n\nWith the new synopsis formatting backend, no special asciidoc markup\nis needed.\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n Documentation/git-clone.txt | 20 ++++++++++----------\n Documentation/git-init.txt  | 12 ++++++------\n 2 files changed, 16 insertions(+), 16 deletions(-)\n\ndiff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt\nindex 70a3f0331f83..53b1c3e23f75 100644\n--- a/Documentation/git-clone.txt\n+++ b/Documentation/git-clone.txt\n@@ -8,16 +8,16 @@ git-clone - Clone a repository into a new directory\n \n SYNOPSIS\n --------\n-[verse]\n-`git clone` [++--template=++__<template-directory>__]\n-\t  [`-l`] [`-s`] [`--no-hardlinks`] [`-q`] [`-n`] [`--bare`] [`--mirror`]\n-\t  [`-o` _<name>_] [`-b` _<name>_] [`-u` _<upload-pack>_] [`--reference` _<repository>_]\n-\t  [`--dissociate`] [`--separate-git-dir` _<git-dir>_]\n-\t  [`--depth` _<depth>_] [`--`[`no-`]`single-branch`] [`--no-tags`]\n-\t  [++--recurse-submodules++[++=++__<pathspec>__]] [`--`[`no-`]`shallow-submodules`]\n-\t  [`--`[`no-`]`remote-submodules`] [`--jobs` _<n>_] [`--sparse`] [`--`[`no-`]`reject-shallow`]\n-\t  [++--filter=++__<filter-spec>__] [`--also-filter-submodules`]] [`--`] _<repository>_\n-\t  [__<directory>__]\n+[synopsis]\n+git clone [--template=<template-directory>]\n+\t  [-l] [-s] [--no-hardlinks] [-q] [-n] [--bare] [--mirror]\n+\t  [-o <name>] [-b <name>] [-u <upload-pack>] [--reference <repository>]\n+\t  [--dissociate] [--separate-git-dir <git-dir>]\n+\t  [--depth <depth>] [--[no-]single-branch] [--no-tags]\n+\t  [--recurse-submodules[=<pathspec>]] [--[no-]shallow-submodules]\n+\t  [--[no-]remote-submodules] [--jobs <n>] [--sparse] [--[no-]reject-shallow]\n+\t  [--filter=<filter-spec>] [--also-filter-submodules]] [--] <repository>\n+\t  [<directory>]\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-init.txt b/Documentation/git-init.txt\nindex 7cdc693e1c68..eba67fdde83f 100644\n--- a/Documentation/git-init.txt\n+++ b/Documentation/git-init.txt\n@@ -8,12 +8,12 @@ git-init - Create an empty Git repository or reinitialize an existing one\n \n SYNOPSIS\n --------\n-[verse]\n-`git init` [`-q` | `--quiet`] [`--bare`] [++--template=++__<template-directory>__]\n-\t  [`--separate-git-dir` _<git-dir>_] [++--object-format=++__<format>__]\n-\t  [++--ref-format=++__<format>__]\n-\t  [`-b` _<branch-name>_ | ++--initial-branch=++__<branch-name>__]\n-\t  [`--shared`[++=++__<permissions>__]] [__<directory>__]\n+[synopsis]\n+git init [-q | --quiet] [--bare] [--template=<template-directory>]\n+\t [--separate-git-dir <git-dir>] [--object-format=<format>]\n+\t [--ref-format=<format>]\n+\t [-b <branch-name> | --initial-branch=<branch-name>]\n+\t [--shared[=<permissions>]] [<directory>]\n \n \n DESCRIPTION\n-- \ngitgitgadget\n"},{"id":"499209","messageId":"2911357.mvXUDI8C0e@cayenne","threadId":"61831","inReplyTo":"pull.1766.git.1721774680.gitgitgadget@gmail.com","subject":"Re: [PATCH 0/3] doc: introducing synopsis para","fromName":"Jean-Noël AVILA","fromEmail":"jn.avila@free.fr","sentAt":"2024-07-23T23:04:41Z","receivedAt":"2024-07-23T23:05:02Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"Sorry for the noise: this patch series does not work on macOS.\n\nBR\n\nJean-Noël\n\n\n\n"},{"id":"499211","messageId":"xmqqo76nznnv.fsf@gitster.g","threadId":"61831","inReplyTo":"704f0333ef17c0e3596ba7ef7976ba6584345eff.1721774680.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 1/3] doc: introduce a synopsis custom paragraph attribute","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-07-23T23:36:20Z","receivedAt":"2024-07-23T23:36:23Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Jean-Noël Avila via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n> +ifdef::backend-docbook[]\n> +ifdef::doctype-manpage[]\n> +[paradef-default]\n> +#synopsis-style=template=\"verseparagraph\",filter=\"sed -E 's!&lt;[a-z-]+&gt;!<emphasis>\\\\0</emphasis>!g' -E 's!([a-z-]+)!<literal>\\\\1</literal>!g'\"\n> +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'\"\n> +#synopsis-style=template=\"verseparagraph\"\n\nThis has three candidate definitions, but two are commented out?\n\n> +endif::doctype-manpage[]\n> +endif::backend-docbook[]\n> +\n> +ifdef::backend-xhtml11[]\n> +[paradef-default]\n> +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'\"\n> +endif::backend-xhtml11[]\n\nWith this update, do we now assume that anybody who want to format\nthe documentation from source must have a minimally working Perl on\ntheir $PATH?  It probably is an OK requirement to have.\n"},{"id":"499212","messageId":"xmqqjzhbznmm.fsf@gitster.g","threadId":"61831","inReplyTo":"b0547422e5cf31c1141f2b6078a43e5bc60cb652.1721774680.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 2/3] doc: update the guidelines to reflect the current formatting rules","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-07-23T23:37:05Z","receivedAt":"2024-07-23T23:37:09Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Jean-Noël Avila via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n> From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n>\n> Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>\n> ---\n>  Documentation/CodingGuidelines | 34 +++++++++++++++++++---------------\n>  1 file changed, 19 insertions(+), 15 deletions(-)\n>\n> diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines\n> index 1d92b2da03e8..4d59e8f89ec8 100644\n> --- a/Documentation/CodingGuidelines\n> +++ b/Documentation/CodingGuidelines\n> @@ -760,56 +760,60 @@ Markup:\n>  \n>  Synopsis Syntax\n>  \n> - Syntax grammar is formatted neither as literal nor as placeholder.\n> + The synopsis (a paragraph with [synopsis] attribute) is automatically\n> + formatted by the toolchain and does not need typesetting.\n\nHow pleasant ;-)\n\n>   And a somewhat more contrived example:\n> -   `--diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]`\n> +   --diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]\n>     Here \"=\" is outside the brackets, because \"--diff-filter=\" is a\n>     valid usage.  \"*\" has its own pair of brackets, because it can\n>     (optionally) be specified only when one or more of the letters is\n"},{"id":"499295","messageId":"pull.1766.v2.git.1721855179.gitgitgadget@gmail.com","threadId":"61831","inReplyTo":"pull.1766.git.1721774680.gitgitgadget@gmail.com","subject":"[PATCH v2 0/3] doc: introducing synopsis para","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-07-24T21:06:16Z","receivedAt":"2024-07-24T21:06:23Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"Following several issues with the way the formatting of synopsis is done in\nthe manpages that were recently reworked, this patch series introduces the\nprocessing of a new custom paragraph attribute 'synopsis'.\n\nThis extension is added to asciidoc and asciidoctor and lets write the\nsynopsis of the commands without any typeset. The git-init and git-clone\nmanpages are converted to this new system.\n\nChanges since V1:\n\n * switch to sed for asciidoc filter and refine the regex for support under\n   macOS\n\nJean-Noël Avila (3):\n  doc: introduce a synopsis custom paragraph attribute\n  doc: update the guidelines to reflect the current formatting rules\n  doc: apply synopsis simplification on git-clone and git-init\n\n Documentation/CodingGuidelines          | 34 ++++++++++++++-----------\n Documentation/asciidoc.conf             | 12 +++++++++\n Documentation/asciidoctor-extensions.rb | 17 +++++++++++++\n Documentation/git-clone.txt             | 20 +++++++--------\n Documentation/git-init.txt              | 12 ++++-----\n t/t0450-txt-doc-vs-help.sh              | 11 +++-----\n 6 files changed, 68 insertions(+), 38 deletions(-)\n\n\nbase-commit: ad57f148c6b5f8735b62238dda8f571c582e0e54\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-1766%2Fjnavila%2Fdoc_synopsis_para-v2\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1766/jnavila/doc_synopsis_para-v2\nPull-Request: https://github.com/gitgitgadget/git/pull/1766\n\nRange-diff vs v1:\n\n 1:  704f0333ef1 ! 1:  aba144f4ff3 doc: introduce a synopsis custom paragraph attribute\n     @@ Documentation/asciidoc.conf: git-relative-html-prefix=\n      +ifdef::backend-docbook[]\n      +ifdef::doctype-manpage[]\n      +[paradef-default]\n     -+#synopsis-style=template=\"verseparagraph\",filter=\"sed -E 's!&lt;[a-z-]+&gt;!<emphasis>\\\\0</emphasis>!g' -E 's!([a-z-]+)!<literal>\\\\1</literal>!g'\"\n     -+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'\"\n     -+#synopsis-style=template=\"verseparagraph\"\n     ++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'\"\n      +endif::doctype-manpage[]\n      +endif::backend-docbook[]\n      +\n      +ifdef::backend-xhtml11[]\n      +[paradef-default]\n     -+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'\"\n     ++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'\"\n      +endif::backend-xhtml11[]\n      \n       ## Documentation/asciidoctor-extensions.rb ##\n     @@ Documentation/asciidoctor-extensions.rb: module Git\n      +\n      +      def process parent, reader, attrs\n      +        outlines = reader.lines.map do |l|\n     -+          l.gsub(/([\\[\\] |()>]|^)([a-zA-Z0-9\\-:+=]+)/, '\\\\1{empty}`\\\\2`{empty}')\n     -+           .gsub(/(<[a-zA-Z0-9\\-.]+>)/, '__\\\\1__')\n     ++          l.gsub(/([\\[\\] |()>]|^)([-a-zA-Z0-9:+=.]+)/, '\\\\1{empty}`\\\\2`{empty}')\n     ++           .gsub(/(<[-a-zA-Z0-9.]+>)/, '__\\\\1__')\n      +           .gsub(']', ']{empty}')\n      +        end\n      +        create_block parent, :verse, outlines, attrs\n     @@ Documentation/asciidoctor-extensions.rb: module Git\n         postprocessor Git::Documentation::DocumentPostProcessor\n       end\n      \n     - ## Documentation/git-clone.txt ##\n     -@@ Documentation/git-clone.txt: SYNOPSIS\n     - \t  [++--recurse-submodules++[++=++__<pathspec>__]] [`--`[`no-`]`shallow-submodules`]\n     - \t  [`--`[`no-`]`remote-submodules`] [`--jobs` _<n>_] [`--sparse`] [`--`[`no-`]`reject-shallow`]\n     - \t  [++--filter=++__<filter-spec>__] [`--also-filter-submodules`]] [`--`] _<repository>_\n     --\t  [_<directory>_]\n     -+\t  [__<directory>__]\n     - \n     - DESCRIPTION\n     - -----------\n     -\n     - ## Documentation/git-init.txt ##\n     -@@ Documentation/git-init.txt: SYNOPSIS\n     - \t  [`--separate-git-dir` _<git-dir>_] [++--object-format=++__<format>__]\n     - \t  [++--ref-format=++__<format>__]\n     - \t  [`-b` _<branch-name>_ | ++--initial-branch=++__<branch-name>__]\n     --\t  [++--shared++[++=++__<permissions>__]] [_<directory>_]\n     -+\t  [`--shared`[++=++__<permissions>__]] [__<directory>__]\n     - \n     - \n     - DESCRIPTION\n     -\n       ## t/t0450-txt-doc-vs-help.sh ##\n      @@ t/t0450-txt-doc-vs-help.sh: txt_to_synopsis () {\n       \tfi &&\n       \tb2t=\"$(builtin_to_txt \"$builtin\")\" &&\n       \tsed -n \\\n      -\t\t-e '/^\\[verse\\]$/,/^$/ {\n     -+\t\t-e '/^\\[\\(verse\\|synopsis\\)\\]$/,/^$/ {\n     ++\t\t-E '/^\\[(verse|synopsis)\\]$/,/^$/ {\n       \t\t\t/^$/d;\n      -\t\t\t/^\\[verse\\]$/d;\n      -\t\t\ts/_//g;\n      -\t\t\ts/++//g;\n      -\t\t\ts/`//g;\n     -+\t\t\t/^\\[\\(verse\\|synopsis\\)\\]$/d;\n     - \t\t\ts/{litdd}/--/g;\n     - \t\t\ts/'\\''\\(git[ a-z-]*\\)'\\''/\\1/g;\n     +-\t\t\ts/{litdd}/--/g;\n     +-\t\t\ts/'\\''\\(git[ a-z-]*\\)'\\''/\\1/g;\n     ++\t\t\t/^\\[(verse|synopsis)\\]$/d;\n     ++\t\t\ts/\\{litdd\\}/--/g;\n     ++\t\t\ts/'\\''(git[ a-z-]*)'\\''/\\1/g;\n       \n     + \t\t\tp;\n     + \t\t}' \\\n 2:  b0547422e5c = 2:  b6387bef40d doc: update the guidelines to reflect the current formatting rules\n 3:  3bcbe455747 ! 3:  2a61e0945de doc: apply synopsis simplification on git-clone and git-init\n     @@ Documentation/git-clone.txt: git-clone - Clone a repository into a new directory\n      -\t  [`-l`] [`-s`] [`--no-hardlinks`] [`-q`] [`-n`] [`--bare`] [`--mirror`]\n      -\t  [`-o` _<name>_] [`-b` _<name>_] [`-u` _<upload-pack>_] [`--reference` _<repository>_]\n      -\t  [`--dissociate`] [`--separate-git-dir` _<git-dir>_]\n     --\t  [`--depth` _<depth>_] [`--`[`no-`]`single-branch`] [`--no-tags`]\n     --\t  [++--recurse-submodules++[++=++__<pathspec>__]] [`--`[`no-`]`shallow-submodules`]\n     --\t  [`--`[`no-`]`remote-submodules`] [`--jobs` _<n>_] [`--sparse`] [`--`[`no-`]`reject-shallow`]\n     +-\t  [`--depth` _<depth>_] [`--`[`no-`]{empty}`single-branch`] [`--no-tags`]\n     +-\t  [++--recurse-submodules++[++=++__<pathspec>__]] [++--++[++no-++]{empty}++shallow-submodules++]\n     +-\t  [`--`[`no-`]{empty}`remote-submodules`] [`--jobs` _<n>_] [`--sparse`] [`--`[`no-`]{empty}`reject-shallow`]\n      -\t  [++--filter=++__<filter-spec>__] [`--also-filter-submodules`]] [`--`] _<repository>_\n     --\t  [__<directory>__]\n     +-\t  [_<directory>_]\n      +[synopsis]\n      +git clone [--template=<template-directory>]\n      +\t  [-l] [-s] [--no-hardlinks] [-q] [-n] [--bare] [--mirror]\n     @@ Documentation/git-init.txt: git-init - Create an empty Git repository or reiniti\n      -\t  [`--separate-git-dir` _<git-dir>_] [++--object-format=++__<format>__]\n      -\t  [++--ref-format=++__<format>__]\n      -\t  [`-b` _<branch-name>_ | ++--initial-branch=++__<branch-name>__]\n     --\t  [`--shared`[++=++__<permissions>__]] [__<directory>__]\n     +-\t  [++--shared++[++=++__<permissions>__]] [_<directory>_]\n      +[synopsis]\n      +git init [-q | --quiet] [--bare] [--template=<template-directory>]\n      +\t [--separate-git-dir <git-dir>] [--object-format=<format>]\n\n-- \ngitgitgadget\n"},{"id":"499296","messageId":"aba144f4ff3fe204aa76864c8d439f39719e4bab.1721855179.git.gitgitgadget@gmail.com","threadId":"61831","inReplyTo":"pull.1766.v2.git.1721855179.gitgitgadget@gmail.com","subject":"[PATCH v2 1/3] doc: introduce a synopsis custom paragraph attribute","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-07-24T21:06:17Z","receivedAt":"2024-07-24T21:06:23Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n\nIn order to follow the common manpage usage, the synopsis of the\ncommands needs to be heavily typeset. A first try was performed with\nusing native markup, but it turned out to make the document source\nalmost unreadable, difficult to write and prone to mistakes with\nunwanted Asciidoc's role attributes.\n\nIn order to both simplify the writer's task and obtain a consistant\ntypesetting in the synopsis, a custom 'synopsis' paragraph type is\ncreated and the backends of asciidoc and asciidoctor take in charge to\ncorrectly add the required typesetting.\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n Documentation/asciidoc.conf             | 12 ++++++++++++\n Documentation/asciidoctor-extensions.rb | 17 +++++++++++++++++\n t/t0450-txt-doc-vs-help.sh              | 11 ++++-------\n 3 files changed, 33 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf\nindex 60f76f43edab..08111e98ab33 100644\n--- a/Documentation/asciidoc.conf\n+++ b/Documentation/asciidoc.conf\n@@ -57,3 +57,15 @@ git-relative-html-prefix=\n [linkgit-inlinemacro]\n <a href=\"{git-relative-html-prefix}{target}.html\">{target}{0?({0})}</a>\n endif::backend-xhtml11[]\n+\n+ifdef::backend-docbook[]\n+ifdef::doctype-manpage[]\n+[paradef-default]\n+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'\"\n+endif::doctype-manpage[]\n+endif::backend-docbook[]\n+\n+ifdef::backend-xhtml11[]\n+[paradef-default]\n+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'\"\n+endif::backend-xhtml11[]\ndiff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb\nindex d906a008039c..8c7612743504 100644\n--- a/Documentation/asciidoctor-extensions.rb\n+++ b/Documentation/asciidoctor-extensions.rb\n@@ -39,10 +39,27 @@ module Git\n         output\n       end\n     end\n+\n+    class SynopsisBlock < Asciidoctor::Extensions::BlockProcessor\n+\n+      use_dsl\n+      named :synopsis\n+      parse_content_as :simple\n+\n+      def process parent, reader, attrs\n+        outlines = reader.lines.map do |l|\n+          l.gsub(/([\\[\\] |()>]|^)([-a-zA-Z0-9:+=.]+)/, '\\\\1{empty}`\\\\2`{empty}')\n+           .gsub(/(<[-a-zA-Z0-9.]+>)/, '__\\\\1__')\n+           .gsub(']', ']{empty}')\n+        end\n+        create_block parent, :verse, outlines, attrs\n+      end\n+    end\n   end\n end\n \n Asciidoctor::Extensions.register do\n   inline_macro Git::Documentation::LinkGitProcessor, :linkgit\n+  block Git::Documentation::SynopsisBlock\n   postprocessor Git::Documentation::DocumentPostProcessor\n end\ndiff --git a/t/t0450-txt-doc-vs-help.sh b/t/t0450-txt-doc-vs-help.sh\nindex 69917d7b8459..f99a69ae1b74 100755\n--- a/t/t0450-txt-doc-vs-help.sh\n+++ b/t/t0450-txt-doc-vs-help.sh\n@@ -56,14 +56,11 @@ txt_to_synopsis () {\n \tfi &&\n \tb2t=\"$(builtin_to_txt \"$builtin\")\" &&\n \tsed -n \\\n-\t\t-e '/^\\[verse\\]$/,/^$/ {\n+\t\t-E '/^\\[(verse|synopsis)\\]$/,/^$/ {\n \t\t\t/^$/d;\n-\t\t\t/^\\[verse\\]$/d;\n-\t\t\ts/_//g;\n-\t\t\ts/++//g;\n-\t\t\ts/`//g;\n-\t\t\ts/{litdd}/--/g;\n-\t\t\ts/'\\''\\(git[ a-z-]*\\)'\\''/\\1/g;\n+\t\t\t/^\\[(verse|synopsis)\\]$/d;\n+\t\t\ts/\\{litdd\\}/--/g;\n+\t\t\ts/'\\''(git[ a-z-]*)'\\''/\\1/g;\n \n \t\t\tp;\n \t\t}' \\\n-- \ngitgitgadget\n\n"},{"id":"499297","messageId":"b6387bef40d08395313bb826a6f7cdf459f4c5f4.1721855179.git.gitgitgadget@gmail.com","threadId":"61831","inReplyTo":"pull.1766.v2.git.1721855179.gitgitgadget@gmail.com","subject":"[PATCH v2 2/3] doc: update the guidelines to reflect the current formatting rules","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-07-24T21:06:18Z","receivedAt":"2024-07-24T21:06:24Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n Documentation/CodingGuidelines | 34 +++++++++++++++++++---------------\n 1 file changed, 19 insertions(+), 15 deletions(-)\n\ndiff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines\nindex 1d92b2da03e8..4d59e8f89ec8 100644\n--- a/Documentation/CodingGuidelines\n+++ b/Documentation/CodingGuidelines\n@@ -760,56 +760,60 @@ Markup:\n \n Synopsis Syntax\n \n- Syntax grammar is formatted neither as literal nor as placeholder.\n+ The synopsis (a paragraph with [synopsis] attribute) is automatically\n+ formatted by the toolchain and does not need typesetting.\n \n  A few commented examples follow to provide reference when writing or\n  modifying command usage strings and synopsis sections in the manual\n  pages:\n \n  Possibility of multiple occurrences is indicated by three dots:\n-   _<file>_...\n+   <file>...\n    (One or more of <file>.)\n \n  Optional parts are enclosed in square brackets:\n-   [_<file>_...]\n+   [<file>...]\n    (Zero or more of <file>.)\n \n-   ++--exec-path++[++=++__<path>__]\n+ An optional parameter needs to be typeset with unconstrained pairs\n+   [<repository>]\n+\n+   --exec-path[=<path>]\n    (Option with an optional argument.  Note that the \"=\" is inside the\n    brackets.)\n \n-   [_<patch>_...]\n+   [<patch>...]\n    (Zero or more of <patch>.  Note that the dots are inside, not\n    outside the brackets.)\n \n  Multiple alternatives are indicated with vertical bars:\n-   [`-q` | `--quiet`]\n-   [`--utf8` | `--no-utf8`]\n+   [-q | --quiet]\n+   [--utf8 | --no-utf8]\n \n  Use spacing around \"|\" token(s), but not immediately after opening or\n  before closing a [] or () pair:\n-   Do: [`-q` | `--quiet`]\n-   Don't: [`-q`|`--quiet`]\n+   Do: [-q | --quiet]\n+   Don't: [-q|--quiet]\n \n  Don't use spacing around \"|\" tokens when they're used to separate the\n  alternate arguments of an option:\n-    Do: ++--track++[++=++(`direct`|`inherit`)]`\n-    Don't: ++--track++[++=++(`direct` | `inherit`)]\n+    Do: --track[=(direct|inherit)]\n+    Don't: --track[=(direct | inherit)]\n \n  Parentheses are used for grouping:\n-   [(_<rev>_ | _<range>_)...]\n+   [(<rev>|<range>)...]\n    (Any number of either <rev> or <range>.  Parens are needed to make\n    it clear that \"...\" pertains to both <rev> and <range>.)\n \n-   [(`-p` _<parent>_)...]\n+   [(-p <parent>)...]\n    (Any number of option -p, each with one <parent> argument.)\n \n-   `git remote set-head` _<name>_ (`-a` | `-d` | _<branch>_)\n+   git remote set-head <name> (-a|-d|<branch>)\n    (One and only one of \"-a\", \"-d\" or \"<branch>\" _must_ (no square\n    brackets) be provided.)\n \n  And a somewhat more contrived example:\n-   `--diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]`\n+   --diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]\n    Here \"=\" is outside the brackets, because \"--diff-filter=\" is a\n    valid usage.  \"*\" has its own pair of brackets, because it can\n    (optionally) be specified only when one or more of the letters is\n-- \ngitgitgadget\n\n"},{"id":"499298","messageId":"2a61e0945deb204547a930614eec431b50b1bd1d.1721855179.git.gitgitgadget@gmail.com","threadId":"61831","inReplyTo":"pull.1766.v2.git.1721855179.gitgitgadget@gmail.com","subject":"[PATCH v2 3/3] doc: apply synopsis simplification on git-clone and git-init","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-07-24T21:06:19Z","receivedAt":"2024-07-24T21:06:25Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n\nWith the new synopsis formatting backend, no special asciidoc markup\nis needed.\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n Documentation/git-clone.txt | 20 ++++++++++----------\n Documentation/git-init.txt  | 12 ++++++------\n 2 files changed, 16 insertions(+), 16 deletions(-)\n\ndiff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt\nindex 8e925db7e9c6..53b1c3e23f75 100644\n--- a/Documentation/git-clone.txt\n+++ b/Documentation/git-clone.txt\n@@ -8,16 +8,16 @@ git-clone - Clone a repository into a new directory\n \n SYNOPSIS\n --------\n-[verse]\n-`git clone` [++--template=++__<template-directory>__]\n-\t  [`-l`] [`-s`] [`--no-hardlinks`] [`-q`] [`-n`] [`--bare`] [`--mirror`]\n-\t  [`-o` _<name>_] [`-b` _<name>_] [`-u` _<upload-pack>_] [`--reference` _<repository>_]\n-\t  [`--dissociate`] [`--separate-git-dir` _<git-dir>_]\n-\t  [`--depth` _<depth>_] [`--`[`no-`]{empty}`single-branch`] [`--no-tags`]\n-\t  [++--recurse-submodules++[++=++__<pathspec>__]] [++--++[++no-++]{empty}++shallow-submodules++]\n-\t  [`--`[`no-`]{empty}`remote-submodules`] [`--jobs` _<n>_] [`--sparse`] [`--`[`no-`]{empty}`reject-shallow`]\n-\t  [++--filter=++__<filter-spec>__] [`--also-filter-submodules`]] [`--`] _<repository>_\n-\t  [_<directory>_]\n+[synopsis]\n+git clone [--template=<template-directory>]\n+\t  [-l] [-s] [--no-hardlinks] [-q] [-n] [--bare] [--mirror]\n+\t  [-o <name>] [-b <name>] [-u <upload-pack>] [--reference <repository>]\n+\t  [--dissociate] [--separate-git-dir <git-dir>]\n+\t  [--depth <depth>] [--[no-]single-branch] [--no-tags]\n+\t  [--recurse-submodules[=<pathspec>]] [--[no-]shallow-submodules]\n+\t  [--[no-]remote-submodules] [--jobs <n>] [--sparse] [--[no-]reject-shallow]\n+\t  [--filter=<filter-spec>] [--also-filter-submodules]] [--] <repository>\n+\t  [<directory>]\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-init.txt b/Documentation/git-init.txt\nindex daff93bd164b..eba67fdde83f 100644\n--- a/Documentation/git-init.txt\n+++ b/Documentation/git-init.txt\n@@ -8,12 +8,12 @@ git-init - Create an empty Git repository or reinitialize an existing one\n \n SYNOPSIS\n --------\n-[verse]\n-`git init` [`-q` | `--quiet`] [`--bare`] [++--template=++__<template-directory>__]\n-\t  [`--separate-git-dir` _<git-dir>_] [++--object-format=++__<format>__]\n-\t  [++--ref-format=++__<format>__]\n-\t  [`-b` _<branch-name>_ | ++--initial-branch=++__<branch-name>__]\n-\t  [++--shared++[++=++__<permissions>__]] [_<directory>_]\n+[synopsis]\n+git init [-q | --quiet] [--bare] [--template=<template-directory>]\n+\t [--separate-git-dir <git-dir>] [--object-format=<format>]\n+\t [--ref-format=<format>]\n+\t [-b <branch-name> | --initial-branch=<branch-name>]\n+\t [--shared[=<permissions>]] [<directory>]\n \n \n DESCRIPTION\n-- \ngitgitgadget\n"},{"id":"499306","messageId":"xmqqcyn2s7ob.fsf@gitster.g","threadId":"61831","inReplyTo":"pull.1766.v2.git.1721855179.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 0/3] doc: introducing synopsis para","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-07-24T23:15:48Z","receivedAt":"2024-07-24T23:15:57Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Jean-Noël Avila via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n> Following several issues with the way the formatting of synopsis is done in\n> the manpages that were recently reworked, this patch series introduces the\n> processing of a new custom paragraph attribute 'synopsis'.\n\nThe rendered result looks OK but the source being just like what we\nwould write in plain text files without any extra mark-up makes it\nlook quite nice.\n\nI wonder what we want to do with some oddballs, like git-shortlog\nthat uses \"|\" not as an alternative but literally a pipe (i.e. \"feed\nthe output of this other command via a pipe to this command\"),\nthough.\n\n    git log --pretty=short | git shortlog [<options>]\n\nThere may be also some page that indicates \"this command takes its\ninput from its standard input\" by using something like\n\n    git cmd [--foo] [--bar] <input-file\n\nwhich we may need to think how to handle.  The easiest way out may\nbe to say \"don't do these to indicate/force where the input comes\nfrom\".  I dunno.\n\nThanks.\n\n\n"},{"id":"499331","messageId":"13562033.uLZWGnKmhe@cayenne","threadId":"61831","inReplyTo":"xmqqcyn2s7ob.fsf@gitster.g","subject":"Re: [PATCH v2 0/3] doc: introducing synopsis para","fromName":"Jean-Noël AVILA","fromEmail":"jn.avila@free.fr","sentAt":"2024-07-25T12:15:30Z","receivedAt":"2024-07-25T12:15:40Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"On Thursday, 25 July 2024 01:15:48 CEST Junio C Hamano wrote:\n> \"Jean-Noël Avila via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n> \n> > Following several issues with the way the formatting of synopsis is done \nin\n> > the manpages that were recently reworked, this patch series introduces the\n> > processing of a new custom paragraph attribute 'synopsis'.\n> \n> The rendered result looks OK but the source being just like what we\n> would write in plain text files without any extra mark-up makes it\n> look quite nice.\n> \n> I wonder what we want to do with some oddballs, like git-shortlog\n> that uses \"|\" not as an alternative but literally a pipe (i.e. \"feed\n> the output of this other command via a pipe to this command\"),\n> though.\n> \n>     git log --pretty=short | git shortlog [<options>]\n\nI must confess that while reviewing my patch, by switching all [verse] to \n[synopsis] , I looked at this line and understood the pipe as an alternative \nfrom the grammar, not as a shell pipe. I also noted a few spots where the \ngrammar may be misinterpreted e.g. parenthesis in git-grep.\n\nIn theory the typesetting should tell the keyword apart from the grammar, but \nfor signs such as pipes and parenthesis  the rendering does not change enough.\n\n> \n> There may be also some page that indicates \"this command takes its\n> input from its standard input\" by using something like\n> \n>     git cmd [--foo] [--bar] <input-file\n> \n> which we may need to think how to handle.  The easiest way out may\n> be to say \"don't do these to indicate/force where the input comes\n> from\".  I dunno.\n> \n\nThe form \n\n    git cmd  [--foo] [--bar] < <input-file>\n\nis completely acceptable , would render correctly and would remove the use of \nthe pipe. The thing is that this pipe isn't even part of the command. It is \njust an example. Maybe it should not appear in the synopsis at all.\n\nFor keyword signs that are already used in expressing the grammar, we could \nquote the sign to indicate that it is a keyword : \"(\" .\n\nThanks\n\n\n\n\n\n"},{"id":"499350","messageId":"xmqqy15pjxlt.fsf@gitster.g","threadId":"61831","inReplyTo":"13562033.uLZWGnKmhe@cayenne","subject":"Re: [PATCH v2 0/3] doc: introducing synopsis para","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-07-25T15:32:46Z","receivedAt":"2024-07-25T15:32:49Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jean-Noël AVILA <jn.avila@free.fr> writes:\n\n> The form \n>\n>     git cmd  [--foo] [--bar] < <input-file>\n>\n> is completely acceptable , would render correctly and would remove the use of \n> the pipe.\n\nNice.  I was afraid that it might be interpreted as a placeholder\nwhose description is \"<input-file\" ;-)\n\n> The thing is that this pipe isn't even part of the command. It is \n> just an example. Maybe it should not appear in the synopsis at all.\n\nHistorically the command was designed to read from \"git log\" as its\nupstream and nothing else, which was where that sample command in\nthe synopsis originated, but it is unusual to spell out the upstream\n(or downstream for that matter) of a pipe even when the command is\noften used inside a pipeline in the synopsis section.\n\n> For keyword signs that are already used in expressing the grammar, we could \n> quote the sign to indicate that it is a keyword : \"(\" .\n"},{"id":"500599","messageId":"pull.1766.v3.git.1723389612.gitgitgadget@gmail.com","threadId":"61831","inReplyTo":"pull.1766.v2.git.1721855179.gitgitgadget@gmail.com","subject":"[PATCH v3 0/3] doc: introducing synopsis para","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-08-11T15:20:09Z","receivedAt":"2024-08-11T15:20:16Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"Following several issues with the way the formatting of synopsis is done in\nthe manpages that were recently reworked, this patch series introduces the\nprocessing of a new custom paragraph attribute 'synopsis'. Additionally, as\ns macro is introduce to apply the same rules freely in the text.\n\nThis extension is added to asciidoc and asciidoctor and lets write the\nsynopsis of the commands without any typeset. The git-init and git-clone\nmanpages are converted to this new system.\n\nChanges since V1:\n\n * switch to sed for asciidoc filter and refine the regex for support under\n   macOS\n\nChanges since V2:\n\n * introduce the s macro to freely apply synopsis styling wherever needed,\n   without formatting hassle.\n\nJean-Noël Avila (3):\n  doc: introduce a synopsis custom paragraph attribute\n  doc: update the guidelines to reflect the current formatting rules\n  doc: apply synopsis simplification on git-clone and git-init\n\n Documentation/CodingGuidelines          | 54 +++++++++---------\n Documentation/asciidoc.conf             | 21 ++++++-\n Documentation/asciidoctor-extensions.rb | 33 +++++++++++\n Documentation/git-clone.txt             | 76 ++++++++++++-------------\n Documentation/git-init.txt              | 33 +++++------\n Documentation/urls.txt                  | 26 ++++-----\n t/t0450-txt-doc-vs-help.sh              | 11 ++--\n 7 files changed, 150 insertions(+), 104 deletions(-)\n\n\nbase-commit: ad57f148c6b5f8735b62238dda8f571c582e0e54\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-1766%2Fjnavila%2Fdoc_synopsis_para-v3\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1766/jnavila/doc_synopsis_para-v3\nPull-Request: https://github.com/gitgitgadget/git/pull/1766\n\nRange-diff vs v2:\n\n 1:  aba144f4ff3 ! 1:  0d7c1dd8f26 doc: introduce a synopsis custom paragraph attribute\n     @@ Commit message\n          created and the backends of asciidoc and asciidoctor take in charge to\n          correctly add the required typesetting.\n      \n     +    additionally, a 's' macro ('s' standing for synopsis) is introduced to\n     +    allow writers to freely apply automatic styling whereever required.\n     +\n          Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>\n      \n       ## Documentation/asciidoc.conf ##\n     -@@ Documentation/asciidoc.conf: git-relative-html-prefix=\n     +@@\n     + \n     + [macros]\n     + (?su)[\\\\]?(?P<name>linkgit):(?P<target>\\S*?)\\[(?P<attrlist>.*?)\\]=\n     +-\n     ++(?su)[\\\\]?(?P<name>s):(?P<target>\\S*?)\\[\"(?P<attrlist>.*?)\"\\]=\n     + [attributes]\n     + asterisk=&#42;\n     + plus=&#43;\n     +@@ Documentation/asciidoc.conf: ifdef::backend-docbook[]\n     + {0#<citerefentry>}\n     + {0#<refentrytitle>{target}</refentrytitle><manvolnum>{0}</manvolnum>}\n     + {0#</citerefentry>}\n     ++\n     ++[s-inlinemacro]\n     ++{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}'))}\n     + endif::backend-docbook[]\n     + \n     + ifdef::backend-docbook[]\n     +@@ Documentation/asciidoc.conf: ifdef::backend-xhtml11[]\n     + git-relative-html-prefix=\n       [linkgit-inlinemacro]\n       <a href=\"{git-relative-html-prefix}{target}.html\">{target}{0?({0})}</a>\n     - endif::backend-xhtml11[]\n     ++\n     ++[s-inlinemacro]\n     ++{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}'))}\n     ++\n     ++endif::backend-xhtml11[]\n      +\n      +ifdef::backend-docbook[]\n      +ifdef::doctype-manpage[]\n      +[paradef-default]\n     -+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'\"\n     ++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'\"\n      +endif::doctype-manpage[]\n      +endif::backend-docbook[]\n      +\n      +ifdef::backend-xhtml11[]\n      +[paradef-default]\n     -+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'\"\n     -+endif::backend-xhtml11[]\n     ++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'\"\n     + endif::backend-xhtml11[]\n      \n       ## Documentation/asciidoctor-extensions.rb ##\n     +@@ Documentation/asciidoctor-extensions.rb: module Git\n     +       end\n     +     end\n     + \n     ++    class SynopsisMacroProcessor < Asciidoctor::Extensions::InlineMacroProcessor\n     ++      use_dsl\n     ++\n     ++      named :s\n     ++      match(/s:\\[\"(.+?)\"\\]/)\n     ++\n     ++      def process(parent, target, attrs)\n     ++        l = target.gsub(/([\\[\\] |()]|^|&gt;)(\\.?[-a-zA-Z0-9:+=~@,\\/]+\\.?)/, '\\1{empty}`\\2`{empty}')\n     ++                  .gsub(/(&lt;[-a-zA-Z0-9.]+&gt;)/, '__\\\\1__')\n     ++                  .gsub(']', ']{empty}')\n     ++\n     ++        create_inline parent, :quoted, l, attributes: { 'subs' => :normal }\n     ++      end\n     ++    end\n     ++\n     +     class DocumentPostProcessor < Asciidoctor::Extensions::Postprocessor\n     +       def process document, output\n     +         if document.basebackend? 'docbook'\n      @@ Documentation/asciidoctor-extensions.rb: module Git\n               output\n             end\n     @@ Documentation/asciidoctor-extensions.rb: module Git\n      +\n      +      def process parent, reader, attrs\n      +        outlines = reader.lines.map do |l|\n     -+          l.gsub(/([\\[\\] |()>]|^)([-a-zA-Z0-9:+=.]+)/, '\\\\1{empty}`\\\\2`{empty}')\n     ++          l.gsub(/([\\[\\] |()>]|^)([-a-zA-Z0-9:+=]+)/, '\\1{empty}`\\2`{empty}')\n      +           .gsub(/(<[-a-zA-Z0-9.]+>)/, '__\\\\1__')\n      +           .gsub(']', ']{empty}')\n      +        end\n     @@ Documentation/asciidoctor-extensions.rb: module Git\n       \n       Asciidoctor::Extensions.register do\n         inline_macro Git::Documentation::LinkGitProcessor, :linkgit\n     ++  inline_macro Git::Documentation::SynopsisMacroProcessor\n      +  block Git::Documentation::SynopsisBlock\n         postprocessor Git::Documentation::DocumentPostProcessor\n       end\n 2:  b6387bef40d ! 2:  92f3121cf4e doc: update the guidelines to reflect the current formatting rules\n     @@ Commit message\n      \n       ## Documentation/CodingGuidelines ##\n      @@ Documentation/CodingGuidelines: Markup:\n     +    _<key-id>_\n     + \n     +  When literal and placeholders are mixed, each markup is applied for\n     +- each sub-entity. If they are stuck, a special markup, called\n     +- unconstrained formatting is required.\n     +- Unconstrained formating for placeholders is __<like-this>__\n     +- Unconstrained formatting for literal formatting is ++like this++\n     +-   `--jobs` _<n>_\n     +-   ++--sort=++__<key>__\n     +-   __<directory>__++/.git++\n     +-   ++remote.++__<name>__++.mirror++\n     +-\n     +- caveat: ++ unconstrained format is not verbatim and may expand\n     +- content. Use Asciidoc escapes inside them.\n     ++ each sub-entity. If the formatting is becoming too hairy, you can use the\n     ++ s:[\"foo\"] formatting macro and let it format the groups for you.\n     ++   `--jobs` _<n>_ or s:[\"--jobs <n>\"]\n     ++   s:[\"--sort=<key>\n     ++   s:[\"<directory>/.git\"]\n     ++   s:[\"remote.<name>.mirror\"]\n     ++   s:[\"ssh://[<user>@]<host>[:<port>]/<path-to-git-repo>\"]\n     ++\n     ++Note that the double-quotes are required by the macro.\n       \n       Synopsis Syntax\n       \n 3:  2a61e0945de ! 3:  02406b91894 doc: apply synopsis simplification on git-clone and git-init\n     @@ Documentation/git-clone.txt: git-clone - Clone a repository into a new directory\n       \n       DESCRIPTION\n       -----------\n     +@@ Documentation/git-clone.txt: prevent the unintentional copying of files by dereferencing the symbolic\n     + links.\n     + +\n     + *NOTE*: this operation can race with concurrent modification to the\n     +-source repository, similar to running `cp -r src dst` while modifying\n     +-`src`.\n     ++source repository, similar to running s:[\"cp -r <src> <dst>\"] while modifying\n     ++_<src>_.\n     + \n     + `--no-hardlinks`::\n     + \tForce the cloning process from a repository on a local\n     +@@ Documentation/git-clone.txt: If you want to break the dependency of a repository cloned with `--shared` on\n     + its source repository, you can simply run `git repack -a` to copy all\n     + objects from the source repository into a pack in the cloned repository.\n     + \n     +-`--reference`[`-if-able`] _<repository>_::\n     ++s:[\"--reference[-if-able] <repository>\"]::\n     + \tIf the reference _<repository>_ is on the local machine,\n     + \tautomatically setup `.git/objects/info/alternates` to\n     + \tobtain objects from the reference _<repository>_.  Using\n     +@@ Documentation/git-clone.txt: objects from the source repository into a pack in the cloned repository.\n     + \tis specified. This flag forces progress status even if the\n     + \tstandard error stream is not directed to a terminal.\n     + \n     +-++--server-option=++__<option>__::\n     ++s:[\"--server-option=<option>\"]::\n     + \tTransmit the given string to the server when communicating using\n     + \tprotocol version 2.  The given string must not contain a NUL or LF\n     + \tcharacter.  The server's handling of server options, including\n     + \tunknown ones, is server-specific.\n     +-\tWhen multiple ++--server-option=++__<option>__ are given, they are all\n     ++\tWhen multiple s:[\"--server-option=<option>\"] are given, they are all\n     + \tsent to the other side in the order listed on the command line.\n     + \n     + `-n`::\n     + `--no-checkout`::\n     +-\tNo checkout of HEAD is performed after the clone is complete.\n     ++\tNo checkout of `HEAD` is performed after the clone is complete.\n     + \n     + `--`[`no-`]`reject-shallow`::\n     + \tFail if the source repository is a shallow repository.\n     +@@ Documentation/git-clone.txt: objects from the source repository into a pack in the cloned repository.\n     + `--bare`::\n     + \tMake a 'bare' Git repository.  That is, instead of\n     + \tcreating _<directory>_ and placing the administrative\n     +-\tfiles in _<directory>_`/.git`, make the _<directory>_\n     ++\tfiles in s:[\"<directory>/.git\"], make the _<directory>_\n     + \titself the `$GIT_DIR`. This obviously implies the `--no-checkout`\n     + \tbecause there is nowhere to check out the working tree.\n     + \tAlso the branch heads at the remote are copied directly\n     +@@ Documentation/git-clone.txt: objects from the source repository into a pack in the cloned repository.\n     + \tlinkgit:git-sparse-checkout[1] command can be used to grow the\n     + \tworking directory as needed.\n     + \n     +-++--filter=++__<filter-spec>__::\n     ++s:[\"--filter=<filter-spec>\"]::\n     + \tUse the partial clone feature and request that the server sends\n     + \ta subset of reachable objects according to a given object filter.\n     + \tWhen using `--filter`, the supplied _<filter-spec>_ is used for\n     + \tthe partial clone filter. For example, `--filter=blob:none` will\n     + \tfilter out all blobs (file contents) until needed by Git. Also,\n     +-\t++--filter=blob:limit=++__<size>__ will filter out all blobs of size\n     ++\ts:[\"--filter=blob:limit=<size>\"] will filter out all blobs of size\n     + \tat least _<size>_. For more details on filter specifications, see\n     + \tthe `--filter` option in linkgit:git-rev-list[1].\n     + \n     +@@ Documentation/git-clone.txt: objects from the source repository into a pack in the cloned repository.\n     + \n     + `-b` _<name>_::\n     + `--branch` _<name>_::\n     +-\tInstead of pointing the newly created HEAD to the branch pointed\n     +-\tto by the cloned repository's HEAD, point to _<name>_ branch\n     ++\tInstead of pointing the newly created `HEAD` to the branch pointed\n     ++\tto by the cloned repository's `HEAD`, point to _<name>_ branch\n     + \tinstead. In a non-bare repository, this is the branch that will\n     + \tbe checked out.\n     +-\t`--branch` can also take tags and detaches the HEAD at that commit\n     ++\t`--branch` can also take tags and detaches the `HEAD` at that commit\n     + \tin the resulting repository.\n     + \n     + `-u` _<upload-pack>_::\n     +@@ Documentation/git-clone.txt: objects from the source repository into a pack in the cloned repository.\n     + \tvia ssh, this specifies a non-default path for the command\n     + \trun on the other end.\n     + \n     +-++--template=++__<template-directory>__::\n     ++s:[\"--template=<template-directory>\"]::\n     + \tSpecify the directory from which templates will be used;\n     + \t(See the \"TEMPLATE DIRECTORY\" section of linkgit:git-init[1].)\n     + \n     +-`-c` __<key>__++=++__<value>__::\n     +-`--config` __<key>__++=++__<value>__::\n     ++`-c` s:[\"<key>=<value>\"]::\n     ++`--config` s:[\"<key>=<value>\"]::\n     + \tSet a configuration variable in the newly-created repository;\n     + \tthis takes effect immediately after the repository is\n     + \tinitialized, but before the remote history is fetched or any\n     +@@ Documentation/git-clone.txt: objects from the source repository into a pack in the cloned repository.\n     + Due to limitations of the current implementation, some configuration\n     + variables do not take effect until after the initial fetch and checkout.\n     + Configuration variables known to not take effect are:\n     +-++remote.++__<name>__++.mirror++ and ++remote.++__<name>__++.tagOpt++.  Use the\n     ++s:[\"remote.<name>.mirror\"] and s:[\"remote.<name>.tagOpt\"].  Use the\n     + corresponding `--mirror` and `--no-tags` options instead.\n     + \n     +-`--depth` _<depth>_::\n     ++s:[\"--depth <depth>\"]::\n     + \tCreate a 'shallow' clone with a history truncated to the\n     + \tspecified number of commits. Implies `--single-branch` unless\n     + \t`--no-single-branch` is given to fetch the histories near the\n     + \ttips of all branches. If you want to clone submodules shallowly,\n     + \talso pass `--shallow-submodules`.\n     + \n     +-++--shallow-since=++__<date>__::\n     ++s:[\"--shallow-since=<date>\"]::\n     + \tCreate a shallow clone with a history after the specified time.\n     + \n     +-++--shallow-exclude=++__<revision>__::\n     ++s:[\"--shallow-exclude=<revision>\"]::\n     + \tCreate a shallow clone with a history, excluding commits\n     + \treachable from a specified remote branch or tag.  This option\n     + \tcan be specified multiple times.\n     + \n     +-`--`[`no-`]`single-branch`::\n     ++s:[\"--[no-]single-branch\"]::\n     + \tClone only the history leading to the tip of a single branch,\n     + \teither specified by the `--branch` option or the primary\n     + \tbranch remote's `HEAD` points at.\n     +@@ Documentation/git-clone.txt: corresponding `--mirror` and `--no-tags` options instead.\n     + \n     + `--no-tags`::\n     + \tDon't clone any tags, and set\n     +-\t`remote.<remote>.tagOpt=--no-tags` in the config, ensuring\n     ++\ts:[\"remote.<remote>.tagOpt=--no-tags\"] in the config, ensuring\n     + \tthat future `git pull` and `git fetch` operations won't follow\n     + \tany tags. Subsequent explicit tag fetches will still work,\n     + \t(see linkgit:git-fetch[1]).\n     +@@ Documentation/git-clone.txt: maintain a branch with no references other than a single cloned\n     + branch. This is useful e.g. to maintain minimal clones of the default\n     + branch of some repository for search indexing.\n     + \n     +-`--recurse-submodules`[`=`{empty}__<pathspec>__]::\n     ++s:[\"--recurse-submodules[=<pathspec>]\"]::\n     + \tAfter the clone is created, initialize and clone submodules\n     + \twithin based on the provided _<pathspec>_.  If no _=<pathspec>_ is\n     + \tprovided, all submodules are initialized and cloned.\n     +@@ Documentation/git-clone.txt: branch of some repository for search indexing.\n     + +\n     + Submodules are initialized and cloned using their default settings. This is\n     + equivalent to running\n     +-`git submodule update --init --recursive <pathspec>` immediately after\n     ++s:[\"git submodule update --init --recursive <pathspec>\"] immediately after\n     + the clone is finished. This option is ignored if the cloned repository does\n     + not have a worktree/checkout (i.e. if any of `--no-checkout`/`-n`, `--bare`,\n     + or `--mirror` is given)\n     + \n     +-`--`[`no-`]`shallow-submodules`::\n     ++s:[\"--[no-]shallow-submodules\"]::\n     + \tAll submodules which are cloned will be shallow with a depth of 1.\n     + \n     +-`--`[`no-`]`remote-submodules`::\n     ++s:[\"--[no-]remote-submodules\"]::\n     + \tAll submodules which are cloned will use the status of the submodule's\n     + \tremote-tracking branch to update the submodule, rather than the\n     + \tsuperproject's recorded SHA-1. Equivalent to passing `--remote` to\n     + \t`git submodule update`.\n     + \n     +-`--separate-git-dir=`{empty}__<git-dir>__::\n     ++s:[\"--separate-git-dir=<git-dir>\"]::\n     + \tInstead of placing the cloned repository where it is supposed\n     + \tto be, place the cloned repository at the specified directory,\n     + \tthen make a filesystem-agnostic Git symbolic link to there.\n     + \tThe result is Git repository can be separated from working\n     + \ttree.\n     + \n     +-`--ref-format=`{empty}__<ref-format>__::\n     ++s:[\"--ref-format=<ref-format>\"]::\n     + \n     + Specify the given ref storage format for the repository. The valid values are:\n     + +\n     +@@ Documentation/git-clone.txt: _<directory>_::\n     + \tfor `host.xz:foo/.git`).  Cloning into an existing directory\n     + \tis only allowed if the directory is empty.\n     + \n     +-`--bundle-uri=`{empty}__<uri>__::\n     ++s:[\"--bundle-uri=<uri>\"]::\n     + \tBefore fetching from the remote, fetch a bundle from the given\n     + \t_<uri>_ and unbundle the data into the local repository. The refs\n     + \tin the bundle will be stored under the hidden `refs/bundle/*`\n      \n       ## Documentation/git-init.txt ##\n      @@ Documentation/git-init.txt: git-init - Create an empty Git repository or reinitialize an existing one\n     @@ Documentation/git-init.txt: git-init - Create an empty Git repository or reiniti\n       \n       \n       DESCRIPTION\n     +@@ Documentation/git-init.txt: directory with subdirectories for `objects`, `refs/heads`,\n     + commits will be created (see the `--initial-branch` option below\n     + for its name).\n     + \n     +-If the `$GIT_DIR` environment variable is set then it specifies a path\n     ++If the `GIT_DIR` environment variable is set then it specifies a path\n     + to use instead of `./.git` for the base of the repository.\n     + \n     + If the object storage directory is specified via the\n     +-`$GIT_OBJECT_DIRECTORY` environment variable then the sha1 directories\n     ++`GIT_OBJECT_DIRECTORY` environment variable then the sha1 directories\n     + are created underneath; otherwise, the default `$GIT_DIR/objects`\n     + directory is used.\n     + \n     +@@ Documentation/git-init.txt: Only print error and warning messages; all other output will be suppressed.\n     + Create a bare repository. If `GIT_DIR` environment is not set, it is set to the\n     + current working directory.\n     + \n     +-++--object-format=++__<format>__::\n     +-\n     ++s:[\"--object-format=<format>\"]::\n     + Specify the given object _<format>_ (hash algorithm) for the repository.  The valid\n     + values are `sha1` and (if enabled) `sha256`.  `sha1` is the default.\n     + +\n     + include::object-format-disclaimer.txt[]\n     + \n     +-++--ref-format=++__<format>__::\n     +-\n     ++s:[\"--ref-format=<format>\"]::\n     + Specify the given ref storage _<format>_ for the repository. The valid values are:\n     + +\n     + include::ref-storage-format.txt[]\n     + \n     +-++--template=++__<template-directory>__::\n     +-\n     ++s:[\"--template=<template-directory>\"]::\n     + Specify the directory from which templates will be used.  (See the \"TEMPLATE\n     + DIRECTORY\" section below.)\n     + \n     +-++--separate-git-dir=++__<git-dir>__::\n     +-\n     ++s:[\"--separate-git-dir=<git-dir>\"]::\n     + Instead of initializing the repository as a directory to either `$GIT_DIR` or\n     + `./.git/`, create a text file there containing the path to the actual\n     + repository.  This file acts as a filesystem-agnostic Git symbolic link to the\n     +@@ Documentation/git-init.txt: repository.\n     + If this is a reinitialization, the repository will be moved to the specified path.\n     + \n     + `-b` _<branch-name>_::\n     +-++--initial-branch=++__<branch-name>__::\n     +-\n     ++s:[\"--initial-branch=<branch-name>\"]::\n     + Use _<branch-name>_ for the initial branch in the newly created\n     + repository.  If not specified, fall back to the default name (currently\n     + `master`, but this is subject to change in the future; the name can be\n     + customized via the `init.defaultBranch` configuration variable).\n     + \n     +-++--shared++[++=++(`false`|`true`|`umask`|`group`|`all`|`world`|`everybody`|_<perm>_)]::\n     ++s:[\"--shared[=(false|true|umask|group|all|world|everybody|<perm>)]\"]::\n     + \n     + Specify that the Git repository is to be shared amongst several users.  This\n     + allows users belonging to the same group to push into that\n     +\n     + ## Documentation/urls.txt ##\n     +@@ Documentation/urls.txt: Git supports ssh, git, http, and https protocols (in addition, ftp\n     + and ftps can be used for fetching, but this is inefficient and\n     + deprecated; do not use them).\n     + \n     +-The native transport (i.e. git:// URL) does no authentication and\n     ++The native transport (i.e. `git://` URL) does no authentication and\n     + should be used with caution on unsecured networks.\n     + \n     + The following syntaxes may be used with them:\n     + \n     +-- ++ssh://++{startsb}__<user>__++@++{endsb}__<host>__{startsb}++:++__<port>__{endsb}++/++__<path-to-git-repo>__\n     +-- ++git://++__<host>__{startsb}:__<port>__{endsb}++/++__<path-to-git-repo>__\n     +-- ++http++{startsb}++s++{endsb}++://++__<host>__{startsb}++:++__<port>__{endsb}++/++__<path-to-git-repo>__\n     +-- ++ftp++{startsb}++s++{endsb}++://++__<host>__{startsb}++:++__<port>__{endsb}++/++__<path-to-git-repo>__\n     ++- s:[\"ssh://[<user>@]<host>[:<port>]/<path-to-git-repo>\"]\n     ++- s:[\"git://<host>[:<port>]/<path-to-git-repo>\"]\n     ++- s:[\"http[s]://<host>[:<port>]/<path-to-git-repo>\"]\n     ++- s:[\"ftp[s]://<host>[:<port>]/<path-to-git-repo>\"]\n     + \n     + An alternative scp-like syntax may also be used with the ssh protocol:\n     + \n     +-- {startsb}__<user>__++@++{endsb}__<host>__++:/++__<path-to-git-repo>__\n     ++- s:[\"[<user>@]<host>:/<path-to-git-repo>\"]\n     + \n     + This syntax is only recognized if there are no slashes before the\n     + first colon. This helps differentiate a local path that contains a\n     +@@ Documentation/urls.txt: colon. For example the local path `foo:bar` could be specified as an\n     + absolute path or `./foo:bar` to avoid being misinterpreted as an ssh\n     + url.\n     + \n     +-The ssh and git protocols additionally support ++~++__<username>__ expansion:\n     ++The ssh and git protocols additionally support s:[\"~<username>\"] expansion:\n     + \n     +-- ++ssh://++{startsb}__<user>__++@++{endsb}__<host>__{startsb}++:++__<port>__{endsb}++/~++__<user>__++/++__<path-to-git-repo>__\n     +-- ++git://++__<host>__{startsb}++:++__<port>__{endsb}++/~++__<user>__++/++__<path-to-git-repo>__\n     +-- {startsb}__<user>__++@++{endsb}__<host>__++:~++__<user>__++/++__<path-to-git-repo>__\n     ++- s:[\"ssh://[<user>@]<host>[:<port>]/~<user>/<path-to-git-repo>\"]\n     ++- s:[\"git://<host>[:<port>]/~<user>/<path-to-git-repo>\"]\n     ++- s:[\"[<user>@]<host>:~<user>/<path-to-git-repo>\"]\n     + \n     + For local repositories, also supported by Git natively, the following\n     + syntaxes may be used:\n     + \n     + - `/path/to/repo.git/`\n     +-- ++file:///path/to/repo.git/++\n     ++- `file:///path/to/repo.git/`\n     + \n     + ifndef::git-clone[]\n     + These two syntaxes are mostly equivalent, except when cloning, when\n     +@@ Documentation/urls.txt: endif::git-clone[]\n     + accept a suitable bundle file. See linkgit:git-bundle[1].\n     + \n     + When Git doesn't know how to handle a certain transport protocol, it\n     +-attempts to use the `remote-`{empty}__<transport>__ remote helper, if one\n     ++attempts to use the s:[\"remote-<transport>\"] remote helper, if one\n     + exists. To explicitly request a remote helper, the following syntax\n     + may be used:\n     + \n     +-- _<transport>_::__<address>__\n     ++- s:[\"<transport>::<address>\"]\n     + \n     + where _<address>_ may be a path, a server and path, or an arbitrary\n     + URL-like string recognized by the specific remote helper being\n\n-- \ngitgitgadget\n"},{"id":"500598","messageId":"0d7c1dd8f26f8bdfd93bcbf981b5bb6a6041f069.1723389612.git.gitgitgadget@gmail.com","threadId":"61831","inReplyTo":"pull.1766.v3.git.1723389612.gitgitgadget@gmail.com","subject":"[PATCH v3 1/3] doc: introduce a synopsis custom paragraph attribute","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-08-11T15:20:10Z","receivedAt":"2024-08-11T15:20:17Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n\nIn order to follow the common manpage usage, the synopsis of the\ncommands needs to be heavily typeset. A first try was performed with\nusing native markup, but it turned out to make the document source\nalmost unreadable, difficult to write and prone to mistakes with\nunwanted Asciidoc's role attributes.\n\nIn order to both simplify the writer's task and obtain a consistant\ntypesetting in the synopsis, a custom 'synopsis' paragraph type is\ncreated and the backends of asciidoc and asciidoctor take in charge to\ncorrectly add the required typesetting.\n\nadditionally, a 's' macro ('s' standing for synopsis) is introduced to\nallow writers to freely apply automatic styling whereever required.\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n Documentation/asciidoc.conf             | 21 +++++++++++++++-\n Documentation/asciidoctor-extensions.rb | 33 +++++++++++++++++++++++++\n t/t0450-txt-doc-vs-help.sh              | 11 +++------\n 3 files changed, 57 insertions(+), 8 deletions(-)\n\ndiff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf\nindex 60f76f43eda..04405453415 100644\n--- a/Documentation/asciidoc.conf\n+++ b/Documentation/asciidoc.conf\n@@ -9,7 +9,7 @@\n \n [macros]\n (?su)[\\\\]?(?P<name>linkgit):(?P<target>\\S*?)\\[(?P<attrlist>.*?)\\]=\n-\n+(?su)[\\\\]?(?P<name>s):(?P<target>\\S*?)\\[\"(?P<attrlist>.*?)\"\\]=\n [attributes]\n asterisk=&#42;\n plus=&#43;\n@@ -28,6 +28,9 @@ ifdef::backend-docbook[]\n {0#<citerefentry>}\n {0#<refentrytitle>{target}</refentrytitle><manvolnum>{0}</manvolnum>}\n {0#</citerefentry>}\n+\n+[s-inlinemacro]\n+{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}'))}\n endif::backend-docbook[]\n \n ifdef::backend-docbook[]\n@@ -56,4 +59,20 @@ ifdef::backend-xhtml11[]\n git-relative-html-prefix=\n [linkgit-inlinemacro]\n <a href=\"{git-relative-html-prefix}{target}.html\">{target}{0?({0})}</a>\n+\n+[s-inlinemacro]\n+{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}'))}\n+\n+endif::backend-xhtml11[]\n+\n+ifdef::backend-docbook[]\n+ifdef::doctype-manpage[]\n+[paradef-default]\n+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'\"\n+endif::doctype-manpage[]\n+endif::backend-docbook[]\n+\n+ifdef::backend-xhtml11[]\n+[paradef-default]\n+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'\"\n endif::backend-xhtml11[]\ndiff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb\nindex d906a008039..46cbbbbfd76 100644\n--- a/Documentation/asciidoctor-extensions.rb\n+++ b/Documentation/asciidoctor-extensions.rb\n@@ -24,6 +24,21 @@ module Git\n       end\n     end\n \n+    class SynopsisMacroProcessor < Asciidoctor::Extensions::InlineMacroProcessor\n+      use_dsl\n+\n+      named :s\n+      match(/s:\\[\"(.+?)\"\\]/)\n+\n+      def process(parent, target, attrs)\n+        l = target.gsub(/([\\[\\] |()]|^|&gt;)(\\.?[-a-zA-Z0-9:+=~@,\\/]+\\.?)/, '\\1{empty}`\\2`{empty}')\n+                  .gsub(/(&lt;[-a-zA-Z0-9.]+&gt;)/, '__\\\\1__')\n+                  .gsub(']', ']{empty}')\n+\n+        create_inline parent, :quoted, l, attributes: { 'subs' => :normal }\n+      end\n+    end\n+\n     class DocumentPostProcessor < Asciidoctor::Extensions::Postprocessor\n       def process document, output\n         if document.basebackend? 'docbook'\n@@ -39,10 +54,28 @@ module Git\n         output\n       end\n     end\n+\n+    class SynopsisBlock < Asciidoctor::Extensions::BlockProcessor\n+\n+      use_dsl\n+      named :synopsis\n+      parse_content_as :simple\n+\n+      def process parent, reader, attrs\n+        outlines = reader.lines.map do |l|\n+          l.gsub(/([\\[\\] |()>]|^)([-a-zA-Z0-9:+=]+)/, '\\1{empty}`\\2`{empty}')\n+           .gsub(/(<[-a-zA-Z0-9.]+>)/, '__\\\\1__')\n+           .gsub(']', ']{empty}')\n+        end\n+        create_block parent, :verse, outlines, attrs\n+      end\n+    end\n   end\n end\n \n Asciidoctor::Extensions.register do\n   inline_macro Git::Documentation::LinkGitProcessor, :linkgit\n+  inline_macro Git::Documentation::SynopsisMacroProcessor\n+  block Git::Documentation::SynopsisBlock\n   postprocessor Git::Documentation::DocumentPostProcessor\n end\ndiff --git a/t/t0450-txt-doc-vs-help.sh b/t/t0450-txt-doc-vs-help.sh\nindex 69917d7b845..f99a69ae1b7 100755\n--- a/t/t0450-txt-doc-vs-help.sh\n+++ b/t/t0450-txt-doc-vs-help.sh\n@@ -56,14 +56,11 @@ txt_to_synopsis () {\n \tfi &&\n \tb2t=\"$(builtin_to_txt \"$builtin\")\" &&\n \tsed -n \\\n-\t\t-e '/^\\[verse\\]$/,/^$/ {\n+\t\t-E '/^\\[(verse|synopsis)\\]$/,/^$/ {\n \t\t\t/^$/d;\n-\t\t\t/^\\[verse\\]$/d;\n-\t\t\ts/_//g;\n-\t\t\ts/++//g;\n-\t\t\ts/`//g;\n-\t\t\ts/{litdd}/--/g;\n-\t\t\ts/'\\''\\(git[ a-z-]*\\)'\\''/\\1/g;\n+\t\t\t/^\\[(verse|synopsis)\\]$/d;\n+\t\t\ts/\\{litdd\\}/--/g;\n+\t\t\ts/'\\''(git[ a-z-]*)'\\''/\\1/g;\n \n \t\t\tp;\n \t\t}' \\\n-- \ngitgitgadget\n\n"},{"id":"500600","messageId":"92f3121cf4e719d1bd6f85e3af454a3ea7547930.1723389612.git.gitgitgadget@gmail.com","threadId":"61831","inReplyTo":"pull.1766.v3.git.1723389612.gitgitgadget@gmail.com","subject":"[PATCH v3 2/3] doc: update the guidelines to reflect the current formatting rules","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-08-11T15:20:11Z","receivedAt":"2024-08-11T15:20:18Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n Documentation/CodingGuidelines | 54 ++++++++++++++++++----------------\n 1 file changed, 28 insertions(+), 26 deletions(-)\n\ndiff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines\nindex 1d92b2da03e..1c2d2ecbea9 100644\n--- a/Documentation/CodingGuidelines\n+++ b/Documentation/CodingGuidelines\n@@ -746,70 +746,72 @@ Markup:\n    _<key-id>_\n \n  When literal and placeholders are mixed, each markup is applied for\n- each sub-entity. If they are stuck, a special markup, called\n- unconstrained formatting is required.\n- Unconstrained formating for placeholders is __<like-this>__\n- Unconstrained formatting for literal formatting is ++like this++\n-   `--jobs` _<n>_\n-   ++--sort=++__<key>__\n-   __<directory>__++/.git++\n-   ++remote.++__<name>__++.mirror++\n-\n- caveat: ++ unconstrained format is not verbatim and may expand\n- content. Use Asciidoc escapes inside them.\n+ each sub-entity. If the formatting is becoming too hairy, you can use the\n+ s:[\"foo\"] formatting macro and let it format the groups for you.\n+   `--jobs` _<n>_ or s:[\"--jobs <n>\"]\n+   s:[\"--sort=<key>\n+   s:[\"<directory>/.git\"]\n+   s:[\"remote.<name>.mirror\"]\n+   s:[\"ssh://[<user>@]<host>[:<port>]/<path-to-git-repo>\"]\n+\n+Note that the double-quotes are required by the macro.\n \n Synopsis Syntax\n \n- Syntax grammar is formatted neither as literal nor as placeholder.\n+ The synopsis (a paragraph with [synopsis] attribute) is automatically\n+ formatted by the toolchain and does not need typesetting.\n \n  A few commented examples follow to provide reference when writing or\n  modifying command usage strings and synopsis sections in the manual\n  pages:\n \n  Possibility of multiple occurrences is indicated by three dots:\n-   _<file>_...\n+   <file>...\n    (One or more of <file>.)\n \n  Optional parts are enclosed in square brackets:\n-   [_<file>_...]\n+   [<file>...]\n    (Zero or more of <file>.)\n \n-   ++--exec-path++[++=++__<path>__]\n+ An optional parameter needs to be typeset with unconstrained pairs\n+   [<repository>]\n+\n+   --exec-path[=<path>]\n    (Option with an optional argument.  Note that the \"=\" is inside the\n    brackets.)\n \n-   [_<patch>_...]\n+   [<patch>...]\n    (Zero or more of <patch>.  Note that the dots are inside, not\n    outside the brackets.)\n \n  Multiple alternatives are indicated with vertical bars:\n-   [`-q` | `--quiet`]\n-   [`--utf8` | `--no-utf8`]\n+   [-q | --quiet]\n+   [--utf8 | --no-utf8]\n \n  Use spacing around \"|\" token(s), but not immediately after opening or\n  before closing a [] or () pair:\n-   Do: [`-q` | `--quiet`]\n-   Don't: [`-q`|`--quiet`]\n+   Do: [-q | --quiet]\n+   Don't: [-q|--quiet]\n \n  Don't use spacing around \"|\" tokens when they're used to separate the\n  alternate arguments of an option:\n-    Do: ++--track++[++=++(`direct`|`inherit`)]`\n-    Don't: ++--track++[++=++(`direct` | `inherit`)]\n+    Do: --track[=(direct|inherit)]\n+    Don't: --track[=(direct | inherit)]\n \n  Parentheses are used for grouping:\n-   [(_<rev>_ | _<range>_)...]\n+   [(<rev>|<range>)...]\n    (Any number of either <rev> or <range>.  Parens are needed to make\n    it clear that \"...\" pertains to both <rev> and <range>.)\n \n-   [(`-p` _<parent>_)...]\n+   [(-p <parent>)...]\n    (Any number of option -p, each with one <parent> argument.)\n \n-   `git remote set-head` _<name>_ (`-a` | `-d` | _<branch>_)\n+   git remote set-head <name> (-a|-d|<branch>)\n    (One and only one of \"-a\", \"-d\" or \"<branch>\" _must_ (no square\n    brackets) be provided.)\n \n  And a somewhat more contrived example:\n-   `--diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]`\n+   --diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]\n    Here \"=\" is outside the brackets, because \"--diff-filter=\" is a\n    valid usage.  \"*\" has its own pair of brackets, because it can\n    (optionally) be specified only when one or more of the letters is\n-- \ngitgitgadget\n\n"},{"id":"500601","messageId":"02406b9189455cd376c1a9dd065760759b7a02e1.1723389612.git.gitgitgadget@gmail.com","threadId":"61831","inReplyTo":"pull.1766.v3.git.1723389612.gitgitgadget@gmail.com","subject":"[PATCH v3 3/3] doc: apply synopsis simplification on git-clone and git-init","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-08-11T15:20:12Z","receivedAt":"2024-08-11T15:20:19Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n\nWith the new synopsis formatting backend, no special asciidoc markup\nis needed.\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n Documentation/git-clone.txt | 76 ++++++++++++++++++-------------------\n Documentation/git-init.txt  | 33 +++++++---------\n Documentation/urls.txt      | 26 ++++++-------\n 3 files changed, 65 insertions(+), 70 deletions(-)\n\ndiff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt\nindex 8e925db7e9c..f0d508ebf51 100644\n--- a/Documentation/git-clone.txt\n+++ b/Documentation/git-clone.txt\n@@ -8,16 +8,16 @@ git-clone - Clone a repository into a new directory\n \n SYNOPSIS\n --------\n-[verse]\n-`git clone` [++--template=++__<template-directory>__]\n-\t  [`-l`] [`-s`] [`--no-hardlinks`] [`-q`] [`-n`] [`--bare`] [`--mirror`]\n-\t  [`-o` _<name>_] [`-b` _<name>_] [`-u` _<upload-pack>_] [`--reference` _<repository>_]\n-\t  [`--dissociate`] [`--separate-git-dir` _<git-dir>_]\n-\t  [`--depth` _<depth>_] [`--`[`no-`]{empty}`single-branch`] [`--no-tags`]\n-\t  [++--recurse-submodules++[++=++__<pathspec>__]] [++--++[++no-++]{empty}++shallow-submodules++]\n-\t  [`--`[`no-`]{empty}`remote-submodules`] [`--jobs` _<n>_] [`--sparse`] [`--`[`no-`]{empty}`reject-shallow`]\n-\t  [++--filter=++__<filter-spec>__] [`--also-filter-submodules`]] [`--`] _<repository>_\n-\t  [_<directory>_]\n+[synopsis]\n+git clone [--template=<template-directory>]\n+\t  [-l] [-s] [--no-hardlinks] [-q] [-n] [--bare] [--mirror]\n+\t  [-o <name>] [-b <name>] [-u <upload-pack>] [--reference <repository>]\n+\t  [--dissociate] [--separate-git-dir <git-dir>]\n+\t  [--depth <depth>] [--[no-]single-branch] [--no-tags]\n+\t  [--recurse-submodules[=<pathspec>]] [--[no-]shallow-submodules]\n+\t  [--[no-]remote-submodules] [--jobs <n>] [--sparse] [--[no-]reject-shallow]\n+\t  [--filter=<filter-spec>] [--also-filter-submodules]] [--] <repository>\n+\t  [<directory>]\n \n DESCRIPTION\n -----------\n@@ -64,8 +64,8 @@ prevent the unintentional copying of files by dereferencing the symbolic\n links.\n +\n *NOTE*: this operation can race with concurrent modification to the\n-source repository, similar to running `cp -r src dst` while modifying\n-`src`.\n+source repository, similar to running s:[\"cp -r <src> <dst>\"] while modifying\n+_<src>_.\n \n `--no-hardlinks`::\n \tForce the cloning process from a repository on a local\n@@ -101,7 +101,7 @@ If you want to break the dependency of a repository cloned with `--shared` on\n its source repository, you can simply run `git repack -a` to copy all\n objects from the source repository into a pack in the cloned repository.\n \n-`--reference`[`-if-able`] _<repository>_::\n+s:[\"--reference[-if-able] <repository>\"]::\n \tIf the reference _<repository>_ is on the local machine,\n \tautomatically setup `.git/objects/info/alternates` to\n \tobtain objects from the reference _<repository>_.  Using\n@@ -142,17 +142,17 @@ objects from the source repository into a pack in the cloned repository.\n \tis specified. This flag forces progress status even if the\n \tstandard error stream is not directed to a terminal.\n \n-++--server-option=++__<option>__::\n+s:[\"--server-option=<option>\"]::\n \tTransmit the given string to the server when communicating using\n \tprotocol version 2.  The given string must not contain a NUL or LF\n \tcharacter.  The server's handling of server options, including\n \tunknown ones, is server-specific.\n-\tWhen multiple ++--server-option=++__<option>__ are given, they are all\n+\tWhen multiple s:[\"--server-option=<option>\"] are given, they are all\n \tsent to the other side in the order listed on the command line.\n \n `-n`::\n `--no-checkout`::\n-\tNo checkout of HEAD is performed after the clone is complete.\n+\tNo checkout of `HEAD` is performed after the clone is complete.\n \n `--`[`no-`]`reject-shallow`::\n \tFail if the source repository is a shallow repository.\n@@ -162,7 +162,7 @@ objects from the source repository into a pack in the cloned repository.\n `--bare`::\n \tMake a 'bare' Git repository.  That is, instead of\n \tcreating _<directory>_ and placing the administrative\n-\tfiles in _<directory>_`/.git`, make the _<directory>_\n+\tfiles in s:[\"<directory>/.git\"], make the _<directory>_\n \titself the `$GIT_DIR`. This obviously implies the `--no-checkout`\n \tbecause there is nowhere to check out the working tree.\n \tAlso the branch heads at the remote are copied directly\n@@ -177,13 +177,13 @@ objects from the source repository into a pack in the cloned repository.\n \tlinkgit:git-sparse-checkout[1] command can be used to grow the\n \tworking directory as needed.\n \n-++--filter=++__<filter-spec>__::\n+s:[\"--filter=<filter-spec>\"]::\n \tUse the partial clone feature and request that the server sends\n \ta subset of reachable objects according to a given object filter.\n \tWhen using `--filter`, the supplied _<filter-spec>_ is used for\n \tthe partial clone filter. For example, `--filter=blob:none` will\n \tfilter out all blobs (file contents) until needed by Git. Also,\n-\t++--filter=blob:limit=++__<size>__ will filter out all blobs of size\n+\ts:[\"--filter=blob:limit=<size>\"] will filter out all blobs of size\n \tat least _<size>_. For more details on filter specifications, see\n \tthe `--filter` option in linkgit:git-rev-list[1].\n \n@@ -208,11 +208,11 @@ objects from the source repository into a pack in the cloned repository.\n \n `-b` _<name>_::\n `--branch` _<name>_::\n-\tInstead of pointing the newly created HEAD to the branch pointed\n-\tto by the cloned repository's HEAD, point to _<name>_ branch\n+\tInstead of pointing the newly created `HEAD` to the branch pointed\n+\tto by the cloned repository's `HEAD`, point to _<name>_ branch\n \tinstead. In a non-bare repository, this is the branch that will\n \tbe checked out.\n-\t`--branch` can also take tags and detaches the HEAD at that commit\n+\t`--branch` can also take tags and detaches the `HEAD` at that commit\n \tin the resulting repository.\n \n `-u` _<upload-pack>_::\n@@ -221,12 +221,12 @@ objects from the source repository into a pack in the cloned repository.\n \tvia ssh, this specifies a non-default path for the command\n \trun on the other end.\n \n-++--template=++__<template-directory>__::\n+s:[\"--template=<template-directory>\"]::\n \tSpecify the directory from which templates will be used;\n \t(See the \"TEMPLATE DIRECTORY\" section of linkgit:git-init[1].)\n \n-`-c` __<key>__++=++__<value>__::\n-`--config` __<key>__++=++__<value>__::\n+`-c` s:[\"<key>=<value>\"]::\n+`--config` s:[\"<key>=<value>\"]::\n \tSet a configuration variable in the newly-created repository;\n \tthis takes effect immediately after the repository is\n \tinitialized, but before the remote history is fetched or any\n@@ -239,25 +239,25 @@ objects from the source repository into a pack in the cloned repository.\n Due to limitations of the current implementation, some configuration\n variables do not take effect until after the initial fetch and checkout.\n Configuration variables known to not take effect are:\n-++remote.++__<name>__++.mirror++ and ++remote.++__<name>__++.tagOpt++.  Use the\n+s:[\"remote.<name>.mirror\"] and s:[\"remote.<name>.tagOpt\"].  Use the\n corresponding `--mirror` and `--no-tags` options instead.\n \n-`--depth` _<depth>_::\n+s:[\"--depth <depth>\"]::\n \tCreate a 'shallow' clone with a history truncated to the\n \tspecified number of commits. Implies `--single-branch` unless\n \t`--no-single-branch` is given to fetch the histories near the\n \ttips of all branches. If you want to clone submodules shallowly,\n \talso pass `--shallow-submodules`.\n \n-++--shallow-since=++__<date>__::\n+s:[\"--shallow-since=<date>\"]::\n \tCreate a shallow clone with a history after the specified time.\n \n-++--shallow-exclude=++__<revision>__::\n+s:[\"--shallow-exclude=<revision>\"]::\n \tCreate a shallow clone with a history, excluding commits\n \treachable from a specified remote branch or tag.  This option\n \tcan be specified multiple times.\n \n-`--`[`no-`]`single-branch`::\n+s:[\"--[no-]single-branch\"]::\n \tClone only the history leading to the tip of a single branch,\n \teither specified by the `--branch` option or the primary\n \tbranch remote's `HEAD` points at.\n@@ -269,7 +269,7 @@ corresponding `--mirror` and `--no-tags` options instead.\n \n `--no-tags`::\n \tDon't clone any tags, and set\n-\t`remote.<remote>.tagOpt=--no-tags` in the config, ensuring\n+\ts:[\"remote.<remote>.tagOpt=--no-tags\"] in the config, ensuring\n \tthat future `git pull` and `git fetch` operations won't follow\n \tany tags. Subsequent explicit tag fetches will still work,\n \t(see linkgit:git-fetch[1]).\n@@ -279,7 +279,7 @@ maintain a branch with no references other than a single cloned\n branch. This is useful e.g. to maintain minimal clones of the default\n branch of some repository for search indexing.\n \n-`--recurse-submodules`[`=`{empty}__<pathspec>__]::\n+s:[\"--recurse-submodules[=<pathspec>]\"]::\n \tAfter the clone is created, initialize and clone submodules\n \twithin based on the provided _<pathspec>_.  If no _=<pathspec>_ is\n \tprovided, all submodules are initialized and cloned.\n@@ -290,28 +290,28 @@ branch of some repository for search indexing.\n +\n Submodules are initialized and cloned using their default settings. This is\n equivalent to running\n-`git submodule update --init --recursive <pathspec>` immediately after\n+s:[\"git submodule update --init --recursive <pathspec>\"] immediately after\n the clone is finished. This option is ignored if the cloned repository does\n not have a worktree/checkout (i.e. if any of `--no-checkout`/`-n`, `--bare`,\n or `--mirror` is given)\n \n-`--`[`no-`]`shallow-submodules`::\n+s:[\"--[no-]shallow-submodules\"]::\n \tAll submodules which are cloned will be shallow with a depth of 1.\n \n-`--`[`no-`]`remote-submodules`::\n+s:[\"--[no-]remote-submodules\"]::\n \tAll submodules which are cloned will use the status of the submodule's\n \tremote-tracking branch to update the submodule, rather than the\n \tsuperproject's recorded SHA-1. Equivalent to passing `--remote` to\n \t`git submodule update`.\n \n-`--separate-git-dir=`{empty}__<git-dir>__::\n+s:[\"--separate-git-dir=<git-dir>\"]::\n \tInstead of placing the cloned repository where it is supposed\n \tto be, place the cloned repository at the specified directory,\n \tthen make a filesystem-agnostic Git symbolic link to there.\n \tThe result is Git repository can be separated from working\n \ttree.\n \n-`--ref-format=`{empty}__<ref-format>__::\n+s:[\"--ref-format=<ref-format>\"]::\n \n Specify the given ref storage format for the repository. The valid values are:\n +\n@@ -334,7 +334,7 @@ _<directory>_::\n \tfor `host.xz:foo/.git`).  Cloning into an existing directory\n \tis only allowed if the directory is empty.\n \n-`--bundle-uri=`{empty}__<uri>__::\n+s:[\"--bundle-uri=<uri>\"]::\n \tBefore fetching from the remote, fetch a bundle from the given\n \t_<uri>_ and unbundle the data into the local repository. The refs\n \tin the bundle will be stored under the hidden `refs/bundle/*`\ndiff --git a/Documentation/git-init.txt b/Documentation/git-init.txt\nindex daff93bd164..fccd21cf3fb 100644\n--- a/Documentation/git-init.txt\n+++ b/Documentation/git-init.txt\n@@ -8,12 +8,12 @@ git-init - Create an empty Git repository or reinitialize an existing one\n \n SYNOPSIS\n --------\n-[verse]\n-`git init` [`-q` | `--quiet`] [`--bare`] [++--template=++__<template-directory>__]\n-\t  [`--separate-git-dir` _<git-dir>_] [++--object-format=++__<format>__]\n-\t  [++--ref-format=++__<format>__]\n-\t  [`-b` _<branch-name>_ | ++--initial-branch=++__<branch-name>__]\n-\t  [++--shared++[++=++__<permissions>__]] [_<directory>_]\n+[synopsis]\n+git init [-q | --quiet] [--bare] [--template=<template-directory>]\n+\t [--separate-git-dir <git-dir>] [--object-format=<format>]\n+\t [--ref-format=<format>]\n+\t [-b <branch-name> | --initial-branch=<branch-name>]\n+\t [--shared[=<permissions>]] [<directory>]\n \n \n DESCRIPTION\n@@ -25,11 +25,11 @@ directory with subdirectories for `objects`, `refs/heads`,\n commits will be created (see the `--initial-branch` option below\n for its name).\n \n-If the `$GIT_DIR` environment variable is set then it specifies a path\n+If the `GIT_DIR` environment variable is set then it specifies a path\n to use instead of `./.git` for the base of the repository.\n \n If the object storage directory is specified via the\n-`$GIT_OBJECT_DIRECTORY` environment variable then the sha1 directories\n+`GIT_OBJECT_DIRECTORY` environment variable then the sha1 directories\n are created underneath; otherwise, the default `$GIT_DIR/objects`\n directory is used.\n \n@@ -51,26 +51,22 @@ Only print error and warning messages; all other output will be suppressed.\n Create a bare repository. If `GIT_DIR` environment is not set, it is set to the\n current working directory.\n \n-++--object-format=++__<format>__::\n-\n+s:[\"--object-format=<format>\"]::\n Specify the given object _<format>_ (hash algorithm) for the repository.  The valid\n values are `sha1` and (if enabled) `sha256`.  `sha1` is the default.\n +\n include::object-format-disclaimer.txt[]\n \n-++--ref-format=++__<format>__::\n-\n+s:[\"--ref-format=<format>\"]::\n Specify the given ref storage _<format>_ for the repository. The valid values are:\n +\n include::ref-storage-format.txt[]\n \n-++--template=++__<template-directory>__::\n-\n+s:[\"--template=<template-directory>\"]::\n Specify the directory from which templates will be used.  (See the \"TEMPLATE\n DIRECTORY\" section below.)\n \n-++--separate-git-dir=++__<git-dir>__::\n-\n+s:[\"--separate-git-dir=<git-dir>\"]::\n Instead of initializing the repository as a directory to either `$GIT_DIR` or\n `./.git/`, create a text file there containing the path to the actual\n repository.  This file acts as a filesystem-agnostic Git symbolic link to the\n@@ -79,14 +75,13 @@ repository.\n If this is a reinitialization, the repository will be moved to the specified path.\n \n `-b` _<branch-name>_::\n-++--initial-branch=++__<branch-name>__::\n-\n+s:[\"--initial-branch=<branch-name>\"]::\n Use _<branch-name>_ for the initial branch in the newly created\n repository.  If not specified, fall back to the default name (currently\n `master`, but this is subject to change in the future; the name can be\n customized via the `init.defaultBranch` configuration variable).\n \n-++--shared++[++=++(`false`|`true`|`umask`|`group`|`all`|`world`|`everybody`|_<perm>_)]::\n+s:[\"--shared[=(false|true|umask|group|all|world|everybody|<perm>)]\"]::\n \n Specify that the Git repository is to be shared amongst several users.  This\n allows users belonging to the same group to push into that\ndiff --git a/Documentation/urls.txt b/Documentation/urls.txt\nindex 7cec85aef17..ffeeeb3599f 100644\n--- a/Documentation/urls.txt\n+++ b/Documentation/urls.txt\n@@ -10,19 +10,19 @@ Git supports ssh, git, http, and https protocols (in addition, ftp\n and ftps can be used for fetching, but this is inefficient and\n deprecated; do not use them).\n \n-The native transport (i.e. git:// URL) does no authentication and\n+The native transport (i.e. `git://` URL) does no authentication and\n should be used with caution on unsecured networks.\n \n The following syntaxes may be used with them:\n \n-- ++ssh://++{startsb}__<user>__++@++{endsb}__<host>__{startsb}++:++__<port>__{endsb}++/++__<path-to-git-repo>__\n-- ++git://++__<host>__{startsb}:__<port>__{endsb}++/++__<path-to-git-repo>__\n-- ++http++{startsb}++s++{endsb}++://++__<host>__{startsb}++:++__<port>__{endsb}++/++__<path-to-git-repo>__\n-- ++ftp++{startsb}++s++{endsb}++://++__<host>__{startsb}++:++__<port>__{endsb}++/++__<path-to-git-repo>__\n+- s:[\"ssh://[<user>@]<host>[:<port>]/<path-to-git-repo>\"]\n+- s:[\"git://<host>[:<port>]/<path-to-git-repo>\"]\n+- s:[\"http[s]://<host>[:<port>]/<path-to-git-repo>\"]\n+- s:[\"ftp[s]://<host>[:<port>]/<path-to-git-repo>\"]\n \n An alternative scp-like syntax may also be used with the ssh protocol:\n \n-- {startsb}__<user>__++@++{endsb}__<host>__++:/++__<path-to-git-repo>__\n+- s:[\"[<user>@]<host>:/<path-to-git-repo>\"]\n \n This syntax is only recognized if there are no slashes before the\n first colon. This helps differentiate a local path that contains a\n@@ -30,17 +30,17 @@ colon. For example the local path `foo:bar` could be specified as an\n absolute path or `./foo:bar` to avoid being misinterpreted as an ssh\n url.\n \n-The ssh and git protocols additionally support ++~++__<username>__ expansion:\n+The ssh and git protocols additionally support s:[\"~<username>\"] expansion:\n \n-- ++ssh://++{startsb}__<user>__++@++{endsb}__<host>__{startsb}++:++__<port>__{endsb}++/~++__<user>__++/++__<path-to-git-repo>__\n-- ++git://++__<host>__{startsb}++:++__<port>__{endsb}++/~++__<user>__++/++__<path-to-git-repo>__\n-- {startsb}__<user>__++@++{endsb}__<host>__++:~++__<user>__++/++__<path-to-git-repo>__\n+- s:[\"ssh://[<user>@]<host>[:<port>]/~<user>/<path-to-git-repo>\"]\n+- s:[\"git://<host>[:<port>]/~<user>/<path-to-git-repo>\"]\n+- s:[\"[<user>@]<host>:~<user>/<path-to-git-repo>\"]\n \n For local repositories, also supported by Git natively, the following\n syntaxes may be used:\n \n - `/path/to/repo.git/`\n-- ++file:///path/to/repo.git/++\n+- `file:///path/to/repo.git/`\n \n ifndef::git-clone[]\n These two syntaxes are mostly equivalent, except when cloning, when\n@@ -57,11 +57,11 @@ endif::git-clone[]\n accept a suitable bundle file. See linkgit:git-bundle[1].\n \n When Git doesn't know how to handle a certain transport protocol, it\n-attempts to use the `remote-`{empty}__<transport>__ remote helper, if one\n+attempts to use the s:[\"remote-<transport>\"] remote helper, if one\n exists. To explicitly request a remote helper, the following syntax\n may be used:\n \n-- _<transport>_::__<address>__\n+- s:[\"<transport>::<address>\"]\n \n where _<address>_ may be a path, a server and path, or an arbitrary\n URL-like string recognized by the specific remote helper being\n-- \ngitgitgadget\n"},{"id":"500611","messageId":"CAPig+cSGeExca0d=o0jewFERTx30+EgR5HccTO_gOsKtnXxuwA@mail.gmail.com","threadId":"61831","inReplyTo":"92f3121cf4e719d1bd6f85e3af454a3ea7547930.1723389612.git.gitgitgadget@gmail.com","subject":"Re: [PATCH v3 2/3] doc: update the guidelines to reflect the current formatting rules","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2024-08-11T23:56:21Z","receivedAt":"2024-08-11T23:56:33Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Sun, Aug 11, 2024 at 11:20 AM Jean-Noël Avila via GitGitGadget\n<gitgitgadget@gmail.com> wrote:\n> Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>\n> ---\n> diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines\n> @@ -746,70 +746,72 @@ Markup:\n>   When literal and placeholders are mixed, each markup is applied for\n> + each sub-entity. If the formatting is becoming too hairy, you can use the\n> + s:[\"foo\"] formatting macro and let it format the groups for you.\n> +   `--jobs` _<n>_ or s:[\"--jobs <n>\"]\n> +   s:[\"--sort=<key>\n> +   s:[\"<directory>/.git\"]\n> +   s:[\"remote.<name>.mirror\"]\n> +   s:[\"ssh://[<user>@]<host>[:<port>]/<path-to-git-repo>\"]\n> +\n> +Note that the double-quotes are required by the macro.\n\nThe closing `\"]` is missing from the --sort example. Is that intentional?\n"},{"id":"500616","messageId":"71b427c1-55a3-4f61-bfcb-65f7fe1a02cd@scantech.com","threadId":"61831","inReplyTo":"CAPig+cSGeExca0d=o0jewFERTx30+EgR5HccTO_gOsKtnXxuwA@mail.gmail.com","subject":"Re: [PATCH v3 2/3] doc: update the guidelines to reflect the current formatting rules","fromName":"Jean-Noël Avila","fromEmail":"jean-noel.avila@scantech.com","sentAt":"2024-08-12T06:18:28Z","receivedAt":"2024-08-12T07:34:09Z","isPatch":true,"sender":{"key":"jean-noel.avila@scantech.com","avatar":null},"body":"Le 12/08/2024 à 01:56, Eric Sunshine a écrit :\n> On Sun, Aug 11, 2024 at 11:20 AM Jean-Noël Avila via GitGitGadget\n> <gitgitgadget@gmail.com> wrote:\n>> Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>\n>> ---\n>> diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines\n>> @@ -746,70 +746,72 @@ Markup:\n>>   When literal and placeholders are mixed, each markup is applied for\n>> + each sub-entity. If the formatting is becoming too hairy, you can use the\n>> + s:[\"foo\"] formatting macro and let it format the groups for you.\n>> +   `--jobs` _<n>_ or s:[\"--jobs <n>\"]\n>> +   s:[\"--sort=<key>\n>> +   s:[\"<directory>/.git\"]\n>> +   s:[\"remote.<name>.mirror\"]\n>> +   s:[\"ssh://[<user>@]<host>[:<port>]/<path-to-git-repo>\"]\n>> +\n>> +Note that the double-quotes are required by the macro.\n> \n> The closing `\"]` is missing from the --sort example. Is that intentional?\n\nNot at all. Will fix it.\n\nThanks\n\n\n\nbegin:vcard\nfn;quoted-printable:Jean-No=C3=ABl Avila\nn;quoted-printable:Avila;Jean-No=C3=ABl\norg:Scantech S.A.\nadr;quoted-printable:Savoie Technolac BP 244;;B=C3=A2timent Androm=C3=A8de - 108 Avenue du Lac L=C3=A9man ; LA MOTTE SERVOLEX;;73290;France\nemail;internet:jean-noel.avila@scantech.com\ntitle:Embedded systems manager\ntel;work:+33 479 25 54 50\ntel;cell:+33 633 04 64 18\nx-mozilla-html:FALSE\nurl:http://www.scantech.com\nversion:2.1\nend:vcard\n\n"},{"id":"501301","messageId":"xmqqzfp8cm30.fsf@gitster.g","threadId":"61831","inReplyTo":"pull.1766.v3.git.1723389612.gitgitgadget@gmail.com","subject":"Re: [PATCH v3 0/3] doc: introducing synopsis para","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-08-19T20:08:19Z","receivedAt":"2024-08-19T20:08:22Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Jean-Noël Avila via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n> Jean-Noël Avila (3):\n>   doc: introduce a synopsis custom paragraph attribute\n>   doc: update the guidelines to reflect the current formatting rules\n>   doc: apply synopsis simplification on git-clone and git-init\n\nThis topic has become quiet.  I still find s:[\"someything you really\nwant to say\"] notation a bit annoying to my eyes, but its may be the\nbest compromise we can come up with.\n\nSo unless we have a strong objection, or (even better) an objection\nwith an alternative that is less yucky, perhaps it is time to\ndeclare that this is the variant of AsciiDoc/Asciidoctor that we'd\nadopt for our documentation.  Comments?\n\nThanks.\n"},{"id":"501463","messageId":"1986021.PYKUYFuaPT@cayenne","threadId":"61831","inReplyTo":"xmqqzfp8cm30.fsf@gitster.g","subject":"Re: [PATCH v3 0/3] doc: introducing synopsis para","fromName":"Jean-Noël AVILA","fromEmail":"jn.avila@free.fr","sentAt":"2024-08-21T21:05:57Z","receivedAt":"2024-08-21T21:06:10Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"Le lundi 19 août 2024, 22:08:19 CEST Junio C Hamano a écrit :\n> \"Jean-Noël Avila via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n> \n> > Jean-Noël Avila (3):\n> >   doc: introduce a synopsis custom paragraph attribute\n> >   doc: update the guidelines to reflect the current formatting rules\n> >   doc: apply synopsis simplification on git-clone and git-init\n> \n> This topic has become quiet.  I still find s:[\"someything you really\n> want to say\"] notation a bit annoying to my eyes, but its may be the\n> best compromise we can come up with.\n> \n> So unless we have a strong objection, or (even better) an objection\n> with an alternative that is less yucky, perhaps it is time to\n> declare that this is the variant of AsciiDoc/Asciidoctor that we'd\n> adopt for our documentation.  Comments?\n> \n> Thanks.\n> \n\nI understand that you are reluctant to include a change that, as the \nmaintainer, you do not feel comfortable  keeping alive. \n\nThe whole discussion thread tells me that other developers are not ready to go \ndown the \"full markup\" path. Understandably, this makes it more difficult for \neveryone to propose changes and review them, as there's no tool to track such \nformatting errors and we have to rely on careful manual cross-checking.\n\nI would like to thank you for pushing so that the markup can be simplified as \nmuch as can be. It can be simplified further one step further: it is possible \nboth in asciidoc/asciidoctor to override the formatting of inline verbatim \ntexts, so that everything that is backquoted is processed as a synopsis \nstring. \nThis way, strings like\n\n`<commit>`\n`diff.statGraphWidth=<width>`\n` --dirstat-by-file[=<param>,...]`\n\nare automatically rendered with the expected styles.\n\nHowever, contrary to the s macro, this is quite disruptive as it forces the \nnew processing on all existing manpages. Another drawback is that it is no \nlonger genuine asciidoc, but it seems more in line with the critics. I'm \nrefining the regexp at the moment to check for side-effects.\n\nIs this proposition more appropriate?\n\n\n\n\n"},{"id":"501929","messageId":"xmqqa5gtsxz5.fsf@gitster.g","threadId":"61831","inReplyTo":"1986021.PYKUYFuaPT@cayenne","subject":"Re: [PATCH v3 0/3] doc: introducing synopsis para","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-08-30T17:48:46Z","receivedAt":"2024-08-30T17:48:49Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jean-Noël AVILA <jn.avila@free.fr> writes:\n\n> ... It can be simplified further one step further: it is possible \n> both in asciidoc/asciidoctor to override the formatting of inline verbatim \n> texts, so that everything that is backquoted is processed as a synopsis \n> string. \n> This way, strings like\n>\n> `<commit>`\n> `diff.statGraphWidth=<width>`\n> ` --dirstat-by-file[=<param>,...]`\n>\n> are automatically rendered with the expected styles.\n>\n> However, contrary to the s macro, this is quite disruptive as it forces the \n> new processing on all existing manpages. Another drawback is that it is no \n> longer genuine asciidoc, but it seems more in line with the critics. I'm \n> refining the regexp at the moment to check for side-effects.\n>\n> Is this proposition more appropriate?\n\nThanks for thinking these things through.  The fact that such a\n\"magic\" processing will hide the gory details from those whose\nprimary interest is to describe the commands and their options cuts\nboth ways.  It is a very welcome thing for developers around here, I\nwould assume.  At the same time, I can understand that purists would\nfind it unacceptably ugly, as `backticks` is now much more than a\nmark-up that means \"this text is typeset in monospace\".  Inside it,\n<text inside angle brackets>, [optional text], and (choices), all\nsignal that they have special meaning by being typeset differently.\n\nI do not personally mind that, and I would even dream about a future\nin which other projects notice what you did to AsciiDoctor, love it,\nadopt it, and eventually it feeds back to improve AsciiDoctor proper.\n\nIt is very likely that is because I haven't seen any \"side effects\"\nyet ;-)\n\nThanks.\n\n"},{"id":"502289","messageId":"c09968d7ccbaa22b36daf0f3f8e88eb3e154c654.1725573126.git.gitgitgadget@gmail.com","threadId":"61831","inReplyTo":"pull.1766.v4.git.1725573126.gitgitgadget@gmail.com","subject":"[PATCH v4 1/3] doc: introduce a synopsis typesetting","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-09-05T21:52:04Z","receivedAt":"2024-09-05T21:52:10Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n\nIn order to follow the common manpage usage, the synopsis of the\ncommands needs to be heavily typeset. A first try was performed with\nusing native markup, but it turned out to make the document source\nalmost unreadable, difficult to write and prone to mistakes with\nunwanted Asciidoc's role attributes.\n\nIn order to both simplify the writer's task and obtain a consistant\ntypesetting in the synopsis, a custom 'synopsis' paragraph type is\ncreated and the processor for backticked text are modified. The\nbackends of asciidoc and asciidoctor take in charge to correctly add\nthe required typesetting.\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n Documentation/asciidoc.conf             | 20 ++++++\n Documentation/asciidoctor-extensions.rb | 87 +++++++++++++++++++++++++\n ci/install-dependencies.sh              |  1 +\n t/t0450-txt-doc-vs-help.sh              | 11 ++--\n 4 files changed, 112 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf\nindex 60f76f43eda..75ae9f3da92 100644\n--- a/Documentation/asciidoc.conf\n+++ b/Documentation/asciidoc.conf\n@@ -28,6 +28,10 @@ ifdef::backend-docbook[]\n {0#<citerefentry>}\n {0#<refentrytitle>{target}</refentrytitle><manvolnum>{0}</manvolnum>}\n {0#</citerefentry>}\n+\n+[literal-inlinemacro]\n+{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])))}\n+\n endif::backend-docbook[]\n \n ifdef::backend-docbook[]\n@@ -56,4 +60,20 @@ ifdef::backend-xhtml11[]\n git-relative-html-prefix=\n [linkgit-inlinemacro]\n <a href=\"{git-relative-html-prefix}{target}.html\">{target}{0?({0})}</a>\n+\n+[literal-inlinemacro]\n+{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])))}\n+\n+endif::backend-xhtml11[]\n+\n+ifdef::backend-docbook[]\n+ifdef::doctype-manpage[]\n+[paradef-default]\n+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'\"\n+endif::doctype-manpage[]\n+endif::backend-docbook[]\n+\n+ifdef::backend-xhtml11[]\n+[paradef-default]\n+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'\"\n endif::backend-xhtml11[]\ndiff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb\nindex d906a008039..cb24480b63d 100644\n--- a/Documentation/asciidoctor-extensions.rb\n+++ b/Documentation/asciidoctor-extensions.rb\n@@ -1,5 +1,7 @@\n require 'asciidoctor'\n require 'asciidoctor/extensions'\n+require 'asciidoctor/converter/docbook5'\n+require 'asciidoctor/converter/html5'\n \n module Git\n   module Documentation\n@@ -39,10 +41,95 @@ module Git\n         output\n       end\n     end\n+\n+    class SynopsisBlock < Asciidoctor::Extensions::BlockProcessor\n+\n+      use_dsl\n+      named :synopsis\n+      parse_content_as :simple\n+\n+      def process parent, reader, attrs\n+        outlines = reader.lines.map do |l|\n+          l.gsub(/(\\.\\.\\.?)([^\\]$.])/, '`\\1`\\2')\n+           .gsub(%r{([\\[\\] |()>]|^)([-a-zA-Z0-9:+=~@,/_^\\$]+)}, '\\1{empty}`\\2`{empty}')\n+           .gsub(/(<[-a-zA-Z0-9.]+>)/, '__\\\\1__')\n+           .gsub(']', ']{empty}')\n+        end\n+        create_block parent, :verse, outlines, attrs\n+      end\n+    end\n+\n+    class GitDBConverter < Asciidoctor::Converter::DocBook5Converter\n+\n+      extend Asciidoctor::Converter::Config\n+      register_for 'docbook5'\n+\n+      def convert_inline_quoted node\n+        if (type = node.type) == :asciimath\n+          # NOTE fop requires jeuclid to process mathml markup\n+          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>)\n+        elsif type == :latexmath\n+          # unhandled math; pass source to alt and required mathphrase element; dblatex will process alt as LaTeX math\n+          %(<inlineequation><alt><![CDATA[#{equation = node.text}]]></alt><mathphrase><![CDATA[#{equation}]]></mathphrase></inlineequation>)\n+        elsif type == :monospaced\n+          node.text.gsub(/(\\.\\.\\.?)([^\\]$.])/, '<literal>\\1</literal>\\2')\n+              .gsub(%r{([\\[\\s|()>.]|^|\\]|&gt;)(\\.?([-a-zA-Z0-9:+=~@,/_^\\$]+\\.{0,2})+)}, '\\1<literal>\\2</literal>')\n+              .gsub(/(&lt;[-a-zA-Z0-9.]+&gt;)/, '<emphasis>\\1</emphasis>')\n+        else\n+          open, close, supports_phrase = QUOTE_TAGS[type]\n+          text = node.text\n+          if node.role\n+            if supports_phrase\n+              quoted_text = %(#{open}<phrase role=\"#{node.role}\">#{text}</phrase>#{close})\n+            else\n+              quoted_text = %(#{open.chop} role=\"#{node.role}\">#{text}#{close})\n+            end\n+          else\n+            quoted_text = %(#{open}#{text}#{close})\n+          end\n+          node.id ? %(<anchor#{common_attributes node.id, nil, text}/>#{quoted_text}) : quoted_text\n+        end\n+      end\n+    end\n+\n+    # register a html5 converter that takes in charge to convert monospaced text into Git style synopsis\n+    class GitHTMLConverter < Asciidoctor::Converter::Html5Converter\n+\n+      extend Asciidoctor::Converter::Config\n+      register_for 'html5'\n+\n+      def convert_inline_quoted node\n+        if node.type == :monospaced\n+          node.text.gsub(/(\\.\\.\\.?)([^\\]$.])/, '<code>\\1</code>\\2')\n+              .gsub(%r{([\\[\\s|()>.]|^|\\]|&gt;)(\\.?([-a-zA-Z0-9:+=~@,/_^\\$]+\\.{0,2})+)}, '\\1<code>\\2</code>')\n+              .gsub(/(&lt;[-a-zA-Z0-9.]+&gt;)/, '<em>\\1</em>')\n+\n+        else\n+          open, close, tag = QUOTE_TAGS[node.type]\n+          if node.id\n+            class_attr = node.role ? %( class=\"#{node.role}\") : ''\n+            if tag\n+              %(#{open.chop} id=\"#{node.id}\"#{class_attr}>#{node.text}#{close})\n+            else\n+              %(<span id=\"#{node.id}\"#{class_attr}>#{open}#{node.text}#{close}</span>)\n+            end\n+          elsif node.role\n+            if tag\n+              %(#{open.chop} class=\"#{node.role}\">#{node.text}#{close})\n+            else\n+              %(<span class=\"#{node.role}\">#{open}#{node.text}#{close}</span>)\n+            end\n+          else\n+            %(#{open}#{node.text}#{close})\n+          end\n+        end\n+      end\n+    end\n   end\n end\n \n Asciidoctor::Extensions.register do\n   inline_macro Git::Documentation::LinkGitProcessor, :linkgit\n+  block Git::Documentation::SynopsisBlock\n   postprocessor Git::Documentation::DocumentPostProcessor\n end\ndiff --git a/ci/install-dependencies.sh b/ci/install-dependencies.sh\nindex 4781cd20bb0..3e3ae39cbb1 100755\n--- a/ci/install-dependencies.sh\n+++ b/ci/install-dependencies.sh\n@@ -107,6 +107,7 @@ Documentation)\n \n \ttest -n \"$ALREADY_HAVE_ASCIIDOCTOR\" ||\n \tsudo gem install --version 1.5.8 asciidoctor\n+\tsudo gem install concurrent-ruby\n \t;;\n esac\n \ndiff --git a/t/t0450-txt-doc-vs-help.sh b/t/t0450-txt-doc-vs-help.sh\nindex 69917d7b845..f99a69ae1b7 100755\n--- a/t/t0450-txt-doc-vs-help.sh\n+++ b/t/t0450-txt-doc-vs-help.sh\n@@ -56,14 +56,11 @@ txt_to_synopsis () {\n \tfi &&\n \tb2t=\"$(builtin_to_txt \"$builtin\")\" &&\n \tsed -n \\\n-\t\t-e '/^\\[verse\\]$/,/^$/ {\n+\t\t-E '/^\\[(verse|synopsis)\\]$/,/^$/ {\n \t\t\t/^$/d;\n-\t\t\t/^\\[verse\\]$/d;\n-\t\t\ts/_//g;\n-\t\t\ts/++//g;\n-\t\t\ts/`//g;\n-\t\t\ts/{litdd}/--/g;\n-\t\t\ts/'\\''\\(git[ a-z-]*\\)'\\''/\\1/g;\n+\t\t\t/^\\[(verse|synopsis)\\]$/d;\n+\t\t\ts/\\{litdd\\}/--/g;\n+\t\t\ts/'\\''(git[ a-z-]*)'\\''/\\1/g;\n \n \t\t\tp;\n \t\t}' \\\n-- \ngitgitgadget\n\n"},{"id":"502290","messageId":"pull.1766.v4.git.1725573126.gitgitgadget@gmail.com","threadId":"61831","inReplyTo":"pull.1766.v3.git.1723389612.gitgitgadget@gmail.com","subject":"[PATCH v4 0/3] doc: introducing synopsis para","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-09-05T21:52:03Z","receivedAt":"2024-09-05T21:52:11Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"In the continuation of the simplification of manpage editing, the synopsis\nprocessing that was developed for synopsis paragraph style is also applied\nto all inline backquoted texts.\n\nRefining the magic regexp took more time than expected, but this one should\nreally enhance writers'experience. I had to fight a bit more with\nasciidoctor, due to discrepancies between version 2.0 on my laptop and the\n1.5.6 used by Github actions.\n\nThe git-init and git-clone manpages are converted to this new system.\n\nChanges since V1:\n\n * switch to sed for asciidoc filter and refine the regex for support under\n   macOS\n\nChanges since V2:\n\n * introduce the s macro to freely apply synopsis styling wherever needed,\n   without formatting hassle.\n\nChanges since V3:\n\n * replace s macro by direct processing of literal text at the level of\n   output processors.\n\nJean-Noël Avila (3):\n  doc: introduce a synopsis typesetting\n  doc: update the guidelines to reflect the current formatting rules\n  doc: apply synopsis simplification on git-clone and git-init\n\n Documentation/CodingGuidelines          | 58 +++++++++--------\n Documentation/asciidoc.conf             | 20 ++++++\n Documentation/asciidoctor-extensions.rb | 87 +++++++++++++++++++++++++\n Documentation/git-clone.txt             | 78 +++++++++++-----------\n Documentation/git-init.txt              | 35 +++++-----\n Documentation/urls.txt                  | 26 ++++----\n ci/install-dependencies.sh              |  1 +\n t/t0450-txt-doc-vs-help.sh              | 11 ++--\n 8 files changed, 209 insertions(+), 107 deletions(-)\n\n\nbase-commit: 2e7b89e038c0c888acf61f1b4ee5a43d4dd5e94c\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-1766%2Fjnavila%2Fdoc_synopsis_para-v4\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1766/jnavila/doc_synopsis_para-v4\nPull-Request: https://github.com/gitgitgadget/git/pull/1766\n\nRange-diff vs v3:\n\n 1:  0d7c1dd8f26 ! 1:  c09968d7ccb doc: introduce a synopsis custom paragraph attribute\n     @@ Metadata\n      Author: Jean-Noël Avila <jn.avila@free.fr>\n      \n       ## Commit message ##\n     -    doc: introduce a synopsis custom paragraph attribute\n     +    doc: introduce a synopsis typesetting\n      \n          In order to follow the common manpage usage, the synopsis of the\n          commands needs to be heavily typeset. A first try was performed with\n     @@ Commit message\n      \n          In order to both simplify the writer's task and obtain a consistant\n          typesetting in the synopsis, a custom 'synopsis' paragraph type is\n     -    created and the backends of asciidoc and asciidoctor take in charge to\n     -    correctly add the required typesetting.\n     -\n     -    additionally, a 's' macro ('s' standing for synopsis) is introduced to\n     -    allow writers to freely apply automatic styling whereever required.\n     +    created and the processor for backticked text are modified. The\n     +    backends of asciidoc and asciidoctor take in charge to correctly add\n     +    the required typesetting.\n      \n          Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>\n      \n       ## Documentation/asciidoc.conf ##\n     -@@\n     - \n     - [macros]\n     - (?su)[\\\\]?(?P<name>linkgit):(?P<target>\\S*?)\\[(?P<attrlist>.*?)\\]=\n     --\n     -+(?su)[\\\\]?(?P<name>s):(?P<target>\\S*?)\\[\"(?P<attrlist>.*?)\"\\]=\n     - [attributes]\n     - asterisk=&#42;\n     - plus=&#43;\n      @@ Documentation/asciidoc.conf: ifdef::backend-docbook[]\n       {0#<citerefentry>}\n       {0#<refentrytitle>{target}</refentrytitle><manvolnum>{0}</manvolnum>}\n       {0#</citerefentry>}\n      +\n     -+[s-inlinemacro]\n     -+{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}'))}\n     ++[literal-inlinemacro]\n     ++{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])))}\n     ++\n       endif::backend-docbook[]\n       \n       ifdef::backend-docbook[]\n     @@ Documentation/asciidoc.conf: ifdef::backend-xhtml11[]\n       [linkgit-inlinemacro]\n       <a href=\"{git-relative-html-prefix}{target}.html\">{target}{0?({0})}</a>\n      +\n     -+[s-inlinemacro]\n     -+{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}'))}\n     ++[literal-inlinemacro]\n     ++{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])))}\n      +\n      +endif::backend-xhtml11[]\n      +\n      +ifdef::backend-docbook[]\n      +ifdef::doctype-manpage[]\n      +[paradef-default]\n     -+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'\"\n     ++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'\"\n      +endif::doctype-manpage[]\n      +endif::backend-docbook[]\n      +\n      +ifdef::backend-xhtml11[]\n      +[paradef-default]\n     -+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'\"\n     ++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'\"\n       endif::backend-xhtml11[]\n      \n       ## Documentation/asciidoctor-extensions.rb ##\n     -@@ Documentation/asciidoctor-extensions.rb: module Git\n     -       end\n     -     end\n     +@@\n     + require 'asciidoctor'\n     + require 'asciidoctor/extensions'\n     ++require 'asciidoctor/converter/docbook5'\n     ++require 'asciidoctor/converter/html5'\n       \n     -+    class SynopsisMacroProcessor < Asciidoctor::Extensions::InlineMacroProcessor\n     -+      use_dsl\n     -+\n     -+      named :s\n     -+      match(/s:\\[\"(.+?)\"\\]/)\n     -+\n     -+      def process(parent, target, attrs)\n     -+        l = target.gsub(/([\\[\\] |()]|^|&gt;)(\\.?[-a-zA-Z0-9:+=~@,\\/]+\\.?)/, '\\1{empty}`\\2`{empty}')\n     -+                  .gsub(/(&lt;[-a-zA-Z0-9.]+&gt;)/, '__\\\\1__')\n     -+                  .gsub(']', ']{empty}')\n     -+\n     -+        create_inline parent, :quoted, l, attributes: { 'subs' => :normal }\n     -+      end\n     -+    end\n     -+\n     -     class DocumentPostProcessor < Asciidoctor::Extensions::Postprocessor\n     -       def process document, output\n     -         if document.basebackend? 'docbook'\n     + module Git\n     +   module Documentation\n      @@ Documentation/asciidoctor-extensions.rb: module Git\n               output\n             end\n     @@ Documentation/asciidoctor-extensions.rb: module Git\n      +\n      +      def process parent, reader, attrs\n      +        outlines = reader.lines.map do |l|\n     -+          l.gsub(/([\\[\\] |()>]|^)([-a-zA-Z0-9:+=]+)/, '\\1{empty}`\\2`{empty}')\n     ++          l.gsub(/(\\.\\.\\.?)([^\\]$.])/, '`\\1`\\2')\n     ++           .gsub(%r{([\\[\\] |()>]|^)([-a-zA-Z0-9:+=~@,/_^\\$]+)}, '\\1{empty}`\\2`{empty}')\n      +           .gsub(/(<[-a-zA-Z0-9.]+>)/, '__\\\\1__')\n      +           .gsub(']', ']{empty}')\n      +        end\n      +        create_block parent, :verse, outlines, attrs\n      +      end\n     ++    end\n     ++\n     ++    class GitDBConverter < Asciidoctor::Converter::DocBook5Converter\n     ++\n     ++      extend Asciidoctor::Converter::Config\n     ++      register_for 'docbook5'\n     ++\n     ++      def convert_inline_quoted node\n     ++        if (type = node.type) == :asciimath\n     ++          # NOTE fop requires jeuclid to process mathml markup\n     ++          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>)\n     ++        elsif type == :latexmath\n     ++          # unhandled math; pass source to alt and required mathphrase element; dblatex will process alt as LaTeX math\n     ++          %(<inlineequation><alt><![CDATA[#{equation = node.text}]]></alt><mathphrase><![CDATA[#{equation}]]></mathphrase></inlineequation>)\n     ++        elsif type == :monospaced\n     ++          node.text.gsub(/(\\.\\.\\.?)([^\\]$.])/, '<literal>\\1</literal>\\2')\n     ++              .gsub(%r{([\\[\\s|()>.]|^|\\]|&gt;)(\\.?([-a-zA-Z0-9:+=~@,/_^\\$]+\\.{0,2})+)}, '\\1<literal>\\2</literal>')\n     ++              .gsub(/(&lt;[-a-zA-Z0-9.]+&gt;)/, '<emphasis>\\1</emphasis>')\n     ++        else\n     ++          open, close, supports_phrase = QUOTE_TAGS[type]\n     ++          text = node.text\n     ++          if node.role\n     ++            if supports_phrase\n     ++              quoted_text = %(#{open}<phrase role=\"#{node.role}\">#{text}</phrase>#{close})\n     ++            else\n     ++              quoted_text = %(#{open.chop} role=\"#{node.role}\">#{text}#{close})\n     ++            end\n     ++          else\n     ++            quoted_text = %(#{open}#{text}#{close})\n     ++          end\n     ++          node.id ? %(<anchor#{common_attributes node.id, nil, text}/>#{quoted_text}) : quoted_text\n     ++        end\n     ++      end\n     ++    end\n     ++\n     ++    # register a html5 converter that takes in charge to convert monospaced text into Git style synopsis\n     ++    class GitHTMLConverter < Asciidoctor::Converter::Html5Converter\n     ++\n     ++      extend Asciidoctor::Converter::Config\n     ++      register_for 'html5'\n     ++\n     ++      def convert_inline_quoted node\n     ++        if node.type == :monospaced\n     ++          node.text.gsub(/(\\.\\.\\.?)([^\\]$.])/, '<code>\\1</code>\\2')\n     ++              .gsub(%r{([\\[\\s|()>.]|^|\\]|&gt;)(\\.?([-a-zA-Z0-9:+=~@,/_^\\$]+\\.{0,2})+)}, '\\1<code>\\2</code>')\n     ++              .gsub(/(&lt;[-a-zA-Z0-9.]+&gt;)/, '<em>\\1</em>')\n     ++\n     ++        else\n     ++          open, close, tag = QUOTE_TAGS[node.type]\n     ++          if node.id\n     ++            class_attr = node.role ? %( class=\"#{node.role}\") : ''\n     ++            if tag\n     ++              %(#{open.chop} id=\"#{node.id}\"#{class_attr}>#{node.text}#{close})\n     ++            else\n     ++              %(<span id=\"#{node.id}\"#{class_attr}>#{open}#{node.text}#{close}</span>)\n     ++            end\n     ++          elsif node.role\n     ++            if tag\n     ++              %(#{open.chop} class=\"#{node.role}\">#{node.text}#{close})\n     ++            else\n     ++              %(<span class=\"#{node.role}\">#{open}#{node.text}#{close}</span>)\n     ++            end\n     ++          else\n     ++            %(#{open}#{node.text}#{close})\n     ++          end\n     ++        end\n     ++      end\n      +    end\n         end\n       end\n       \n       Asciidoctor::Extensions.register do\n         inline_macro Git::Documentation::LinkGitProcessor, :linkgit\n     -+  inline_macro Git::Documentation::SynopsisMacroProcessor\n      +  block Git::Documentation::SynopsisBlock\n         postprocessor Git::Documentation::DocumentPostProcessor\n       end\n      \n     + ## ci/install-dependencies.sh ##\n     +@@ ci/install-dependencies.sh: Documentation)\n     + \n     + \ttest -n \"$ALREADY_HAVE_ASCIIDOCTOR\" ||\n     + \tsudo gem install --version 1.5.8 asciidoctor\n     ++\tsudo gem install concurrent-ruby\n     + \t;;\n     + esac\n     + \n     +\n       ## t/t0450-txt-doc-vs-help.sh ##\n      @@ t/t0450-txt-doc-vs-help.sh: txt_to_synopsis () {\n       \tfi &&\n 2:  92f3121cf4e ! 2:  c48649ccd63 doc: update the guidelines to reflect the current formatting rules\n     @@ Commit message\n      \n       ## Documentation/CodingGuidelines ##\n      @@ Documentation/CodingGuidelines: Markup:\n     +    _<new-branch-name>_\n     +    _<template-directory>_\n     + \n     +- A placeholder is not enclosed in backticks, as it is not a literal.\n     +-\n     +  When needed, use a distinctive identifier for placeholders, usually\n     +  made of a qualification and a type:\n     +    _<git-dir>_\n          _<key-id>_\n       \n     -  When literal and placeholders are mixed, each markup is applied for\n     +- When literal and placeholders are mixed, each markup is applied for\n      - each sub-entity. If they are stuck, a special markup, called\n      - unconstrained formatting is required.\n      - Unconstrained formating for placeholders is __<like-this>__\n     @@ Documentation/CodingGuidelines: Markup:\n      -   ++--sort=++__<key>__\n      -   __<directory>__++/.git++\n      -   ++remote.++__<name>__++.mirror++\n     --\n     ++ Git's Asciidoc processor has been tailored to treat backticked text\n     ++ as complex synopsis. When literal and placeholders are mixed, you can\n     ++ use the backtick notation which will take care of correctly typesetting\n     ++ the content.\n     ++   `--jobs <n>`\n     ++   `--sort=<key>`\n     ++   `<directory>/.git`\n     ++   `remote.<name>.mirror`\n     ++   `ssh://[<user>@]<host>[:<port>]/<path-to-git-repo>`\n     + \n      - caveat: ++ unconstrained format is not verbatim and may expand\n      - content. Use Asciidoc escapes inside them.\n     -+ each sub-entity. If the formatting is becoming too hairy, you can use the\n     -+ s:[\"foo\"] formatting macro and let it format the groups for you.\n     -+   `--jobs` _<n>_ or s:[\"--jobs <n>\"]\n     -+   s:[\"--sort=<key>\n     -+   s:[\"<directory>/.git\"]\n     -+   s:[\"remote.<name>.mirror\"]\n     -+   s:[\"ssh://[<user>@]<host>[:<port>]/<path-to-git-repo>\"]\n     -+\n     -+Note that the double-quotes are required by the macro.\n     ++As a side effect, backquoted placeholders are correctly typeset, but\n     ++this style is not recommended.\n       \n       Synopsis Syntax\n       \n 3:  02406b91894 ! 3:  719188da711 doc: apply synopsis simplification on git-clone and git-init\n     @@ Documentation/git-clone.txt: git-clone - Clone a repository into a new directory\n       \n       DESCRIPTION\n       -----------\n     +@@ Documentation/git-clone.txt: OPTIONS\n     + \tto save space when possible.\n     + +\n     + If the repository is specified as a local path (e.g., `/path/to/repo`),\n     +-this is the default, and --local is essentially a no-op.  If the\n     ++this is the default, and `--local` is essentially a no-op.  If the\n     + repository is specified as a URL, then this flag is ignored (and we\n     + never use the local optimizations).  Specifying `--no-local` will\n     + override the default when `/path/to/repo` is given, using the regular\n      @@ Documentation/git-clone.txt: prevent the unintentional copying of files by dereferencing the symbolic\n       links.\n       +\n       *NOTE*: this operation can race with concurrent modification to the\n      -source repository, similar to running `cp -r src dst` while modifying\n      -`src`.\n     -+source repository, similar to running s:[\"cp -r <src> <dst>\"] while modifying\n     ++source repository, similar to running `cp -r <src> <dst>` while modifying\n      +_<src>_.\n       \n       `--no-hardlinks`::\n     @@ Documentation/git-clone.txt: If you want to break the dependency of a repository\n       objects from the source repository into a pack in the cloned repository.\n       \n      -`--reference`[`-if-able`] _<repository>_::\n     -+s:[\"--reference[-if-able] <repository>\"]::\n     ++`--reference[-if-able] <repository>`::\n       \tIf the reference _<repository>_ is on the local machine,\n       \tautomatically setup `.git/objects/info/alternates` to\n       \tobtain objects from the reference _<repository>_.  Using\n     @@ Documentation/git-clone.txt: objects from the source repository into a pack in t\n       \tstandard error stream is not directed to a terminal.\n       \n      -++--server-option=++__<option>__::\n     -+s:[\"--server-option=<option>\"]::\n     ++`--server-option=<option>`::\n       \tTransmit the given string to the server when communicating using\n       \tprotocol version 2.  The given string must not contain a NUL or LF\n       \tcharacter.  The server's handling of server options, including\n       \tunknown ones, is server-specific.\n      -\tWhen multiple ++--server-option=++__<option>__ are given, they are all\n     -+\tWhen multiple s:[\"--server-option=<option>\"] are given, they are all\n     ++\tWhen multiple `--server-option=<option>` are given, they are all\n       \tsent to the other side in the order listed on the command line.\n       \n       `-n`::\n     @@ Documentation/git-clone.txt: objects from the source repository into a pack in t\n       \tMake a 'bare' Git repository.  That is, instead of\n       \tcreating _<directory>_ and placing the administrative\n      -\tfiles in _<directory>_`/.git`, make the _<directory>_\n     -+\tfiles in s:[\"<directory>/.git\"], make the _<directory>_\n     ++\tfiles in `<directory>/.git`, make the _<directory>_\n       \titself the `$GIT_DIR`. This obviously implies the `--no-checkout`\n       \tbecause there is nowhere to check out the working tree.\n       \tAlso the branch heads at the remote are copied directly\n     @@ Documentation/git-clone.txt: objects from the source repository into a pack in t\n       \tworking directory as needed.\n       \n      -++--filter=++__<filter-spec>__::\n     -+s:[\"--filter=<filter-spec>\"]::\n     ++`--filter=<filter-spec>`::\n       \tUse the partial clone feature and request that the server sends\n       \ta subset of reachable objects according to a given object filter.\n       \tWhen using `--filter`, the supplied _<filter-spec>_ is used for\n       \tthe partial clone filter. For example, `--filter=blob:none` will\n       \tfilter out all blobs (file contents) until needed by Git. Also,\n      -\t++--filter=blob:limit=++__<size>__ will filter out all blobs of size\n     -+\ts:[\"--filter=blob:limit=<size>\"] will filter out all blobs of size\n     ++\t`--filter=blob:limit=<size>` will filter out all blobs of size\n       \tat least _<size>_. For more details on filter specifications, see\n       \tthe `--filter` option in linkgit:git-rev-list[1].\n       \n     @@ Documentation/git-clone.txt: objects from the source repository into a pack in t\n       \trun on the other end.\n       \n      -++--template=++__<template-directory>__::\n     -+s:[\"--template=<template-directory>\"]::\n     ++`--template=<template-directory>`::\n       \tSpecify the directory from which templates will be used;\n       \t(See the \"TEMPLATE DIRECTORY\" section of linkgit:git-init[1].)\n       \n      -`-c` __<key>__++=++__<value>__::\n      -`--config` __<key>__++=++__<value>__::\n     -+`-c` s:[\"<key>=<value>\"]::\n     -+`--config` s:[\"<key>=<value>\"]::\n     ++`-c` `<key>=<value>`::\n     ++`--config` `<key>=<value>`::\n       \tSet a configuration variable in the newly-created repository;\n       \tthis takes effect immediately after the repository is\n       \tinitialized, but before the remote history is fetched or any\n     @@ Documentation/git-clone.txt: objects from the source repository into a pack in t\n       variables do not take effect until after the initial fetch and checkout.\n       Configuration variables known to not take effect are:\n      -++remote.++__<name>__++.mirror++ and ++remote.++__<name>__++.tagOpt++.  Use the\n     -+s:[\"remote.<name>.mirror\"] and s:[\"remote.<name>.tagOpt\"].  Use the\n     ++`remote.<name>.mirror` and `remote.<name>.tagOpt`.  Use the\n       corresponding `--mirror` and `--no-tags` options instead.\n       \n      -`--depth` _<depth>_::\n     -+s:[\"--depth <depth>\"]::\n     ++`--depth <depth>`::\n       \tCreate a 'shallow' clone with a history truncated to the\n       \tspecified number of commits. Implies `--single-branch` unless\n       \t`--no-single-branch` is given to fetch the histories near the\n     @@ Documentation/git-clone.txt: objects from the source repository into a pack in t\n       \talso pass `--shallow-submodules`.\n       \n      -++--shallow-since=++__<date>__::\n     -+s:[\"--shallow-since=<date>\"]::\n     ++`--shallow-since=<date>`::\n       \tCreate a shallow clone with a history after the specified time.\n       \n      -++--shallow-exclude=++__<revision>__::\n     -+s:[\"--shallow-exclude=<revision>\"]::\n     ++`--shallow-exclude=<revision>`::\n       \tCreate a shallow clone with a history, excluding commits\n       \treachable from a specified remote branch or tag.  This option\n       \tcan be specified multiple times.\n       \n      -`--`[`no-`]`single-branch`::\n     -+s:[\"--[no-]single-branch\"]::\n     ++`--[no-]single-branch`::\n       \tClone only the history leading to the tip of a single branch,\n       \teither specified by the `--branch` option or the primary\n       \tbranch remote's `HEAD` points at.\n     -@@ Documentation/git-clone.txt: corresponding `--mirror` and `--no-tags` options instead.\n     - \n     - `--no-tags`::\n     - \tDon't clone any tags, and set\n     --\t`remote.<remote>.tagOpt=--no-tags` in the config, ensuring\n     -+\ts:[\"remote.<remote>.tagOpt=--no-tags\"] in the config, ensuring\n     - \tthat future `git pull` and `git fetch` operations won't follow\n     - \tany tags. Subsequent explicit tag fetches will still work,\n     - \t(see linkgit:git-fetch[1]).\n      @@ Documentation/git-clone.txt: maintain a branch with no references other than a single cloned\n       branch. This is useful e.g. to maintain minimal clones of the default\n       branch of some repository for search indexing.\n       \n      -`--recurse-submodules`[`=`{empty}__<pathspec>__]::\n     -+s:[\"--recurse-submodules[=<pathspec>]\"]::\n     ++`--recurse-submodules[=<pathspec>]`::\n       \tAfter the clone is created, initialize and clone submodules\n     - \twithin based on the provided _<pathspec>_.  If no _=<pathspec>_ is\n     +-\twithin based on the provided _<pathspec>_.  If no _=<pathspec>_ is\n     ++\twithin based on the provided _<pathspec>_.  If no `=<pathspec>` is\n       \tprovided, all submodules are initialized and cloned.\n     -@@ Documentation/git-clone.txt: branch of some repository for search indexing.\n     + \tThis option can be given multiple times for pathspecs consisting\n     + \tof multiple entries.  The resulting clone has `submodule.active` set to\n     +-\tthe provided pathspec, or \".\" (meaning all submodules) if no\n     ++\tthe provided pathspec, or \"`.`\" (meaning all submodules) if no\n     + \tpathspec is provided.\n       +\n       Submodules are initialized and cloned using their default settings. This is\n     - equivalent to running\n     --`git submodule update --init --recursive <pathspec>` immediately after\n     -+s:[\"git submodule update --init --recursive <pathspec>\"] immediately after\n     - the clone is finished. This option is ignored if the cloned repository does\n     +@@ Documentation/git-clone.txt: the clone is finished. This option is ignored if the cloned repository does\n       not have a worktree/checkout (i.e. if any of `--no-checkout`/`-n`, `--bare`,\n       or `--mirror` is given)\n       \n      -`--`[`no-`]`shallow-submodules`::\n     -+s:[\"--[no-]shallow-submodules\"]::\n     ++`--[no-]shallow-submodules`::\n       \tAll submodules which are cloned will be shallow with a depth of 1.\n       \n      -`--`[`no-`]`remote-submodules`::\n     -+s:[\"--[no-]remote-submodules\"]::\n     ++`--[no-]remote-submodules`::\n       \tAll submodules which are cloned will use the status of the submodule's\n       \tremote-tracking branch to update the submodule, rather than the\n       \tsuperproject's recorded SHA-1. Equivalent to passing `--remote` to\n       \t`git submodule update`.\n       \n      -`--separate-git-dir=`{empty}__<git-dir>__::\n     -+s:[\"--separate-git-dir=<git-dir>\"]::\n     ++`--separate-git-dir=<git-dir>`::\n       \tInstead of placing the cloned repository where it is supposed\n       \tto be, place the cloned repository at the specified directory,\n       \tthen make a filesystem-agnostic Git symbolic link to there.\n     @@ Documentation/git-clone.txt: branch of some repository for search indexing.\n       \ttree.\n       \n      -`--ref-format=`{empty}__<ref-format>__::\n     -+s:[\"--ref-format=<ref-format>\"]::\n     ++`--ref-format=<ref-format>`::\n       \n       Specify the given ref storage format for the repository. The valid values are:\n       +\n     @@ Documentation/git-clone.txt: _<directory>_::\n       \tis only allowed if the directory is empty.\n       \n      -`--bundle-uri=`{empty}__<uri>__::\n     -+s:[\"--bundle-uri=<uri>\"]::\n     ++`--bundle-uri=<uri>`::\n       \tBefore fetching from the remote, fetch a bundle from the given\n       \t_<uri>_ and unbundle the data into the local repository. The refs\n       \tin the bundle will be stored under the hidden `refs/bundle/*`\n     @@ Documentation/git-init.txt: Only print error and warning messages; all other out\n       \n      -++--object-format=++__<format>__::\n      -\n     -+s:[\"--object-format=<format>\"]::\n     ++`--object-format=<format>`::\n       Specify the given object _<format>_ (hash algorithm) for the repository.  The valid\n       values are `sha1` and (if enabled) `sha256`.  `sha1` is the default.\n       +\n     @@ Documentation/git-init.txt: Only print error and warning messages; all other out\n       \n      -++--ref-format=++__<format>__::\n      -\n     -+s:[\"--ref-format=<format>\"]::\n     ++`--ref-format=<format>`::\n       Specify the given ref storage _<format>_ for the repository. The valid values are:\n       +\n       include::ref-storage-format.txt[]\n       \n      -++--template=++__<template-directory>__::\n      -\n     -+s:[\"--template=<template-directory>\"]::\n     ++`--template=<template-directory>`::\n       Specify the directory from which templates will be used.  (See the \"TEMPLATE\n       DIRECTORY\" section below.)\n       \n      -++--separate-git-dir=++__<git-dir>__::\n      -\n     -+s:[\"--separate-git-dir=<git-dir>\"]::\n     ++`--separate-git-dir=<git-dir>`::\n       Instead of initializing the repository as a directory to either `$GIT_DIR` or\n       `./.git/`, create a text file there containing the path to the actual\n       repository.  This file acts as a filesystem-agnostic Git symbolic link to the\n      @@ Documentation/git-init.txt: repository.\n     + +\n       If this is a reinitialization, the repository will be moved to the specified path.\n       \n     - `-b` _<branch-name>_::\n     +-`-b` _<branch-name>_::\n      -++--initial-branch=++__<branch-name>__::\n      -\n     -+s:[\"--initial-branch=<branch-name>\"]::\n     ++`-b <branch-name>`::\n     ++`--initial-branch=<branch-name>`::\n       Use _<branch-name>_ for the initial branch in the newly created\n       repository.  If not specified, fall back to the default name (currently\n       `master`, but this is subject to change in the future; the name can be\n       customized via the `init.defaultBranch` configuration variable).\n       \n      -++--shared++[++=++(`false`|`true`|`umask`|`group`|`all`|`world`|`everybody`|_<perm>_)]::\n     -+s:[\"--shared[=(false|true|umask|group|all|world|everybody|<perm>)]\"]::\n     ++`--shared[=(false|true|umask|group|all|world|everybody|<perm>)]`::\n       \n       Specify that the Git repository is to be shared amongst several users.  This\n       allows users belonging to the same group to push into that\n     @@ Documentation/urls.txt: Git supports ssh, git, http, and https protocols (in add\n      -- ++git://++__<host>__{startsb}:__<port>__{endsb}++/++__<path-to-git-repo>__\n      -- ++http++{startsb}++s++{endsb}++://++__<host>__{startsb}++:++__<port>__{endsb}++/++__<path-to-git-repo>__\n      -- ++ftp++{startsb}++s++{endsb}++://++__<host>__{startsb}++:++__<port>__{endsb}++/++__<path-to-git-repo>__\n     -+- s:[\"ssh://[<user>@]<host>[:<port>]/<path-to-git-repo>\"]\n     -+- s:[\"git://<host>[:<port>]/<path-to-git-repo>\"]\n     -+- s:[\"http[s]://<host>[:<port>]/<path-to-git-repo>\"]\n     -+- s:[\"ftp[s]://<host>[:<port>]/<path-to-git-repo>\"]\n     ++- `ssh://[<user>@]<host>[:<port>]/<path-to-git-repo>`\n     ++- `git://<host>[:<port>]/<path-to-git-repo>`\n     ++- `http[s]://<host>[:<port>]/<path-to-git-repo>`\n     ++- `ftp[s]://<host>[:<port>]/<path-to-git-repo>`\n       \n       An alternative scp-like syntax may also be used with the ssh protocol:\n       \n      -- {startsb}__<user>__++@++{endsb}__<host>__++:/++__<path-to-git-repo>__\n     -+- s:[\"[<user>@]<host>:/<path-to-git-repo>\"]\n     ++- `[<user>@]<host>:/<path-to-git-repo>`\n       \n       This syntax is only recognized if there are no slashes before the\n       first colon. This helps differentiate a local path that contains a\n     @@ Documentation/urls.txt: colon. For example the local path `foo:bar` could be spe\n       url.\n       \n      -The ssh and git protocols additionally support ++~++__<username>__ expansion:\n     -+The ssh and git protocols additionally support s:[\"~<username>\"] expansion:\n     ++The ssh and git protocols additionally support `~<username>` expansion:\n       \n      -- ++ssh://++{startsb}__<user>__++@++{endsb}__<host>__{startsb}++:++__<port>__{endsb}++/~++__<user>__++/++__<path-to-git-repo>__\n      -- ++git://++__<host>__{startsb}++:++__<port>__{endsb}++/~++__<user>__++/++__<path-to-git-repo>__\n      -- {startsb}__<user>__++@++{endsb}__<host>__++:~++__<user>__++/++__<path-to-git-repo>__\n     -+- s:[\"ssh://[<user>@]<host>[:<port>]/~<user>/<path-to-git-repo>\"]\n     -+- s:[\"git://<host>[:<port>]/~<user>/<path-to-git-repo>\"]\n     -+- s:[\"[<user>@]<host>:~<user>/<path-to-git-repo>\"]\n     ++- `ssh://[<user>@]<host>[:<port>]/~<user>/<path-to-git-repo>`\n     ++- `git://<host>[:<port>]/~<user>/<path-to-git-repo>`\n     ++- `[<user>@]<host>:~<user>/<path-to-git-repo>`\n       \n       For local repositories, also supported by Git natively, the following\n       syntaxes may be used:\n     @@ Documentation/urls.txt: endif::git-clone[]\n       \n       When Git doesn't know how to handle a certain transport protocol, it\n      -attempts to use the `remote-`{empty}__<transport>__ remote helper, if one\n     -+attempts to use the s:[\"remote-<transport>\"] remote helper, if one\n     ++attempts to use the `remote-<transport>` remote helper, if one\n       exists. To explicitly request a remote helper, the following syntax\n       may be used:\n       \n      -- _<transport>_::__<address>__\n     -+- s:[\"<transport>::<address>\"]\n     ++- `<transport>::<address>`\n       \n       where _<address>_ may be a path, a server and path, or an arbitrary\n       URL-like string recognized by the specific remote helper being\n\n-- \ngitgitgadget\n"},{"id":"502291","messageId":"c48649ccd63bf8388c548f18bca545beca9bb41e.1725573126.git.gitgitgadget@gmail.com","threadId":"61831","inReplyTo":"pull.1766.v4.git.1725573126.gitgitgadget@gmail.com","subject":"[PATCH v4 2/3] doc: update the guidelines to reflect the current formatting rules","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-09-05T21:52:05Z","receivedAt":"2024-09-05T21:52:12Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n Documentation/CodingGuidelines | 58 ++++++++++++++++++----------------\n 1 file changed, 30 insertions(+), 28 deletions(-)\n\ndiff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines\nindex ccaea39752c..13cbcf1d7a5 100644\n--- a/Documentation/CodingGuidelines\n+++ b/Documentation/CodingGuidelines\n@@ -820,78 +820,80 @@ Markup:\n    _<new-branch-name>_\n    _<template-directory>_\n \n- A placeholder is not enclosed in backticks, as it is not a literal.\n-\n  When needed, use a distinctive identifier for placeholders, usually\n  made of a qualification and a type:\n    _<git-dir>_\n    _<key-id>_\n \n- When literal and placeholders are mixed, each markup is applied for\n- each sub-entity. If they are stuck, a special markup, called\n- unconstrained formatting is required.\n- Unconstrained formating for placeholders is __<like-this>__\n- Unconstrained formatting for literal formatting is ++like this++\n-   `--jobs` _<n>_\n-   ++--sort=++__<key>__\n-   __<directory>__++/.git++\n-   ++remote.++__<name>__++.mirror++\n+ Git's Asciidoc processor has been tailored to treat backticked text\n+ as complex synopsis. When literal and placeholders are mixed, you can\n+ use the backtick notation which will take care of correctly typesetting\n+ the content.\n+   `--jobs <n>`\n+   `--sort=<key>`\n+   `<directory>/.git`\n+   `remote.<name>.mirror`\n+   `ssh://[<user>@]<host>[:<port>]/<path-to-git-repo>`\n \n- caveat: ++ unconstrained format is not verbatim and may expand\n- content. Use Asciidoc escapes inside them.\n+As a side effect, backquoted placeholders are correctly typeset, but\n+this style is not recommended.\n \n Synopsis Syntax\n \n- Syntax grammar is formatted neither as literal nor as placeholder.\n+ The synopsis (a paragraph with [synopsis] attribute) is automatically\n+ formatted by the toolchain and does not need typesetting.\n \n  A few commented examples follow to provide reference when writing or\n  modifying command usage strings and synopsis sections in the manual\n  pages:\n \n  Possibility of multiple occurrences is indicated by three dots:\n-   _<file>_...\n+   <file>...\n    (One or more of <file>.)\n \n  Optional parts are enclosed in square brackets:\n-   [_<file>_...]\n+   [<file>...]\n    (Zero or more of <file>.)\n \n-   ++--exec-path++[++=++__<path>__]\n+ An optional parameter needs to be typeset with unconstrained pairs\n+   [<repository>]\n+\n+   --exec-path[=<path>]\n    (Option with an optional argument.  Note that the \"=\" is inside the\n    brackets.)\n \n-   [_<patch>_...]\n+   [<patch>...]\n    (Zero or more of <patch>.  Note that the dots are inside, not\n    outside the brackets.)\n \n  Multiple alternatives are indicated with vertical bars:\n-   [`-q` | `--quiet`]\n-   [`--utf8` | `--no-utf8`]\n+   [-q | --quiet]\n+   [--utf8 | --no-utf8]\n \n  Use spacing around \"|\" token(s), but not immediately after opening or\n  before closing a [] or () pair:\n-   Do: [`-q` | `--quiet`]\n-   Don't: [`-q`|`--quiet`]\n+   Do: [-q | --quiet]\n+   Don't: [-q|--quiet]\n \n  Don't use spacing around \"|\" tokens when they're used to separate the\n  alternate arguments of an option:\n-    Do: ++--track++[++=++(`direct`|`inherit`)]`\n-    Don't: ++--track++[++=++(`direct` | `inherit`)]\n+    Do: --track[=(direct|inherit)]\n+    Don't: --track[=(direct | inherit)]\n \n  Parentheses are used for grouping:\n-   [(_<rev>_ | _<range>_)...]\n+   [(<rev>|<range>)...]\n    (Any number of either <rev> or <range>.  Parens are needed to make\n    it clear that \"...\" pertains to both <rev> and <range>.)\n \n-   [(`-p` _<parent>_)...]\n+   [(-p <parent>)...]\n    (Any number of option -p, each with one <parent> argument.)\n \n-   `git remote set-head` _<name>_ (`-a` | `-d` | _<branch>_)\n+   git remote set-head <name> (-a|-d|<branch>)\n    (One and only one of \"-a\", \"-d\" or \"<branch>\" _must_ (no square\n    brackets) be provided.)\n \n  And a somewhat more contrived example:\n-   `--diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]`\n+   --diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]\n    Here \"=\" is outside the brackets, because \"--diff-filter=\" is a\n    valid usage.  \"*\" has its own pair of brackets, because it can\n    (optionally) be specified only when one or more of the letters is\n-- \ngitgitgadget\n\n"},{"id":"502292","messageId":"719188da711f9e2f66dea706b3df28e4930fa060.1725573126.git.gitgitgadget@gmail.com","threadId":"61831","inReplyTo":"pull.1766.v4.git.1725573126.gitgitgadget@gmail.com","subject":"[PATCH v4 3/3] doc: apply synopsis simplification on git-clone and git-init","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-09-05T21:52:06Z","receivedAt":"2024-09-05T21:52:13Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n\nWith the new synopsis formatting backend, no special asciidoc markup\nis needed.\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n Documentation/git-clone.txt | 78 ++++++++++++++++++-------------------\n Documentation/git-init.txt  | 35 +++++++----------\n Documentation/urls.txt      | 26 ++++++-------\n 3 files changed, 67 insertions(+), 72 deletions(-)\n\ndiff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt\nindex 8e925db7e9c..9c13f847da3 100644\n--- a/Documentation/git-clone.txt\n+++ b/Documentation/git-clone.txt\n@@ -8,16 +8,16 @@ git-clone - Clone a repository into a new directory\n \n SYNOPSIS\n --------\n-[verse]\n-`git clone` [++--template=++__<template-directory>__]\n-\t  [`-l`] [`-s`] [`--no-hardlinks`] [`-q`] [`-n`] [`--bare`] [`--mirror`]\n-\t  [`-o` _<name>_] [`-b` _<name>_] [`-u` _<upload-pack>_] [`--reference` _<repository>_]\n-\t  [`--dissociate`] [`--separate-git-dir` _<git-dir>_]\n-\t  [`--depth` _<depth>_] [`--`[`no-`]{empty}`single-branch`] [`--no-tags`]\n-\t  [++--recurse-submodules++[++=++__<pathspec>__]] [++--++[++no-++]{empty}++shallow-submodules++]\n-\t  [`--`[`no-`]{empty}`remote-submodules`] [`--jobs` _<n>_] [`--sparse`] [`--`[`no-`]{empty}`reject-shallow`]\n-\t  [++--filter=++__<filter-spec>__] [`--also-filter-submodules`]] [`--`] _<repository>_\n-\t  [_<directory>_]\n+[synopsis]\n+git clone [--template=<template-directory>]\n+\t  [-l] [-s] [--no-hardlinks] [-q] [-n] [--bare] [--mirror]\n+\t  [-o <name>] [-b <name>] [-u <upload-pack>] [--reference <repository>]\n+\t  [--dissociate] [--separate-git-dir <git-dir>]\n+\t  [--depth <depth>] [--[no-]single-branch] [--no-tags]\n+\t  [--recurse-submodules[=<pathspec>]] [--[no-]shallow-submodules]\n+\t  [--[no-]remote-submodules] [--jobs <n>] [--sparse] [--[no-]reject-shallow]\n+\t  [--filter=<filter-spec>] [--also-filter-submodules]] [--] <repository>\n+\t  [<directory>]\n \n DESCRIPTION\n -----------\n@@ -52,7 +52,7 @@ OPTIONS\n \tto save space when possible.\n +\n If the repository is specified as a local path (e.g., `/path/to/repo`),\n-this is the default, and --local is essentially a no-op.  If the\n+this is the default, and `--local` is essentially a no-op.  If the\n repository is specified as a URL, then this flag is ignored (and we\n never use the local optimizations).  Specifying `--no-local` will\n override the default when `/path/to/repo` is given, using the regular\n@@ -64,8 +64,8 @@ prevent the unintentional copying of files by dereferencing the symbolic\n links.\n +\n *NOTE*: this operation can race with concurrent modification to the\n-source repository, similar to running `cp -r src dst` while modifying\n-`src`.\n+source repository, similar to running `cp -r <src> <dst>` while modifying\n+_<src>_.\n \n `--no-hardlinks`::\n \tForce the cloning process from a repository on a local\n@@ -101,7 +101,7 @@ If you want to break the dependency of a repository cloned with `--shared` on\n its source repository, you can simply run `git repack -a` to copy all\n objects from the source repository into a pack in the cloned repository.\n \n-`--reference`[`-if-able`] _<repository>_::\n+`--reference[-if-able] <repository>`::\n \tIf the reference _<repository>_ is on the local machine,\n \tautomatically setup `.git/objects/info/alternates` to\n \tobtain objects from the reference _<repository>_.  Using\n@@ -142,17 +142,17 @@ objects from the source repository into a pack in the cloned repository.\n \tis specified. This flag forces progress status even if the\n \tstandard error stream is not directed to a terminal.\n \n-++--server-option=++__<option>__::\n+`--server-option=<option>`::\n \tTransmit the given string to the server when communicating using\n \tprotocol version 2.  The given string must not contain a NUL or LF\n \tcharacter.  The server's handling of server options, including\n \tunknown ones, is server-specific.\n-\tWhen multiple ++--server-option=++__<option>__ are given, they are all\n+\tWhen multiple `--server-option=<option>` are given, they are all\n \tsent to the other side in the order listed on the command line.\n \n `-n`::\n `--no-checkout`::\n-\tNo checkout of HEAD is performed after the clone is complete.\n+\tNo checkout of `HEAD` is performed after the clone is complete.\n \n `--`[`no-`]`reject-shallow`::\n \tFail if the source repository is a shallow repository.\n@@ -162,7 +162,7 @@ objects from the source repository into a pack in the cloned repository.\n `--bare`::\n \tMake a 'bare' Git repository.  That is, instead of\n \tcreating _<directory>_ and placing the administrative\n-\tfiles in _<directory>_`/.git`, make the _<directory>_\n+\tfiles in `<directory>/.git`, make the _<directory>_\n \titself the `$GIT_DIR`. This obviously implies the `--no-checkout`\n \tbecause there is nowhere to check out the working tree.\n \tAlso the branch heads at the remote are copied directly\n@@ -177,13 +177,13 @@ objects from the source repository into a pack in the cloned repository.\n \tlinkgit:git-sparse-checkout[1] command can be used to grow the\n \tworking directory as needed.\n \n-++--filter=++__<filter-spec>__::\n+`--filter=<filter-spec>`::\n \tUse the partial clone feature and request that the server sends\n \ta subset of reachable objects according to a given object filter.\n \tWhen using `--filter`, the supplied _<filter-spec>_ is used for\n \tthe partial clone filter. For example, `--filter=blob:none` will\n \tfilter out all blobs (file contents) until needed by Git. Also,\n-\t++--filter=blob:limit=++__<size>__ will filter out all blobs of size\n+\t`--filter=blob:limit=<size>` will filter out all blobs of size\n \tat least _<size>_. For more details on filter specifications, see\n \tthe `--filter` option in linkgit:git-rev-list[1].\n \n@@ -208,11 +208,11 @@ objects from the source repository into a pack in the cloned repository.\n \n `-b` _<name>_::\n `--branch` _<name>_::\n-\tInstead of pointing the newly created HEAD to the branch pointed\n-\tto by the cloned repository's HEAD, point to _<name>_ branch\n+\tInstead of pointing the newly created `HEAD` to the branch pointed\n+\tto by the cloned repository's `HEAD`, point to _<name>_ branch\n \tinstead. In a non-bare repository, this is the branch that will\n \tbe checked out.\n-\t`--branch` can also take tags and detaches the HEAD at that commit\n+\t`--branch` can also take tags and detaches the `HEAD` at that commit\n \tin the resulting repository.\n \n `-u` _<upload-pack>_::\n@@ -221,12 +221,12 @@ objects from the source repository into a pack in the cloned repository.\n \tvia ssh, this specifies a non-default path for the command\n \trun on the other end.\n \n-++--template=++__<template-directory>__::\n+`--template=<template-directory>`::\n \tSpecify the directory from which templates will be used;\n \t(See the \"TEMPLATE DIRECTORY\" section of linkgit:git-init[1].)\n \n-`-c` __<key>__++=++__<value>__::\n-`--config` __<key>__++=++__<value>__::\n+`-c` `<key>=<value>`::\n+`--config` `<key>=<value>`::\n \tSet a configuration variable in the newly-created repository;\n \tthis takes effect immediately after the repository is\n \tinitialized, but before the remote history is fetched or any\n@@ -239,25 +239,25 @@ objects from the source repository into a pack in the cloned repository.\n Due to limitations of the current implementation, some configuration\n variables do not take effect until after the initial fetch and checkout.\n Configuration variables known to not take effect are:\n-++remote.++__<name>__++.mirror++ and ++remote.++__<name>__++.tagOpt++.  Use the\n+`remote.<name>.mirror` and `remote.<name>.tagOpt`.  Use the\n corresponding `--mirror` and `--no-tags` options instead.\n \n-`--depth` _<depth>_::\n+`--depth <depth>`::\n \tCreate a 'shallow' clone with a history truncated to the\n \tspecified number of commits. Implies `--single-branch` unless\n \t`--no-single-branch` is given to fetch the histories near the\n \ttips of all branches. If you want to clone submodules shallowly,\n \talso pass `--shallow-submodules`.\n \n-++--shallow-since=++__<date>__::\n+`--shallow-since=<date>`::\n \tCreate a shallow clone with a history after the specified time.\n \n-++--shallow-exclude=++__<revision>__::\n+`--shallow-exclude=<revision>`::\n \tCreate a shallow clone with a history, excluding commits\n \treachable from a specified remote branch or tag.  This option\n \tcan be specified multiple times.\n \n-`--`[`no-`]`single-branch`::\n+`--[no-]single-branch`::\n \tClone only the history leading to the tip of a single branch,\n \teither specified by the `--branch` option or the primary\n \tbranch remote's `HEAD` points at.\n@@ -279,13 +279,13 @@ maintain a branch with no references other than a single cloned\n branch. This is useful e.g. to maintain minimal clones of the default\n branch of some repository for search indexing.\n \n-`--recurse-submodules`[`=`{empty}__<pathspec>__]::\n+`--recurse-submodules[=<pathspec>]`::\n \tAfter the clone is created, initialize and clone submodules\n-\twithin based on the provided _<pathspec>_.  If no _=<pathspec>_ is\n+\twithin based on the provided _<pathspec>_.  If no `=<pathspec>` is\n \tprovided, all submodules are initialized and cloned.\n \tThis option can be given multiple times for pathspecs consisting\n \tof multiple entries.  The resulting clone has `submodule.active` set to\n-\tthe provided pathspec, or \".\" (meaning all submodules) if no\n+\tthe provided pathspec, or \"`.`\" (meaning all submodules) if no\n \tpathspec is provided.\n +\n Submodules are initialized and cloned using their default settings. This is\n@@ -295,23 +295,23 @@ the clone is finished. This option is ignored if the cloned repository does\n not have a worktree/checkout (i.e. if any of `--no-checkout`/`-n`, `--bare`,\n or `--mirror` is given)\n \n-`--`[`no-`]`shallow-submodules`::\n+`--[no-]shallow-submodules`::\n \tAll submodules which are cloned will be shallow with a depth of 1.\n \n-`--`[`no-`]`remote-submodules`::\n+`--[no-]remote-submodules`::\n \tAll submodules which are cloned will use the status of the submodule's\n \tremote-tracking branch to update the submodule, rather than the\n \tsuperproject's recorded SHA-1. Equivalent to passing `--remote` to\n \t`git submodule update`.\n \n-`--separate-git-dir=`{empty}__<git-dir>__::\n+`--separate-git-dir=<git-dir>`::\n \tInstead of placing the cloned repository where it is supposed\n \tto be, place the cloned repository at the specified directory,\n \tthen make a filesystem-agnostic Git symbolic link to there.\n \tThe result is Git repository can be separated from working\n \ttree.\n \n-`--ref-format=`{empty}__<ref-format>__::\n+`--ref-format=<ref-format>`::\n \n Specify the given ref storage format for the repository. The valid values are:\n +\n@@ -334,7 +334,7 @@ _<directory>_::\n \tfor `host.xz:foo/.git`).  Cloning into an existing directory\n \tis only allowed if the directory is empty.\n \n-`--bundle-uri=`{empty}__<uri>__::\n+`--bundle-uri=<uri>`::\n \tBefore fetching from the remote, fetch a bundle from the given\n \t_<uri>_ and unbundle the data into the local repository. The refs\n \tin the bundle will be stored under the hidden `refs/bundle/*`\ndiff --git a/Documentation/git-init.txt b/Documentation/git-init.txt\nindex daff93bd164..315f7f7530c 100644\n--- a/Documentation/git-init.txt\n+++ b/Documentation/git-init.txt\n@@ -8,12 +8,12 @@ git-init - Create an empty Git repository or reinitialize an existing one\n \n SYNOPSIS\n --------\n-[verse]\n-`git init` [`-q` | `--quiet`] [`--bare`] [++--template=++__<template-directory>__]\n-\t  [`--separate-git-dir` _<git-dir>_] [++--object-format=++__<format>__]\n-\t  [++--ref-format=++__<format>__]\n-\t  [`-b` _<branch-name>_ | ++--initial-branch=++__<branch-name>__]\n-\t  [++--shared++[++=++__<permissions>__]] [_<directory>_]\n+[synopsis]\n+git init [-q | --quiet] [--bare] [--template=<template-directory>]\n+\t [--separate-git-dir <git-dir>] [--object-format=<format>]\n+\t [--ref-format=<format>]\n+\t [-b <branch-name> | --initial-branch=<branch-name>]\n+\t [--shared[=<permissions>]] [<directory>]\n \n \n DESCRIPTION\n@@ -25,11 +25,11 @@ directory with subdirectories for `objects`, `refs/heads`,\n commits will be created (see the `--initial-branch` option below\n for its name).\n \n-If the `$GIT_DIR` environment variable is set then it specifies a path\n+If the `GIT_DIR` environment variable is set then it specifies a path\n to use instead of `./.git` for the base of the repository.\n \n If the object storage directory is specified via the\n-`$GIT_OBJECT_DIRECTORY` environment variable then the sha1 directories\n+`GIT_OBJECT_DIRECTORY` environment variable then the sha1 directories\n are created underneath; otherwise, the default `$GIT_DIR/objects`\n directory is used.\n \n@@ -51,26 +51,22 @@ Only print error and warning messages; all other output will be suppressed.\n Create a bare repository. If `GIT_DIR` environment is not set, it is set to the\n current working directory.\n \n-++--object-format=++__<format>__::\n-\n+`--object-format=<format>`::\n Specify the given object _<format>_ (hash algorithm) for the repository.  The valid\n values are `sha1` and (if enabled) `sha256`.  `sha1` is the default.\n +\n include::object-format-disclaimer.txt[]\n \n-++--ref-format=++__<format>__::\n-\n+`--ref-format=<format>`::\n Specify the given ref storage _<format>_ for the repository. The valid values are:\n +\n include::ref-storage-format.txt[]\n \n-++--template=++__<template-directory>__::\n-\n+`--template=<template-directory>`::\n Specify the directory from which templates will be used.  (See the \"TEMPLATE\n DIRECTORY\" section below.)\n \n-++--separate-git-dir=++__<git-dir>__::\n-\n+`--separate-git-dir=<git-dir>`::\n Instead of initializing the repository as a directory to either `$GIT_DIR` or\n `./.git/`, create a text file there containing the path to the actual\n repository.  This file acts as a filesystem-agnostic Git symbolic link to the\n@@ -78,15 +74,14 @@ repository.\n +\n If this is a reinitialization, the repository will be moved to the specified path.\n \n-`-b` _<branch-name>_::\n-++--initial-branch=++__<branch-name>__::\n-\n+`-b <branch-name>`::\n+`--initial-branch=<branch-name>`::\n Use _<branch-name>_ for the initial branch in the newly created\n repository.  If not specified, fall back to the default name (currently\n `master`, but this is subject to change in the future; the name can be\n customized via the `init.defaultBranch` configuration variable).\n \n-++--shared++[++=++(`false`|`true`|`umask`|`group`|`all`|`world`|`everybody`|_<perm>_)]::\n+`--shared[=(false|true|umask|group|all|world|everybody|<perm>)]`::\n \n Specify that the Git repository is to be shared amongst several users.  This\n allows users belonging to the same group to push into that\ndiff --git a/Documentation/urls.txt b/Documentation/urls.txt\nindex 7cec85aef17..9c871e716a1 100644\n--- a/Documentation/urls.txt\n+++ b/Documentation/urls.txt\n@@ -10,19 +10,19 @@ Git supports ssh, git, http, and https protocols (in addition, ftp\n and ftps can be used for fetching, but this is inefficient and\n deprecated; do not use them).\n \n-The native transport (i.e. git:// URL) does no authentication and\n+The native transport (i.e. `git://` URL) does no authentication and\n should be used with caution on unsecured networks.\n \n The following syntaxes may be used with them:\n \n-- ++ssh://++{startsb}__<user>__++@++{endsb}__<host>__{startsb}++:++__<port>__{endsb}++/++__<path-to-git-repo>__\n-- ++git://++__<host>__{startsb}:__<port>__{endsb}++/++__<path-to-git-repo>__\n-- ++http++{startsb}++s++{endsb}++://++__<host>__{startsb}++:++__<port>__{endsb}++/++__<path-to-git-repo>__\n-- ++ftp++{startsb}++s++{endsb}++://++__<host>__{startsb}++:++__<port>__{endsb}++/++__<path-to-git-repo>__\n+- `ssh://[<user>@]<host>[:<port>]/<path-to-git-repo>`\n+- `git://<host>[:<port>]/<path-to-git-repo>`\n+- `http[s]://<host>[:<port>]/<path-to-git-repo>`\n+- `ftp[s]://<host>[:<port>]/<path-to-git-repo>`\n \n An alternative scp-like syntax may also be used with the ssh protocol:\n \n-- {startsb}__<user>__++@++{endsb}__<host>__++:/++__<path-to-git-repo>__\n+- `[<user>@]<host>:/<path-to-git-repo>`\n \n This syntax is only recognized if there are no slashes before the\n first colon. This helps differentiate a local path that contains a\n@@ -30,17 +30,17 @@ colon. For example the local path `foo:bar` could be specified as an\n absolute path or `./foo:bar` to avoid being misinterpreted as an ssh\n url.\n \n-The ssh and git protocols additionally support ++~++__<username>__ expansion:\n+The ssh and git protocols additionally support `~<username>` expansion:\n \n-- ++ssh://++{startsb}__<user>__++@++{endsb}__<host>__{startsb}++:++__<port>__{endsb}++/~++__<user>__++/++__<path-to-git-repo>__\n-- ++git://++__<host>__{startsb}++:++__<port>__{endsb}++/~++__<user>__++/++__<path-to-git-repo>__\n-- {startsb}__<user>__++@++{endsb}__<host>__++:~++__<user>__++/++__<path-to-git-repo>__\n+- `ssh://[<user>@]<host>[:<port>]/~<user>/<path-to-git-repo>`\n+- `git://<host>[:<port>]/~<user>/<path-to-git-repo>`\n+- `[<user>@]<host>:~<user>/<path-to-git-repo>`\n \n For local repositories, also supported by Git natively, the following\n syntaxes may be used:\n \n - `/path/to/repo.git/`\n-- ++file:///path/to/repo.git/++\n+- `file:///path/to/repo.git/`\n \n ifndef::git-clone[]\n These two syntaxes are mostly equivalent, except when cloning, when\n@@ -57,11 +57,11 @@ endif::git-clone[]\n accept a suitable bundle file. See linkgit:git-bundle[1].\n \n When Git doesn't know how to handle a certain transport protocol, it\n-attempts to use the `remote-`{empty}__<transport>__ remote helper, if one\n+attempts to use the `remote-<transport>` remote helper, if one\n exists. To explicitly request a remote helper, the following syntax\n may be used:\n \n-- _<transport>_::__<address>__\n+- `<transport>::<address>`\n \n where _<address>_ may be a path, a server and path, or an arbitrary\n URL-like string recognized by the specific remote helper being\n-- \ngitgitgadget\n"},{"id":"502771","messageId":"xmqqo74rxvw0.fsf@gitster.g","threadId":"61831","inReplyTo":"pull.1766.v4.git.1725573126.gitgitgadget@gmail.com","subject":"Re: [PATCH v4 0/3] doc: introducing synopsis para","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-09-13T18:15:43Z","receivedAt":"2024-09-13T18:15:46Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Jean-Noël Avila via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n> In the continuation of the simplification of manpage editing, the synopsis\n> processing that was developed for synopsis paragraph style is also applied\n> to all inline backquoted texts.\n>\n> Refining the magic regexp took more time than expected, but this one should\n> really enhance writers'experience. I had to fight a bit more with\n> asciidoctor, due to discrepancies between version 2.0 on my laptop and the\n> 1.5.6 used by Github actions.\n>\n> The git-init and git-clone manpages are converted to this new system.\n\nThe fact that such a \"magic\" processing will hide the gory details\nfrom those whose primary interest is to describe the commands and\ntheir options cuts both ways.  While I can understand that purists\nwould find it ugly, as `backticks` is now much more than a mark-up\nthat means \"this text is typeset in monospace\", it is a very welcome\nthing for developers around here, who just want to write their\ndocument in a way even whose source is readable without having to\nworry about suh gory details.  Maybe this gets popular enough after\nother projects notice what you did to AsciiDoctor, love it, adopt\nit, and eventually it feeds back to improve AsciiDoctor proper ;-).\n\nSo, unless there are objections and people want to discuss it further,\nI'll mark the topic for 'next' soonish.\n\nThanks.\n"},{"id":"503174","messageId":"4ww5v253vz2g4i3z2x3dmgkrot7mcn2qm6ckjcxbyky6yvrozy@mr5hnrsfj6sn","threadId":"61831","inReplyTo":"xmqqo74rxvw0.fsf@gitster.g","subject":"Re: [PATCH v4 0/3] doc: introducing synopsis para","fromName":"Josh Steadmon","fromEmail":"steadmon@google.com","sentAt":"2024-09-20T23:14:26Z","receivedAt":"2024-09-20T23:14:32Z","isPatch":true,"sender":{"key":"steadmon@google.com","avatar":"https://avatars.githubusercontent.com/u/2654920?v=4"},"body":"On 2024.09.13 11:15, Junio C Hamano wrote:\n> \"Jean-Noël Avila via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n> \n> > In the continuation of the simplification of manpage editing, the synopsis\n> > processing that was developed for synopsis paragraph style is also applied\n> > to all inline backquoted texts.\n> >\n> > Refining the magic regexp took more time than expected, but this one should\n> > really enhance writers'experience. I had to fight a bit more with\n> > asciidoctor, due to discrepancies between version 2.0 on my laptop and the\n> > 1.5.6 used by Github actions.\n> >\n> > The git-init and git-clone manpages are converted to this new system.\n> \n> The fact that such a \"magic\" processing will hide the gory details\n> from those whose primary interest is to describe the commands and\n> their options cuts both ways.  While I can understand that purists\n> would find it ugly, as `backticks` is now much more than a mark-up\n> that means \"this text is typeset in monospace\", it is a very welcome\n> thing for developers around here, who just want to write their\n> document in a way even whose source is readable without having to\n> worry about suh gory details.  Maybe this gets popular enough after\n> other projects notice what you did to AsciiDoctor, love it, adopt\n> it, and eventually it feeds back to improve AsciiDoctor proper ;-).\n> \n> So, unless there are objections and people want to discuss it further,\n> I'll mark the topic for 'next' soonish.\n> \n> Thanks.\n> \n\nThis still breaks on MacOS, as `sed` doesn't understand the '-E' option\nthere.\n"},{"id":"503178","messageId":"xmqqcykxbxb3.fsf@gitster.g","threadId":"61831","inReplyTo":"4ww5v253vz2g4i3z2x3dmgkrot7mcn2qm6ckjcxbyky6yvrozy@mr5hnrsfj6sn","subject":"Re: [PATCH v4 0/3] doc: introducing synopsis para","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-09-21T01:38:40Z","receivedAt":"2024-09-21T01:38:42Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Josh Steadmon <steadmon@google.com> writes:\n\n>> So, unless there are objections and people want to discuss it further,\n>> I'll mark the topic for 'next' soonish.\n>> \n>> Thanks.\n>> \n>\n> This still breaks on MacOS, as `sed` doesn't understand the '-E' option\n> there.\n\nThanks for a report.\n\nWhat is sad is that we are seeing this after the topic gets very\nclose to 'master' (it has been in 'next' already for a few days).\n\nPerhaps nobody builds documentation on macOS, in which case the\nbreakage may be totally acceptable?  Is that the message we are\nhearing from mac based developers?\n\nGrumpy...\n\n"},{"id":"503183","messageId":"xmqq34ltbkah.fsf@gitster.g","threadId":"61831","inReplyTo":"4ww5v253vz2g4i3z2x3dmgkrot7mcn2qm6ckjcxbyky6yvrozy@mr5hnrsfj6sn","subject":"Re: [PATCH v4 0/3] doc: introducing synopsis para","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-09-21T06:19:50Z","receivedAt":"2024-09-21T06:19:53Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Josh Steadmon <steadmon@google.com> writes:\n\n> This still breaks on MacOS, as `sed` doesn't understand the '-E' option\n> there.\n\nCan you try to see t6030 also breaks due to lack of ERE in the same\nenvironment?  It seems it uses \"sed -E\", so it should fail to find\nwhat it is trying to.\n\nThanks.\n"},{"id":"503184","messageId":"xmqqy13la5jb.fsf@gitster.g","threadId":"61831","inReplyTo":"xmqq34ltbkah.fsf@gitster.g","subject":"Re: [PATCH v4 0/3] doc: introducing synopsis para","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-09-21T06:23:52Z","receivedAt":"2024-09-21T06:23:55Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano <gitster@pobox.com> writes:\n\n> Josh Steadmon <steadmon@google.com> writes:\n>\n>> This still breaks on MacOS, as `sed` doesn't understand the '-E' option\n>> there.\n>\n> Can you try to see t6030 also breaks due to lack of ERE in the same\n> environment?  It seems it uses \"sed -E\", so it should fail to find\n> what it is trying to.\n>\n> Thanks.\n\nThe reason why I am curious is because https://ss64.com/mac/sed.html\nclaims that -E works.\n\nEarlier I wrote somewhere whatever problem it is it would be shared\nwith BSD implementation of sed.  But apparently BSD's sed also works\nwith the -E option.  https://man.freebsd.org/cgi/man.cgi?sed(1)\n\nSo, I dunno.  Perhaps it is not -E but some specific construct used\nin the pattern?\n"},{"id":"503185","messageId":"CAPx1GvdfE+v-wV=gbTZJi6GvwGhw8NZcZHnEwj0K+YSTfMs4Kw@mail.gmail.com","threadId":"61831","inReplyTo":"xmqqy13la5jb.fsf@gitster.g","subject":"Re: [PATCH v4 0/3] doc: introducing synopsis para","fromName":"Chris Torek","fromEmail":"chris.torek@gmail.com","sentAt":"2024-09-21T06:54:28Z","receivedAt":"2024-09-21T06:54:42Z","isPatch":true,"sender":{"key":"chris.torek@gmail.com","avatar":"https://avatars.githubusercontent.com/u/16826774?v=4"},"body":"On Fri, Sep 20, 2024 at 11:24 PM Junio C Hamano <gitster@pobox.com> wrote:\n> The reason why I am curious is because https://ss64.com/mac/sed.html\n> claims that -E works.\n\nIt does for me, on my Mac, which is deliberately behind current: I am\nstill on Big Sur.\n\nChris\n"},{"id":"503265","messageId":"xmqqh6a6496d.fsf@gitster.g","threadId":"61831","inReplyTo":"CAPx1GvdfE+v-wV=gbTZJi6GvwGhw8NZcZHnEwj0K+YSTfMs4Kw@mail.gmail.com","subject":"Re: [PATCH v4 0/3] doc: introducing synopsis para","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-09-23T16:38:34Z","receivedAt":"2024-09-23T16:38:37Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Chris Torek <chris.torek@gmail.com> writes:\n\n> On Fri, Sep 20, 2024 at 11:24 PM Junio C Hamano <gitster@pobox.com> wrote:\n>> The reason why I am curious is because https://ss64.com/mac/sed.html\n>> claims that -E works.\n>\n> It does for me, on my Mac, which is deliberately behind current: I am\n> still on Big Sur.\n\nThanks, Chris.\n\nJosh, the topic has been cooking in 'next' long enough to graduate\nto 'master' without anybody else complaining.  Could you\ndouble-check and if possible see what is different in your\nenvironment from others?\n\nI can hold the topic in 'next' longer but not forever without\nprogress.  Help from macOS folks (if it is macOS specific issue)\nis greatly appreciated.\n\nThanks.\n\n\n\n"},{"id":"503332","messageId":"pull.1766.v5.git.1727161730.gitgitgadget@gmail.com","threadId":"61831","inReplyTo":"pull.1766.v4.git.1725573126.gitgitgadget@gmail.com","subject":"[PATCH v5 0/3] doc: introducing synopsis para","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-09-24T07:08:47Z","receivedAt":"2024-09-24T07:08:54Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"In the continuation of the simplification of manpage editing, the synopsis\nprocessing that was developed for synopsis paragraph style is also applied\nto all inline backquoted texts.\n\nRefining the magic regexp took more time than expected, but this one should\nreally enhance writers'experience. I had to fight a bit more with\nasciidoctor, due to discrepancies between version 2.0 on my laptop and the\n1.5.6 used by Github actions.\n\nThe git-init and git-clone manpages are converted to this new system.\n\nChanges since V1:\n\n * switch to sed for asciidoc filter and refine the regex for support under\n   macOS\n\nChanges since V2:\n\n * introduce the s macro to freely apply synopsis styling wherever needed,\n   without formatting hassle.\n\nChanges since V3:\n\n * replace s macro by direct processing of literal text at the level of\n   output processors.\n\nChanges since V4:\n\n * used BRE in sed filter\n * rework the processing of three dots\n\nJean-Noël Avila (3):\n  doc: introduce a synopsis typesetting\n  doc: update the guidelines to reflect the current formatting rules\n  doc: apply synopsis simplification on git-clone and git-init\n\n Documentation/CodingGuidelines          | 58 +++++++++--------\n Documentation/asciidoc.conf             | 20 ++++++\n Documentation/asciidoctor-extensions.rb | 87 +++++++++++++++++++++++++\n Documentation/git-clone.txt             | 78 +++++++++++-----------\n Documentation/git-init.txt              | 35 +++++-----\n Documentation/urls.txt                  | 26 ++++----\n ci/install-dependencies.sh              |  1 +\n t/t0450-txt-doc-vs-help.sh              | 11 ++--\n 8 files changed, 209 insertions(+), 107 deletions(-)\n\n\nbase-commit: 2e7b89e038c0c888acf61f1b4ee5a43d4dd5e94c\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-1766%2Fjnavila%2Fdoc_synopsis_para-v5\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1766/jnavila/doc_synopsis_para-v5\nPull-Request: https://github.com/gitgitgadget/git/pull/1766\n\nRange-diff vs v4:\n\n 1:  c09968d7ccb ! 1:  2946cc80314 doc: introduce a synopsis typesetting\n     @@ Documentation/asciidoc.conf: ifdef::backend-xhtml11[]\n      +ifdef::backend-docbook[]\n      +ifdef::doctype-manpage[]\n      +[paradef-default]\n     -+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'\"\n     ++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'\"\n      +endif::doctype-manpage[]\n      +endif::backend-docbook[]\n      +\n      +ifdef::backend-xhtml11[]\n      +[paradef-default]\n     -+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'\"\n     ++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'\"\n       endif::backend-xhtml11[]\n      \n       ## Documentation/asciidoctor-extensions.rb ##\n 2:  c48649ccd63 = 2:  06b8fff6a57 doc: update the guidelines to reflect the current formatting rules\n 3:  719188da711 = 3:  a76998d6443 doc: apply synopsis simplification on git-clone and git-init\n\n-- \ngitgitgadget\n"},{"id":"503333","messageId":"2946cc80314aa2b3f653c83e34ccb7aeb1db44d8.1727161730.git.gitgitgadget@gmail.com","threadId":"61831","inReplyTo":"pull.1766.v5.git.1727161730.gitgitgadget@gmail.com","subject":"[PATCH v5 1/3] doc: introduce a synopsis typesetting","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-09-24T07:08:48Z","receivedAt":"2024-09-24T07:08:54Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n\nIn order to follow the common manpage usage, the synopsis of the\ncommands needs to be heavily typeset. A first try was performed with\nusing native markup, but it turned out to make the document source\nalmost unreadable, difficult to write and prone to mistakes with\nunwanted Asciidoc's role attributes.\n\nIn order to both simplify the writer's task and obtain a consistant\ntypesetting in the synopsis, a custom 'synopsis' paragraph type is\ncreated and the processor for backticked text are modified. The\nbackends of asciidoc and asciidoctor take in charge to correctly add\nthe required typesetting.\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n Documentation/asciidoc.conf             | 20 ++++++\n Documentation/asciidoctor-extensions.rb | 87 +++++++++++++++++++++++++\n ci/install-dependencies.sh              |  1 +\n t/t0450-txt-doc-vs-help.sh              | 11 ++--\n 4 files changed, 112 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf\nindex 60f76f43eda..f6da6d1fbd2 100644\n--- a/Documentation/asciidoc.conf\n+++ b/Documentation/asciidoc.conf\n@@ -28,6 +28,10 @@ ifdef::backend-docbook[]\n {0#<citerefentry>}\n {0#<refentrytitle>{target}</refentrytitle><manvolnum>{0}</manvolnum>}\n {0#</citerefentry>}\n+\n+[literal-inlinemacro]\n+{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])))}\n+\n endif::backend-docbook[]\n \n ifdef::backend-docbook[]\n@@ -56,4 +60,20 @@ ifdef::backend-xhtml11[]\n git-relative-html-prefix=\n [linkgit-inlinemacro]\n <a href=\"{git-relative-html-prefix}{target}.html\">{target}{0?({0})}</a>\n+\n+[literal-inlinemacro]\n+{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])))}\n+\n+endif::backend-xhtml11[]\n+\n+ifdef::backend-docbook[]\n+ifdef::doctype-manpage[]\n+[paradef-default]\n+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'\"\n+endif::doctype-manpage[]\n+endif::backend-docbook[]\n+\n+ifdef::backend-xhtml11[]\n+[paradef-default]\n+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'\"\n endif::backend-xhtml11[]\ndiff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb\nindex d906a008039..cb24480b63d 100644\n--- a/Documentation/asciidoctor-extensions.rb\n+++ b/Documentation/asciidoctor-extensions.rb\n@@ -1,5 +1,7 @@\n require 'asciidoctor'\n require 'asciidoctor/extensions'\n+require 'asciidoctor/converter/docbook5'\n+require 'asciidoctor/converter/html5'\n \n module Git\n   module Documentation\n@@ -39,10 +41,95 @@ module Git\n         output\n       end\n     end\n+\n+    class SynopsisBlock < Asciidoctor::Extensions::BlockProcessor\n+\n+      use_dsl\n+      named :synopsis\n+      parse_content_as :simple\n+\n+      def process parent, reader, attrs\n+        outlines = reader.lines.map do |l|\n+          l.gsub(/(\\.\\.\\.?)([^\\]$.])/, '`\\1`\\2')\n+           .gsub(%r{([\\[\\] |()>]|^)([-a-zA-Z0-9:+=~@,/_^\\$]+)}, '\\1{empty}`\\2`{empty}')\n+           .gsub(/(<[-a-zA-Z0-9.]+>)/, '__\\\\1__')\n+           .gsub(']', ']{empty}')\n+        end\n+        create_block parent, :verse, outlines, attrs\n+      end\n+    end\n+\n+    class GitDBConverter < Asciidoctor::Converter::DocBook5Converter\n+\n+      extend Asciidoctor::Converter::Config\n+      register_for 'docbook5'\n+\n+      def convert_inline_quoted node\n+        if (type = node.type) == :asciimath\n+          # NOTE fop requires jeuclid to process mathml markup\n+          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>)\n+        elsif type == :latexmath\n+          # unhandled math; pass source to alt and required mathphrase element; dblatex will process alt as LaTeX math\n+          %(<inlineequation><alt><![CDATA[#{equation = node.text}]]></alt><mathphrase><![CDATA[#{equation}]]></mathphrase></inlineequation>)\n+        elsif type == :monospaced\n+          node.text.gsub(/(\\.\\.\\.?)([^\\]$.])/, '<literal>\\1</literal>\\2')\n+              .gsub(%r{([\\[\\s|()>.]|^|\\]|&gt;)(\\.?([-a-zA-Z0-9:+=~@,/_^\\$]+\\.{0,2})+)}, '\\1<literal>\\2</literal>')\n+              .gsub(/(&lt;[-a-zA-Z0-9.]+&gt;)/, '<emphasis>\\1</emphasis>')\n+        else\n+          open, close, supports_phrase = QUOTE_TAGS[type]\n+          text = node.text\n+          if node.role\n+            if supports_phrase\n+              quoted_text = %(#{open}<phrase role=\"#{node.role}\">#{text}</phrase>#{close})\n+            else\n+              quoted_text = %(#{open.chop} role=\"#{node.role}\">#{text}#{close})\n+            end\n+          else\n+            quoted_text = %(#{open}#{text}#{close})\n+          end\n+          node.id ? %(<anchor#{common_attributes node.id, nil, text}/>#{quoted_text}) : quoted_text\n+        end\n+      end\n+    end\n+\n+    # register a html5 converter that takes in charge to convert monospaced text into Git style synopsis\n+    class GitHTMLConverter < Asciidoctor::Converter::Html5Converter\n+\n+      extend Asciidoctor::Converter::Config\n+      register_for 'html5'\n+\n+      def convert_inline_quoted node\n+        if node.type == :monospaced\n+          node.text.gsub(/(\\.\\.\\.?)([^\\]$.])/, '<code>\\1</code>\\2')\n+              .gsub(%r{([\\[\\s|()>.]|^|\\]|&gt;)(\\.?([-a-zA-Z0-9:+=~@,/_^\\$]+\\.{0,2})+)}, '\\1<code>\\2</code>')\n+              .gsub(/(&lt;[-a-zA-Z0-9.]+&gt;)/, '<em>\\1</em>')\n+\n+        else\n+          open, close, tag = QUOTE_TAGS[node.type]\n+          if node.id\n+            class_attr = node.role ? %( class=\"#{node.role}\") : ''\n+            if tag\n+              %(#{open.chop} id=\"#{node.id}\"#{class_attr}>#{node.text}#{close})\n+            else\n+              %(<span id=\"#{node.id}\"#{class_attr}>#{open}#{node.text}#{close}</span>)\n+            end\n+          elsif node.role\n+            if tag\n+              %(#{open.chop} class=\"#{node.role}\">#{node.text}#{close})\n+            else\n+              %(<span class=\"#{node.role}\">#{open}#{node.text}#{close}</span>)\n+            end\n+          else\n+            %(#{open}#{node.text}#{close})\n+          end\n+        end\n+      end\n+    end\n   end\n end\n \n Asciidoctor::Extensions.register do\n   inline_macro Git::Documentation::LinkGitProcessor, :linkgit\n+  block Git::Documentation::SynopsisBlock\n   postprocessor Git::Documentation::DocumentPostProcessor\n end\ndiff --git a/ci/install-dependencies.sh b/ci/install-dependencies.sh\nindex 4781cd20bb0..3e3ae39cbb1 100755\n--- a/ci/install-dependencies.sh\n+++ b/ci/install-dependencies.sh\n@@ -107,6 +107,7 @@ Documentation)\n \n \ttest -n \"$ALREADY_HAVE_ASCIIDOCTOR\" ||\n \tsudo gem install --version 1.5.8 asciidoctor\n+\tsudo gem install concurrent-ruby\n \t;;\n esac\n \ndiff --git a/t/t0450-txt-doc-vs-help.sh b/t/t0450-txt-doc-vs-help.sh\nindex 69917d7b845..f99a69ae1b7 100755\n--- a/t/t0450-txt-doc-vs-help.sh\n+++ b/t/t0450-txt-doc-vs-help.sh\n@@ -56,14 +56,11 @@ txt_to_synopsis () {\n \tfi &&\n \tb2t=\"$(builtin_to_txt \"$builtin\")\" &&\n \tsed -n \\\n-\t\t-e '/^\\[verse\\]$/,/^$/ {\n+\t\t-E '/^\\[(verse|synopsis)\\]$/,/^$/ {\n \t\t\t/^$/d;\n-\t\t\t/^\\[verse\\]$/d;\n-\t\t\ts/_//g;\n-\t\t\ts/++//g;\n-\t\t\ts/`//g;\n-\t\t\ts/{litdd}/--/g;\n-\t\t\ts/'\\''\\(git[ a-z-]*\\)'\\''/\\1/g;\n+\t\t\t/^\\[(verse|synopsis)\\]$/d;\n+\t\t\ts/\\{litdd\\}/--/g;\n+\t\t\ts/'\\''(git[ a-z-]*)'\\''/\\1/g;\n \n \t\t\tp;\n \t\t}' \\\n-- \ngitgitgadget\n\n"},{"id":"503334","messageId":"06b8fff6a57642aa0f6853528c00b8c30896842d.1727161730.git.gitgitgadget@gmail.com","threadId":"61831","inReplyTo":"pull.1766.v5.git.1727161730.gitgitgadget@gmail.com","subject":"[PATCH v5 2/3] doc: update the guidelines to reflect the current formatting rules","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-09-24T07:08:49Z","receivedAt":"2024-09-24T07:08:56Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n Documentation/CodingGuidelines | 58 ++++++++++++++++++----------------\n 1 file changed, 30 insertions(+), 28 deletions(-)\n\ndiff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines\nindex ccaea39752c..13cbcf1d7a5 100644\n--- a/Documentation/CodingGuidelines\n+++ b/Documentation/CodingGuidelines\n@@ -820,78 +820,80 @@ Markup:\n    _<new-branch-name>_\n    _<template-directory>_\n \n- A placeholder is not enclosed in backticks, as it is not a literal.\n-\n  When needed, use a distinctive identifier for placeholders, usually\n  made of a qualification and a type:\n    _<git-dir>_\n    _<key-id>_\n \n- When literal and placeholders are mixed, each markup is applied for\n- each sub-entity. If they are stuck, a special markup, called\n- unconstrained formatting is required.\n- Unconstrained formating for placeholders is __<like-this>__\n- Unconstrained formatting for literal formatting is ++like this++\n-   `--jobs` _<n>_\n-   ++--sort=++__<key>__\n-   __<directory>__++/.git++\n-   ++remote.++__<name>__++.mirror++\n+ Git's Asciidoc processor has been tailored to treat backticked text\n+ as complex synopsis. When literal and placeholders are mixed, you can\n+ use the backtick notation which will take care of correctly typesetting\n+ the content.\n+   `--jobs <n>`\n+   `--sort=<key>`\n+   `<directory>/.git`\n+   `remote.<name>.mirror`\n+   `ssh://[<user>@]<host>[:<port>]/<path-to-git-repo>`\n \n- caveat: ++ unconstrained format is not verbatim and may expand\n- content. Use Asciidoc escapes inside them.\n+As a side effect, backquoted placeholders are correctly typeset, but\n+this style is not recommended.\n \n Synopsis Syntax\n \n- Syntax grammar is formatted neither as literal nor as placeholder.\n+ The synopsis (a paragraph with [synopsis] attribute) is automatically\n+ formatted by the toolchain and does not need typesetting.\n \n  A few commented examples follow to provide reference when writing or\n  modifying command usage strings and synopsis sections in the manual\n  pages:\n \n  Possibility of multiple occurrences is indicated by three dots:\n-   _<file>_...\n+   <file>...\n    (One or more of <file>.)\n \n  Optional parts are enclosed in square brackets:\n-   [_<file>_...]\n+   [<file>...]\n    (Zero or more of <file>.)\n \n-   ++--exec-path++[++=++__<path>__]\n+ An optional parameter needs to be typeset with unconstrained pairs\n+   [<repository>]\n+\n+   --exec-path[=<path>]\n    (Option with an optional argument.  Note that the \"=\" is inside the\n    brackets.)\n \n-   [_<patch>_...]\n+   [<patch>...]\n    (Zero or more of <patch>.  Note that the dots are inside, not\n    outside the brackets.)\n \n  Multiple alternatives are indicated with vertical bars:\n-   [`-q` | `--quiet`]\n-   [`--utf8` | `--no-utf8`]\n+   [-q | --quiet]\n+   [--utf8 | --no-utf8]\n \n  Use spacing around \"|\" token(s), but not immediately after opening or\n  before closing a [] or () pair:\n-   Do: [`-q` | `--quiet`]\n-   Don't: [`-q`|`--quiet`]\n+   Do: [-q | --quiet]\n+   Don't: [-q|--quiet]\n \n  Don't use spacing around \"|\" tokens when they're used to separate the\n  alternate arguments of an option:\n-    Do: ++--track++[++=++(`direct`|`inherit`)]`\n-    Don't: ++--track++[++=++(`direct` | `inherit`)]\n+    Do: --track[=(direct|inherit)]\n+    Don't: --track[=(direct | inherit)]\n \n  Parentheses are used for grouping:\n-   [(_<rev>_ | _<range>_)...]\n+   [(<rev>|<range>)...]\n    (Any number of either <rev> or <range>.  Parens are needed to make\n    it clear that \"...\" pertains to both <rev> and <range>.)\n \n-   [(`-p` _<parent>_)...]\n+   [(-p <parent>)...]\n    (Any number of option -p, each with one <parent> argument.)\n \n-   `git remote set-head` _<name>_ (`-a` | `-d` | _<branch>_)\n+   git remote set-head <name> (-a|-d|<branch>)\n    (One and only one of \"-a\", \"-d\" or \"<branch>\" _must_ (no square\n    brackets) be provided.)\n \n  And a somewhat more contrived example:\n-   `--diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]`\n+   --diff-filter=[(A|C|D|M|R|T|U|X|B)...[*]]\n    Here \"=\" is outside the brackets, because \"--diff-filter=\" is a\n    valid usage.  \"*\" has its own pair of brackets, because it can\n    (optionally) be specified only when one or more of the letters is\n-- \ngitgitgadget\n\n"},{"id":"503335","messageId":"a76998d6443a5fd3de97e296223ec845413bbb29.1727161730.git.gitgitgadget@gmail.com","threadId":"61831","inReplyTo":"pull.1766.v5.git.1727161730.gitgitgadget@gmail.com","subject":"[PATCH v5 3/3] doc: apply synopsis simplification on git-clone and git-init","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-09-24T07:08:50Z","receivedAt":"2024-09-24T07:08:57Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n\nWith the new synopsis formatting backend, no special asciidoc markup\nis needed.\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n Documentation/git-clone.txt | 78 ++++++++++++++++++-------------------\n Documentation/git-init.txt  | 35 +++++++----------\n Documentation/urls.txt      | 26 ++++++-------\n 3 files changed, 67 insertions(+), 72 deletions(-)\n\ndiff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt\nindex 8e925db7e9c..9c13f847da3 100644\n--- a/Documentation/git-clone.txt\n+++ b/Documentation/git-clone.txt\n@@ -8,16 +8,16 @@ git-clone - Clone a repository into a new directory\n \n SYNOPSIS\n --------\n-[verse]\n-`git clone` [++--template=++__<template-directory>__]\n-\t  [`-l`] [`-s`] [`--no-hardlinks`] [`-q`] [`-n`] [`--bare`] [`--mirror`]\n-\t  [`-o` _<name>_] [`-b` _<name>_] [`-u` _<upload-pack>_] [`--reference` _<repository>_]\n-\t  [`--dissociate`] [`--separate-git-dir` _<git-dir>_]\n-\t  [`--depth` _<depth>_] [`--`[`no-`]{empty}`single-branch`] [`--no-tags`]\n-\t  [++--recurse-submodules++[++=++__<pathspec>__]] [++--++[++no-++]{empty}++shallow-submodules++]\n-\t  [`--`[`no-`]{empty}`remote-submodules`] [`--jobs` _<n>_] [`--sparse`] [`--`[`no-`]{empty}`reject-shallow`]\n-\t  [++--filter=++__<filter-spec>__] [`--also-filter-submodules`]] [`--`] _<repository>_\n-\t  [_<directory>_]\n+[synopsis]\n+git clone [--template=<template-directory>]\n+\t  [-l] [-s] [--no-hardlinks] [-q] [-n] [--bare] [--mirror]\n+\t  [-o <name>] [-b <name>] [-u <upload-pack>] [--reference <repository>]\n+\t  [--dissociate] [--separate-git-dir <git-dir>]\n+\t  [--depth <depth>] [--[no-]single-branch] [--no-tags]\n+\t  [--recurse-submodules[=<pathspec>]] [--[no-]shallow-submodules]\n+\t  [--[no-]remote-submodules] [--jobs <n>] [--sparse] [--[no-]reject-shallow]\n+\t  [--filter=<filter-spec>] [--also-filter-submodules]] [--] <repository>\n+\t  [<directory>]\n \n DESCRIPTION\n -----------\n@@ -52,7 +52,7 @@ OPTIONS\n \tto save space when possible.\n +\n If the repository is specified as a local path (e.g., `/path/to/repo`),\n-this is the default, and --local is essentially a no-op.  If the\n+this is the default, and `--local` is essentially a no-op.  If the\n repository is specified as a URL, then this flag is ignored (and we\n never use the local optimizations).  Specifying `--no-local` will\n override the default when `/path/to/repo` is given, using the regular\n@@ -64,8 +64,8 @@ prevent the unintentional copying of files by dereferencing the symbolic\n links.\n +\n *NOTE*: this operation can race with concurrent modification to the\n-source repository, similar to running `cp -r src dst` while modifying\n-`src`.\n+source repository, similar to running `cp -r <src> <dst>` while modifying\n+_<src>_.\n \n `--no-hardlinks`::\n \tForce the cloning process from a repository on a local\n@@ -101,7 +101,7 @@ If you want to break the dependency of a repository cloned with `--shared` on\n its source repository, you can simply run `git repack -a` to copy all\n objects from the source repository into a pack in the cloned repository.\n \n-`--reference`[`-if-able`] _<repository>_::\n+`--reference[-if-able] <repository>`::\n \tIf the reference _<repository>_ is on the local machine,\n \tautomatically setup `.git/objects/info/alternates` to\n \tobtain objects from the reference _<repository>_.  Using\n@@ -142,17 +142,17 @@ objects from the source repository into a pack in the cloned repository.\n \tis specified. This flag forces progress status even if the\n \tstandard error stream is not directed to a terminal.\n \n-++--server-option=++__<option>__::\n+`--server-option=<option>`::\n \tTransmit the given string to the server when communicating using\n \tprotocol version 2.  The given string must not contain a NUL or LF\n \tcharacter.  The server's handling of server options, including\n \tunknown ones, is server-specific.\n-\tWhen multiple ++--server-option=++__<option>__ are given, they are all\n+\tWhen multiple `--server-option=<option>` are given, they are all\n \tsent to the other side in the order listed on the command line.\n \n `-n`::\n `--no-checkout`::\n-\tNo checkout of HEAD is performed after the clone is complete.\n+\tNo checkout of `HEAD` is performed after the clone is complete.\n \n `--`[`no-`]`reject-shallow`::\n \tFail if the source repository is a shallow repository.\n@@ -162,7 +162,7 @@ objects from the source repository into a pack in the cloned repository.\n `--bare`::\n \tMake a 'bare' Git repository.  That is, instead of\n \tcreating _<directory>_ and placing the administrative\n-\tfiles in _<directory>_`/.git`, make the _<directory>_\n+\tfiles in `<directory>/.git`, make the _<directory>_\n \titself the `$GIT_DIR`. This obviously implies the `--no-checkout`\n \tbecause there is nowhere to check out the working tree.\n \tAlso the branch heads at the remote are copied directly\n@@ -177,13 +177,13 @@ objects from the source repository into a pack in the cloned repository.\n \tlinkgit:git-sparse-checkout[1] command can be used to grow the\n \tworking directory as needed.\n \n-++--filter=++__<filter-spec>__::\n+`--filter=<filter-spec>`::\n \tUse the partial clone feature and request that the server sends\n \ta subset of reachable objects according to a given object filter.\n \tWhen using `--filter`, the supplied _<filter-spec>_ is used for\n \tthe partial clone filter. For example, `--filter=blob:none` will\n \tfilter out all blobs (file contents) until needed by Git. Also,\n-\t++--filter=blob:limit=++__<size>__ will filter out all blobs of size\n+\t`--filter=blob:limit=<size>` will filter out all blobs of size\n \tat least _<size>_. For more details on filter specifications, see\n \tthe `--filter` option in linkgit:git-rev-list[1].\n \n@@ -208,11 +208,11 @@ objects from the source repository into a pack in the cloned repository.\n \n `-b` _<name>_::\n `--branch` _<name>_::\n-\tInstead of pointing the newly created HEAD to the branch pointed\n-\tto by the cloned repository's HEAD, point to _<name>_ branch\n+\tInstead of pointing the newly created `HEAD` to the branch pointed\n+\tto by the cloned repository's `HEAD`, point to _<name>_ branch\n \tinstead. In a non-bare repository, this is the branch that will\n \tbe checked out.\n-\t`--branch` can also take tags and detaches the HEAD at that commit\n+\t`--branch` can also take tags and detaches the `HEAD` at that commit\n \tin the resulting repository.\n \n `-u` _<upload-pack>_::\n@@ -221,12 +221,12 @@ objects from the source repository into a pack in the cloned repository.\n \tvia ssh, this specifies a non-default path for the command\n \trun on the other end.\n \n-++--template=++__<template-directory>__::\n+`--template=<template-directory>`::\n \tSpecify the directory from which templates will be used;\n \t(See the \"TEMPLATE DIRECTORY\" section of linkgit:git-init[1].)\n \n-`-c` __<key>__++=++__<value>__::\n-`--config` __<key>__++=++__<value>__::\n+`-c` `<key>=<value>`::\n+`--config` `<key>=<value>`::\n \tSet a configuration variable in the newly-created repository;\n \tthis takes effect immediately after the repository is\n \tinitialized, but before the remote history is fetched or any\n@@ -239,25 +239,25 @@ objects from the source repository into a pack in the cloned repository.\n Due to limitations of the current implementation, some configuration\n variables do not take effect until after the initial fetch and checkout.\n Configuration variables known to not take effect are:\n-++remote.++__<name>__++.mirror++ and ++remote.++__<name>__++.tagOpt++.  Use the\n+`remote.<name>.mirror` and `remote.<name>.tagOpt`.  Use the\n corresponding `--mirror` and `--no-tags` options instead.\n \n-`--depth` _<depth>_::\n+`--depth <depth>`::\n \tCreate a 'shallow' clone with a history truncated to the\n \tspecified number of commits. Implies `--single-branch` unless\n \t`--no-single-branch` is given to fetch the histories near the\n \ttips of all branches. If you want to clone submodules shallowly,\n \talso pass `--shallow-submodules`.\n \n-++--shallow-since=++__<date>__::\n+`--shallow-since=<date>`::\n \tCreate a shallow clone with a history after the specified time.\n \n-++--shallow-exclude=++__<revision>__::\n+`--shallow-exclude=<revision>`::\n \tCreate a shallow clone with a history, excluding commits\n \treachable from a specified remote branch or tag.  This option\n \tcan be specified multiple times.\n \n-`--`[`no-`]`single-branch`::\n+`--[no-]single-branch`::\n \tClone only the history leading to the tip of a single branch,\n \teither specified by the `--branch` option or the primary\n \tbranch remote's `HEAD` points at.\n@@ -279,13 +279,13 @@ maintain a branch with no references other than a single cloned\n branch. This is useful e.g. to maintain minimal clones of the default\n branch of some repository for search indexing.\n \n-`--recurse-submodules`[`=`{empty}__<pathspec>__]::\n+`--recurse-submodules[=<pathspec>]`::\n \tAfter the clone is created, initialize and clone submodules\n-\twithin based on the provided _<pathspec>_.  If no _=<pathspec>_ is\n+\twithin based on the provided _<pathspec>_.  If no `=<pathspec>` is\n \tprovided, all submodules are initialized and cloned.\n \tThis option can be given multiple times for pathspecs consisting\n \tof multiple entries.  The resulting clone has `submodule.active` set to\n-\tthe provided pathspec, or \".\" (meaning all submodules) if no\n+\tthe provided pathspec, or \"`.`\" (meaning all submodules) if no\n \tpathspec is provided.\n +\n Submodules are initialized and cloned using their default settings. This is\n@@ -295,23 +295,23 @@ the clone is finished. This option is ignored if the cloned repository does\n not have a worktree/checkout (i.e. if any of `--no-checkout`/`-n`, `--bare`,\n or `--mirror` is given)\n \n-`--`[`no-`]`shallow-submodules`::\n+`--[no-]shallow-submodules`::\n \tAll submodules which are cloned will be shallow with a depth of 1.\n \n-`--`[`no-`]`remote-submodules`::\n+`--[no-]remote-submodules`::\n \tAll submodules which are cloned will use the status of the submodule's\n \tremote-tracking branch to update the submodule, rather than the\n \tsuperproject's recorded SHA-1. Equivalent to passing `--remote` to\n \t`git submodule update`.\n \n-`--separate-git-dir=`{empty}__<git-dir>__::\n+`--separate-git-dir=<git-dir>`::\n \tInstead of placing the cloned repository where it is supposed\n \tto be, place the cloned repository at the specified directory,\n \tthen make a filesystem-agnostic Git symbolic link to there.\n \tThe result is Git repository can be separated from working\n \ttree.\n \n-`--ref-format=`{empty}__<ref-format>__::\n+`--ref-format=<ref-format>`::\n \n Specify the given ref storage format for the repository. The valid values are:\n +\n@@ -334,7 +334,7 @@ _<directory>_::\n \tfor `host.xz:foo/.git`).  Cloning into an existing directory\n \tis only allowed if the directory is empty.\n \n-`--bundle-uri=`{empty}__<uri>__::\n+`--bundle-uri=<uri>`::\n \tBefore fetching from the remote, fetch a bundle from the given\n \t_<uri>_ and unbundle the data into the local repository. The refs\n \tin the bundle will be stored under the hidden `refs/bundle/*`\ndiff --git a/Documentation/git-init.txt b/Documentation/git-init.txt\nindex daff93bd164..315f7f7530c 100644\n--- a/Documentation/git-init.txt\n+++ b/Documentation/git-init.txt\n@@ -8,12 +8,12 @@ git-init - Create an empty Git repository or reinitialize an existing one\n \n SYNOPSIS\n --------\n-[verse]\n-`git init` [`-q` | `--quiet`] [`--bare`] [++--template=++__<template-directory>__]\n-\t  [`--separate-git-dir` _<git-dir>_] [++--object-format=++__<format>__]\n-\t  [++--ref-format=++__<format>__]\n-\t  [`-b` _<branch-name>_ | ++--initial-branch=++__<branch-name>__]\n-\t  [++--shared++[++=++__<permissions>__]] [_<directory>_]\n+[synopsis]\n+git init [-q | --quiet] [--bare] [--template=<template-directory>]\n+\t [--separate-git-dir <git-dir>] [--object-format=<format>]\n+\t [--ref-format=<format>]\n+\t [-b <branch-name> | --initial-branch=<branch-name>]\n+\t [--shared[=<permissions>]] [<directory>]\n \n \n DESCRIPTION\n@@ -25,11 +25,11 @@ directory with subdirectories for `objects`, `refs/heads`,\n commits will be created (see the `--initial-branch` option below\n for its name).\n \n-If the `$GIT_DIR` environment variable is set then it specifies a path\n+If the `GIT_DIR` environment variable is set then it specifies a path\n to use instead of `./.git` for the base of the repository.\n \n If the object storage directory is specified via the\n-`$GIT_OBJECT_DIRECTORY` environment variable then the sha1 directories\n+`GIT_OBJECT_DIRECTORY` environment variable then the sha1 directories\n are created underneath; otherwise, the default `$GIT_DIR/objects`\n directory is used.\n \n@@ -51,26 +51,22 @@ Only print error and warning messages; all other output will be suppressed.\n Create a bare repository. If `GIT_DIR` environment is not set, it is set to the\n current working directory.\n \n-++--object-format=++__<format>__::\n-\n+`--object-format=<format>`::\n Specify the given object _<format>_ (hash algorithm) for the repository.  The valid\n values are `sha1` and (if enabled) `sha256`.  `sha1` is the default.\n +\n include::object-format-disclaimer.txt[]\n \n-++--ref-format=++__<format>__::\n-\n+`--ref-format=<format>`::\n Specify the given ref storage _<format>_ for the repository. The valid values are:\n +\n include::ref-storage-format.txt[]\n \n-++--template=++__<template-directory>__::\n-\n+`--template=<template-directory>`::\n Specify the directory from which templates will be used.  (See the \"TEMPLATE\n DIRECTORY\" section below.)\n \n-++--separate-git-dir=++__<git-dir>__::\n-\n+`--separate-git-dir=<git-dir>`::\n Instead of initializing the repository as a directory to either `$GIT_DIR` or\n `./.git/`, create a text file there containing the path to the actual\n repository.  This file acts as a filesystem-agnostic Git symbolic link to the\n@@ -78,15 +74,14 @@ repository.\n +\n If this is a reinitialization, the repository will be moved to the specified path.\n \n-`-b` _<branch-name>_::\n-++--initial-branch=++__<branch-name>__::\n-\n+`-b <branch-name>`::\n+`--initial-branch=<branch-name>`::\n Use _<branch-name>_ for the initial branch in the newly created\n repository.  If not specified, fall back to the default name (currently\n `master`, but this is subject to change in the future; the name can be\n customized via the `init.defaultBranch` configuration variable).\n \n-++--shared++[++=++(`false`|`true`|`umask`|`group`|`all`|`world`|`everybody`|_<perm>_)]::\n+`--shared[=(false|true|umask|group|all|world|everybody|<perm>)]`::\n \n Specify that the Git repository is to be shared amongst several users.  This\n allows users belonging to the same group to push into that\ndiff --git a/Documentation/urls.txt b/Documentation/urls.txt\nindex 7cec85aef17..9c871e716a1 100644\n--- a/Documentation/urls.txt\n+++ b/Documentation/urls.txt\n@@ -10,19 +10,19 @@ Git supports ssh, git, http, and https protocols (in addition, ftp\n and ftps can be used for fetching, but this is inefficient and\n deprecated; do not use them).\n \n-The native transport (i.e. git:// URL) does no authentication and\n+The native transport (i.e. `git://` URL) does no authentication and\n should be used with caution on unsecured networks.\n \n The following syntaxes may be used with them:\n \n-- ++ssh://++{startsb}__<user>__++@++{endsb}__<host>__{startsb}++:++__<port>__{endsb}++/++__<path-to-git-repo>__\n-- ++git://++__<host>__{startsb}:__<port>__{endsb}++/++__<path-to-git-repo>__\n-- ++http++{startsb}++s++{endsb}++://++__<host>__{startsb}++:++__<port>__{endsb}++/++__<path-to-git-repo>__\n-- ++ftp++{startsb}++s++{endsb}++://++__<host>__{startsb}++:++__<port>__{endsb}++/++__<path-to-git-repo>__\n+- `ssh://[<user>@]<host>[:<port>]/<path-to-git-repo>`\n+- `git://<host>[:<port>]/<path-to-git-repo>`\n+- `http[s]://<host>[:<port>]/<path-to-git-repo>`\n+- `ftp[s]://<host>[:<port>]/<path-to-git-repo>`\n \n An alternative scp-like syntax may also be used with the ssh protocol:\n \n-- {startsb}__<user>__++@++{endsb}__<host>__++:/++__<path-to-git-repo>__\n+- `[<user>@]<host>:/<path-to-git-repo>`\n \n This syntax is only recognized if there are no slashes before the\n first colon. This helps differentiate a local path that contains a\n@@ -30,17 +30,17 @@ colon. For example the local path `foo:bar` could be specified as an\n absolute path or `./foo:bar` to avoid being misinterpreted as an ssh\n url.\n \n-The ssh and git protocols additionally support ++~++__<username>__ expansion:\n+The ssh and git protocols additionally support `~<username>` expansion:\n \n-- ++ssh://++{startsb}__<user>__++@++{endsb}__<host>__{startsb}++:++__<port>__{endsb}++/~++__<user>__++/++__<path-to-git-repo>__\n-- ++git://++__<host>__{startsb}++:++__<port>__{endsb}++/~++__<user>__++/++__<path-to-git-repo>__\n-- {startsb}__<user>__++@++{endsb}__<host>__++:~++__<user>__++/++__<path-to-git-repo>__\n+- `ssh://[<user>@]<host>[:<port>]/~<user>/<path-to-git-repo>`\n+- `git://<host>[:<port>]/~<user>/<path-to-git-repo>`\n+- `[<user>@]<host>:~<user>/<path-to-git-repo>`\n \n For local repositories, also supported by Git natively, the following\n syntaxes may be used:\n \n - `/path/to/repo.git/`\n-- ++file:///path/to/repo.git/++\n+- `file:///path/to/repo.git/`\n \n ifndef::git-clone[]\n These two syntaxes are mostly equivalent, except when cloning, when\n@@ -57,11 +57,11 @@ endif::git-clone[]\n accept a suitable bundle file. See linkgit:git-bundle[1].\n \n When Git doesn't know how to handle a certain transport protocol, it\n-attempts to use the `remote-`{empty}__<transport>__ remote helper, if one\n+attempts to use the `remote-<transport>` remote helper, if one\n exists. To explicitly request a remote helper, the following syntax\n may be used:\n \n-- _<transport>_::__<address>__\n+- `<transport>::<address>`\n \n where _<address>_ may be a path, a server and path, or an arbitrary\n URL-like string recognized by the specific remote helper being\n-- \ngitgitgadget\n"},{"id":"503372","messageId":"xmqq5xqlug4l.fsf@gitster.g","threadId":"61831","inReplyTo":"pull.1766.v5.git.1727161730.gitgitgadget@gmail.com","subject":"Re: [PATCH v5 0/3] doc: introducing synopsis para","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-09-24T17:16:10Z","receivedAt":"2024-09-24T17:16:16Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Jean-Noël Avila via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n> Changes since V4:\n>\n>  * used BRE in sed filter\n>  * rework the processing of three dots\n\nThe topic has been deep in 'next' already, and I wasn't expecting a\nwholesale replacement.  But thanks for updating.\n\nAs the patches are more in the technology demonstration phase by\nconverting only a few pages and making sure other uses of `` outside\nthe synopsis section in unconverted pages are not broken, we can\ndeclare that the three-patch series will not be in 2.47 and will\nkeep it in 'next'.  So let me revert the merge of the previous one\nout of 'next' and queue this one afresh to 'seen' to see how well it\nworks.\n\nJosh (or whoever is taking over this week from him at Google), can\nyou see if the breakage you saw that stopped us merging the topic\nbefore it causes us trouble on 'master' reproduces with this version\n(either by running \"make doc\" on the topic branch by itself, or on\n'seen' that merges the topic) in your environment that had trouble\nwith the previous round?\n\nIt would also be highly appreciated if other macOS users try \"make\ndoc\" and see the resulting git-init and git-clone documentation\npages are reasonable, both for the previous round that has been\ncooking in 'next' and for this latest round.  Inputs from folks on\nmore mainstream platforms with modern asciidoc/asciidoctor toolchain\nwould also help.  The more people we have who look at how the new\nway the synopsis section is written and how the resulting documents\nget rendered, the more fairly we can assess the value of this topic.\n\nThanks.\n"},{"id":"503392","messageId":"20240924193004.GA20138@tb-raspi4","threadId":"61831","inReplyTo":"xmqq5xqlug4l.fsf@gitster.g","subject":"Re: [PATCH v5 0/3] doc: introducing synopsis para","fromName":"Torsten Bögershausen","fromEmail":"tboegi@web.de","sentAt":"2024-09-24T19:30:04Z","receivedAt":"2024-09-24T19:30:15Z","isPatch":true,"sender":{"key":"tboegi@web.de","avatar":"https://avatars.githubusercontent.com/u/7138363?v=4"},"body":"On Tue, Sep 24, 2024 at 10:16:10AM -0700, Junio C Hamano wrote:\n> \"Jean-Noël Avila via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n>\n> > Changes since V4:\n> >\n> >  * used BRE in sed filter\n> >  * rework the processing of three dots\n>\n> The topic has been deep in 'next' already, and I wasn't expecting a\n> wholesale replacement.  But thanks for updating.\n>\n> As the patches are more in the technology demonstration phase by\n> converting only a few pages and making sure other uses of `` outside\n> the synopsis section in unconverted pages are not broken, we can\n> declare that the three-patch series will not be in 2.47 and will\n> keep it in 'next'.  So let me revert the merge of the previous one\n> out of 'next' and queue this one afresh to 'seen' to see how well it\n> works.\n>\n> Josh (or whoever is taking over this week from him at Google), can\n> you see if the breakage you saw that stopped us merging the topic\n> before it causes us trouble on 'master' reproduces with this version\n> (either by running \"make doc\" on the topic branch by itself, or on\n> 'seen' that merges the topic) in your environment that had trouble\n> with the previous round?\n>\n> It would also be highly appreciated if other macOS users try \"make\n> doc\" and see the resulting git-init and git-clone documentation\n> pages are reasonable, both for the previous round that has been\n> cooking in 'next' and for this latest round.  Inputs from folks on\n> more mainstream platforms with modern asciidoc/asciidoctor toolchain\n> would also help.  The more people we have who look at how the new\n> way the synopsis section is written and how the resulting documents\n> get rendered, the more fairly we can assess the value of this topic.\n>\n> Thanks.\n>\n\nHere a report from a MacOs user,\nasciidoc --version\nasciidoc 10.2.0\n\ninstalled via macports.\n\nNo problems seen in the seen branch.\n\nI diffed git-init.html from seen of today against both master and next,\nsome (minor) improvements (like GIT_OBJECT_DIRECTORY vs $GIT_OBJECT_DIRECTORY)\nAll in all it looks all sensible.\n(and yes, `sed` understands -E)\n\n"},{"id":"503394","messageId":"xmqqbk0cssel.fsf@gitster.g","threadId":"61831","inReplyTo":"20240924193004.GA20138@tb-raspi4","subject":"Re: [PATCH v5 0/3] doc: introducing synopsis para","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-09-24T20:33:54Z","receivedAt":"2024-09-24T20:33:57Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Torsten Bögershausen <tboegi@web.de> writes:\n\n> On Tue, Sep 24, 2024 at 10:16:10AM -0700, Junio C Hamano wrote:\n>> \"Jean-Noël Avila via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n>>\n>> > Changes since V4:\n>> >\n>> >  * used BRE in sed filter\n>> >  * rework the processing of three dots\n>> ...\n>> Josh (or whoever is taking over this week from him at Google), can\n>> you see if the breakage you saw that stopped us merging the topic\n>> before it causes us trouble on 'master' reproduces with this version\n>> (either by running \"make doc\" on the topic branch by itself, or on\n>> 'seen' that merges the topic) in your environment that had trouble\n>> with the previous round?\n>>\n>> It would also be highly appreciated if other macOS users try \"make\n>> doc\" and see the resulting git-init and git-clone documentation\n>> pages are reasonable, both for the previous round that has been\n>> cooking in 'next' and for this latest round.  Inputs from folks on\n>> more mainstream platforms with modern asciidoc/asciidoctor toolchain\n>> would also help.  The more people we have who look at how the new\n>> way the synopsis section is written and how the resulting documents\n>> get rendered, the more fairly we can assess the value of this topic.\n>>\n> Here a report from a MacOs user,\n> asciidoc --version\n> asciidoc 10.2.0\n>\n> installed via macports.\n>\n> No problems seen in the seen branch.\n>\n> I diffed git-init.html from seen of today against both master and next,\n> some (minor) improvements (like GIT_OBJECT_DIRECTORY vs $GIT_OBJECT_DIRECTORY)\n> All in all it looks all sensible.\n> (and yes, `sed` understands -E)\n\nSince I haven't pushed out the 'seen' branch with latest iteration,\nyour sucess report is about the previous iteration that Josh said\n\"still breaks on MacOS\" [*].  The plot thickens...\n\nThanks.\n\n\n[Reference]\n\n * https://lore.kernel.org/git/4ww5v253vz2g4i3z2x3dmgkrot7mcn2qm6ckjcxbyky6yvrozy@mr5hnrsfj6sn/\n"},{"id":"503429","messageId":"gfwncnuvogwawlvp7mr64xrar3xv7fmevy3n3puro25wubi6mq@qdt6qmqi3o5n","threadId":"61831","inReplyTo":"CAPig+cQgw8xf5bQaUEW=qvKQpnxrkiTrMsqa+VW9d_GX0au1sA@mail.gmail.com","subject":"Re: [PATCH v4 0/3] doc: introducing synopsis para","fromName":"Josh Steadmon","fromEmail":"steadmon@google.com","sentAt":"2024-09-24T22:03:21Z","receivedAt":"2024-09-24T22:03:42Z","isPatch":true,"sender":{"key":"steadmon@google.com","avatar":"https://avatars.githubusercontent.com/u/2654920?v=4"},"body":"On 2024.09.23 14:14, Eric Sunshine wrote:\n> On Mon, Sep 23, 2024 at 12:38 PM Junio C Hamano <gitster@pobox.com> wrote:\n> > Chris Torek <chris.torek@gmail.com> writes:\n> > > On Fri, Sep 20, 2024 at 11:24 PM Junio C Hamano <gitster@pobox.com> wrote:\n> > >> The reason why I am curious is because https://ss64.com/mac/sed.html\n> > >> claims that -E works.\n> > >\n> > > It does for me, on my Mac, which is deliberately behind current: I am\n> > > still on Big Sur.\n> >\n> > Josh, the topic has been cooking in 'next' long enough to graduate\n> > to 'master' without anybody else complaining.  Could you\n> > double-check and if possible see what is different in your\n> > environment from others?\n> >\n> > I can hold the topic in 'next' longer but not forever without\n> > progress.  Help from macOS folks (if it is macOS specific issue)\n> > is greatly appreciated.\n> \n> I checked my High Sierra installation (macOS 10.13) which is even\n> older than Big Sur (macOS 11), and High Sierra's \"sed\" also\n> understands -E.\n\nHi folks, sorry for the false alarm and the delayed response. For some\nreason our build environment has a >decade old version of sed. I'm still\ntracking down why that is, but please do not hold back this topic any\nlonger due to our out-of-date-ness. Sorry again!\n"},{"id":"503452","messageId":"xmqqed58r5ho.fsf@gitster.g","threadId":"61831","inReplyTo":"gfwncnuvogwawlvp7mr64xrar3xv7fmevy3n3puro25wubi6mq@qdt6qmqi3o5n","subject":"Re: [PATCH v4 0/3] doc: introducing synopsis para","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-09-24T23:34:11Z","receivedAt":"2024-09-24T23:34:14Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Josh Steadmon <steadmon@google.com> writes:\n\n>> I checked my High Sierra installation (macOS 10.13) which is even\n>> older than Big Sur (macOS 11), and High Sierra's \"sed\" also\n>> understands -E.\n>\n> Hi folks, sorry for the false alarm and the delayed response. For some\n> reason our build environment has a >decade old version of sed. I'm still\n> tracking down why that is, but please do not hold back this topic any\n> longer due to our out-of-date-ness. Sorry again!\n\nThanks.\n\nI think Jean-Noël's latest rewrote ERE down to BRE but also tweaked\nsomething else around U+2026 …. Please try that version again when\nyou have a chance.\n\n\n"},{"id":"503976","messageId":"wuxy3oit7bculbpct3xnmpzxrfnsgaeoh2gvp5fsaaszchktoy@5ygjwbkdvozh","threadId":"61831","inReplyTo":"xmqqbk0cssel.fsf@gitster.g","subject":"Re: [PATCH v5 0/3] doc: introducing synopsis para","fromName":"Josh Steadmon","fromEmail":"steadmon@google.com","sentAt":"2024-10-02T21:41:58Z","receivedAt":"2024-10-02T21:42:08Z","isPatch":true,"sender":{"key":"steadmon@google.com","avatar":"https://avatars.githubusercontent.com/u/2654920?v=4"},"body":"On 2024.09.24 13:33, Junio C Hamano wrote:\n> Torsten Bögershausen <tboegi@web.de> writes:\n> \n> > On Tue, Sep 24, 2024 at 10:16:10AM -0700, Junio C Hamano wrote:\n> >> \"Jean-Noël Avila via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n> >>\n> >> > Changes since V4:\n> >> >\n> >> >  * used BRE in sed filter\n> >> >  * rework the processing of three dots\n> >> ...\n> >> Josh (or whoever is taking over this week from him at Google), can\n> >> you see if the breakage you saw that stopped us merging the topic\n> >> before it causes us trouble on 'master' reproduces with this version\n> >> (either by running \"make doc\" on the topic branch by itself, or on\n> >> 'seen' that merges the topic) in your environment that had trouble\n> >> with the previous round?\n> >>\n> >> It would also be highly appreciated if other macOS users try \"make\n> >> doc\" and see the resulting git-init and git-clone documentation\n> >> pages are reasonable, both for the previous round that has been\n> >> cooking in 'next' and for this latest round.  Inputs from folks on\n> >> more mainstream platforms with modern asciidoc/asciidoctor toolchain\n> >> would also help.  The more people we have who look at how the new\n> >> way the synopsis section is written and how the resulting documents\n> >> get rendered, the more fairly we can assess the value of this topic.\n> >>\n> > Here a report from a MacOs user,\n> > asciidoc --version\n> > asciidoc 10.2.0\n> >\n> > installed via macports.\n> >\n> > No problems seen in the seen branch.\n> >\n> > I diffed git-init.html from seen of today against both master and next,\n> > some (minor) improvements (like GIT_OBJECT_DIRECTORY vs $GIT_OBJECT_DIRECTORY)\n> > All in all it looks all sensible.\n> > (and yes, `sed` understands -E)\n> \n> Since I haven't pushed out the 'seen' branch with latest iteration,\n> your sucess report is about the previous iteration that Josh said\n> \"still breaks on MacOS\" [*].  The plot thickens...\n> \n> Thanks.\n> \n> \n> [Reference]\n> \n>  * https://lore.kernel.org/git/4ww5v253vz2g4i3z2x3dmgkrot7mcn2qm6ckjcxbyky6yvrozy@mr5hnrsfj6sn/\n\nI finally got the chance to test this version on $DAYJOB's build\ninfrastructure, and I verified that it works (I also got a much more\nrecent version of sed installed).\n"},{"id":"503996","messageId":"xmqqzfnmjfd2.fsf@gitster.g","threadId":"61831","inReplyTo":"wuxy3oit7bculbpct3xnmpzxrfnsgaeoh2gvp5fsaaszchktoy@5ygjwbkdvozh","subject":"Re: [PATCH v5 0/3] doc: introducing synopsis para","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-10-02T22:43:05Z","receivedAt":"2024-10-02T22:43:10Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Josh Steadmon <steadmon@google.com> writes:\n\n> I finally got the chance to test this version on $DAYJOB's build\n> infrastructure, and I verified that it works (I also got a much more\n> recent version of sed installed).\n\nThanks for a follow-up.\n\n"}]}