Re: [PATCH] docs: link generating patch sections

[John Cai <johncai86@gmail.com>]

Hi Junio

On 9 Dec 2022, at 19:29, Junio C Hamano wrote:

> "John Cai via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
>> diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt
>> index 3674ac48e92..5acffdd129e 100644
>> --- a/Documentation/diff-options.txt
>> +++ b/Documentation/diff-options.txt
>> @@ -22,7 +22,13 @@ ifndef::git-format-patch[]
>>  -p::
>>  -u::
>>  --patch::
>> -	Generate patch (see section on generating patches).
>> +	Generate patch (see section on
>> +ifdef::git-log[]
>> +<<_generating_patch_text_with_p, generating patches>>).
>
> Is this "prepend underscore, downcase, and replace each run of
> non-alnum with an underscore" ASCIIDoc magic?  AsciiDoctor magic?
> All such backends prepare the anchor in the same format?

Yes, I believe this is asciidoc magic.

>
> I am mostly worried about relying on automatic magic that can
> silently be broken when say the title in diff-generate-patch.txt
> file is improved.  Whoever is updating the file would not know
> it is being referenced from elsewhere (and it is hard to check).
>
> Or perhaps you forgot a single liner patch to diff-generate-patch.txt
> that adds [[_generating_patch_text_with_p]] anchor yourself?

Good point, adding an explicit anchor makes sense.

>
>> +endif::git-log[]
>> +ifndef::git-log[]
>> +Generate patch text with -p).
>
> The capitalization makes it look somewhat odd in the resulting
> text.  Quoting, e.g.
>
> 	see the section titled "Generate patch text ..."
>
> may make it acceptable, though.

yeah I agree here--I can adjust this in the next version

thanks
John

>
>> +endif::git-log[]
>>  ifdef::git-diff[]
>>  	This is the default.
>>  endif::git-diff[]
>>
>> base-commit: 2e71cbbddd64695d43383c25c7a054ac4ff86882