[PATCH] docs: fix literal quoted spaces

[PATCH] docs: fix literal quoted spaces

[Adam Dinwoodie]

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

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

Re: [PATCH] docs: fix literal quoted spaces

[Jeff King]

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.

(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

Re: [PATCH] docs: fix literal quoted spaces

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

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

> (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

Re: [PATCH] docs: fix literal quoted spaces

[Adam Dinwoodie]

On Thu, Jun 01, 2017 at 11:06:18AM +0900, Junio C Hamano wrote:
> 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.

[PATCH v2] docs: fix formatting and grammar

[Adam Dinwoodie]

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

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

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

[Jeff King]

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

-Peff

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

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

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

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:
 

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

[Jeff King]

On Fri, Jun 02, 2017 at 10:45:38AM +0900, Junio C Hamano wrote:

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