Skip to contentSkip to conversation

some doc fixes on v2.42.0-rc2

PATCH In review Martin Ågren 3 participants 12 messages Aug 16, 2023 – Aug 17, 2023 Documentation

lore
Share & tools
lore
#0 lore raw

cover 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(-)
Signature · 1 line
2.42.0.rc2.215.g538df5cf27
#1 lore raw

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

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.

---
 Documentation/git-notes.txt | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)
Documentation/git-notes.txt +4 -5
index bc1bfa3791..9043274ce8 100644
@@ -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>::
Signature · 1 line
2.42.0.rc2.215.g538df5cf27
#3 lore raw

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

In reply to 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.

---
 Documentation/git-notes.txt | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)
Documentation/git-notes.txt +3 -3
index 9043274ce8..f8310e56a8 100644
@@ -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
Signature · 1 line
2.42.0.rc2.215.g538df5cf27
#6 lore raw

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

In reply to 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.

---
 Documentation/git-show-ref.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
Documentation/git-show-ref.txt +2 -2
index 44c7387d78..2fe274b8fa 100644
@@ -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;
Signature · 1 line
2.42.0.rc2.215.g538df5cf27
#7 lore raw

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

In reply to Martin Ågren

With --stdin, we read *from* standard input, not *for*.

---
 Documentation/rev-list-options.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/rev-list-options.txt +1 -1
index e6468bf0eb..a4a0cb93b2 100644
@@ -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.
Signature · 1 line
2.42.0.rc2.215.g538df5cf27
#11 lore raw
In reply to Martin Ågren
Quoted 3 lines · 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.

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 ;-)

Quoted 3 lines

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.

#8 lore raw

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

In reply to Martin Ågren
Quoted 1 line · Martin Ågren

With --stdin, we read *from* standard input, not *for*.

True, and the name of the stream is "the standard input".

Quoted 18 lines
---
 Documentation/rev-list-options.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/rev-list-options.txt +1 -1
index e6468bf0eb..a4a0cb93b2 100644
@@ -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.
#9 lore raw

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

Quoted 5 lines · Junio C Hamano
Quoted 1 line · Martin Ågren

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.

Quoted 19 lines
Quoted 19 lines
---
 Documentation/rev-list-options.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/rev-list-options.txt +1 -1
index e6468bf0eb..a4a0cb93b2 100644
@@ -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 lore raw

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

In reply to Martin Ågren
Quoted 28 lines

"Martin Ågren" <[email protected]> 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.

---
 Documentation/git-notes.txt | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)
Documentation/git-notes.txt +2 -2
index bc1bfa3791..9043274ce8 100644
@@ -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>::

Documentation/git-notes.txt OPTIONS · line 154

Quoted 10 lines
Documentation/git-notes.txt +2 -3
 --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.

Quoted 4 lines
Documentation/git-notes.txt +0 -0
 -C <object>::
 --reuse-message=<object>::
Signature · 1 line
2.42.0.rc2.215.g538df5cf27

Thanks

#4 lore raw

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

In reply to Martin Ågren
Quoted 16 lines · 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.

---
 Documentation/git-notes.txt | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)
Documentation/git-notes.txt +0 -0
index 9043274ce8..f8310e56a8 100644

Documentation/git-notes.txt OPTIONS · line 184

Quoted 9 lines
Documentation/git-notes.txt +3 -3
@@ -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?

Quoted 4 lines
Documentation/git-notes.txt +0 -0
 --ref <ref>::
 	Manipulate the notes tree in <ref>.  This overrides
Signature · 1 line
2.42.0.rc2.215.g538df5cf27

Thanks for fixing this.

#10 lore raw

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

In reply to Junio C Hamano
Quoted 8 lines · Junio C Hamano
Quoted 5 lines · Junio C Hamano
Quoted 1 line · Martin Ågren

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.

Quoted 2 lines

... but there are too numerous instances of unadorned "standard input" in the documentation, let's leave it for now.

Ok.

Martin

#5 lore raw

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

In reply to Teng Long
Quoted 12 lines · Teng Long

Documentation/git-notes.txt OPTIONS · line 184

Quoted 8 lines · Martin Ågren

Strip leading and trailing whitespace from the note message. Also strip out empty lines other than a single line between

Documentation/git-notes.txt +3 -3
-     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.
Quoted 3 lines

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