Re: [PATCH] docs: link generating patch sections
- From
Junio C Hamano <gitster@pobox.com>
- Date
- Dec 10, 2022, 00:29 UTC
- Message-ID
- <xmqqk030xfrd.fsf@gitster.g>
- In-Reply-To
- <pull.1392.git.git.1670614892380.gitgitgadget@gmail.com>
"John Cai via GitGitGadget" <gitgitgadget@gmail.com> writes:
Show 12 quoted lines
> 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?
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?
> +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.
Show 6 quoted lines
> +endif::git-log[] > ifdef::git-diff[] > This is the default. > endif::git-diff[] > > base-commit: 2e71cbbddd64695d43383c25c7a054ac4ff86882