# [PATCH 1/1] doc/diff-options: fix link to generating patch section 6 messages from 2023-09-05 to 2023-09-06. Participants: Sergey Organov, Junio C Hamano. Thread: https://gitlist.dev/t/60200 ## Sergey Organov, 2023-09-05 17:52 Subject: [PATCH 1/1] doc/diff-options: fix link to generating patch section Message-ID: <87zg20qzhg.fsf@osv.gnss.ru> URL: https://gitlist.dev/e/87zg20qzhg.fsf%40osv.gnss.ru ``` First, there is no need for conditional referencing, as all the files that include "diff-options.txt" eventually include "diff-generate-patch.txt" as well. Next, when formatted as man-page, the section title is rendered "GENERATING PATCH TEXT WITH -P" whereas reference still reads "Generating patch text with -p", that is both inconsistent and makes searching harder than it needs to be. Fix the issues by just referring to the section, without custom reference text, and then unconditionally. Fixes: ebdc46c242 (docs: link generating patch sections) Signed-off-by: Sergey Organov --- Documentation/diff-options.txt | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index 9f33f887711d..c07488b123c6 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -22,13 +22,7 @@ ifndef::git-format-patch[] -p:: -u:: --patch:: - Generate patch (see section titled -ifdef::git-log[] -<>). -endif::git-log[] -ifndef::git-log[] -"Generating patch text with -p"). -endif::git-log[] + Generate patch (see <>). ifdef::git-diff[] This is the default. endif::git-diff[] -- 2.25.1 ``` ## Junio C Hamano, 2023-09-05 22:49 Subject: Re: [PATCH 1/1] doc/diff-options: fix link to generating patch section Message-ID: URL: https://gitlist.dev/e/xmqq34zsqlr3.fsf%40gitster.g In-Reply-To: <87zg20qzhg.fsf@osv.gnss.ru> ``` Sergey Organov writes: > First, there is no need for conditional referencing, as all the files > that include "diff-options.txt" eventually include > "diff-generate-patch.txt" as well. Except for git-format-patch.txt which includes the former but not the latter. But this is inside ifndef::git-format-patch[], so the above description being a bit imprecise does not cause any actual damage. Documentation for all commands that want to describe the `-p` option by including the "diff-options.txt" file also include the "diff-generate-patch.txt" file, so an internal link would work for all of them. or something like that, perhaps. > Next, when formatted as man-page, the section title is rendered > "GENERATING PATCH TEXT WITH -P" whereas reference still reads > "Generating patch text with -p", that is both inconsistent and makes > searching harder than it needs to be. > > Fix the issues by just referring to the section, without custom > reference text, and then unconditionally. That does make sense. > Fixes: ebdc46c242 (docs: link generating patch sections) > Signed-off-by: Sergey Organov > --- > Documentation/diff-options.txt | 8 +------- > 1 file changed, 1 insertion(+), 7 deletions(-) > > diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt > index 9f33f887711d..c07488b123c6 100644 > --- a/Documentation/diff-options.txt > +++ b/Documentation/diff-options.txt > @@ -22,13 +22,7 @@ ifndef::git-format-patch[] > -p:: > -u:: > --patch:: > - Generate patch (see section titled > -ifdef::git-log[] > -<>). > -endif::git-log[] > -ifndef::git-log[] > -"Generating patch text with -p"). > -endif::git-log[] > + Generate patch (see <>). > ifdef::git-diff[] > This is the default. > endif::git-diff[] ``` ## Sergey Organov, 2023-09-06 06:40 Subject: Re: [PATCH 1/1] doc/diff-options: fix link to generating patch section Message-ID: <87zg1zpzxv.fsf@osv.gnss.ru> URL: https://gitlist.dev/e/87zg1zpzxv.fsf%40osv.gnss.ru In-Reply-To: ``` Junio C Hamano writes: > Sergey Organov writes: > >> First, there is no need for conditional referencing, as all the files >> that include "diff-options.txt" eventually include >> "diff-generate-patch.txt" as well. > > Except for git-format-patch.txt which includes the former but not > the latter. But this is inside ifndef::git-format-patch[], so the > above description being a bit imprecise does not cause any actual > damage. Ah, nice catch! > > Documentation for all commands that want to describe the `-p` > option by including the "diff-options.txt" file also include the > "diff-generate-patch.txt" file, so an internal link would work > for all of them. Sounds fine. Would you re-phrase it yourself, or should I rather re-roll? Thanks, -- Sergey Organov ``` ## Sergey Organov, 2023-09-06 06:47 Subject: Re: [PATCH 1/1] doc/diff-options: fix link to generating patch section Message-ID: <87tts7pzl2.fsf@osv.gnss.ru> URL: https://gitlist.dev/e/87tts7pzl2.fsf%40osv.gnss.ru In-Reply-To: ``` Junio C Hamano writes: > Sergey Organov writes: > >> First, there is no need for conditional referencing, as all the files >> that include "diff-options.txt" eventually include >> "diff-generate-patch.txt" as well. > > Except for git-format-patch.txt which includes the former but not > the latter. But this is inside ifndef::git-format-patch[], so the > above description being a bit imprecise does not cause any actual > damage. > > Documentation for all commands that want to describe the `-p` > option by including the "diff-options.txt" file also include the > "diff-generate-patch.txt" file, so an internal link would work > for all of them. > > or something like that, perhaps. In fact I just realized that removing conditionals in fact *fixes* those documents by providing proper link in them as well, so I'll think of better description taking into account your observation as well, and then will re-roll. Thanks, -- Sergey Organov ``` ## Sergey Organov, 2023-09-06 07:15 Subject: [PATCH v2 1/1] doc/diff-options: fix link to generating patch section Message-ID: <87msxzpybo.fsf_-_@osv.gnss.ru> URL: https://gitlist.dev/e/87msxzpybo.fsf_-_%40osv.gnss.ru In-Reply-To: ``` When formatted as man-page, the section title is rendered "GENERATING PATCH TEXT WITH -P" whereas reference still reads "Generating patch text with -p", that is inconsistent and makes searching harder than it needs to be. Fix this by getting rid of custom reference text. Also, documentation for every command that describes `-p` option by including the "diff-options.txt" file does include the "diff-generate-patch.txt" file as well (as it should), so the internal link is in fact useful for any of them. Fix this by getting rid of conditionals around the reference. Fixes: ebdc46c242 (docs: link generating patch sections) Signed-off-by: Sergey Organov --- Documentation/diff-options.txt | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index 9f33f887711d..c07488b123c6 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -22,13 +22,7 @@ ifndef::git-format-patch[] -p:: -u:: --patch:: - Generate patch (see section titled -ifdef::git-log[] -<>). -endif::git-log[] -ifndef::git-log[] -"Generating patch text with -p"). -endif::git-log[] + Generate patch (see <>). ifdef::git-diff[] This is the default. endif::git-diff[] -- 2.25.1 ``` ## Junio C Hamano, 2023-09-06 15:58 Subject: Re: [PATCH 1/1] doc/diff-options: fix link to generating patch section Message-ID: URL: https://gitlist.dev/e/xmqqpm2vnvjk.fsf%40gitster.g In-Reply-To: <87tts7pzl2.fsf@osv.gnss.ru> ``` Sergey Organov writes: > In fact I just realized that removing conditionals in fact *fixes* those > documents by providing proper link in them as well, so I'll think of > better description taking into account your observation as well, and > then will re-roll. Thanks. ```