{"thread":{"id":"60200","subject":"[PATCH 1/1] doc/diff-options: fix link to generating patch section","startedAt":"2023-09-05T19:25:31Z","lastAt":"2023-09-06T15:58:14Z","messageCount":6,"participants":["Sergey Organov","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":1},"messages":[{"id":"481405","messageId":"87zg20qzhg.fsf@osv.gnss.ru","threadId":"60200","inReplyTo":null,"subject":"[PATCH 1/1] doc/diff-options: fix link to generating patch section","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2023-09-05T17:52:27Z","receivedAt":"2023-09-05T19:25:31Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"First, there is no need for conditional referencing, as all the files\nthat include \"diff-options.txt\" eventually include\n\"diff-generate-patch.txt\" as well.\n\nNext, when formatted as man-page, the section title is rendered\n\"GENERATING PATCH TEXT WITH -P\" whereas reference still reads\n\"Generating patch text with -p\", that is both inconsistent and makes\nsearching harder than it needs to be.\n\nFix the issues by just referring to the section, without custom\nreference text, and then unconditionally.\n\nFixes: ebdc46c242 (docs: link generating patch sections)\nSigned-off-by: Sergey Organov <sorganov@gmail.com>\n---\n Documentation/diff-options.txt | 8 +-------\n 1 file changed, 1 insertion(+), 7 deletions(-)\n\ndiff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt\nindex 9f33f887711d..c07488b123c6 100644\n--- a/Documentation/diff-options.txt\n+++ b/Documentation/diff-options.txt\n@@ -22,13 +22,7 @@ ifndef::git-format-patch[]\n -p::\n -u::\n --patch::\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+\tGenerate patch (see <<generate_patch_text_with_p>>).\n ifdef::git-diff[]\n \tThis is the default.\n endif::git-diff[]\n-- \n2.25.1\n\n"},{"id":"481419","messageId":"xmqq34zsqlr3.fsf@gitster.g","threadId":"60200","inReplyTo":"87zg20qzhg.fsf@osv.gnss.ru","subject":"Re: [PATCH 1/1] doc/diff-options: fix link to generating patch section","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-09-05T22:49:04Z","receivedAt":"2023-09-05T22:49:11Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Sergey Organov <sorganov@gmail.com> writes:\n\n> First, there is no need for conditional referencing, as all the files\n> that include \"diff-options.txt\" eventually include\n> \"diff-generate-patch.txt\" as well.\n\nExcept for git-format-patch.txt which includes the former but not\nthe latter.  But this is inside ifndef::git-format-patch[], so the\nabove description being a bit imprecise does not cause any actual\ndamage.\n\n    Documentation for all commands that want to describe the `-p`\n    option by including the \"diff-options.txt\" file also include the\n    \"diff-generate-patch.txt\" file, so an internal link would work\n    for all of them.\n\nor something like that, perhaps.\n\n> Next, when formatted as man-page, the section title is rendered\n> \"GENERATING PATCH TEXT WITH -P\" whereas reference still reads\n> \"Generating patch text with -p\", that is both inconsistent and makes\n> searching harder than it needs to be.\n>\n> Fix the issues by just referring to the section, without custom\n> reference text, and then unconditionally.\n\nThat does make sense.\n\n> Fixes: ebdc46c242 (docs: link generating patch sections)\n> Signed-off-by: Sergey Organov <sorganov@gmail.com>\n> ---\n>  Documentation/diff-options.txt | 8 +-------\n>  1 file changed, 1 insertion(+), 7 deletions(-)\n>\n> diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt\n> index 9f33f887711d..c07488b123c6 100644\n> --- a/Documentation/diff-options.txt\n> +++ b/Documentation/diff-options.txt\n> @@ -22,13 +22,7 @@ ifndef::git-format-patch[]\n>  -p::\n>  -u::\n>  --patch::\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> +\tGenerate patch (see <<generate_patch_text_with_p>>).\n>  ifdef::git-diff[]\n>  \tThis is the default.\n>  endif::git-diff[]\n"},{"id":"481429","messageId":"87zg1zpzxv.fsf@osv.gnss.ru","threadId":"60200","inReplyTo":"xmqq34zsqlr3.fsf@gitster.g","subject":"Re: [PATCH 1/1] doc/diff-options: fix link to generating patch section","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2023-09-06T06:40:12Z","receivedAt":"2023-09-06T06:40:19Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Junio C Hamano <gitster@pobox.com> writes:\n\n> Sergey Organov <sorganov@gmail.com> writes:\n>\n>> First, there is no need for conditional referencing, as all the files\n>> that include \"diff-options.txt\" eventually include\n>> \"diff-generate-patch.txt\" as well.\n>\n> Except for git-format-patch.txt which includes the former but not\n> the latter.  But this is inside ifndef::git-format-patch[], so the\n> above description being a bit imprecise does not cause any actual\n> damage.\n\nAh, nice catch!\n\n>\n>     Documentation for all commands that want to describe the `-p`\n>     option by including the \"diff-options.txt\" file also include the\n>     \"diff-generate-patch.txt\" file, so an internal link would work\n>     for all of them.\n\nSounds fine. Would you re-phrase it yourself, or should I rather\nre-roll?\n\n\nThanks,\n-- Sergey Organov\n"},{"id":"481430","messageId":"87tts7pzl2.fsf@osv.gnss.ru","threadId":"60200","inReplyTo":"xmqq34zsqlr3.fsf@gitster.g","subject":"Re: [PATCH 1/1] doc/diff-options: fix link to generating patch section","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2023-09-06T06:47:53Z","receivedAt":"2023-09-06T06:47:57Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"Junio C Hamano <gitster@pobox.com> writes:\n\n> Sergey Organov <sorganov@gmail.com> writes:\n>\n>> First, there is no need for conditional referencing, as all the files\n>> that include \"diff-options.txt\" eventually include\n>> \"diff-generate-patch.txt\" as well.\n>\n> Except for git-format-patch.txt which includes the former but not\n> the latter.  But this is inside ifndef::git-format-patch[], so the\n> above description being a bit imprecise does not cause any actual\n> damage.\n>\n>     Documentation for all commands that want to describe the `-p`\n>     option by including the \"diff-options.txt\" file also include the\n>     \"diff-generate-patch.txt\" file, so an internal link would work\n>     for all of them.\n>\n> or something like that, perhaps.\n\nIn fact I just realized that removing conditionals in fact *fixes* those\ndocuments by providing proper link in them as well, so I'll think of\nbetter description taking into account your observation as well, and\nthen will re-roll.\n\nThanks,\n-- Sergey Organov\n"},{"id":"481431","messageId":"87msxzpybo.fsf_-_@osv.gnss.ru","threadId":"60200","inReplyTo":"xmqq34zsqlr3.fsf@gitster.g","subject":"[PATCH v2 1/1] doc/diff-options: fix link to generating patch section","fromName":"Sergey Organov","fromEmail":"sorganov@gmail.com","sentAt":"2023-09-06T07:15:07Z","receivedAt":"2023-09-06T07:15:13Z","isPatch":true,"sender":{"key":"sorganov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8501568?v=4"},"body":"When formatted as man-page, the section title is rendered\n\"GENERATING PATCH TEXT WITH -P\" whereas reference still reads\n\"Generating patch text with -p\", that is inconsistent and makes\nsearching harder than it needs to be.\n\nFix this by getting rid of custom reference text.\n\nAlso, documentation for every command that describes `-p` option by\nincluding the \"diff-options.txt\" file does include the\n\"diff-generate-patch.txt\" file as well (as it should), so the internal\nlink is in fact useful for any of them.\n\nFix this by getting rid of conditionals around the reference.\n\nFixes: ebdc46c242 (docs: link generating patch sections)\nSigned-off-by: Sergey Organov <sorganov@gmail.com>\n---\n Documentation/diff-options.txt | 8 +-------\n 1 file changed, 1 insertion(+), 7 deletions(-)\n\ndiff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt\nindex 9f33f887711d..c07488b123c6 100644\n--- a/Documentation/diff-options.txt\n+++ b/Documentation/diff-options.txt\n@@ -22,13 +22,7 @@ ifndef::git-format-patch[]\n -p::\n -u::\n --patch::\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+\tGenerate patch (see <<generate_patch_text_with_p>>).\n ifdef::git-diff[]\n \tThis is the default.\n endif::git-diff[]\n-- \n2.25.1\n\n"},{"id":"481440","messageId":"xmqqpm2vnvjk.fsf@gitster.g","threadId":"60200","inReplyTo":"87tts7pzl2.fsf@osv.gnss.ru","subject":"Re: [PATCH 1/1] doc/diff-options: fix link to generating patch section","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-09-06T15:58:07Z","receivedAt":"2023-09-06T15:58:14Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Sergey Organov <sorganov@gmail.com> writes:\n\n> In fact I just realized that removing conditionals in fact *fixes* those\n> documents by providing proper link in them as well, so I'll think of\n> better description taking into account your observation as well, and\n> then will re-roll.\n\nThanks.\n"}]}