pretty-formats.txt: fix whitespace

Message ID	pull.950.git.1695391818917.gitgitgadget@gmail.com (mailing list archive)
State	New, archived
Headers	show Return-Path: <git-owner@vger.kernel.org> Message-ID: <pull.950.git.1695391818917.gitgitgadget@gmail.com> Date: Fri, 22 Sep 2023 14:10:18 +0000 Subject: [PATCH] pretty-formats.txt: fix whitespace Fcc: Sent Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit MIME-Version: 1.0 To: git@vger.kernel.org Cc: Josh Soref <jsoref@gmail.com>, Josh Soref <jsoref@gmail.com> Precedence: bulk From: Josh Soref <jsoref@gmail.com>
Series	pretty-formats.txt: fix whitespace \| expand pretty-formats.txt: fix whitespace

Josh Soref Sept. 22, 2023, 2:10 p.m. UTC

From: Josh Soref <jsoref@gmail.com>

* two spaces after periods for sentences
* comma (before/)after `i.e.` and `e.g.`
* comma after `etc.` when not ending a sentence
* space before `(`

Signed-off-by: Josh Soref <jsoref@gmail.com>
---
    pretty-formats.txt: fix whitespace
    
    follow-up-to:
    https://github.com/gitgitgadget/git/pull/939#discussion_r624652778
    
     * two spaces after periods for sentences
     * comma (before/)after i.e. and e.g.
     * space before (
    
    Signed-off-by: Josh Soref jsoref@gmail.com

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-950%2Fjsoref%2Fwhitespace-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-950/jsoref/whitespace-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/950

 Documentation/pretty-formats.txt | 68 ++++++++++++++++----------------
 1 file changed, 34 insertions(+), 34 deletions(-)


base-commit: bda494f4043963b9ec9a1ecd4b19b7d1cd9a0518

Junio C Hamano Sept. 22, 2023, 9:56 p.m. UTC | #1

"Josh Soref via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Josh Soref <jsoref@gmail.com>
>
> * two spaces after periods for sentences

Although I admit I tend to hit my spacebar twice after a sentence, I
think more people tend to just do with a single space and let the
formatting software (like AsciiDoc) take care of the inter-sentence
spacing.  To me, this falls into "it would be nicer if we did this
when we write a new sentence, but it is not worth the patch noise if
somebody already wrote with a single space to change them" category.

The title of the patch may have been written after you did the
above, but now it includes other changes listed below, so it may
want to be revised.

> * comma (before/)after `i.e.` and `e.g.`

That's modern American English.  I think our documentation is
mixture so this may also fall into "if it is already written that
way, it is not worth the patch noise to change" category.

> * comma after `etc.` when not ending a sentence

There is one instance that says "A, B, C, D, etc., are all accepted."
without the comma after 'etc.' and the patch corrects it.  OK.

> * space before `(`

If you mean by the above that we used to say

	... as described below(see linkgit:git-config[1]))

and you added a SP before "(see", that is a definite improvement.  I
however didn't find an example of a line that lacks SP before '('
that got corrected to have a SP there.

> Signed-off-by: Josh Soref <jsoref@gmail.com>
> ---

Thanks.

>     pretty-formats.txt: fix whitespace
>     
>     follow-up-to:
>     https://github.com/gitgitgadget/git/pull/939#discussion_r624652778
>     
>      * two spaces after periods for sentences
>      * comma (before/)after i.e. and e.g.
>      * space before (
>     
>     Signed-off-by: Josh Soref jsoref@gmail.com
>
> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-950%2Fjsoref%2Fwhitespace-v1
> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-950/jsoref/whitespace-v1
> Pull-Request: https://github.com/gitgitgadget/git/pull/950
>
>  Documentation/pretty-formats.txt | 68 ++++++++++++++++----------------
>  1 file changed, 34 insertions(+), 34 deletions(-)
>
> diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt
> index d38b4ab5666..f64c0a2d92e 100644
> --- a/Documentation/pretty-formats.txt
> +++ b/Documentation/pretty-formats.txt
> @@ -15,7 +15,7 @@ There are several built-in formats, and you can define
>  additional formats by setting a pretty.<name>
>  config option to either another format name, or a
>  'format:' string, as described below (see
> -linkgit:git-config[1]). Here are the details of the
> +linkgit:git-config[1]).  Here are the details of the
>  built-in formats:
>  
>  * 'oneline'
> @@ -96,15 +96,15 @@ stored in the commit object.  Notably, the hashes are
>  displayed in full, regardless of whether --abbrev or
>  --no-abbrev are used, and 'parents' information show the
>  true parent commits, without taking grafts or history
> -simplification into account. Note that this format affects the way
> -commits are displayed, but not the way the diff is shown e.g. with
> -`git log --raw`. To get full object names in a raw diff format,
> +simplification into account.  Note that this format affects the way
> +commits are displayed, but not the way the diff is shown, e.g., with
> +`git log --raw`.  To get full object names in a raw diff format,
>  use `--no-abbrev`.
>  
>  * 'format:<format-string>'
>  +
>  The 'format:<format-string>' format allows you to specify which information
> -you want to show. It works a little bit like printf format,
> +you want to show.  It works a little bit like printf format,
>  with the notable exception that you get a newline with '%n'
>  instead of '\n'.
>  +
> @@ -136,13 +136,13 @@ The placeholders are:
>  	    default, colors are shown only when enabled for log output
>  	    (by `color.diff`, `color.ui`, or `--color`, and respecting
>  	    the `auto` settings of the former if we are going to a
> -	    terminal). `%C(auto,...)` is accepted as a historical
> -	    synonym for the default (e.g., `%C(auto,red)`). Specifying
> +	    terminal).  `%C(auto,...)` is accepted as a historical
> +	    synonym for the default (e.g., `%C(auto,red)`).  Specifying
>  	    `%C(always,...)` will show the colors even when color is
>  	    not otherwise enabled (though consider just using
>  	    `--color=always` to enable color for the whole output,
>  	    including this format and anything else git might color).
> -	    `auto` alone (i.e. `%C(auto)`) will turn on auto coloring
> +	    `auto` alone (i.e., `%C(auto)`) will turn on auto coloring
>  	    on the next placeholders until the color is switched
>  	    again.
>  '%m':: left (`<`), right (`>`) or boundary (`-`) mark
> @@ -177,7 +177,7 @@ The placeholders are:
>  			  spaces
>  '%><( <N> )', '%><|( <M> )':: similar to '%<( <N> )', '%<|( <M> )'
>  			  respectively, but padding both sides
> -			  (i.e. the text is centered)
> +			  (i.e., the text is centered)
>  
>  - Placeholders that expand to information extracted from the commit:
>  '%H':: commit hash
> @@ -225,9 +225,9 @@ The placeholders are:
>  '%d':: ref names, like the --decorate option of linkgit:git-log[1]
>  '%D':: ref names without the " (", ")" wrapping.
>  '%(decorate[:<options>])'::
> -ref names with custom decorations. The `decorate` string may be followed by a
> -colon and zero or more comma-separated options. Option values may contain
> -literal formatting codes. These must be used for commas (`%x2C`) and closing
> +ref names with custom decorations.  The `decorate` string may be followed by a
> +colon and zero or more comma-separated options.  Option values may contain
> +literal formatting codes.  These must be used for commas (`%x2C`) and closing
>  parentheses (`%x29`), due to their role in the option syntax.
>  +
>  ** 'prefix=<value>': Shown before the list of ref names.  Defaults to "{nbsp}`(`".
> @@ -235,7 +235,7 @@ parentheses (`%x29`), due to their role in the option syntax.
>  ** 'separator=<value>': Shown between ref names.  Defaults to "`,`{nbsp}".
>  ** 'pointer=<value>': Shown between HEAD and the branch it points to, if any.
>  		      Defaults to "{nbsp}`->`{nbsp}".
> -** 'tag=<value>': Shown before tag names. Defaults to "`tag:`{nbsp}".
> +** 'tag=<value>': Shown before tag names.  Defaults to "`tag:`{nbsp}".
>  
>  +
>  For example, to produce decorations with no wrapping
> @@ -277,7 +277,7 @@ endif::git-rev-list[]
>  	"X" for a good signature that has expired,
>  	"Y" for a good signature made by an expired key,
>  	"R" for a good signature made by a revoked key,
> -	"E" if the signature cannot be checked (e.g. missing key)
> +	"E" if the signature cannot be checked (e.g., missing key)
>  	and "N" for no signature
>  '%GS':: show the name of the signer for a signed commit
>  '%GK':: show the key used to sign a signed commit
> @@ -287,7 +287,7 @@ endif::git-rev-list[]
>  '%GT':: show the trust level for the key used to sign a signed commit
>  '%gD':: reflog selector, e.g., `refs/stash@{1}` or `refs/stash@{2
>  	minutes ago}`; the format follows the rules described for the
> -	`-g` option. The portion before the `@` is the refname as
> +	`-g` option.  The portion before the `@` is the refname as
>  	given on the command line (so `git log -g refs/heads/master`
>  	would yield `refs/heads/master@{0}`).
>  '%gd':: shortened reflog selector; same as `%gD`, but the refname
> @@ -302,48 +302,48 @@ endif::git-rev-list[]
>  '%gs':: reflog subject
>  '%(trailers[:<options>])'::
>  display the trailers of the body as interpreted by
> -linkgit:git-interpret-trailers[1]. The `trailers` string may be followed by
> -a colon and zero or more comma-separated options. If any option is provided
> +linkgit:git-interpret-trailers[1].  The `trailers` string may be followed by
> +a colon and zero or more comma-separated options.  If any option is provided
>  multiple times, the last occurrence wins.
>  +
> -** 'key=<key>': only show trailers with specified <key>. Matching is done
> -   case-insensitively and trailing colon is optional. If option is
> +** 'key=<key>': only show trailers with specified <key>.  Matching is done
> +   case-insensitively and trailing colon is optional.  If option is
>     given multiple times trailer lines matching any of the keys are
> -   shown. This option automatically enables the `only` option so that
> -   non-trailer lines in the trailer block are hidden. If that is not
> +   shown.  This option automatically enables the `only` option so that
> +   non-trailer lines in the trailer block are hidden.  If that is not
>     desired it can be disabled with `only=false`.  E.g.,
>     `%(trailers:key=Reviewed-by)` shows trailer lines with key
>     `Reviewed-by`.
>  ** 'only[=<bool>]': select whether non-trailer lines from the trailer
>     block should be included.
>  ** 'separator=<sep>': specify a separator inserted between trailer
> -   lines. When this option is not given each trailer line is
> -   terminated with a line feed character. The string <sep> may contain
> -   the literal formatting codes described above. To use comma as
> +   lines.  When this option is not given each trailer line is
> +   terminated with a line feed character.  The string <sep> may contain
> +   the literal formatting codes described above.  To use comma as
>     separator one must use `%x2C` as it would otherwise be parsed as
> -   next option. E.g., `%(trailers:key=Ticket,separator=%x2C )`
> +   next option.  E.g., `%(trailers:key=Ticket,separator=%x2C )`
>     shows all trailer lines whose key is "Ticket" separated by a comma
>     and a space.
>  ** 'unfold[=<bool>]': make it behave as if interpret-trailer's `--unfold`
> -   option was given. E.g.,
> +   option was given.  E.g.,
>     `%(trailers:only,unfold=true)` unfolds and shows all trailer lines.
>  ** 'keyonly[=<bool>]': only show the key part of the trailer.
>  ** 'valueonly[=<bool>]': only show the value part of the trailer.
>  ** 'key_value_separator=<sep>': specify a separator inserted between
> -   trailer lines. When this option is not given each trailer key-value
> -   pair is separated by ": ". Otherwise it shares the same semantics
> +   trailer lines.  When this option is not given each trailer key-value
> +   pair is separated by ": ".  Otherwise it shares the same semantics
>     as 'separator=<sep>' above.
>  
>  NOTE: Some placeholders may depend on other options given to the
> -revision traversal engine. For example, the `%g*` reflog options will
> +revision traversal engine.  For example, the `%g*` reflog options will
>  insert an empty string unless we are traversing reflog entries (e.g., by
> -`git log -g`). The `%d` and `%D` placeholders will use the "short"
> +`git log -g`).  The `%d` and `%D` placeholders will use the "short"
>  decoration format if `--decorate` was not already provided on the command
>  line.
>  
> -The boolean options accept an optional value `[=<bool-value>]`. The values
> -`true`, `false`, `on`, `off` etc. are all accepted. See the "boolean"
> -sub-section in "EXAMPLES" in linkgit:git-config[1]. If a boolean
> +The boolean options accept an optional value `[=<bool-value>]`.  The values
> +`true`, `false`, `on`, `off`, etc., are all accepted.  See the "boolean"
> +sub-section in "EXAMPLES" in linkgit:git-config[1].  If a boolean
>  option is given with no value, it's enabled.
>  
>  If you add a `+` (plus sign) after '%' of a placeholder, a line-feed
> @@ -361,7 +361,7 @@ placeholder expands to a non-empty string.
>  * 'tformat:'
>  +
>  The 'tformat:' format works exactly like 'format:', except that it
> -provides "terminator" semantics instead of "separator" semantics. In
> +provides "terminator" semantics instead of "separator" semantics.  In
>  other words, each commit has the message terminator character (usually a
>  newline) appended, rather than a separator placed between entries.
>  This means that the final entry of a single-line format will be properly
>
> base-commit: bda494f4043963b9ec9a1ecd4b19b7d1cd9a0518

Josh Soref Sept. 24, 2023, 10:31 a.m. UTC | #2

Junio C Hamano <gitster@pobox.com> wrote:
> > * two spaces after periods for sentences
>
> Although I admit I tend to hit my spacebar twice after a sentence, I
> think more people tend to just do with a single space and let the
> formatting software (like AsciiDoc) take care of the inter-sentence
> spacing.  To me, this falls into "it would be nicer if we did this
> when we write a new sentence, but it is not worth the patch noise if
> somebody already wrote with a single space to change them" category.

> The title of the patch may have been written after you did the
> above, but now it includes other changes listed below, so it may
> want to be revised.

Indeed.

Would it get revised or just abandoned in favor of something else?

> > * comma (before/)after `i.e.` and `e.g.`
>
> That's modern American English.  I think our documentation is
> mixture so this may also fall into "if it is already written that
> way, it is not worth the patch noise to change" category.
>
> > * comma after `etc.` when not ending a sentence
>
> There is one instance that says "A, B, C, D, etc., are all accepted."
> without the comma after 'etc.' and the patch corrects it.  OK.

It seems like this is the only change that's of interest.

Do I just make a distinct gitgitgadget PR with that change, or do I
ask it to mark that single change as a V2 to this? (given the branch
name assumed whitespace and the only change would be a comma, it'd be
kinda wrong...)

> > * space before `(`
>
> If you mean by the above that we used to say
>
>         ... as described below(see linkgit:git-config[1]))
>
> and you added a SP before "(see", that is a definite improvement.  I
> however didn't find an example of a line that lacks SP before '('
> that got corrected to have a SP there.

I'm pretty sure that's what I meant, but I can't find the change in my
git reflog, and I'm not quite sure how I could have made that mistake.

Junio C Hamano Sept. 25, 2023, 5:24 p.m. UTC | #3

Josh Soref <jsoref@gmail.com> writes:

>> > * comma after `etc.` when not ending a sentence
>>
>> There is one instance that says "A, B, C, D, etc., are all accepted."
>> without the comma after 'etc.' and the patch corrects it.  OK.
>
> It seems like this is the only change that's of interest.
>
> Do I just make a distinct gitgitgadget PR with that change, or do I
> ask it to mark that single change as a V2 to this? (given the branch
> name assumed whitespace and the only change would be a comma, it'd be
> kinda wrong...)

;-)

Up to you.  If I were doing this patch, I would wait and see if
others chime in (to support other changes in v1 that I was on the
negative side) and then make v2 with the changes you still believe
in when that happens.

Thanks.

Kristoffer Haugsbakk Sept. 25, 2023, 8:04 p.m. UTC | #4

On Fri, Sep 22, 2023, at 16:10, Josh Soref via GitGitGadget wrote:
> From: Josh Soref <jsoref@gmail.com>
>
> * two spaces after periods for sentences

Where's the two-spacing convention documented? I didn't find it in
`CodingGuidelines` or `SubmittingPatches`.

Thanks

Josh Soref Sept. 26, 2023, 2:51 a.m. UTC | #5

> From: Josh Soref <jsoref@gmail.com>
> * two spaces after periods for sentences

Kristoffer Haugsbakk wrote:
> Where's the two-spacing convention documented? I didn't find it in
> `CodingGuidelines` or `SubmittingPatches`.

There appeared to be too many instances of two spaces after a period
in the file to be accidental. In some ways, it was an invitation for
people to indicate if they have a preference.

I personally do not have a preference between two spaces after and one
space after, but I do have a preference against a mix of two spaces
after and one space after.

As it (IMO) takes effort (admittedly trivial, and quite likely
habitual) to insert a second space, I assume that this was a desired
thing and the one space was the aberration, hence the patch went in
favor of two spaces.

I'd just as soon submit a patch the other way (and if people have an
opinion one way or the other, I'm happy to include a change to
CodingGuidelines/SubmittingPatches based on people's opinions).

Junio C Hamano Sept. 26, 2023, 4:42 p.m. UTC | #6

Josh Soref <jsoref@gmail.com> writes:

> As it (IMO) takes effort (admittedly trivial, and quite likely
> habitual) to insert a second space, I assume that this was a desired
> thing and the one space was the aberration, hence the patch went in
> favor of two spaces.

Back in typewriter days, people were taught to leave two spaces
after a full stop, because on monospace output it was easier to read
that way.  Then the desktop publishing software came and people were
encouraged to leave the appearance up to the software.

So to old timers who have already been trained to type two spaces
after a sentence, it takes more effort not to type the space bar
twice.

But as I said already, I personally feel that the consistency
guidelines around this area should be:

 (1) it would be nice if a new document does not use mixed style, but

 (2) it is not worth the patch noise only to "fix" them one way or
     the other.

Here "patch noise" does not primarily mean the effort a producer of
such a patch spends making sure what they did is correct.  The cost
of making sure unrelated mistakes do not slip into the codebase and
documentation without being noticed is much higher for such a patch
that ought to be a mechanical conversion.

Thanks.

Linus Arver Sept. 26, 2023, 6:52 p.m. UTC | #7

Josh Soref <jsoref@gmail.com> writes:

> Junio C Hamano <gitster@pobox.com> wrote:
>> > * space before `(`
>>
>> If you mean by the above that we used to say
>>
>>         ... as described below(see linkgit:git-config[1]))
>>
>> and you added a SP before "(see", that is a definite improvement.  I
>> however didn't find an example of a line that lacks SP before '('
>> that got corrected to have a SP there.
>
> I'm pretty sure that's what I meant, but I can't find the change in my
> git reflog, and I'm not quite sure how I could have made that mistake.

I too would support this sort of fix (fixing a missing space before
`(`).

WRT 2-space vs 1-space, I am not sure we need this because this is a
stylistic issue. Same thing for the commas. I am much more in favor of
changes that would actually help users find the information they need
(e.g., fixing spelling mistakes so that users who type in the correct
spelling can get the expected documentation hits).

FWIW we already have some guidelines about what is acceptable for doc
patches in SubmittingPatches:

    We currently have a liberal mixture of US and UK English norms for
    spelling and grammar, which is somewhat unfortunate.  A huge patch that
    touches the files all over the place only to correct the inconsistency
    is not welcome, though.  Potential clashes with other changes that can
    result from such a patch are not worth it.  We prefer to gradually
    reconcile the inconsistencies in favor of US English, with small and
    easily digestible patches, as a side effect of doing some other real
    work in the vicinity (e.g. rewriting a paragraph for clarity, while
    turning en_UK spelling to en_US).  Obvious typographical fixes are much
    more welcomed ("teh -> "the"), preferably submitted as independent
    patches separate from other documentation changes.

and both the 2-space vs 1-space and comma changes seem to fall into the
"not welcome" category.

Josh Soref Sept. 26, 2023, 7:51 p.m. UTC | #8

Linus Arver wrote:
> FWIW we already have some guidelines about what is acceptable for doc
> patches in SubmittingPatches:
>
>     We currently have a liberal mixture of US and UK English norms for
>     spelling and grammar, which is somewhat unfortunate.  A huge patch that
>     touches the files all over the place only to correct the inconsistency
>     is not welcome, though.  Potential clashes with other changes that can
>     result from such a patch are not worth it.  We prefer to gradually
>     reconcile the inconsistencies in favor of US English, with small and
>     easily digestible patches, as a side effect of doing some other real
>     work in the vicinity (e.g. rewriting a paragraph for clarity, while
>     turning en_UK spelling to en_US).  Obvious typographical fixes are much
>     more welcomed ("teh -> "the"), preferably submitted as independent
>     patches separate from other documentation changes.
>
> and both the 2-space vs 1-space and comma changes seem to fall into the
> "not welcome" category.

Ok, then, I think at this point I'll abandon this PR.

I could probably find the time to justify rewriting one paragraph in
this single file to try to abide by the requirements, but it doesn't
seem worth it. I'm sorry I wasted everyone's time.

Linus Arver Sept. 26, 2023, 9:20 p.m. UTC | #9

Josh Soref <jsoref@gmail.com> writes:

> Linus Arver wrote:
>> FWIW we already have some guidelines about what is acceptable for doc
>> patches in SubmittingPatches:
>>
>>     We currently have a liberal mixture of US and UK English norms for
>>     spelling and grammar, which is somewhat unfortunate.  A huge patch that
>>     touches the files all over the place only to correct the inconsistency
>>     is not welcome, though.  Potential clashes with other changes that can
>>     result from such a patch are not worth it.  We prefer to gradually
>>     reconcile the inconsistencies in favor of US English, with small and
>>     easily digestible patches, as a side effect of doing some other real
>>     work in the vicinity (e.g. rewriting a paragraph for clarity, while
>>     turning en_UK spelling to en_US).  Obvious typographical fixes are much
>>     more welcomed ("teh -> "the"), preferably submitted as independent
>>     patches separate from other documentation changes.
>>
>> and both the 2-space vs 1-space and comma changes seem to fall into the
>> "not welcome" category.
>
> Ok, then, I think at this point I'll abandon this PR.
>
> I could probably find the time to justify rewriting one paragraph in
> this single file to try to abide by the requirements, but it doesn't
> seem worth it.

The change to make a paragraph read better (fixes to awkward wording,
for example) are very much appreciated and would be good as a follow-up
patch in its own right.

> I'm sorry I wasted everyone's time.

Please don't let this experience deter you from considering future
contributions to our documentation. Thanks.

pretty-formats.txt: fix whitespace

Commit Message

Comments

Patch