docs: link generating patch sections
PATCH 1/1 docs: link generating patch sections
From: John Cai <[email protected]>
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.
---
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.
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(-)
Documentation/diff-options.txt +7 -1
@@ -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[]
base-commit: 2e71cbbddd64695d43383c25c7a054ac4ff86882
Signature · 1 line
gitgitgadget
Documentation/diff-options.txt ifndef::git-format-patch[] · line 27
Quoted 12 lines · John Cai via GitGitGadget
Documentation/diff-options.txt +3
-1@@ -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?
Documentation/diff-options.txt ifndef::git-format-patch[] · line 30
Quoted 3 lines
Documentation/diff-options.txt +3
-0+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.
Quoted 6 lines
Documentation/diff-options.txt +1
-0+endif::git-log[] ifdef::git-diff[] This is the default. endif::git-diff[]base-commit:
2e71cbbddd64695d43383c25c7a054ac4ff86882
Hi Junio
Quoted 18 lines · Junio C Hamano
Documentation/diff-options.txt ifndef::git-format-patch[] · line 27
Quoted 12 lines · John Cai via GitGitGadget
Documentation/diff-options.txt +3
-1@@ -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.
Quoted 8 lines
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.
Quoted 11 lines
Documentation/diff-options.txt ifndef::git-format-patch[] · line 30
Quoted 4 lines
Documentation/diff-options.txt +3
-0+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
Quoted 7 lines
Quoted 7 lines
Documentation/diff-options.txt +1
-0+endif::git-log[] ifdef::git-diff[] This is the default. endif::git-diff[]base-commit:
2e71cbbddd64695d43383c25c7a054ac4ff86882
PATCH v2 1/1 docs: link generating patch sections
In reply to John Cai via GitGitGadgetFrom: John Cai <[email protected]>
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.
---
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.
Since v1:
* added explicit anchor for generating patch text section
* adjusted verbiage to include quotations
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1392%2Fjohn-cai%2Fjc%2Fdoc-generate-patch-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1392/john-cai/jc/doc-generate-patch-v2
Pull-Request: https://github.com/git/git/pull/1392
Range-diff vs v1:
1: 88e7e52fbc6 ! 1: 087f9b8d63a docs: link generating patch sections
@@ Commit message
+ ## Documentation/diff-generate-patch.txt ##
+@@
++[[generate_patch_text_with_p]]
+ Generating patch text with -p
+ -----------------------------
+
+
## Documentation/diff-options.txt ##
@@ Documentation/diff-options.txt: ifndef::git-format-patch[]
-p::
-u::
--patch::
- Generate patch (see section on generating patches).
-+ Generate patch (see section on
++ Generate patch (see section titled
+ifdef::git-log[]
-+<<_generating_patch_text_with_p, generating patches>>). ++<<generate_patch_text_with_p, "Generating patch text with -p">>).
+endif::git-log[]
+ifndef::git-log[]
-+Generate patch text with -p).
++"Generating patch text with -p").
+endif::git-log[]
ifdef::git-diff[]
This is the default.
Documentation/diff-generate-patch.txt | 1 + Documentation/diff-options.txt | 8 +++++++- 2 files changed, 8 insertions(+), 1 deletion(-)
Documentation/diff-generate-patch.txt +1 -0
@@ -1,3 +1,4 @@ +[[generate_patch_text_with_p]] Generating patch text with -p -----------------------------
Documentation/diff-options.txt +7 -1
@@ -22,7 +22,13 @@ ifndef::git-format-patch[] -p:: -u:: --patch:: - Generate patch (see section on generating patches). + Generate patch (see section titled +ifdef::git-log[] +<<generate_patch_text_with_p, "Generating patch text with -p">>). +endif::git-log[] +ifndef::git-log[] +"Generating patch text with -p"). +endif::git-log[] ifdef::git-diff[] This is the default. endif::git-diff[]
base-commit: a38d39a4c50d1275833aba54c4dbdfce9e2e9ca1
Signature · 1 line
gitgitgadget