Re: [RFC PATCH 2/4] doc: remembering-renames.adoc: fix asciidoc warnings

From: Junio C Hamano <gitster@pobox.com>
Date: Sep 26, 2025, 15:42 UTC
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?

Show 20 quoted lines

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

Show 15 quoted lines

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