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

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

[Martin Ågren]

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

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

[Martin Ågren]

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

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

[Martin Ågren]

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

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

[Martin Ågren]

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

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

[Martin Ågren]

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

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

[Junio C Hamano]

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.

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

[Junio C Hamano]

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.

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

[Junio C Hamano]

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.

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

[Teng Long]

> "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

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

[Teng Long]

"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.

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

[Martin Ågren]

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

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

[Martin Ågren]

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