Re: [PATCH] docs: link generating patch sections

[Junio C Hamano <gitster@pobox.com>]

"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?

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.

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