* [PATCH 1/4] notes doc: split up run-on sentences
2023-08-16 14:24 [PATCH 0/4] some doc fixes on v2.42.0-rc2 Martin Ågren
@ 2023-08-16 14:24 ` Martin Ågren
2023-08-17 2:22 ` Teng Long
2023-08-16 14:24 ` [PATCH 2/4] notes doc: tidy up `--no-stripspace` paragraph Martin Ågren
` (3 subsequent siblings)
4 siblings, 1 reply; 12+ messages in thread
From: Martin Ågren @ 2023-08-16 14:24 UTC (permalink / raw
To: git; +Cc: Teng Long
When commit c4e2aa7d45 (notes.c: introduce "--[no-]stripspace" option,
2023-05-27) mentioned the new `--no-stripspace` in the documentation for
`-m` and `-F`, it created run-on sentences. It also used slightly
different language in the two sections for no apparent reason. Split the
sentences in two to improve readability, and while touching the two
sites, make them more similar.
Signed-off-by: Martin Ågren <martin.agren@gmail.com>
---
Documentation/git-notes.txt | 9 ++++-----
1 file changed, 4 insertions(+), 5 deletions(-)
diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt
index bc1bfa3791..9043274ce8 100644
--- a/Documentation/git-notes.txt
+++ b/Documentation/git-notes.txt
@@ -141,17 +141,16 @@ OPTIONS
If multiple `-m` options are given, their values
are concatenated as separate paragraphs.
Lines starting with `#` and empty lines other than a
- single line between paragraphs will be stripped out,
- if you wish to keep them verbatim, use `--no-stripspace`.
+ single line between paragraphs will be stripped out.
+ If you wish to keep them verbatim, use `--no-stripspace`.
-F <file>::
--file=<file>::
Take the note message from the given file. Use '-' to
read the note message from the standard input.
Lines starting with `#` and empty lines other than a
- single line between paragraphs will be stripped out,
- if you wish to keep them verbatim, use with
- `--no-stripspace` option.
+ single line between paragraphs will be stripped out.
+ If you wish to keep them verbatim, use `--no-stripspace`.
-C <object>::
--reuse-message=<object>::
--
2.42.0.rc2.215.g538df5cf27
^ permalink raw reply related [flat|nested] 12+ messages in thread* [PATCH 1/4] notes doc: split up run-on sentences
2023-08-16 14:24 ` [PATCH 1/4] notes doc: split up run-on sentences Martin Ågren
@ 2023-08-17 2:22 ` Teng Long
0 siblings, 0 replies; 12+ messages in thread
From: Teng Long @ 2023-08-17 2:22 UTC (permalink / raw
To: martin.agren; +Cc: dyroneteng, git
> "Martin Ågren" <martin.agren@gmail.com> writes:
>
> When commit c4e2aa7d45 (notes.c: introduce "--[no-]stripspace" option,
> 2023-05-27) mentioned the new `--no-stripspace` in the documentation for
> `-m` and `-F`, it created run-on sentences. It also used slightly
> different language in the two sections for no apparent reason. Split the
> sentences in two to improve readability, and while touching the two
> sites, make them more similar.
>
> Signed-off-by: Martin Ågren <martin.agren@gmail.com>
> ---
> Documentation/git-notes.txt | 9 ++++-----
> 1 file changed, 4 insertions(+), 5 deletions(-)
>
> diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt
> index bc1bfa3791..9043274ce8 100644
> --- a/Documentation/git-notes.txt
> +++ b/Documentation/git-notes.txt
> @@ -141,17 +141,16 @@ OPTIONS
> If multiple `-m` options are given, their values
> are concatenated as separate paragraphs.
> Lines starting with `#` and empty lines other than a
> - single line between paragraphs will be stripped out,
> - if you wish to keep them verbatim, use `--no-stripspace`.
> + single line between paragraphs will be stripped out.
> + If you wish to keep them verbatim, use `--no-stripspace`.
>
> -F <file>::
> --file=<file>::
> Take the note message from the given file. Use '-' to
> read the note message from the standard input.
> Lines starting with `#` and empty lines other than a
> - single line between paragraphs will be stripped out,
> - if you wish to keep them verbatim, use with
> - `--no-stripspace` option.
> + single line between paragraphs will be stripped out.
> + If you wish to keep them verbatim, use `--no-stripspace`.
>
LGTM.
Thanks for catching and fixing these docs.
> -C <object>::
> --reuse-message=<object>::
> --
> 2.42.0.rc2.215.g538df5cf27
Thanks
^ permalink raw reply [flat|nested] 12+ messages in thread
* [PATCH 2/4] notes doc: tidy up `--no-stripspace` paragraph
2023-08-16 14:24 [PATCH 0/4] some doc fixes on v2.42.0-rc2 Martin Ågren
2023-08-16 14:24 ` [PATCH 1/4] notes doc: split up run-on sentences Martin Ågren
@ 2023-08-16 14:24 ` Martin Ågren
2023-08-17 2:52 ` Teng Long
2023-08-16 14:24 ` [PATCH 3/4] show-ref doc: fix carets in monospace Martin Ågren
` (2 subsequent siblings)
4 siblings, 1 reply; 12+ messages in thread
From: Martin Ågren @ 2023-08-16 14:24 UTC (permalink / raw
To: git; +Cc: Teng Long
Where we document the `--no-stripspace` option, remove a superfluous
"For" to fix the grammar. Mark option names and command names using
`backticks` to set them in monospace.
Signed-off-by: Martin Ågren <martin.agren@gmail.com>
---
Documentation/git-notes.txt | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt
index 9043274ce8..f8310e56a8 100644
--- a/Documentation/git-notes.txt
+++ b/Documentation/git-notes.txt
@@ -179,9 +179,9 @@ OPTIONS
--[no-]stripspace::
Strip leading and trailing whitespace from the note message.
Also strip out empty lines other than a single line between
- paragraphs. For lines starting with `#` will be stripped out
- in non-editor cases like "-m", "-F" and "-C", but not in
- editor case like "git notes edit", "-c", etc.
+ paragraphs. Lines starting with `#` will be stripped out
+ in non-editor cases like `-m`, `-F` and `-C`, but not in
+ editor case like `git notes edit`, `-c`, etc.
--ref <ref>::
Manipulate the notes tree in <ref>. This overrides
--
2.42.0.rc2.215.g538df5cf27
^ permalink raw reply related [flat|nested] 12+ messages in thread* [PATCH 2/4] notes doc: tidy up `--no-stripspace` paragraph
2023-08-16 14:24 ` [PATCH 2/4] notes doc: tidy up `--no-stripspace` paragraph Martin Ågren
@ 2023-08-17 2:52 ` Teng Long
2023-08-17 6:52 ` Martin Ågren
0 siblings, 1 reply; 12+ messages in thread
From: Teng Long @ 2023-08-17 2:52 UTC (permalink / raw
To: martin.agren; +Cc: dyroneteng, git
"Martin Ågren" <martin.agren@gmail.com> writes:
> Where we document the `--no-stripspace` option, remove a superfluous
> "For" to fix the grammar. Mark option names and command names using
> `backticks` to set them in monospace.
> Signed-off-by: Martin Ågren <martin.agren@gmail.com>
> ---
> Documentation/git-notes.txt | 6 +++---
> 1 file changed, 3 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt
> index 9043274ce8..f8310e56a8 100644
> --- a/Documentation/git-notes.txt
> +++ b/Documentation/git-notes.txt
> @@ -179,9 +179,9 @@ OPTIONS
> --[no-]stripspace::
> Strip leading and trailing whitespace from the note message.
> Also strip out empty lines other than a single line between
> - paragraphs. For lines starting with `#` will be stripped out
> - in non-editor cases like "-m", "-F" and "-C", but not in
> - editor case like "git notes edit", "-c", etc.
> + paragraphs. Lines starting with `#` will be stripped out
> + in non-editor cases like `-m`, `-F` and `-C`, but not in
> + editor case like `git notes edit`, `-c`, etc.
Oops! I didn't notice to distingush ` and ", there are some places
still using ", but here we think to use ` is the apppropriate
way to surround option and command, etc. in docs, right?
> --ref <ref>::
> Manipulate the notes tree in <ref>. This overrides
> --
> 2.42.0.rc2.215.g538df5cf27
Thanks for fixing this.
^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: [PATCH 2/4] notes doc: tidy up `--no-stripspace` paragraph
2023-08-17 2:52 ` Teng Long
@ 2023-08-17 6:52 ` Martin Ågren
0 siblings, 0 replies; 12+ messages in thread
From: Martin Ågren @ 2023-08-17 6:52 UTC (permalink / raw
To: Teng Long; +Cc: git
On Thu, 17 Aug 2023 at 04:52, Teng Long <dyroneteng@gmail.com> wrote:
>
> "Martin Ågren" <martin.agren@gmail.com> writes:
>
> > Strip leading and trailing whitespace from the note message.
> > Also strip out empty lines other than a single line between
> > - paragraphs. For lines starting with `#` will be stripped out
> > - in non-editor cases like "-m", "-F" and "-C", but not in
> > - editor case like "git notes edit", "-c", etc.
> > + paragraphs. Lines starting with `#` will be stripped out
> > + in non-editor cases like `-m`, `-F` and `-C`, but not in
> > + editor case like `git notes edit`, `-c`, etc.
>
> Oops! I didn't notice to distingush ` and ", there are some places
> still using ", but here we think to use ` is the apppropriate
> way to surround option and command, etc. in docs, right?
Yes, we prefer `backticks`. The coding guidelines go into this around
line 730(!). Of course, we're far from perfect. This file does a pretty
good job at it, but it could always be better. This patch was mostly
"since I'm touching this anyway, let's do this now so any future cleanup
will be slightly easier".
Martin
^ permalink raw reply [flat|nested] 12+ messages in thread
* [PATCH 3/4] show-ref doc: fix carets in monospace
2023-08-16 14:24 [PATCH 0/4] some doc fixes on v2.42.0-rc2 Martin Ågren
2023-08-16 14:24 ` [PATCH 1/4] notes doc: split up run-on sentences Martin Ågren
2023-08-16 14:24 ` [PATCH 2/4] notes doc: tidy up `--no-stripspace` paragraph Martin Ågren
@ 2023-08-16 14:24 ` Martin Ågren
2023-08-16 14:24 ` [PATCH 4/4] rev-list-options: fix typo in `--stdin` documentation Martin Ågren
2023-08-16 18:35 ` [PATCH 0/4] some doc fixes on v2.42.0-rc2 Junio C Hamano
4 siblings, 0 replies; 12+ messages in thread
From: Martin Ågren @ 2023-08-16 14:24 UTC (permalink / raw
To: git; +Cc: Sean Allred
When commit 00bf685975 (show-ref doc: update for internal consistency,
2023-05-19) switched from double quotes to backticks around our {caret}
macro, we started rendering "{caret}" literally. Fix this by replacing
by a "^" character.
Signed-off-by: Martin Ågren <martin.agren@gmail.com>
---
Documentation/git-show-ref.txt | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt
index 44c7387d78..2fe274b8fa 100644
--- a/Documentation/git-show-ref.txt
+++ b/Documentation/git-show-ref.txt
@@ -47,7 +47,7 @@ OPTIONS
-d::
--dereference::
- Dereference tags into object IDs as well. They will be shown with `{caret}{}`
+ Dereference tags into object IDs as well. They will be shown with `^{}`
appended.
-s::
@@ -78,7 +78,7 @@ OPTIONS
Make `git show-ref` act as a filter that reads refs from stdin of the
form `^(?:<anything>\s)?<refname>(?:\^{})?$`
and performs the following actions on each:
- (1) strip `{caret}{}` at the end of line if any;
+ (1) strip `^{}` at the end of line if any;
(2) ignore if pattern is provided and does not head-match refname;
(3) warn if refname is not a well-formed refname and skip;
(4) ignore if refname is a ref that exists in the local repository;
--
2.42.0.rc2.215.g538df5cf27
^ permalink raw reply related [flat|nested] 12+ messages in thread* [PATCH 4/4] rev-list-options: fix typo in `--stdin` documentation
2023-08-16 14:24 [PATCH 0/4] some doc fixes on v2.42.0-rc2 Martin Ågren
` (2 preceding siblings ...)
2023-08-16 14:24 ` [PATCH 3/4] show-ref doc: fix carets in monospace Martin Ågren
@ 2023-08-16 14:24 ` Martin Ågren
2023-08-16 18:41 ` Junio C Hamano
2023-08-16 18:35 ` [PATCH 0/4] some doc fixes on v2.42.0-rc2 Junio C Hamano
4 siblings, 1 reply; 12+ messages in thread
From: Martin Ågren @ 2023-08-16 14:24 UTC (permalink / raw
To: git; +Cc: Patrick Steinhardt
With `--stdin`, we read *from* standard input, not *for*.
Signed-off-by: Martin Ågren <martin.agren@gmail.com>
---
Documentation/rev-list-options.txt | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
index e6468bf0eb..a4a0cb93b2 100644
--- a/Documentation/rev-list-options.txt
+++ b/Documentation/rev-list-options.txt
@@ -237,7 +237,7 @@ endif::git-rev-list[]
--stdin::
In addition to getting arguments from the command line, read
- them for standard input as well. This accepts commits and
+ them from standard input as well. This accepts commits and
pseudo-options like `--all` and `--glob=`. When a `--` separator
is seen, the following input is treated as paths and used to
limit the result.
--
2.42.0.rc2.215.g538df5cf27
^ permalink raw reply related [flat|nested] 12+ messages in thread* Re: [PATCH 4/4] rev-list-options: fix typo in `--stdin` documentation
2023-08-16 14:24 ` [PATCH 4/4] rev-list-options: fix typo in `--stdin` documentation Martin Ågren
@ 2023-08-16 18:41 ` Junio C Hamano
2023-08-16 18:52 ` Junio C Hamano
0 siblings, 1 reply; 12+ messages in thread
From: Junio C Hamano @ 2023-08-16 18:41 UTC (permalink / raw
To: Martin Ågren; +Cc: git, Patrick Steinhardt
Martin Ågren <martin.agren@gmail.com> writes:
> With `--stdin`, we read *from* standard input, not *for*.
True, and the name of the stream is "the standard input".
> Signed-off-by: Martin Ågren <martin.agren@gmail.com>
> ---
> Documentation/rev-list-options.txt | 2 +-
> 1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
> index e6468bf0eb..a4a0cb93b2 100644
> --- a/Documentation/rev-list-options.txt
> +++ b/Documentation/rev-list-options.txt
> @@ -237,7 +237,7 @@ endif::git-rev-list[]
>
> --stdin::
> In addition to getting arguments from the command line, read
> - them for standard input as well. This accepts commits and
> + them from standard input as well. This accepts commits and
> pseudo-options like `--all` and `--glob=`. When a `--` separator
> is seen, the following input is treated as paths and used to
> limit the result.
^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: [PATCH 4/4] rev-list-options: fix typo in `--stdin` documentation
2023-08-16 18:41 ` Junio C Hamano
@ 2023-08-16 18:52 ` Junio C Hamano
2023-08-17 6:51 ` Martin Ågren
0 siblings, 1 reply; 12+ messages in thread
From: Junio C Hamano @ 2023-08-16 18:52 UTC (permalink / raw
To: Martin Ågren; +Cc: git, Patrick Steinhardt
Junio C Hamano <gitster@pobox.com> writes:
> Martin Ågren <martin.agren@gmail.com> writes:
>
>> With `--stdin`, we read *from* standard input, not *for*.
>
> True, and the name of the stream is "the standard input".
... but there are too numerous instances of unadorned "standard
input" in the documentation, let's leave it for now.
Thanks for these fixes. Queued all four and will fast track.
>
>> Signed-off-by: Martin Ågren <martin.agren@gmail.com>
>> ---
>> Documentation/rev-list-options.txt | 2 +-
>> 1 file changed, 1 insertion(+), 1 deletion(-)
>>
>> diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
>> index e6468bf0eb..a4a0cb93b2 100644
>> --- a/Documentation/rev-list-options.txt
>> +++ b/Documentation/rev-list-options.txt
>> @@ -237,7 +237,7 @@ endif::git-rev-list[]
>>
>> --stdin::
>> In addition to getting arguments from the command line, read
>> - them for standard input as well. This accepts commits and
>> + them from standard input as well. This accepts commits and
>> pseudo-options like `--all` and `--glob=`. When a `--` separator
>> is seen, the following input is treated as paths and used to
>> limit the result.
^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: [PATCH 4/4] rev-list-options: fix typo in `--stdin` documentation
2023-08-16 18:52 ` Junio C Hamano
@ 2023-08-17 6:51 ` Martin Ågren
0 siblings, 0 replies; 12+ messages in thread
From: Martin Ågren @ 2023-08-17 6:51 UTC (permalink / raw
To: Junio C Hamano; +Cc: git, Patrick Steinhardt
On Wed, 16 Aug 2023 at 20:52, Junio C Hamano <gitster@pobox.com> wrote:
>
> Junio C Hamano <gitster@pobox.com> writes:
>
> > Martin Ågren <martin.agren@gmail.com> writes:
> >
> >> With `--stdin`, we read *from* standard input, not *for*.
> >
> > True, and the name of the stream is "the standard input".
That's a good point, I hadn't really thought of that.
> ... but there are too numerous instances of unadorned "standard
> input" in the documentation, let's leave it for now.
Ok.
Martin
^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: [PATCH 0/4] some doc fixes on v2.42.0-rc2
2023-08-16 14:24 [PATCH 0/4] some doc fixes on v2.42.0-rc2 Martin Ågren
` (3 preceding siblings ...)
2023-08-16 14:24 ` [PATCH 4/4] rev-list-options: fix typo in `--stdin` documentation Martin Ågren
@ 2023-08-16 18:35 ` Junio C Hamano
4 siblings, 0 replies; 12+ messages in thread
From: Junio C Hamano @ 2023-08-16 18:35 UTC (permalink / raw
To: Martin Ågren; +Cc: git, Teng Long, Sean Allred, Patrick Steinhardt
Martin Ågren <martin.agren@gmail.com> writes:
> Looking into the changes to our documentation from v2.41.0 up to
> v2.42.0-rc2, I found some improvements we could make. I've cc'd the
> original authors on this cover letter and the respective patches.
It is good that you looked into these, as everything else is slow
during the pre-release freeze period, and we are prioritizing
regressions made during the latest cycle. Watching out for bugs in
the documentation updated during the cycle is much better than
building a random new feature ;-)
> I realize we're fairly late in the release cycle. The impact of these
> patches is small, which could mean they're "low risk" or "low benefit"
> depending on how you want to look at it.
That is certainly true.
Thanks.
^ permalink raw reply [flat|nested] 12+ messages in thread