Subject: Re: [PATCH] doc: fix asciidoctor synopsis processing of triple-dots

From: Junio C Hamano <[email-masked]>
Date: Tue, 01 Apr 2025 14:48:00 -0700

Jean-Noël Avila <[email-masked]> writes:

> The processing of triple dot notation is tricky because it can be
> mis-interpreted as an ellipsis.
>
> Another issue is that the formatting of synopsis paragraph in
> Asciidoctor spits out another asciidoc formatted text where verbatim
> text formatted with backquotes must have surrounding separators in
> order to be properly detected, even if they are sticking to another
> text.
>
> The special processing of the ellipsis is now complete and takes into
> account the case of `git-mv <source>... <dest>`
>
> Signed-off-by: Jean-Noël Avila <[email-masked]>
> ---
>  Documentation/asciidoctor-extensions.rb.in | 8 +++++---
>  Documentation/diff-generate-patch.adoc     | 2 +-
>  2 files changed, 6 insertions(+), 4 deletions(-)

The .gsub() changes seem to interact with your "doc: fix synopsis
analysis logic" in the series that updates reset/mv/rm documentation
mark-up.

> diff --git a/Documentation/asciidoctor-extensions.rb.in b/Documentation/asciidoctor-extensions.rb.in
> index 2494f17a51..0ded90c28b 100644
> --- a/Documentation/asciidoctor-extensions.rb.in
> +++ b/Documentation/asciidoctor-extensions.rb.in
> @@ -49,7 +49,7 @@ module Git
>  
>        def process parent, reader, attrs
>          outlines = reader.lines.map do |l|
> -          l.gsub(/(\.\.\.?)([^\]$.])/, '`\1`\2')
> +          l.gsub(/(\.\.\.?)([^\]$\. ])/, '{empty}`\1`{empty}\2')
>             .gsub(%r{([\[\] |()>]|^)([-a-zA-Z0-9:+=~@,/_^\$]+)}, '\1{empty}`\2`{empty}')
>             .gsub(/(<[-a-zA-Z0-9.]+>)/, '__\\1__')
>             .gsub(']', ']{empty}')
> @@ -72,6 +72,7 @@ module Git
>            %(<inlineequation><alt><![CDATA[#{equation = node.text}]]></alt><mathphrase><![CDATA[#{equation}]]></mathphrase></inlineequation>)
>          elsif type == :monospaced
>            node.text.gsub(/(\.\.\.?)([^\]$.])/, '<literal>\1</literal>\2')
> +              .gsub(/^\.\.\.?$/, '<literal>\0</literal>\2')
>                .gsub(%r{([\[\s|()>.]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@,/_^\$]+\.{0,2})+)}, '\1<literal>\2</literal>')
>                .gsub(/(&lt;[-a-zA-Z0-9.]+&gt;)/, '<emphasis>\1</emphasis>')
>          else
> @@ -100,8 +101,9 @@ module Git
>        def convert_inline_quoted node
>          if node.type == :monospaced
>            node.text.gsub(/(\.\.\.?)([^\]$.])/, '<code>\1</code>\2')
> -              .gsub(%r{([\[\s|()>.]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@,/_^\$]+\.{0,2})+)}, '\1<code>\2</code>')
> -              .gsub(/(&lt;[-a-zA-Z0-9.]+&gt;)/, '<em>\1</em>')
> +            .gsub(/^\.\.\.?$/, '<code>\0</code>')
> +            .gsub(%r{([\[\s|()>.]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@,/_^\$]+\.{0,2})+)}, '\1<code>\2</code>')
> +            .gsub(/(&lt;[-a-zA-Z0-9.]+&gt;)/, '<em>\1</em>')
>  
>          else
>            open, close, tag = QUOTE_TAGS[node.type]
> diff --git a/Documentation/diff-generate-patch.adoc b/Documentation/diff-generate-patch.adoc
> index e5c813c96f..7b6cdd1980 100644
> --- a/Documentation/diff-generate-patch.adoc
> +++ b/Documentation/diff-generate-patch.adoc
> @@ -138,7 +138,7 @@ or like this (when the `--cc` option is used):
>  +
>  [synopsis]
>  index <hash>,<hash>..<hash>
> -mode <mode>,<mode>`..`<mode>
> +mode <mode>,<mode>..<mode>
>  new file mode <mode>
>  deleted file mode <mode>,<mode>
>  +