* [PATCH 1/1] doc/diff-options: fix link to generating patch section
@ 2023-09-05 17:52 Sergey Organov
2023-09-05 22:49 ` Junio C Hamano
0 siblings, 1 reply; 6+ messages in thread
From: Sergey Organov @ 2023-09-05 17:52 UTC (permalink / raw)
To: git; +Cc: Junio C Hamano, John Cai
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 <sorganov@gmail.com>
---
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[]
-<<generate_patch_text_with_p, "Generating patch text with -p">>).
-endif::git-log[]
-ifndef::git-log[]
-"Generating patch text with -p").
-endif::git-log[]
+ Generate patch (see <<generate_patch_text_with_p>>).
ifdef::git-diff[]
This is the default.
endif::git-diff[]
--
2.25.1
^ permalink raw reply related [flat|nested] 6+ messages in thread
* Re: [PATCH 1/1] doc/diff-options: fix link to generating patch section
2023-09-05 17:52 [PATCH 1/1] doc/diff-options: fix link to generating patch section Sergey Organov
@ 2023-09-05 22:49 ` Junio C Hamano
2023-09-06 6:40 ` Sergey Organov
` (2 more replies)
0 siblings, 3 replies; 6+ messages in thread
From: Junio C Hamano @ 2023-09-05 22:49 UTC (permalink / raw)
To: Sergey Organov; +Cc: git, John Cai
Sergey Organov <sorganov@gmail.com> 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 <sorganov@gmail.com>
> ---
> 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[]
> -<<generate_patch_text_with_p, "Generating patch text with -p">>).
> -endif::git-log[]
> -ifndef::git-log[]
> -"Generating patch text with -p").
> -endif::git-log[]
> + Generate patch (see <<generate_patch_text_with_p>>).
> ifdef::git-diff[]
> This is the default.
> endif::git-diff[]
^ permalink raw reply [flat|nested] 6+ messages in thread* Re: [PATCH 1/1] doc/diff-options: fix link to generating patch section
2023-09-05 22:49 ` Junio C Hamano
@ 2023-09-06 6:40 ` Sergey Organov
2023-09-06 6:47 ` Sergey Organov
2023-09-06 7:15 ` [PATCH v2 " Sergey Organov
2 siblings, 0 replies; 6+ messages in thread
From: Sergey Organov @ 2023-09-06 6:40 UTC (permalink / raw)
To: Junio C Hamano; +Cc: git, John Cai
Junio C Hamano <gitster@pobox.com> writes:
> Sergey Organov <sorganov@gmail.com> 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
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH 1/1] doc/diff-options: fix link to generating patch section
2023-09-05 22:49 ` Junio C Hamano
2023-09-06 6:40 ` Sergey Organov
@ 2023-09-06 6:47 ` Sergey Organov
2023-09-06 15:58 ` Junio C Hamano
2023-09-06 7:15 ` [PATCH v2 " Sergey Organov
2 siblings, 1 reply; 6+ messages in thread
From: Sergey Organov @ 2023-09-06 6:47 UTC (permalink / raw)
To: Junio C Hamano; +Cc: git, John Cai
Junio C Hamano <gitster@pobox.com> writes:
> Sergey Organov <sorganov@gmail.com> 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
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH 1/1] doc/diff-options: fix link to generating patch section
2023-09-06 6:47 ` Sergey Organov
@ 2023-09-06 15:58 ` Junio C Hamano
0 siblings, 0 replies; 6+ messages in thread
From: Junio C Hamano @ 2023-09-06 15:58 UTC (permalink / raw)
To: Sergey Organov; +Cc: git, John Cai
Sergey Organov <sorganov@gmail.com> 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.
^ permalink raw reply [flat|nested] 6+ messages in thread
* [PATCH v2 1/1] doc/diff-options: fix link to generating patch section
2023-09-05 22:49 ` Junio C Hamano
2023-09-06 6:40 ` Sergey Organov
2023-09-06 6:47 ` Sergey Organov
@ 2023-09-06 7:15 ` Sergey Organov
2 siblings, 0 replies; 6+ messages in thread
From: Sergey Organov @ 2023-09-06 7:15 UTC (permalink / raw)
To: Junio C Hamano; +Cc: git, John Cai
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 <sorganov@gmail.com>
---
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[]
-<<generate_patch_text_with_p, "Generating patch text with -p">>).
-endif::git-log[]
-ifndef::git-log[]
-"Generating patch text with -p").
-endif::git-log[]
+ Generate patch (see <<generate_patch_text_with_p>>).
ifdef::git-diff[]
This is the default.
endif::git-diff[]
--
2.25.1
^ permalink raw reply related [flat|nested] 6+ messages in thread
end of thread, other threads:[~2023-09-06 15:58 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2023-09-05 17:52 [PATCH 1/1] doc/diff-options: fix link to generating patch section Sergey Organov
2023-09-05 22:49 ` Junio C Hamano
2023-09-06 6:40 ` Sergey Organov
2023-09-06 6:47 ` Sergey Organov
2023-09-06 15:58 ` Junio C Hamano
2023-09-06 7:15 ` [PATCH v2 " Sergey Organov
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).