threads / patch / 46078

patchdocs: fix literal quoted spaces

Subject: [PATCH] docs: fix literal quoted spaces

## tl;dr

8 messages between May 31, 2017 and Jun 2, 2017. Diffs are folded; open one to read it.

replies: 7people: 3as markdown or json

Adam Dinwoodie· May 31, 2017, 15:06 UTC · lore

When compiling the documentation, asciidoc thinks a backtick surrounded by whitespace shouldn't be interpreted as marking the start or end of a literal. In most cases, that's useful behaviour, but in the git-pull documentation the space is clearly intended to be part of the monospace formatted text.

Instead, use + to avoid asciidoc's literal passthrough, and encode the space as {sp}. In particular, this means asciidoc will correctly detect the end of the monospace formatting, rather than having it continue past the backtick.

Signed-off-by: Adam Dinwoodie <adam@dinwoodie.org>
---
 Documentation/git-pull.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
Show changes to Documentation/git-pull.txt +2 −2
diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt
index 942af8e0f..da31c5e40 100644
--- a/Documentation/git-pull.txt
+++ b/Documentation/git-pull.txt
@@ -159,7 +159,7 @@ present while on branch `<name>`, that value is used instead of
 
 In order to determine what URL to use to fetch from, the value
 of the configuration `remote.<origin>.url` is consulted
-and if there is not any such variable, the value on `URL: ` line
+and if there is not any such variable, the value on +URL:{sp}+ line
 in `$GIT_DIR/remotes/<origin>` file is used.
 
 In order to determine what remote branches to fetch (and
@@ -167,7 +167,7 @@ optionally store in the remote-tracking branches) when the command is
 run without any refspec parameters on the command line, values
 of the configuration variable `remote.<origin>.fetch` are
 consulted, and if there aren't any, `$GIT_DIR/remotes/<origin>`
-file is consulted and its `Pull: ` lines are used.
+file is consulted and its +Pull:{sp}+ lines are used.
 In addition to the refspec formats described in the OPTIONS
 section, you can have a globbing refspec that looks like this:
 

-- 
2.12.3
Jeff King· May 31, 2017, 16:07 UTC · re: Adam Dinwoodie · lore

Re: [PATCH] docs: fix literal quoted spaces

On Wed, May 31, 2017 at 04:06:24PM +0100, Adam Dinwoodie wrote:
Show 5 quoted lines
> When compiling the documentation, asciidoc thinks a backtick surrounded
> by whitespace shouldn't be interpreted as marking the start or end of a
> literal.  In most cases, that's useful behaviour, but in the git-pull
> documentation the space is clearly intended to be part of the monospace
> formatted text.
Good catch.
> Instead, use + to avoid asciidoc's literal passthrough, and encode the
> space as {sp}.  In particular, this means asciidoc will correctly detect
> the end of the monospace formatting, rather than having it continue past
> the backtick.

In these particular cases, is the space adding anything? Would a simpler fix be to just use:

  ...the value on `URL:` line

We've had such headaches with other entities like {sp} between different asciidoc versions (not to mention asciidoctor) that I tend to reach for the simplest solution.

(I'd also suggest the minor English correct of saying "_the_ URL line"; that's orthogonal to what you're trying to fix, but may make sense on top while we're here).

-Peff
Junio C Hamano· Jun 1, 2017, 02:06 UTC · re: Jeff King · lore

Re: [PATCH] docs: fix literal quoted spaces

Jeff King <peff@peff.net> writes:
Show 23 quoted lines
> On Wed, May 31, 2017 at 04:06:24PM +0100, Adam Dinwoodie wrote:
>
>> When compiling the documentation, asciidoc thinks a backtick surrounded
>> by whitespace shouldn't be interpreted as marking the start or end of a
>> literal.  In most cases, that's useful behaviour, but in the git-pull
>> documentation the space is clearly intended to be part of the monospace
>> formatted text.
>
> Good catch.
>
>> Instead, use + to avoid asciidoc's literal passthrough, and encode the
>> space as {sp}.  In particular, this means asciidoc will correctly detect
>> the end of the monospace formatting, rather than having it continue past
>> the backtick.
>
> In these particular cases, is the space adding anything? Would a simpler
> fix be to just use:
>
>   ...the value on `URL:` line
>
> We've had such headaches with other entities like {sp} between different
> asciidoc versions (not to mention asciidoctor) that I tend to reach for
> the simplest solution.

Me, too (and no, I am not from AOL). If `URL:` is typeset correctly the approach to drop the space is much more preferred.

Show 5 quoted lines
> (I'd also suggest the minor English correct of saying "_the_ URL line";
> that's orthogonal to what you're trying to fix, but may make sense on
> top while we're here).
>
> -Peff
Adam Dinwoodie· Jun 1, 2017, 09:55 UTC · re: Junio C Hamano · lore

Re: [PATCH] docs: fix literal quoted spaces

On Thu, Jun 01, 2017 at 11:06:18AM +0900, Junio C Hamano wrote:
Show 20 quoted lines
> Jeff King <peff@peff.net> writes:
> 
> > On Wed, May 31, 2017 at 04:06:24PM +0100, Adam Dinwoodie wrote:
> >
> >> Instead, use + to avoid asciidoc's literal passthrough, and encode the
> >> space as {sp}.  In particular, this means asciidoc will correctly detect
> >> the end of the monospace formatting, rather than having it continue past
> >> the backtick.
> >
> > In these particular cases, is the space adding anything? Would a simpler
> > fix be to just use:
> >
> >   ...the value on `URL:` line
> >
> > We've had such headaches with other entities like {sp} between different
> > asciidoc versions (not to mention asciidoctor) that I tend to reach for
> > the simplest solution.
> 
> Me, too (and no, I am not from AOL).  If `URL:` is typeset correctly
> the approach to drop the space is much more preferred.

I decided against that fix on the assumption that there was _some_ reason for including the space, even if I couldn't immediately see it. Given Junio wrote the original text and is now suggesting removing it, I'll respin the patch now.

> > (I'd also suggest the minor English correct of saying "_the_ URL line";
> > that's orthogonal to what you're trying to fix, but may make sense on
> > top while we're here).
Sure.  I'll include that in the follow up patch.
Adam Dinwoodie· Jun 1, 2017, 10:37 UTC · re: Adam Dinwoodie · lore

[PATCH v2] docs: fix formatting and grammar

When compiling the documentation, asciidoc thinks a backtick surrounded by whitespace shouldn't be interpreted as marking the start or end of a literal. In most cases, that's useful behaviour, but in the git-pull documentation it means asciidoc is failing to correctly detect which text should be monospaced and which shouldn't.

To avoid this, remove the extraneous spaces from the text to be monospaced. It would also be possible to fix the formatting by switching to asciidoc's ++ monospace format markers and still have the space characters included in the monospace text, but the spaces aren't necessary and not having them keeps the markup simpler.

Also include a minor grammar fix suggested by Jeff while we're changing these lines.

Signed-off-by: Adam Dinwoodie <adam@dinwoodie.org>
Helped-by: Jeff King <peff@peff.net>
---
 Documentation/git-pull.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
Show changes to Documentation/git-pull.txt +2 −2
diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt
index 942af8e0f..1d90dd17b 100644
--- a/Documentation/git-pull.txt
+++ b/Documentation/git-pull.txt
@@ -159,7 +159,7 @@ present while on branch `<name>`, that value is used instead of
 
 In order to determine what URL to use to fetch from, the value
 of the configuration `remote.<origin>.url` is consulted
-and if there is not any such variable, the value on `URL: ` line
+and if there is not any such variable, the value on the `URL:` line
 in `$GIT_DIR/remotes/<origin>` file is used.
 
 In order to determine what remote branches to fetch (and
@@ -167,7 +167,7 @@ optionally store in the remote-tracking branches) when the command is
 run without any refspec parameters on the command line, values
 of the configuration variable `remote.<origin>.fetch` are
 consulted, and if there aren't any, `$GIT_DIR/remotes/<origin>`
-file is consulted and its `Pull: ` lines are used.
+file is consulted and its `Pull:` lines are used.
 In addition to the refspec formats described in the OPTIONS
 section, you can have a globbing refspec that looks like this:
 

-- 
2.12.3
Jeff King· Jun 1, 2017, 15:53 UTC · re: Adam Dinwoodie · lore

Re: [PATCH v2] docs: fix formatting and grammar

On Thu, Jun 01, 2017 at 11:37:03AM +0100, Adam Dinwoodie wrote:
Show 20 quoted lines
> When compiling the documentation, asciidoc thinks a backtick surrounded
> by whitespace shouldn't be interpreted as marking the start or end of a
> literal.  In most cases, that's useful behaviour, but in the git-pull
> documentation it means asciidoc is failing to correctly detect which
> text should be monospaced and which shouldn't.
> 
> To avoid this, remove the extraneous spaces from the text to be
> monospaced.  It would also be possible to fix the formatting by
> switching to asciidoc's ++ monospace format markers and still have the
> space characters included in the monospace text, but the spaces aren't
> necessary and not having them keeps the markup simpler.
> 
> Also include a minor grammar fix suggested by Jeff while we're changing
> these lines.
> 
> Signed-off-by: Adam Dinwoodie <adam@dinwoodie.org>
> Helped-by: Jeff King <peff@peff.net>
> ---
>  Documentation/git-pull.txt | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
This looks fine, although...
Show 5 quoted lines
>  In order to determine what URL to use to fetch from, the value
>  of the configuration `remote.<origin>.url` is consulted
> -and if there is not any such variable, the value on `URL: ` line
> +and if there is not any such variable, the value on the `URL:` line
>  in `$GIT_DIR/remotes/<origin>` file is used.

...I should have read to the end of the sentence. It should also be "in the `$GIT_DIR/remotes/<origin>` file". Or just drop "file".

-Peff
Junio C Hamano· Jun 2, 2017, 01:45 UTC · re: Jeff King · lore

Re: [PATCH v2] docs: fix formatting and grammar

Jeff King <peff@peff.net> writes:
Show 33 quoted lines
> On Thu, Jun 01, 2017 at 11:37:03AM +0100, Adam Dinwoodie wrote:
>
>> When compiling the documentation, asciidoc thinks a backtick surrounded
>> by whitespace shouldn't be interpreted as marking the start or end of a
>> literal.  In most cases, that's useful behaviour, but in the git-pull
>> documentation it means asciidoc is failing to correctly detect which
>> text should be monospaced and which shouldn't.
>> 
>> To avoid this, remove the extraneous spaces from the text to be
>> monospaced.  It would also be possible to fix the formatting by
>> switching to asciidoc's ++ monospace format markers and still have the
>> space characters included in the monospace text, but the spaces aren't
>> necessary and not having them keeps the markup simpler.
>> 
>> Also include a minor grammar fix suggested by Jeff while we're changing
>> these lines.
>> 
>> Signed-off-by: Adam Dinwoodie <adam@dinwoodie.org>
>> Helped-by: Jeff King <peff@peff.net>
>> ---
>>  Documentation/git-pull.txt | 4 ++--
>>  1 file changed, 2 insertions(+), 2 deletions(-)
>
> This looks fine, although...
>
>>  In order to determine what URL to use to fetch from, the value
>>  of the configuration `remote.<origin>.url` is consulted
>> -and if there is not any such variable, the value on `URL: ` line
>> +and if there is not any such variable, the value on the `URL:` line
>>  in `$GIT_DIR/remotes/<origin>` file is used.
>
> ...I should have read to the end of the sentence. It should also be "in
> the `$GIT_DIR/remotes/<origin>` file". Or just drop "file".

There is another one nearby. Here is what I understand as your suggestion (the "just drop" variant), which I'll queue as SQUASH??? on top of Adam's patch.

Thanks.
 Documentation/git-pull.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
Show changes to Documentation/git-pull.txt +2 −2
diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt
index 1d90dd17bd..e414185f5a 100644
--- a/Documentation/git-pull.txt
+++ b/Documentation/git-pull.txt
@@ -160,14 +160,14 @@ present while on branch `<name>`, that value is used instead of
 In order to determine what URL to use to fetch from, the value
 of the configuration `remote.<origin>.url` is consulted
 and if there is not any such variable, the value on the `URL:` line
-in `$GIT_DIR/remotes/<origin>` file is used.
+in `$GIT_DIR/remotes/<origin>` is used.
 
 In order to determine what remote branches to fetch (and
 optionally store in the remote-tracking branches) when the command is
 run without any refspec parameters on the command line, values
 of the configuration variable `remote.<origin>.fetch` are
 consulted, and if there aren't any, `$GIT_DIR/remotes/<origin>`
-file is consulted and its `Pull:` lines are used.
+is consulted and its `Pull:` lines are used.
 In addition to the refspec formats described in the OPTIONS
 section, you can have a globbing refspec that looks like this:
Jeff King· Jun 2, 2017, 02:07 UTC · re: Junio C Hamano · lore

Re: [PATCH v2] docs: fix formatting and grammar

On Fri, Jun 02, 2017 at 10:45:38AM +0900, Junio C Hamano wrote:
Show 6 quoted lines
> > ...I should have read to the end of the sentence. It should also be "in
> > the `$GIT_DIR/remotes/<origin>` file". Or just drop "file".
> 
> There is another one nearby.  Here is what I understand as your
> suggestion (the "just drop" variant), which I'll queue as SQUASH???
> on top of Adam's patch.

Yes, that's exactly what I meant (and the other looks good, too). Thanks.

-Peff

← back to recent threads