[PATCH] doc: correct command formatting

[PATCH] doc: correct command formatting

[Adam Dinwoodie]

Leaving spaces around the `-delimeters for commands means asciidoc fails
to parse them as the start of a literal string.  Remove an extraneous
space that is causing a literal to not be formatted as such.

Signed-off-by: Adam Dinwoodie <adam@dinwoodie.org>
---
 Documentation/git.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/git.txt b/Documentation/git.txt
index 6e3a6767e..98b9b46b9 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -75,7 +75,7 @@ example the following invocations are equivalent:
 Note that omitting the `=` in `git -c foo.bar ...` is allowed and sets
 `foo.bar` to the boolean true value (just like `[foo]bar` would in a
 config file). Including the equals but with an empty value (like `git -c
-foo.bar= ...`) sets `foo.bar` to the empty string which ` git config
+foo.bar= ...`) sets `foo.bar` to the empty string which `git config
 --bool` will convert to `false`.
 
 --exec-path[=<path>]::
-- 
2.14.1

Re: [PATCH] doc: correct command formatting

[Andreas Heiduk]

Am 28.09.2017 um 16:06 schrieb Adam Dinwoodie:
> Leaving spaces around the `-delimeters for commands means asciidoc fails
> to parse them as the start of a literal string.  Remove an extraneous
> space that is causing a literal to not be formatted as such.
> 
> Signed-off-by: Adam Dinwoodie <adam@dinwoodie.org>
> ---
>  Documentation/git.txt | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/Documentation/git.txt b/Documentation/git.txt
> index 6e3a6767e..98b9b46b9 100644
> --- a/Documentation/git.txt
> +++ b/Documentation/git.txt
> @@ -75,7 +75,7 @@ example the following invocations are equivalent:
>  Note that omitting the `=` in `git -c foo.bar ...` is allowed and sets
>  `foo.bar` to the boolean true value (just like `[foo]bar` would in a
>  config file). Including the equals but with an empty value (like `git -c
> -foo.bar= ...`) sets `foo.bar` to the empty string which ` git config
> +foo.bar= ...`) sets `foo.bar` to the empty string which `git config
>  --bool` will convert to `false`.
>  
>  --exec-path[=<path>]::
> 

+1, Thanks for spotting.

I did a quick

	grep -r " ` "

which came up with with another relevant place:

Documentation/git-format-patch.txt:	`--subject-prefix` option) has ` v<n>` appended to it.  E.g.

But here the space IS relevant but asciidoc does not pick up
the formatting. Perhaps that one could read like this:


	`--subject-prefix` option) has `<SPACE>v<n>` appended to it.  E.g.

Re: [PATCH] doc: correct command formatting

[Jonathan Nieder]

Adam Dinwoodie wrote:

> Leaving spaces around the `-delimeters for commands means asciidoc fails
> to parse them as the start of a literal string.  Remove an extraneous
> space that is causing a literal to not be formatted as such.
>
> Signed-off-by: Adam Dinwoodie <adam@dinwoodie.org>
> ---
>  Documentation/git.txt | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)

Good catch.

Reviewed-by: Jonathan Nieder <jrnieder@gmail.com>

Re: [PATCH] doc: correct command formatting

[Jonathan Nieder]

Hi,

Andreas Heiduk wrote:

> +1, Thanks for spotting.

Thanks for looking it over.  Can we add your Reviewed-by?  (See [1]
for what this means.)

> I did a quick
>
> 	grep -r " ` "
>
> which came up with with another relevant place:
>
> Documentation/git-format-patch.txt:	`--subject-prefix` option) has ` v<n>` appended to it.  E.g.
>
> But here the space IS relevant but asciidoc does not pick up
> the formatting. Perhaps that one could read like this:
>
> 	`--subject-prefix` option) has `<SPACE>v<n>` appended to it.  E.g.

Interesting.  This comes from

  commit 4aad08e061df699b49e24c4d34698d734473fb66
  Author: Junio C Hamano <gitster@pobox.com>
  Date:   Wed Jan 2 14:16:07 2013 -0800

      format-patch: document and test --reroll-count

In some output formats, the text with backticks surrounding it is
shown in a different background color, which makes something like
`{space}v<n>` tempting (with appropriate definition of {space} in
the attributes section of asciidoc.conf).  But that feels way too
subtle.

How about something like

	has a space and `v<n>` appended to it

?

Thanks,
Jonathan

[1] https://kernel.googlesource.com/pub/scm/linux/kernel/git/torvalds/linux/+/9cd6681cb1169e815c41af0265165dd1b872f228/Documentation/process/submitting-patches.rst#563

Re: [PATCH] doc: correct command formatting

[Andreas Heiduk]

Am 28.09.2017 um 21:34 schrieb Jonathan Nieder:
> Andreas Heiduk wrote:
> 
>> +1, Thanks for spotting.
> 
> Thanks for looking it over.  Can we add your Reviewed-by?  (See [1]
> for what this means.)

Well, I'd like to see the following occurrence of the same problem
solved in that patch, too. Beyond that - your welcome.

>>
>> Documentation/git-format-patch.txt:	`--subject-prefix` option) has ` v<n>` appended to it.  E.g.
>>
>> But here the space IS relevant but asciidoc does not pick up
>> the formatting. Perhaps that one could read like this:
>>
>> 	`--subject-prefix` option) has `<SPACE>v<n>` appended to it.  E.g.

...

> In some output formats, the text with backticks surrounding it is
> shown in a different background color, which makes something like
> `{space}v<n>` tempting (with appropriate definition of {space} in
> the attributes section of asciidoc.conf).  But that feels way too
> subtle.
> 
> How about something like
> 
> 	has a space and `v<n>` appended to it

Well, in the original text "<n>" is already used as a replacement
marker. Therefore "<space>" seemed obvious to me as another replacement
marker which avoids exactly that problem.

> 
> ?
> 
> Thanks,
> Jonathan
> 
> [1] https://kernel.googlesource.com/pub/scm/linux/kernel/git/torvalds/linux/+/9cd6681cb1169e815c41af0265165dd1b872f228/Documentation/process/submitting-patches.rst#563
> 

Re: [PATCH] doc: correct command formatting

[Junio C Hamano]

Jonathan Nieder <jrnieder@gmail.com> writes:

> Andreas Heiduk wrote:
>
>> +1, Thanks for spotting.
>
> Thanks for looking it over.  Can we add your Reviewed-by?  (See [1]
> for what this means.)

I would just do "Acked-by: Andreas" after seeing such an obvious
admission of guilt & appreciation for fixing in the exchange.  

Would we rather want to make it more formal like how Linux folks do
the Reviewed-by: thing?

Re: [PATCH] doc: correct command formatting

[Jonathan Nieder]

Junio C Hamano wrote:
> Jonathan Nieder <jrnieder@gmail.com> writes:
>> Andreas Heiduk wrote:

>>> +1, Thanks for spotting.
>>
>> Thanks for looking it over.  Can we add your Reviewed-by?  (See [1]
>> for what this means.)
>
> I would just do "Acked-by: Andreas" after seeing such an obvious
> admission of guilt & appreciation for fixing in the exchange.

Oh!  I had missed that context.

Your instinct would have been right (and is born out by Andreas's
reply to me).

I was just fishing, but in this context there was no reason to fish
for more than the Ack that was already there.

> Would we rather want to make it more formal like how Linux folks do
> the Reviewed-by: thing?

Separate from this example: yes, I think adopting Linux's Reviewed-by
convention would be a good thing.  When I see a positive reply to a
patch, I often wonder whether an ack or a fuller reviewed-by is
intended, and Linux's way of formalizing that appeals to me.

I'll try sending a patch to add it to SubmittingPatches tomorrow
morning (Stefan had also been hinting recently about this being
something worth trying).

Thank you,
Jonathan

Re: [PATCH] doc: correct command formatting

[Junio C Hamano]

Jonathan Nieder <jrnieder@gmail.com> writes:

> Separate from this example: yes, I think adopting Linux's Reviewed-by
> convention would be a good thing.  When I see a positive reply to a
> patch, I often wonder whether an ack or a fuller reviewed-by is
> intended, and Linux's way of formalizing that appeals to me.
>
> I'll try sending a patch to add it to SubmittingPatches tomorrow
> morning (Stefan had also been hinting recently about this being
> something worth trying).

Thanks.  

I agree with the goal of educating list participants not to throw
Reviewed-by: without reading the patches too carelessly.  As akpm
once said in <20121003143200.69a50aad.akpm@linux-foundation.org>,
"Looks ok to me from a quick look" is not a review.

    > > No, lib/lzo has no identifiable maintainer.  I suggest you proceed as
    > > follows:
    > > 
    > > - Post the entire patch series to lkml for review (I'd like a cc please)
    > 
    > Already happened, multiple people reviewed and tested.

    um, I would not consider "Looks ok to me from a quick look." and "I
    couldn't tell from the github view, but I assume you follow standard
    coding style." to indicate a rigorous code review!

    That's the problem with the git presentation: hardly anyone reads the
    patches and there is no patch for a reviewer to reply to.

    So please send the patches out for review.  One at a time, via email.