{"thread":{"id":"60120","subject":"[PATCH 1/4] notes doc: split up run-on sentences","startedAt":"2023-08-16T14:26:54Z","lastAt":"2023-08-17T06:53:43Z","messageCount":12,"participants":["Martin Ågren","Junio C Hamano","Teng Long"],"isPatch":true,"patchVersion":1,"patchTotal":4},"messages":[{"id":"480710","messageId":"a8e5a98da5f577fc6235bff07d7430377344dd93.1692194193.git.martin.agren@gmail.com","threadId":"60120","inReplyTo":"cover.1692194193.git.martin.agren@gmail.com","subject":"[PATCH 1/4] notes doc: split up run-on sentences","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2023-08-16T14:24:33Z","receivedAt":"2023-08-16T14:26:54Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"When commit c4e2aa7d45 (notes.c: introduce \"--[no-]stripspace\" option,\n2023-05-27) mentioned the new `--no-stripspace` in the documentation for\n`-m` and `-F`, it created run-on sentences. It also used slightly\ndifferent language in the two sections for no apparent reason. Split the\nsentences in two to improve readability, and while touching the two\nsites, make them more similar.\n\nSigned-off-by: Martin Ågren \n---\n Documentation/git-notes.txt | 9 ++++-----\n 1 file changed, 4 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt\nindex bc1bfa3791..9043274ce8 100644\n--- a/Documentation/git-notes.txt\n+++ b/Documentation/git-notes.txt\n@@ -141,17 +141,16 @@ OPTIONS\n \tIf multiple `-m` options are given, their values\n \tare concatenated as separate paragraphs.\n \tLines starting with `#` and empty lines other than a\n-\tsingle line between paragraphs will be stripped out,\n-\tif you wish to keep them verbatim, use `--no-stripspace`.\n+\tsingle line between paragraphs will be stripped out.\n+\tIf you wish to keep them verbatim, use `--no-stripspace`.\n \n -F ::\n --file=::\n \tTake the note message from the given file. Use '-' to\n \tread the note message from the standard input.\n \tLines starting with `#` and empty lines other than a\n-\tsingle line between paragraphs will be stripped out,\n-\tif you wish to keep them verbatim, use with\n-\t`--no-stripspace` option.\n+\tsingle line between paragraphs will be stripped out.\n+\tIf you wish to keep them verbatim, use `--no-stripspace`.\n \n -C ::\n --reuse-message=::\n-- \n2.42.0.rc2.215.g538df5cf27\n\n"},{"id":"480711","messageId":"cover.1692194193.git.martin.agren@gmail.com","threadId":"60120","inReplyTo":null,"subject":"[PATCH 0/4] some doc fixes on v2.42.0-rc2","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2023-08-16T14:24:32Z","receivedAt":"2023-08-16T14:26:54Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"Looking into the changes to our documentation from v2.41.0 up to\nv2.42.0-rc2, I found some improvements we could make. I've cc'd the\noriginal authors on this cover letter and the respective patches.\n\nI realize we're fairly late in the release cycle. The impact of these\npatches is small, which could mean they're \"low risk\" or \"low benefit\"\ndepending on how you want to look at it.\n\nMartin\n\nMartin Ågren (4):\n notes doc: split up run-on sentences\n notes doc: tidy up `--no-stripspace` paragraph\n show-ref doc: fix carets in monospace\n rev-list-options: fix typo in `--stdin` documentation\n\n Documentation/git-notes.txt | 15 +++++++--------\n Documentation/git-show-ref.txt | 4 ++--\n Documentation/rev-list-options.txt | 2 +-\n 3 files changed, 10 insertions(+), 11 deletions(-)\n\n-- \n2.42.0.rc2.215.g538df5cf27\n\n"},{"id":"480712","messageId":"b1b3f1d10b64e63c62db0105957a4ad5e0295d34.1692194193.git.martin.agren@gmail.com","threadId":"60120","inReplyTo":"cover.1692194193.git.martin.agren@gmail.com","subject":"[PATCH 4/4] rev-list-options: fix typo in `--stdin` documentation","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2023-08-16T14:24:36Z","receivedAt":"2023-08-16T14:26:55Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"With `--stdin`, we read *from* standard input, not *for*.\n\nSigned-off-by: Martin Ågren \n---\n Documentation/rev-list-options.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt\nindex e6468bf0eb..a4a0cb93b2 100644\n--- a/Documentation/rev-list-options.txt\n+++ b/Documentation/rev-list-options.txt\n@@ -237,7 +237,7 @@ endif::git-rev-list[]\n \n --stdin::\n \tIn addition to getting arguments from the command line, read\n-\tthem for standard input as well. This accepts commits and\n+\tthem from standard input as well. This accepts commits and\n \tpseudo-options like `--all` and `--glob=`. When a `--` separator\n \tis seen, the following input is treated as paths and used to\n \tlimit the result.\n-- \n2.42.0.rc2.215.g538df5cf27\n\n"},{"id":"480713","messageId":"f2e31e70ff6cbf105d00aa5d1188554def34e142.1692194193.git.martin.agren@gmail.com","threadId":"60120","inReplyTo":"cover.1692194193.git.martin.agren@gmail.com","subject":"[PATCH 2/4] notes doc: tidy up `--no-stripspace` paragraph","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2023-08-16T14:24:34Z","receivedAt":"2023-08-16T14:26:55Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"Where we document the `--no-stripspace` option, remove a superfluous\n\"For\" to fix the grammar. Mark option names and command names using\n`backticks` to set them in monospace.\n\nSigned-off-by: Martin Ågren \n---\n Documentation/git-notes.txt | 6 +++---\n 1 file changed, 3 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt\nindex 9043274ce8..f8310e56a8 100644\n--- a/Documentation/git-notes.txt\n+++ b/Documentation/git-notes.txt\n@@ -179,9 +179,9 @@ OPTIONS\n --[no-]stripspace::\n \tStrip leading and trailing whitespace from the note message.\n \tAlso strip out empty lines other than a single line between\n-\tparagraphs. For lines starting with `#` will be stripped out\n-\tin non-editor cases like \"-m\", \"-F\" and \"-C\", but not in\n-\teditor case like \"git notes edit\", \"-c\", etc.\n+\tparagraphs. Lines starting with `#` will be stripped out\n+\tin non-editor cases like `-m`, `-F` and `-C`, but not in\n+\teditor case like `git notes edit`, `-c`, etc.\n \n --ref ::\n \tManipulate the notes tree in . This overrides\n-- \n2.42.0.rc2.215.g538df5cf27\n\n"},{"id":"480714","messageId":"f52247af9027192d0a29b8ee049db20250314d74.1692194193.git.martin.agren@gmail.com","threadId":"60120","inReplyTo":"cover.1692194193.git.martin.agren@gmail.com","subject":"[PATCH 3/4] show-ref doc: fix carets in monospace","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2023-08-16T14:24:35Z","receivedAt":"2023-08-16T14:26:55Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"When commit 00bf685975 (show-ref doc: update for internal consistency,\n2023-05-19) switched from double quotes to backticks around our {caret}\nmacro, we started rendering \"{caret}\" literally. Fix this by replacing\nby a \"^\" character.\n\nSigned-off-by: Martin Ågren \n---\n Documentation/git-show-ref.txt | 4 ++--\n 1 file changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt\nindex 44c7387d78..2fe274b8fa 100644\n--- a/Documentation/git-show-ref.txt\n+++ b/Documentation/git-show-ref.txt\n@@ -47,7 +47,7 @@ OPTIONS\n -d::\n --dereference::\n \n-\tDereference tags into object IDs as well. They will be shown with `{caret}{}`\n+\tDereference tags into object IDs as well. They will be shown with `^{}`\n \tappended.\n \n -s::\n@@ -78,7 +78,7 @@ OPTIONS\n \tMake `git show-ref` act as a filter that reads refs from stdin of the\n \tform `^(?:\\s)?(?:\\^{})?$`\n \tand performs the following actions on each:\n-\t(1) strip `{caret}{}` at the end of line if any;\n+\t(1) strip `^{}` at the end of line if any;\n \t(2) ignore if pattern is provided and does not head-match refname;\n \t(3) warn if refname is not a well-formed refname and skip;\n \t(4) ignore if refname is a ref that exists in the local repository;\n-- \n2.42.0.rc2.215.g538df5cf27\n\n"},{"id":"480723","messageId":"xmqq7cpug7iy.fsf@gitster.g","threadId":"60120","inReplyTo":"cover.1692194193.git.martin.agren@gmail.com","subject":"Re: [PATCH 0/4] some doc fixes on v2.42.0-rc2","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-08-16T18:35:17Z","receivedAt":"2023-08-16T18:36:19Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Martin Ågren writes:\n\n> Looking into the changes to our documentation from v2.41.0 up to\n> v2.42.0-rc2, I found some improvements we could make. I've cc'd the\n> original authors on this cover letter and the respective patches.\n\nIt is good that you looked into these, as everything else is slow\nduring the pre-release freeze period, and we are prioritizing\nregressions made during the latest cycle. Watching out for bugs in\nthe documentation updated during the cycle is much better than\nbuilding a random new feature ;-)\n\n> I realize we're fairly late in the release cycle. The impact of these\n> patches is small, which could mean they're \"low risk\" or \"low benefit\"\n> depending on how you want to look at it.\n\nThat is certainly true.\n\nThanks.\n"},{"id":"480724","messageId":"xmqqzg2qesoq.fsf@gitster.g","threadId":"60120","inReplyTo":"b1b3f1d10b64e63c62db0105957a4ad5e0295d34.1692194193.git.martin.agren@gmail.com","subject":"Re: [PATCH 4/4] rev-list-options: fix typo in `--stdin` documentation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-08-16T18:41:09Z","receivedAt":"2023-08-16T18:42:18Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Martin Ågren writes:\n\n> With `--stdin`, we read *from* standard input, not *for*.\n\nTrue, and the name of the stream is \"the standard input\".\n\n> Signed-off-by: Martin Ågren \n> ---\n> Documentation/rev-list-options.txt | 2 +-\n> 1 file changed, 1 insertion(+), 1 deletion(-)\n>\n> diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt\n> index e6468bf0eb..a4a0cb93b2 100644\n> --- a/Documentation/rev-list-options.txt\n> +++ b/Documentation/rev-list-options.txt\n> @@ -237,7 +237,7 @@ endif::git-rev-list[]\n> \n> --stdin::\n> \tIn addition to getting arguments from the command line, read\n> -\tthem for standard input as well. This accepts commits and\n> +\tthem from standard input as well. This accepts commits and\n> \tpseudo-options like `--all` and `--glob=`. When a `--` separator\n> \tis seen, the following input is treated as paths and used to\n> \tlimit the result.\n"},{"id":"480725","messageId":"xmqqv8dees64.fsf@gitster.g","threadId":"60120","inReplyTo":"xmqqzg2qesoq.fsf@gitster.g","subject":"Re: [PATCH 4/4] rev-list-options: fix typo in `--stdin` documentation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-08-16T18:52:19Z","receivedAt":"2023-08-16T18:53:31Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n> Martin Ågren writes:\n>\n>> With `--stdin`, we read *from* standard input, not *for*.\n>\n> True, and the name of the stream is \"the standard input\".\n\n... but there are too numerous instances of unadorned \"standard\ninput\" in the documentation, let's leave it for now.\n\nThanks for these fixes. Queued all four and will fast track.\n\n>\n>> Signed-off-by: Martin Ågren \n>> ---\n>> Documentation/rev-list-options.txt | 2 +-\n>> 1 file changed, 1 insertion(+), 1 deletion(-)\n>>\n>> diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt\n>> index e6468bf0eb..a4a0cb93b2 100644\n>> --- a/Documentation/rev-list-options.txt\n>> +++ b/Documentation/rev-list-options.txt\n>> @@ -237,7 +237,7 @@ endif::git-rev-list[]\n>> \n>> --stdin::\n>> \tIn addition to getting arguments from the command line, read\n>> -\tthem for standard input as well. This accepts commits and\n>> +\tthem from standard input as well. This accepts commits and\n>> \tpseudo-options like `--all` and `--glob=`. When a `--` separator\n>> \tis seen, the following input is treated as paths and used to\n>> \tlimit the result.\n"},{"id":"480736","messageId":"20230817022258.74357-1-tenglong.tl@alibaba-inc.com","threadId":"60120","inReplyTo":"a8e5a98da5f577fc6235bff07d7430377344dd93.1692194193.git.martin.agren@gmail.com","subject":"[PATCH 1/4] notes doc: split up run-on sentences","fromName":"Teng Long","fromEmail":"dyroneteng@gmail.com","sentAt":"2023-08-17T02:22:57Z","receivedAt":"2023-08-17T02:23:51Z","isPatch":true,"sender":{"key":"dyroneteng@gmail.com","avatar":"https://avatars.githubusercontent.com/u/7803958?v=4"},"body":"> \"Martin Ågren\" writes:\n> \n> When commit c4e2aa7d45 (notes.c: introduce \"--[no-]stripspace\" option,\n> 2023-05-27) mentioned the new `--no-stripspace` in the documentation for\n> `-m` and `-F`, it created run-on sentences. It also used slightly\n> different language in the two sections for no apparent reason. Split the\n> sentences in two to improve readability, and while touching the two\n> sites, make them more similar.\n> \n> Signed-off-by: Martin Ågren \n> ---\n> Documentation/git-notes.txt | 9 ++++-----\n> 1 file changed, 4 insertions(+), 5 deletions(-)\n> \n> diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt\n> index bc1bfa3791..9043274ce8 100644\n> --- a/Documentation/git-notes.txt\n> +++ b/Documentation/git-notes.txt\n> @@ -141,17 +141,16 @@ OPTIONS\n> \tIf multiple `-m` options are given, their values\n> \tare concatenated as separate paragraphs.\n> \tLines starting with `#` and empty lines other than a\n> -\tsingle line between paragraphs will be stripped out,\n> -\tif you wish to keep them verbatim, use `--no-stripspace`.\n> +\tsingle line between paragraphs will be stripped out.\n> +\tIf you wish to keep them verbatim, use `--no-stripspace`.\n> \n> -F ::\n> --file=::\n> \tTake the note message from the given file. Use '-' to\n> \tread the note message from the standard input.\n> \tLines starting with `#` and empty lines other than a\n> -\tsingle line between paragraphs will be stripped out,\n> -\tif you wish to keep them verbatim, use with\n> -\t`--no-stripspace` option.\n> +\tsingle line between paragraphs will be stripped out.\n> +\tIf you wish to keep them verbatim, use `--no-stripspace`.\n> \n\nLGTM.\n\nThanks for catching and fixing these docs.\n\n> -C ::\n> --reuse-message=::\n> -- \n> 2.42.0.rc2.215.g538df5cf27\n\nThanks\n"},{"id":"480737","messageId":"20230817025222.75033-1-tenglong.tl@alibaba-inc.com","threadId":"60120","inReplyTo":"f2e31e70ff6cbf105d00aa5d1188554def34e142.1692194193.git.martin.agren@gmail.com","subject":"[PATCH 2/4] notes doc: tidy up `--no-stripspace` paragraph","fromName":"Teng Long","fromEmail":"dyroneteng@gmail.com","sentAt":"2023-08-17T02:52:22Z","receivedAt":"2023-08-17T02:53:20Z","isPatch":true,"sender":{"key":"dyroneteng@gmail.com","avatar":"https://avatars.githubusercontent.com/u/7803958?v=4"},"body":"\"Martin Ågren\" writes:\n\n> Where we document the `--no-stripspace` option, remove a superfluous\n> \"For\" to fix the grammar. Mark option names and command names using\n> `backticks` to set them in monospace.\n\n\n\n> Signed-off-by: Martin Ågren \n> ---\n> Documentation/git-notes.txt | 6 +++---\n> 1 file changed, 3 insertions(+), 3 deletions(-)\n> \n> diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt\n> index 9043274ce8..f8310e56a8 100644\n> --- a/Documentation/git-notes.txt\n> +++ b/Documentation/git-notes.txt\n> @@ -179,9 +179,9 @@ OPTIONS\n> --[no-]stripspace::\n> \tStrip leading and trailing whitespace from the note message.\n> \tAlso strip out empty lines other than a single line between\n> -\tparagraphs. For lines starting with `#` will be stripped out\n> -\tin non-editor cases like \"-m\", \"-F\" and \"-C\", but not in\n> -\teditor case like \"git notes edit\", \"-c\", etc.\n> +\tparagraphs. Lines starting with `#` will be stripped out\n> +\tin non-editor cases like `-m`, `-F` and `-C`, but not in\n> +\teditor case like `git notes edit`, `-c`, etc.\n\nOops! I didn't notice to distingush ` and \", there are some places\nstill using \", but here we think to use ` is the apppropriate\nway to surround option and command, etc. in docs, right?\n\n> --ref ::\n> \tManipulate the notes tree in . This overrides\n> -- \n> 2.42.0.rc2.215.g538df5cf27\n\nThanks for fixing this.\n"},{"id":"480743","messageId":"CAN0heSq_H4Z4cD8GXG3h_C8x2LoQwP_BvNHmGTBNBGZsoEa-pA@mail.gmail.com","threadId":"60120","inReplyTo":"xmqqv8dees64.fsf@gitster.g","subject":"Re: [PATCH 4/4] rev-list-options: fix typo in `--stdin` documentation","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2023-08-17T06:51:07Z","receivedAt":"2023-08-17T06:52:00Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"On Wed, 16 Aug 2023 at 20:52, Junio C Hamano wrote:\n>\n> Junio C Hamano writes:\n>\n> > Martin Ågren writes:\n> >\n> >> With `--stdin`, we read *from* standard input, not *for*.\n> >\n> > True, and the name of the stream is \"the standard input\".\n\nThat's a good point, I hadn't really thought of that.\n\n> ... but there are too numerous instances of unadorned \"standard\n> input\" in the documentation, let's leave it for now.\n\nOk.\n\nMartin\n"},{"id":"480744","messageId":"CAN0heSoNTPaX6Z-MZnhHHN3CUc5ez7dgjvT-khknAHZeYfPQUw@mail.gmail.com","threadId":"60120","inReplyTo":"20230817025222.75033-1-tenglong.tl@alibaba-inc.com","subject":"Re: [PATCH 2/4] notes doc: tidy up `--no-stripspace` paragraph","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2023-08-17T06:52:23Z","receivedAt":"2023-08-17T06:53:43Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"On Thu, 17 Aug 2023 at 04:52, Teng Long wrote:\n>\n> \"Martin Ågren\" writes:\n>\n> > Strip leading and trailing whitespace from the note message.\n> > Also strip out empty lines other than a single line between\n> > - paragraphs. For lines starting with `#` will be stripped out\n> > - in non-editor cases like \"-m\", \"-F\" and \"-C\", but not in\n> > - editor case like \"git notes edit\", \"-c\", etc.\n> > + paragraphs. Lines starting with `#` will be stripped out\n> > + in non-editor cases like `-m`, `-F` and `-C`, but not in\n> > + editor case like `git notes edit`, `-c`, etc.\n>\n> Oops! I didn't notice to distingush ` and \", there are some places\n> still using \", but here we think to use ` is the apppropriate\n> way to surround option and command, etc. in docs, right?\n\nYes, we prefer `backticks`. The coding guidelines go into this around\nline 730(!). Of course, we're far from perfect. This file does a pretty\ngood job at it, but it could always be better. This patch was mostly\n\"since I'm touching this anyway, let's do this now so any future cleanup\nwill be slightly easier\".\n\nMartin\n"}]}