[PATCH] Documentation/git-config.txt: reword missleading sentence

[PATCH] Documentation/git-config.txt: reword missleading sentence

[PAYRE NATHAN p1508475]

Change the word "bla" to "section.variable" to make it clear that it's a placeholder for a variable name.

See discussion at: https://public-inbox.org/git/20171002061303.Horde.SL92grZCqTRV9oQkBFPELQ7@crashcourse.ca/

Noticed-by: rpjday@crashcourse.ca
---
 Documentation/git-config.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt
index 83f86b923..f9808d7ad 100644
--- a/Documentation/git-config.txt
+++ b/Documentation/git-config.txt
@@ -177,8 +177,8 @@ See also <<FILES>>.
 	'git-config' will expand leading '{tilde}' to the value of
 	'$HOME', and '{tilde}user' to the home directory for the
 	specified user.  This option has no effect when setting the
-	value (but you can use 'git config bla {tilde}/' from the
-	command line to let your shell do the expansion).
+	value (but you can use 'git config section.variable {tilde}/'
+	from the command line to let your shell do the expansion).
 
 -z::
 --null::
-- 
2.14.2

Re: [PATCH] Documentation/git-config.txt: reword missleading sentence

[Junio C Hamano]

On Thu, Oct 5, 2017 at 5:17 PM, PAYRE NATHAN p1508475
<second.payre@gmail.com> wrote:
> Change the word "bla" to "section.variable" to make it clear that it's a placeholder for a variable name.

Please make sure that your log message shows without wrapping and is a
confortable read on a 80-column terminal by wrapping long lines.

>
> See discussion at: https://public-inbox.org/git/20171002061303.Horde.SL92grZCqTRV9oQkBFPELQ7@crashcourse.ca/

I do not think it matters that much in this particular case, but please
make it a habit to assume that time of people who run "git log" to
find out why the change was done is 100x more valuable than the
time you need to leave a good summary of the discussion in the
log message. A URL at the end _in addition to_ a summary in your
words is OK; just a URL without any effort to summarize why you
did this change is not.

I often find myself understanding the issues a lot better _only_
after I try to summarize the argument for a change in the log
message--it forces me to _think_. And (this probably does not
apply to this patch, as it is not a code change) it often results
in a better code. First I come up with a solution, write a quick
patch, try to explain the approach in the log message and then
realize there is a better solution _only_ after doing so. It is a
good habit to get into to try explaining the thought process in
the log message.

> Noticed-by: rpjday@crashcourse.ca
> ---

Here, after "Reported-by:" before the three-dash line, we need
your "Signed-off-by:" line. See Documentation/SubmittingPatches
for details. The name and address should match what appears
on the "From:" field from your e-mail.

Ah, one more thing. Do you want to be known as somebody
with ALL CAPS first and last name, with student number? ;-)
If it is cumbersome to convince your MUA to use your real
name spelled in normal way on the "From:" header, you could
start the body of your message with

    From: Payre Nathan <second.payre@gmail.com>

followed by an empty line, followed by the body of the log
message.


>  Documentation/git-config.txt | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt
> index 83f86b923..f9808d7ad 100644
> --- a/Documentation/git-config.txt
> +++ b/Documentation/git-config.txt
> @@ -177,8 +177,8 @@ See also <<FILES>>.
>         'git-config' will expand leading '{tilde}' to the value of
>         '$HOME', and '{tilde}user' to the home directory for the
>         specified user.  This option has no effect when setting the
> -       value (but you can use 'git config bla {tilde}/' from the
> -       command line to let your shell do the expansion).
> +       value (but you can use 'git config section.variable {tilde}/'
> +       from the command line to let your shell do the expansion).
>

The new text proposed by the patch looks good.

Note that I am not in front of a real computer, and I cannot
verify if there is a whitespace breakage in the patch to make
it unusable. I am guessing this one is OK (it seems there
is only one SP followed by HT on the context lines).

Thanks, and welcome to Git development community.

Re: [PATCH] Documentation/git-config.txt: reword missleading sentence

[Nathan PAYRE]

Hi,

Thanks you for the this complete answer,
we take note of your comments.

We would like to reword something else in the same line
and we don't know what is the best way to do that properly.
Should we do a [PATCH v2] or revert the last commit and
commit a new one?

2017-10-05 12:13 GMT+02:00 Junio C Hamano <gitster@pobox.com>:
> On Thu, Oct 5, 2017 at 5:17 PM, PAYRE NATHAN p1508475
> <second.payre@gmail.com> wrote:
>> Change the word "bla" to "section.variable" to make it clear that it's a placeholder for a variable name.
>
> Please make sure that your log message shows without wrapping and is a
> confortable read on a 80-column terminal by wrapping long lines.
>
>>
>> See discussion at: https://public-inbox.org/git/20171002061303.Horde.SL92grZCqTRV9oQkBFPELQ7@crashcourse.ca/
>
> I do not think it matters that much in this particular case, but please
> make it a habit to assume that time of people who run "git log" to
> find out why the change was done is 100x more valuable than the
> time you need to leave a good summary of the discussion in the
> log message. A URL at the end _in addition to_ a summary in your
> words is OK; just a URL without any effort to summarize why you
> did this change is not.
>
> I often find myself understanding the issues a lot better _only_
> after I try to summarize the argument for a change in the log
> message--it forces me to _think_. And (this probably does not
> apply to this patch, as it is not a code change) it often results
> in a better code. First I come up with a solution, write a quick
> patch, try to explain the approach in the log message and then
> realize there is a better solution _only_ after doing so. It is a
> good habit to get into to try explaining the thought process in
> the log message.
>
>> Noticed-by: rpjday@crashcourse.ca
>> ---
>
> Here, after "Reported-by:" before the three-dash line, we need
> your "Signed-off-by:" line. See Documentation/SubmittingPatches
> for details. The name and address should match what appears
> on the "From:" field from your e-mail.
>
> Ah, one more thing. Do you want to be known as somebody
> with ALL CAPS first and last name, with student number? ;-)
> If it is cumbersome to convince your MUA to use your real
> name spelled in normal way on the "From:" header, you could
> start the body of your message with
>
>     From: Payre Nathan <second.payre@gmail.com>
>
> followed by an empty line, followed by the body of the log
> message.
>
>
>>  Documentation/git-config.txt | 4 ++--
>>  1 file changed, 2 insertions(+), 2 deletions(-)
>>
>> diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt
>> index 83f86b923..f9808d7ad 100644
>> --- a/Documentation/git-config.txt
>> +++ b/Documentation/git-config.txt
>> @@ -177,8 +177,8 @@ See also <<FILES>>.
>>         'git-config' will expand leading '{tilde}' to the value of
>>         '$HOME', and '{tilde}user' to the home directory for the
>>         specified user.  This option has no effect when setting the
>> -       value (but you can use 'git config bla {tilde}/' from the
>> -       command line to let your shell do the expansion).
>> +       value (but you can use 'git config section.variable {tilde}/'
>> +       from the command line to let your shell do the expansion).
>>
>
> The new text proposed by the patch looks good.
>
> Note that I am not in front of a real computer, and I cannot
> verify if there is a whitespace breakage in the patch to make
> it unusable. I am guessing this one is OK (it seems there
> is only one SP followed by HT on the context lines).
>
> Thanks, and welcome to Git development community.

Re: [PATCH] Documentation/git-config.txt: reword missleading sentence

[Junio C Hamano]

Nathan PAYRE <second.payre@gmail.com> writes:

> Thanks you for the this complete answer,
> we take note of your comments.
>
> We would like to reword something else in the same line
> and we don't know what is the best way to do that properly.
> Should we do a [PATCH v2] or revert the last commit and
> commit a new one?

I'd imagine that it is in the same spirit of the old one
(i.e. "let's make it less confusing"), so let's have a single patch
that has both changes which is [PATCH v2].

Thanks.

[PATCH v2] Documentation/git-config.txt: reword missleading sentence

[second.payre]

From: PAYRE NATHAN p1508475 <nathan.payre@etu.univ-lyon1.fr>

Change the word "bla" to "section.variable", "bla" is a placeholder
for a variable name and it wasn't clear for everyone.
This change clarify it.

Change the appearance of 'git config section.variable {tilde}/' to
`git config section.variable {tilde}/` to harmonize it with
the rest of the file, this is a command line then the "`" are
necessary.

Replace "git-config" by "git config" because the command
is not "git-config".

See discussion at:
https://public-inbox.org/git/20171002061303.Horde.SL92grZCqTRV9oQkBFPELQ7@crashcourse.ca/

Signed-off-by: MOY Matthieu <matthieu.moy@univ-lyon1.fr>
Signed-off-by: Daniel Bensoussan <daniel.bensoussan--bohm@etu.univ-lyon1.fr>
Signed-off-by: Timothee Albertin <timothee.albertin@etu.univ-lyon1.fr>
Signed-off-by: Nathan Payre <second.payre@gmail.com>
Noticed-by: rpjday@crashcourse.ca
---
 Documentation/git-config.txt | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt
index 83f86b923..2ab9e4c56 100644
--- a/Documentation/git-config.txt
+++ b/Documentation/git-config.txt
@@ -174,11 +174,11 @@ See also <<FILES>>.
 	either --bool or --int, as described above.
 
 --path::
-	'git-config' will expand leading '{tilde}' to the value of
+	'git config' will expand leading '{tilde}' to the value of
 	'$HOME', and '{tilde}user' to the home directory for the
 	specified user.  This option has no effect when setting the
-	value (but you can use 'git config bla {tilde}/' from the
-	command line to let your shell do the expansion).
+	value (but you can use `git config section.variable {tilde}/`
+	from the command line to let your shell do the expansion).
 
 -z::
 --null::
-- 
2.14.2

Re: [PATCH v2] Documentation/git-config.txt: reword missleading sentence

[Junio C Hamano]

second.payre@gmail.com writes:

> From: PAYRE NATHAN p1508475 <nathan.payre@etu.univ-lyon1.fr>

Should I assume that the name/address on the last Signed-off-by: we
see below is what you want to be known as?  As a part of school
work, I'd imagine that Matthieu wants your work to be associated
with the univ-lyon1.fr address, so perhaps you want to go the other
way around?  It's not my place to decide between the two, but it is
unusual to see that the name/address of the author (which is the
above line) does not match what is on the Signed-off-by: line.

> Change the word "bla" to "section.variable", "bla" is a placeholder
> for a variable name and it wasn't clear for everyone.
> This change clarify it.
>
> Change the appearance of 'git config section.variable {tilde}/' to
> `git config section.variable {tilde}/` to harmonize it with
> the rest of the file, this is a command line then the "`" are
> necessary.
>
> Replace "git-config" by "git config" because the command
> is not "git-config".
>
> See discussion at:
> https://public-inbox.org/git/20171002061303.Horde.SL92grZCqTRV9oQkBFPELQ7@crashcourse.ca/
>
> Signed-off-by: MOY Matthieu <matthieu.moy@univ-lyon1.fr>
> Signed-off-by: Daniel Bensoussan <daniel.bensoussan--bohm@etu.univ-lyon1.fr>
> Signed-off-by: Timothee Albertin <timothee.albertin@etu.univ-lyon1.fr>
> Signed-off-by: Nathan Payre <second.payre@gmail.com>
> Noticed-by: rpjday@crashcourse.ca
> ---
>  Documentation/git-config.txt | 6 +++---
>  1 file changed, 3 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt
> index 83f86b923..2ab9e4c56 100644
> --- a/Documentation/git-config.txt
> +++ b/Documentation/git-config.txt
> @@ -174,11 +174,11 @@ See also <<FILES>>.
>  	either --bool or --int, as described above.
>  
>  --path::
> -	'git-config' will expand leading '{tilde}' to the value of
> +	'git config' will expand leading '{tilde}' to the value of
>  	'$HOME', and '{tilde}user' to the home directory for the
>  	specified user.  This option has no effect when setting the
> -	value (but you can use 'git config bla {tilde}/' from the
> -	command line to let your shell do the expansion).
> +	value (but you can use `git config section.variable {tilde}/`

Does this reference to {tilde} get expanded inside the `literal`
mark-up?  In the description for 'gitdir', we find this passage (in
Documentation/config.txt):

     * If the pattern starts with `~/`, `~` will be substituted with the
       content of the environment variable `HOME`.

So I'd expect `~` to be a safe way to get what you want, not `{tilde}`.

> +	from the command line to let your shell do the expansion).
>  
>  -z::
>  --null::

Re: [PATCH v2] Documentation/git-config.txt: reword missleading sentence

[Moy Matthieu]

Junio C Hamano <gitster@pobox.com> writes:

> second.payre@gmail.com writes:
>
>> From: PAYRE NATHAN p1508475 <nathan.payre@etu.univ-lyon1.fr>
>
> Should I assume that the name/address on the last Signed-off-by: we
> see below is what you want to be known as?  As a part of school
> work, I'd imagine that Matthieu wants your work to be associated
> with the univ-lyon1.fr address, so perhaps you want to go the other
> way around?

Yes, I'd rather have contributions made with the identity
@etu.univ-lyon1.fr, and use the same identity for Signed-off-by: and
From:.

>>  --path::
>> -	'git-config' will expand leading '{tilde}' to the value of
>> +	'git config' will expand leading '{tilde}' to the value of
>>  	'$HOME', and '{tilde}user' to the home directory for the

Didn't notice yesterday, but you still have forward quotes here and
backquotes right below. If you are to fix this paragraph, better fix all
issues at once.

>>  	specified user.  This option has no effect when setting the
>> -	value (but you can use 'git config bla {tilde}/' from the
>> -	command line to let your shell do the expansion).
>> +	value (but you can use `git config section.variable {tilde}/`
>
> Does this reference to {tilde} get expanded inside the `literal`
> mark-up?  In the description for 'gitdir', we find this passage (in
> Documentation/config.txt):
>
>      * If the pattern starts with `~/`, `~` will be substituted with the
>        content of the environment variable `HOME`.
>
> So I'd expect `~` to be a safe way to get what you want, not `{tilde}`.

If I read correctly, the potential issue with ~ is that it's used for
subscript text (i.e. foo~bar~ in asciidoc is LaTeX's $foo_{bar}$). But ~
within a literal string should be safe, and at least we use it in many
places in our doc.

Cheers,

-- 
Matthieu Moy
https://matthieu-moy.fr/

Re: [PATCH v2] Documentation/git-config.txt: reword missleading sentence

[Junio C Hamano]

Moy Matthieu <Matthieu.Moy@univ-lyon1.fr> writes:

>>>  --path::
>>> -	'git-config' will expand leading '{tilde}' to the value of
>>> +	'git config' will expand leading '{tilde}' to the value of
>>>  	'$HOME', and '{tilde}user' to the home directory for the
>
> Didn't notice yesterday, but you still have forward quotes here and
> backquotes right below. If you are to fix this paragraph, better fix all
> issues at once.

When we say ~user in this sentence, unlike $HOME, it is not
something the user would type literally; 'user' in that is a
placeholder to be replaced with a value appropriate in the real
life, e.g. ~moy.  So '{tilde}user' may actually be OK, even though I
agree that `$HOME` may be more correct.

>>>  	specified user.  This option has no effect when setting the
>>> -	value (but you can use 'git config bla {tilde}/' from the
>>> -	command line to let your shell do the expansion).
>>> +	value (but you can use `git config section.variable {tilde}/`
>>
>> Does this reference to {tilde} get expanded inside the `literal`
>> mark-up?  ...
>
> If I read correctly, the potential issue with ~ is that it's used for
> subscript text (i.e. foo~bar~ in asciidoc is LaTeX's $foo_{bar}$). But ~
> within a literal string should be safe, and at least we use it in many
> places in our doc.

My comment was not about "safety" but about correctness.  At least
for me, `{tilde}user` does not expand to ~user, but instead spell
out open-brace, tee, eye, ..., close-brace, followed by "user",
which is not what we want.

[PATCH v3] Documentation/git-config.txt: reword missleading sentence

[PAYRE NATHAN p1508475]

Change the word "bla" to "section.variable", "bla" is a placeholder
for a variable name and it wasn't clear for everyone.  This change
clarify it.

Change the appearance of 'git config section.variable {tilde}/' to
`git config section.variable ~/` to harmonize it with the rest of the
file, this is a command line then the "`" are necessary.

Replace "git-config" by "git config" because the command is not
"git-config".

See discussion at:
https://public-inbox.org/git/20171002061303.Horde.SL92grZCqTRV9oQkBFPELQ7@crashcourse.ca/

Signed-off-by: MOY Matthieu <matthieu.moy@univ-lyon1.fr>
Signed-off-by: Daniel Bensoussan <daniel.bensoussan--bohm@etu.univ-lyon1.fr>
Signed-off-by: Timothee Albertin <timothee.albertin@etu.univ-lyon1.fr>
Signed-off-by: Nathan Payre <nathan.payre@etu.univ-lyon1.fr>
Noticed-by: rpjday@crashcourse.ca
---

Change since v2: use ~ within backquote instead of {tilde}.
Backquoting of 'git config', '~', '$HOME' and '~user' for more
coherence.

Documentation/git-config.txt | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt
index 83f86b923..9b5c3a436 100644
--- a/Documentation/git-config.txt
+++ b/Documentation/git-config.txt
@@ -174,11 +174,11 @@ See also <<FILES>>.
 	either --bool or --int, as described above.
 
 --path::
-	'git-config' will expand leading '{tilde}' to the value of
-	'$HOME', and '{tilde}user' to the home directory for the
+	`git config` will expand leading `~` to the value of
+	`$HOME`, and `~user` to the home directory for the
 	specified user.  This option has no effect when setting the
-	value (but you can use 'git config bla {tilde}/' from the
-	command line to let your shell do the expansion).
+	value (but you can use `git config section.variable ~/`
+	from the command line to let your shell do the expansion).
 
 -z::
 --null::
-- 
2.14.2

Re: [PATCH v3] Documentation/git-config.txt: reword missleading sentence

[Jonathan Nieder]

Hi Nathan et al,

PAYRE NATHAN p1508475 wrote:

> From: PAYRE NATHAN p1508475 <second.payre@gmail.com>

nit: this 'From' line doesn't match any of the authors with sign-offs
below.  I'm wondering if the authorship of the commit (from "git
commit --author" or git's "user.name" / "user.email" settings) made it
through in the email.

If you pass --from='PAYRE NATHAN p1508475 <second.payre@gmail.com>' to
"git format-patch", then it will send email from that address and add
an in-body "From:" line to the message it produces based on the author
field of the git commits.  This can be useful for sending patches that
someone else wrote.  This way, the authorship of the commit gets
through, to be used by "git am".

See https://public-inbox.org/git/20170922203017.53986-7-git@jeffhostetler.com/
for an example of how that works.

> Subject: Documentation/git-config.txt: reword missleading sentence

more nits:

- this subject line can use a more concise name for the subsystem,
  like "config doc"

- there's one too many esses in missleading

- more importantly, this is a good place to provide a summary of what
  change the patch makes, so people reading the shortlog in Git
  release announcements know what changed. Maybe something like
  "use a clearer placeholder in example"?

That would mean something like

	config doc: use a clearer placeholder in example

Or, to capture the other changes being made at the same time:

	config doc: clarify "git config --path" example

Thanks for working on this.

> Change the word "bla" to "section.variable", "bla" is a placeholder
> for a variable name and it wasn't clear for everyone.  This change
> clarify it.

The "," should be a semicolon or period, since it separates two
independent clauses.

I think the "This change clarify it" sentence can go away.  The first
sentence already explains that this is for clarity.

> Change the appearance of 'git config section.variable {tilde}/' to
> `git config section.variable ~/` to harmonize it with the rest of the
> file, this is a command line then the "`" are necessary.

I had to read this sentence a few times to understand it. Maybe:

	While we're here, also reformat this sample command line to use
	monospace instead of italics, to better match the rest of the file.

> Replace "git-config" by "git config" because the command is not
> "git-config".

My first reaction to that is, "But the manpage is git-config(1)!"
To avoid that reaction, it can say

	Use a space instead of a dash in "git config", as is common in the
	rest of Git's documentation.

By the way, should the initial `git config` be 'git config' (in
italics instead of monospace)?  I don't see `git config` anywhere else
in the file and there are a lot of instances of 'git config'.

> See discussion at:
> https://public-inbox.org/git/20171002061303.Horde.SL92grZCqTRV9oQkBFPELQ7@crashcourse.ca/

The commit message is meant to be (and is, I think!) self-contained, so
this link shouldn't be needed for people running into this change in
"git log".  I'd leave it out.

> Signed-off-by: MOY Matthieu <matthieu.moy@univ-lyon1.fr>
> Signed-off-by: Daniel Bensoussan <daniel.bensoussan--bohm@etu.univ-lyon1.fr>
> Signed-off-by: Timothee Albertin <timothee.albertin@etu.univ-lyon1.fr>
> Signed-off-by: Nathan Payre <nathan.payre@etu.univ-lyon1.fr>
> Noticed-by: rpjday@crashcourse.ca

optional:

Reported-by: Robert P. J. Day <rpjday@crashcourse.ca>

This can go before the sign-offs to reflect the chronology.

[...]
> --- a/Documentation/git-config.txt
> +++ b/Documentation/git-config.txt
> @@ -174,11 +174,11 @@ See also <<FILES>>.
>  	either --bool or --int, as described above.
>  
>  --path::
> -	'git-config' will expand leading '{tilde}' to the value of
> +	`git config` will expand leading `~` to the value of

not about this patch: the article "a" is missing before "leading `~`":

	'git config' will expand a leading `~` to the value of ...

> -	'$HOME', and '{tilde}user' to the home directory for the
> +	`$HOME`, and `~user` to the home directory for the
>  	specified user.  This option has no effect when setting the
> -	value (but you can use 'git config bla {tilde}/' from the
> -	command line to let your shell do the expansion).
> +	value (but you can use `git config section.variable ~/`
> +	from the command line to let your shell do the expansion).

I like it.

Thanks and hope that helps,
Jonathan

Re: [PATCH v3] Documentation/git-config.txt: reword missleading sentence

[Junio C Hamano]

Jonathan Nieder <jrnieder@gmail.com> writes:

> Or, to capture the other changes being made at the same time:
>
> 	config doc: clarify "git config --path" example
>
> Thanks for working on this.

Yup.  I'll queue with the above subject; all the suggestions in your
message were sensible, so I'll take them when I do so.

> By the way, should the initial `git config` be 'git config' (in
> italics instead of monospace)?  I don't see `git config` anywhere else
> in the file and there are a lot of instances of 'git config'.

We want to use monospace for something we expect users to type
verbatim while following the description along, and highlight
important terms that are being explained by typesetting in italics.
This one can go either way, so I'll keep it as posted.

Thanks.