{"thread":{"id":"58924","subject":"[PATCH] docs: link generating patch sections","startedAt":"2022-12-09T19:42:33Z","lastAt":"2023-01-13T16:22:09Z","messageCount":4,"participants":["John Cai via GitGitGadget","Junio C Hamano","John Cai"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"468838","messageId":"pull.1392.git.git.1670614892380.gitgitgadget@gmail.com","threadId":"58924","inReplyTo":null,"subject":"[PATCH] docs: link generating patch sections","fromName":"John Cai via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2022-12-09T19:41:32Z","receivedAt":"2022-12-09T19:42:33Z","isPatch":true,"sender":{"key":"johncai86@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2354211?v=4"},"body":"From: John Cai <johncai86@gmail.com>\n\nCurrently, in the git-log documentation, the reference to generating\npatches does not match the section title. This can make the section\n\"Generating patch text with -p\" hard to find, since typically readers of\nthe documentation will copy and paste to search the page.\n\nLet's make this more convenient for readers by linking it directly to\nthe section.\n\nSince git-log pulls in diff-generate-patch.txt, we can provide a direct\nlink to the section. Otherwise, change the verbiage to match exactly\nwhat the section title is, to at least make searching for it an easier\ntask.\n\nSigned-off-by: John Cai <johncai86@gmail.com>\n---\n    docs: link generating patch sections\n    \n    Currently, in the git-log documentation, the reference to generating\n    patches does not match the section title. This can make the section\n    \"Generating patch text with -p\" hard to find, since typically readers of\n    the documentation will copy and paste to search the page.\n    \n    Let's make this more convenient for readers by linking it directly to\n    the section.\n    \n    Signed-off-by: John Cai johncai86@gmail.com\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1392%2Fjohn-cai%2Fjc%2Fdoc-generate-patch-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1392/john-cai/jc/doc-generate-patch-v1\nPull-Request: https://github.com/git/git/pull/1392\n\n Documentation/diff-options.txt | 8 +++++++-\n 1 file changed, 7 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt\nindex 3674ac48e92..5acffdd129e 100644\n--- a/Documentation/diff-options.txt\n+++ b/Documentation/diff-options.txt\n@@ -22,7 +22,13 @@ ifndef::git-format-patch[]\n -p::\n -u::\n --patch::\n-\tGenerate patch (see section on generating patches).\n+\tGenerate patch (see section on\n+ifdef::git-log[]\n+<<_generating_patch_text_with_p, generating patches>>).\n+endif::git-log[]\n+ifndef::git-log[]\n+Generate patch text with -p).\n+endif::git-log[]\n ifdef::git-diff[]\n \tThis is the default.\n endif::git-diff[]\n\nbase-commit: 2e71cbbddd64695d43383c25c7a054ac4ff86882\n-- \ngitgitgadget\n"},{"id":"468855","messageId":"xmqqk030xfrd.fsf@gitster.g","threadId":"58924","inReplyTo":"pull.1392.git.git.1670614892380.gitgitgadget@gmail.com","subject":"Re: [PATCH] docs: link generating patch sections","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-12-10T00:29:42Z","receivedAt":"2022-12-10T00:29:48Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"John Cai via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n\n> diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt\n> index 3674ac48e92..5acffdd129e 100644\n> --- a/Documentation/diff-options.txt\n> +++ b/Documentation/diff-options.txt\n> @@ -22,7 +22,13 @@ ifndef::git-format-patch[]\n>  -p::\n>  -u::\n>  --patch::\n> -\tGenerate patch (see section on generating patches).\n> +\tGenerate patch (see section on\n> +ifdef::git-log[]\n> +<<_generating_patch_text_with_p, generating patches>>).\n\nIs this \"prepend underscore, downcase, and replace each run of\nnon-alnum with an underscore\" ASCIIDoc magic?  AsciiDoctor magic?\nAll such backends prepare the anchor in the same format?\n\nI am mostly worried about relying on automatic magic that can\nsilently be broken when say the title in diff-generate-patch.txt\nfile is improved.  Whoever is updating the file would not know\nit is being referenced from elsewhere (and it is hard to check).\n\nOr perhaps you forgot a single liner patch to diff-generate-patch.txt\nthat adds [[_generating_patch_text_with_p]] anchor yourself?\n\n> +endif::git-log[]\n> +ifndef::git-log[]\n> +Generate patch text with -p).\n\nThe capitalization makes it look somewhat odd in the resulting\ntext.  Quoting, e.g.\n\n\tsee the section titled \"Generate patch text ...\"\n\nmay make it acceptable, though.\n\n> +endif::git-log[]\n>  ifdef::git-diff[]\n>  \tThis is the default.\n>  endif::git-diff[]\n>\n> base-commit: 2e71cbbddd64695d43383c25c7a054ac4ff86882\n"},{"id":"470271","messageId":"0DE08530-2F10-4656-9B50-E7B3CBD60D68@gmail.com","threadId":"58924","inReplyTo":"xmqqk030xfrd.fsf@gitster.g","subject":"Re: [PATCH] docs: link generating patch sections","fromName":"John Cai","fromEmail":"johncai86@gmail.com","sentAt":"2023-01-13T16:14:37Z","receivedAt":"2023-01-13T16:21:26Z","isPatch":true,"sender":{"key":"johncai86@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2354211?v=4"},"body":"Hi Junio\n\nOn 9 Dec 2022, at 19:29, Junio C Hamano wrote:\n\n> \"John Cai via GitGitGadget\" <gitgitgadget@gmail.com> writes:\n>\n>> diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt\n>> index 3674ac48e92..5acffdd129e 100644\n>> --- a/Documentation/diff-options.txt\n>> +++ b/Documentation/diff-options.txt\n>> @@ -22,7 +22,13 @@ ifndef::git-format-patch[]\n>>  -p::\n>>  -u::\n>>  --patch::\n>> -\tGenerate patch (see section on generating patches).\n>> +\tGenerate patch (see section on\n>> +ifdef::git-log[]\n>> +<<_generating_patch_text_with_p, generating patches>>).\n>\n> Is this \"prepend underscore, downcase, and replace each run of\n> non-alnum with an underscore\" ASCIIDoc magic?  AsciiDoctor magic?\n> All such backends prepare the anchor in the same format?\n\nYes, I believe this is asciidoc magic.\n\n>\n> I am mostly worried about relying on automatic magic that can\n> silently be broken when say the title in diff-generate-patch.txt\n> file is improved.  Whoever is updating the file would not know\n> it is being referenced from elsewhere (and it is hard to check).\n>\n> Or perhaps you forgot a single liner patch to diff-generate-patch.txt\n> that adds [[_generating_patch_text_with_p]] anchor yourself?\n\nGood point, adding an explicit anchor makes sense.\n\n>\n>> +endif::git-log[]\n>> +ifndef::git-log[]\n>> +Generate patch text with -p).\n>\n> The capitalization makes it look somewhat odd in the resulting\n> text.  Quoting, e.g.\n>\n> \tsee the section titled \"Generate patch text ...\"\n>\n> may make it acceptable, though.\n\nyeah I agree here--I can adjust this in the next version\n\nthanks\nJohn\n\n>\n>> +endif::git-log[]\n>>  ifdef::git-diff[]\n>>  \tThis is the default.\n>>  endif::git-diff[]\n>>\n>> base-commit: 2e71cbbddd64695d43383c25c7a054ac4ff86882\n"},{"id":"470272","messageId":"pull.1392.v2.git.git.1673626524221.gitgitgadget@gmail.com","threadId":"58924","inReplyTo":"pull.1392.git.git.1670614892380.gitgitgadget@gmail.com","subject":"[PATCH v2] docs: link generating patch sections","fromName":"John Cai via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2023-01-13T16:15:24Z","receivedAt":"2023-01-13T16:22:09Z","isPatch":true,"sender":{"key":"johncai86@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2354211?v=4"},"body":"From: John Cai <johncai86@gmail.com>\n\nCurrently, in the git-log documentation, the reference to generating\npatches does not match the section title. This can make the section\n\"Generating patch text with -p\" hard to find, since typically readers of\nthe documentation will copy and paste to search the page.\n\nLet's make this more convenient for readers by linking it directly to\nthe section.\n\nSince git-log pulls in diff-generate-patch.txt, we can provide a direct\nlink to the section. Otherwise, change the verbiage to match exactly\nwhat the section title is, to at least make searching for it an easier\ntask.\n\nSigned-off-by: John Cai <johncai86@gmail.com>\n---\n    docs: link generating patch sections\n    \n    Currently, in the git-log documentation, the reference to generating\n    patches does not match the section title. This can make the section\n    \"Generating patch text with -p\" hard to find, since typically readers of\n    the documentation will copy and paste to search the page.\n    \n    Let's make this more convenient for readers by linking it directly to\n    the section.\n    \n    Since v1:\n    \n     * added explicit anchor for generating patch text section\n     * adjusted verbiage to include quotations\n    \n    Signed-off-by: John Cai johncai86@gmail.com\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1392%2Fjohn-cai%2Fjc%2Fdoc-generate-patch-v2\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1392/john-cai/jc/doc-generate-patch-v2\nPull-Request: https://github.com/git/git/pull/1392\n\nRange-diff vs v1:\n\n 1:  88e7e52fbc6 ! 1:  087f9b8d63a docs: link generating patch sections\n     @@ Commit message\n      \n          Signed-off-by: John Cai <johncai86@gmail.com>\n      \n     + ## Documentation/diff-generate-patch.txt ##\n     +@@\n     ++[[generate_patch_text_with_p]]\n     + Generating patch text with -p\n     + -----------------------------\n     + \n     +\n       ## Documentation/diff-options.txt ##\n      @@ Documentation/diff-options.txt: ifndef::git-format-patch[]\n       -p::\n       -u::\n       --patch::\n      -\tGenerate patch (see section on generating patches).\n     -+\tGenerate patch (see section on\n     ++\tGenerate patch (see section titled\n      +ifdef::git-log[]\n     -+<<_generating_patch_text_with_p, generating patches>>).\n     ++<<generate_patch_text_with_p, \"Generating patch text with -p\">>).\n      +endif::git-log[]\n      +ifndef::git-log[]\n     -+Generate patch text with -p).\n     ++\"Generating patch text with -p\").\n      +endif::git-log[]\n       ifdef::git-diff[]\n       \tThis is the default.\n\n\n Documentation/diff-generate-patch.txt | 1 +\n Documentation/diff-options.txt        | 8 +++++++-\n 2 files changed, 8 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-generate-patch.txt\nindex c78063d4f74..546adf79e5a 100644\n--- a/Documentation/diff-generate-patch.txt\n+++ b/Documentation/diff-generate-patch.txt\n@@ -1,3 +1,4 @@\n+[[generate_patch_text_with_p]]\n Generating patch text with -p\n -----------------------------\n \ndiff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt\nindex 3674ac48e92..7d73e976d99 100644\n--- a/Documentation/diff-options.txt\n+++ b/Documentation/diff-options.txt\n@@ -22,7 +22,13 @@ ifndef::git-format-patch[]\n -p::\n -u::\n --patch::\n-\tGenerate patch (see section on generating patches).\n+\tGenerate patch (see section titled\n+ifdef::git-log[]\n+<<generate_patch_text_with_p, \"Generating patch text with -p\">>).\n+endif::git-log[]\n+ifndef::git-log[]\n+\"Generating patch text with -p\").\n+endif::git-log[]\n ifdef::git-diff[]\n \tThis is the default.\n endif::git-diff[]\n\nbase-commit: a38d39a4c50d1275833aba54c4dbdfce9e2e9ca1\n-- \ngitgitgadget\n"}]}