threads / patch / 60120

patch, 4 partsnotes doc: split up run-on sentences

Subject: [PATCH 1/4] notes doc: split up run-on sentences

## tl;dr

12 messages between Aug 16, 2023 and Aug 17, 2023. Diffs are folded; open one to read it.

replies: 11people: 3as markdown or json

Martin Ågren· Aug 16, 2023, 14:24 UTC · lore

[PATCH 0/4] some doc fixes on v2.42.0-rc2

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.

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.

Martin
Martin Ågren (4):
  notes doc: split up run-on sentences
  notes doc: tidy up `--no-stripspace` paragraph
  show-ref doc: fix carets in monospace
  rev-list-options: fix typo in `--stdin` documentation
 Documentation/git-notes.txt        | 15 +++++++--------
 Documentation/git-show-ref.txt     |  4 ++--
 Documentation/rev-list-options.txt |  2 +-
 3 files changed, 10 insertions(+), 11 deletions(-)
-- 
2.42.0.rc2.215.g538df5cf27
Martin Ågren· Aug 16, 2023, 14:24 UTC · re: Martin Ågren · lore

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(-)
Show changes to Documentation/git-notes.txt +4 −5
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
Teng Long· Aug 17, 2023, 02:22 UTC · re: Martin Ågren · lore
Show 38 quoted lines
> "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
Martin Ågren· Aug 16, 2023, 14:24 UTC · re: Martin Ågren · lore

[PATCH 4/4] rev-list-options: fix typo in `--stdin` documentation

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(-)
Show changes to Documentation/rev-list-options.txt +1 −1
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
Junio C Hamano· Aug 16, 2023, 18:41 UTC · re: Martin Ågren · lore

Re: [PATCH 4/4] rev-list-options: fix typo in `--stdin` documentation

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".
Show 18 quoted lines
> 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.
Junio C Hamano· Aug 16, 2023, 18:52 UTC · re: Junio C Hamano · lore

Re: [PATCH 4/4] rev-list-options: fix typo in `--stdin` documentation

Junio C Hamano <gitster@pobox.com> writes:
Show 5 quoted lines
> 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.
Show 19 quoted lines
>
>> 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.
Martin Ågren· Aug 17, 2023, 06:51 UTC · re: Junio C Hamano · lore

Re: [PATCH 4/4] rev-list-options: fix typo in `--stdin` documentation

On Wed, 16 Aug 2023 at 20:52, Junio C Hamano <gitster@pobox.com> wrote:
Show 8 quoted lines
>
> 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
Martin Ågren· Aug 16, 2023, 14:24 UTC · re: Martin Ågren · lore

[PATCH 2/4] notes doc: tidy up `--no-stripspace` paragraph

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(-)
Show changes to Documentation/git-notes.txt +3 −3
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
Teng Long· Aug 17, 2023, 02:52 UTC · re: Martin Ågren · lore

[PATCH 2/4] notes doc: tidy up `--no-stripspace` paragraph

"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.
Show 19 quoted lines
> 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.
Martin Ågren· Aug 17, 2023, 06:52 UTC · re: Teng Long · lore

Re: [PATCH 2/4] notes doc: tidy up `--no-stripspace` paragraph

On Thu, 17 Aug 2023 at 04:52, Teng Long <dyroneteng@gmail.com> wrote:
Show 15 quoted lines
>
> "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
Martin Ågren· Aug 16, 2023, 14:24 UTC · re: Martin Ågren · lore

[PATCH 3/4] show-ref doc: fix carets in monospace

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(-)
Show changes to Documentation/git-show-ref.txt +2 −2
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
Junio C Hamano· Aug 16, 2023, 18:35 UTC · re: Martin Ågren · lore

Re: [PATCH 0/4] some doc fixes on v2.42.0-rc2

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.

← back to recent threads