[PATCH] fetch doc: escape asterisk in --tags paragraph

[PATCH] fetch doc: escape asterisk in --tags paragraph

[Ramkumar Ramachandra]

Currently, the paragraph corresponding to the --tags option in
git-fetch(1) looks like:

  -t, --tags
      This is a short-hand for giving "refs/tags/:refs/tags/" refspec
                                                 ^^^^^^^^^^^
						 this is in bold

This happens because the corresponding text in fetch-options.txt is
"refs/tags/*:refs/tags/*"; asciidoc renders the text between the two
asterisks in bold.  Escape the first asterisk, correcting the text.

Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>
---
 Candidate for maint?

 Documentation/fetch-options.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt
index 9cb6496..5f68149 100644
--- a/Documentation/fetch-options.txt
+++ b/Documentation/fetch-options.txt
@@ -61,7 +61,7 @@ endif::git-pull[]
 ifndef::git-pull[]
 -t::
 --tags::
-	This is a short-hand for giving "refs/tags/*:refs/tags/*"
+	This is a short-hand for giving "refs/tags/\*:refs/tags/*"
 	refspec from the command line, to ask all tags to be fetched
 	and stored locally.  Because this acts as an explicit
 	refspec, the default refspecs (configured with the
-- 
1.8.3.20.g7940bce.dirty

Re: [PATCH] fetch doc: escape asterisk in --tags paragraph

[Junio C Hamano]

Ramkumar Ramachandra <artagnon@gmail.com> writes:

> Currently, the paragraph corresponding to the --tags option in
> git-fetch(1) looks like:
>
>   -t, --tags
>       This is a short-hand for giving "refs/tags/:refs/tags/" refspec
>                                                  ^^^^^^^^^^^
> 						 this is in bold
>
> This happens because the corresponding text in fetch-options.txt is
> "refs/tags/*:refs/tags/*"; asciidoc renders the text between the two
> asterisks in bold.  Escape the first asterisk, correcting the text.
>
> Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>
> ---
>  Candidate for maint?

The issue certainly is real and needs a fix for maint.  Your
solution I am not sure about.

  $ git grep '\\\*' -- Documentation/\*.txt

shows only two meaningful hits (git-rm.txt and git-svn.txt);
everybody else uses

$ git grep '{asterisk}' -- Documentation/\*.txt

and the one you spotted in fetch-options.txt is very similar to the
one appears in git-pull.txt, I think.


>  Documentation/fetch-options.txt | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt
> index 9cb6496..5f68149 100644
> --- a/Documentation/fetch-options.txt
> +++ b/Documentation/fetch-options.txt
> @@ -61,7 +61,7 @@ endif::git-pull[]
>  ifndef::git-pull[]
>  -t::
>  --tags::
> -	This is a short-hand for giving "refs/tags/*:refs/tags/*"
> +	This is a short-hand for giving "refs/tags/\*:refs/tags/*"
>  	refspec from the command line, to ask all tags to be fetched
>  	and stored locally.  Because this acts as an explicit
>  	refspec, the default refspecs (configured with the

Re: [PATCH] fetch doc: escape asterisk in --tags paragraph

[Junio C Hamano]

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

> Ramkumar Ramachandra <artagnon@gmail.com> writes:
>
>> Currently, the paragraph corresponding to the --tags option in
>> git-fetch(1) looks like:
>>
>>   -t, --tags
>>       This is a short-hand for giving "refs/tags/:refs/tags/" refspec
>>                                                  ^^^^^^^^^^^
>> 						 this is in bold
>>
>> This happens because the corresponding text in fetch-options.txt is
>> "refs/tags/*:refs/tags/*"; asciidoc renders the text between the two
>> asterisks in bold.  Escape the first asterisk, correcting the text.
>>
>> Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>
>> ---
>>  Candidate for maint?
>
> The issue certainly is real and needs a fix for maint.  Your
> solution I am not sure about.
>
>   $ git grep '\\\*' -- Documentation/\*.txt
>
> shows only two meaningful hits (git-rm.txt and git-svn.txt);
> everybody else uses
>
> $ git grep '{asterisk}' -- Documentation/\*.txt
>
> and the one you spotted in fetch-options.txt is very similar to the
> one appears in git-pull.txt, I think.

How about this?

-- >8 --
Subject: fetch-options.txt: prevent wildcard refspec from getting misformatted 

When explaining the "--tags" option as an equivalent to giving an
explicit "refs/tags/*:refs/tags/*" refspec, the two asterisks were
misinterpreted by AsciiDoc as a request to typeset the string
segment between them in bold.

We could fix it in two ways.  We can replace them with {asterisk}s
while keeping the string as body text, or we can mark it as a
literal string by using the backquotes around it.

Let's do the latter, as it is teaching the user an "exactly as
typed" alternative.

Noticed-by: Ramkumar Ramachandra <artagnon@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/fetch-options.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt
index 6e98bdf..c87bf39 100644
--- a/Documentation/fetch-options.txt
+++ b/Documentation/fetch-options.txt
@@ -57,7 +57,7 @@ endif::git-pull[]
 ifndef::git-pull[]
 -t::
 --tags::
-	This is a short-hand for giving "refs/tags/*:refs/tags/*"
+	This is a short-hand for giving `refs/tags/*:refs/tags/*`
 	refspec from the command line, to ask all tags to be fetched
 	and stored locally.  Because this acts as an explicit
 	refspec, the default refspecs (configured with the

Re: [PATCH] fetch doc: escape asterisk in --tags paragraph

[Ramkumar Ramachandra]

Junio C Hamano wrote:
> How about this?

Looks good, thanks.