some doc fixes on v2.42.0-rc2
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
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
@@ -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
PATCH 1/4 notes doc: split up run-on sentences
Quoted 28 lines
"Martin Ågren" <[email protected]> writes:
When commit
c4e2aa7d45(notes.c: introduce "--[no-]stripspace" option, 2023-05-27) mentioned the new--no-stripspacein the documentation for-mand-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 <[email protected]>--- Documentation/git-notes.txt | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-)Documentation/git-notes.txt +2
-2@@ -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
PATCH 2/4 notes doc: tidy up `--no-stripspace` paragraph
In reply to Martin ÅgrenWhere 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
@@ -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
PATCH 2/4 notes doc: tidy up `--no-stripspace` paragraph
Quoted 16 lines · Martin Ågren
Where we document the
--no-stripspaceoption, remove a superfluous "For" to fix the grammar. Mark option names and command names usingbackticksto set them in monospace.Signed-off-by Martin Ågren <[email protected]>--- Documentation/git-notes.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-)Documentation/git-notes.txt +0
-0
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 overridesSignature · 1 line
2.42.0.rc2.215.g538df5cf27
Thanks for fixing this.
Re: [PATCH 2/4] notes doc: tidy up `--no-stripspace` paragraph
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 useis 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
PATCH 3/4 show-ref doc: fix carets in monospace
In reply to Martin ÅgrenWhen 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
@@ -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
PATCH 4/4 rev-list-options: fix typo in `--stdin` documentation
In reply to Martin ÅgrenWith --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
@@ -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
Re: [PATCH 4/4] rev-list-options: fix typo in `--stdin` documentation
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
Signed-off-by Martin Ågren <[email protected]>--- Documentation/rev-list-options.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)Documentation/rev-list-options.txt +1
-1@@ -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
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
Signed-off-by Martin Ågren <[email protected]>--- Documentation/rev-list-options.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)Documentation/rev-list-options.txt +1
-1@@ -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
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
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.