docs: link generating patch sections

Commit Message

John Cai Dec. 9, 2022, 7:41 p.m. UTC

From: John Cai <[e-mail]>

Currently, in the git-log documentation, the reference to generating
patches does not match the section title. This can make the section
"Generating patch text with -p" hard to find, since typically readers of
the documentation will copy and paste to search the page.

Let's make this more convenient for readers by linking it directly to
the section.

Since git-log pulls in diff-generate-patch.txt, we can provide a direct
link to the section. Otherwise, change the verbiage to match exactly
what the section title is, to at least make searching for it an easier
task.

Signed-off-by: John Cai <[e-mail]>
---
    docs: link generating patch sections
    
    Currently, in the git-log documentation, the reference to generating
    patches does not match the section title. This can make the section
    "Generating patch text with -p" hard to find, since typically readers of
    the documentation will copy and paste to search the page.
    
    Let's make this more convenient for readers by linking it directly to
    the section.
    
    Signed-off-by: John Cai [e-mail]

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1392%2Fjohn-cai%2Fjc%2Fdoc-generate-patch-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1392/john-cai/jc/doc-generate-patch-v1
Pull-Request: https://github.com/git/git/pull/1392

 Documentation/diff-options.txt | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)


base-commit: 2e71cbbddd64695d43383c25c7a054ac4ff86882

Comments

Junio C Hamano Dec. 10, 2022, 12:29 a.m. UTC | #1

"John Cai via GitGitGadget" <[e-mail]> 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

John Cai Jan. 13, 2023, 4:14 p.m. UTC | #2

Hi Junio

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

> "John Cai via GitGitGadget" <[e-mail]> 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

Patch

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>>).
+endif::git-log[]
+ifndef::git-log[]
+Generate patch text with -p).
+endif::git-log[]
 ifdef::git-diff[]
 	This is the default.
 endif::git-diff[]