threads / patch / 46852

patchdoc: correct command formatting

Subject: [PATCH] doc: correct command formatting

## tl;dr

8 messages between Sep 28, 2017 and Sep 29, 2017. Diffs are folded; open one to read it.

replies: 7people: 4as markdown or json

Adam Dinwoodie· Sep 28, 2017, 14:06 UTC · lore

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(-)
Show changes to Documentation/git.txt +1 −1
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
Andreas Heiduk· Sep 28, 2017, 17:18 UTC · re: Adam Dinwoodie · lore

Re: [PATCH] doc: correct command formatting

Am 28.09.2017 um 16:06 schrieb Adam Dinwoodie:
Show 23 quoted lines
> 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.
Jonathan Nieder· Sep 28, 2017, 19:34 UTC · re: Andreas Heiduk · lore

Re: [PATCH] doc: correct command formatting

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.)

Show 12 quoted lines
> 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
Andreas Heiduk· Sep 28, 2017, 22:28 UTC · re: Jonathan Nieder · lore

Re: [PATCH] doc: correct command formatting

Am 28.09.2017 um 21:34 schrieb Jonathan Nieder:
Show 6 quoted lines
> 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.

Show 7 quoted lines
>>
>> 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.
...
Show 9 quoted lines
> 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.

Show 8 quoted lines
> 
> ?
> 
> Thanks,
> Jonathan
> 
> [1] https://kernel.googlesource.com/pub/scm/linux/kernel/git/torvalds/linux/+/9cd6681cb1169e815c41af0265165dd1b872f228/Documentation/process/submitting-patches.rst#563
>
Junio C Hamano· Sep 29, 2017, 01:53 UTC · re: Jonathan Nieder · lore

Re: [PATCH] doc: correct command formatting

Jonathan Nieder <jrnieder@gmail.com> writes:
Show 6 quoted lines
> 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?

Jonathan Nieder· Sep 29, 2017, 03:27 UTC · re: Junio C Hamano · lore

Re: [PATCH] doc: correct command formatting

Junio C Hamano wrote:
> Jonathan Nieder <jrnieder@gmail.com> writes:
>> Andreas Heiduk wrote:
Show 7 quoted lines
>>> +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

Junio C Hamano· Sep 29, 2017, 04:07 UTC · re: Jonathan Nieder · lore

Re: [PATCH] doc: correct command formatting

Jonathan Nieder <jrnieder@gmail.com> writes:
Show 8 quoted lines
> 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.
Jonathan Nieder· Sep 28, 2017, 19:03 UTC · re: Adam Dinwoodie · lore

Re: [PATCH] doc: correct command formatting

Adam Dinwoodie wrote:
Show 8 quoted lines
> 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>

← back to recent threads