From: Junio C Hamano <gitster@pobox.com>
Date: Fri, 26 Sep 2025 15:42:39 GMT
Subject: Re: [RFC PATCH 2/4] doc: remembering-renames.adoc: fix asciidoc warnings
Message-ID: <xmqqqzvtcj9s.fsf@gitster.g>
In-Reply-To: <6dc8844c-8554-4c6c-a3bd-5ad2c04ab7a6@ramsayjones.plus.com>

Ramsay Jones <ramsay@ramsayjones.plus.com> writes:

> Signed-off-by: Ramsay Jones <ramsay@ramsayjones.plus.com>
> ---
>  .../technical/remembering-renames.adoc        | 63 +++++++++----------
>  1 file changed, 31 insertions(+), 32 deletions(-)

I know this is RFC not to be directly applied yet, but can you
describe what warnings are in scope of this fix to help commenting
on the changes?

> diff --git a/Documentation/technical/remembering-renames.adoc b/Documentation/technical/remembering-renames.adoc
> index 73f41761e2..89db8b406d 100644
> --- a/Documentation/technical/remembering-renames.adoc
> +++ b/Documentation/technical/remembering-renames.adoc
> @@ -10,32 +10,32 @@ history as an optimization, assuming all merges are automatic and clean
>  
>  Outline:
>  
> -  0. Assumptions
> +  0 Assumptions
>  
> -  1. How rebasing and cherry-picking work
> +  1 How rebasing and cherry-picking work
> ...  
> -  8. How directory rename detection interacts with the above and why this
> -     optimization is still safe even if merge.directoryRenames is set to
> -     "true".
> +  8 How directory rename detection interacts with the above and why this
> +    optimization is still safe even if merge.directoryRenames is set to
> +    "true".

I always thought that numbered list would have a period "." after
the number, but if doing this produces commonly accepted rendition
of a numbered list without warnings, I can buy it.  I personally may
feel it a bit awkward to read the source text until I get
accustomed, though.

> -=== 0. Assumptions ===
> +== 0. Assumptions ==

This is because these sections are not nested within a group that is
headed with a "== title ==" chapter?  Which makes sense.  I notice
that this one has a period "." after the number (which the warning
mechanism probably did not care---it is just part of the title).

>  Here's an example where that can happen:
> +
>    * E:oldfile had 20 lines
> +
>    * G:newfile added 10 new lines at the beginning of the file
> +
>    * A:oldfile kept the first 3 lines of the file, and deleted all the rest
> +
>  then
> +
>    => A':newfile would have 13 lines, 3 of which matches those in A:oldfile.
> -E:oldfile -> G:newfile would be detected as a rename, but A:oldfile and
> -A':newfile would not be.
> +  E:oldfile -> G:newfile would be detected as a rename, but A:oldfile and
> +  A':newfile would not be.

With blank lines in between I personally find the source text easier
to read, so no complaints ;-)