[PATCH] Documentation: use {asterisk} in rev-list-options.txt when needed

Text between to '*' is emphasized in AsciiDoc which made the
glob-related explanations in rev-list-options.txt very confusing, as
the rendered text would be missing two asterisks and the text between
them would be emphasized instead.

Use '{asterisk}' where needed to make them show up as asterisks in the
rendered text.

Signed-off-by: Carlos Martín Nieto <redacted>
---
 Documentation/rev-list-options.txt |   12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
index 39e6207..6a4b635 100644
--- a/Documentation/rev-list-options.txt
+++ b/Documentation/rev-list-options.txt

@@ -117,27 +117,27 @@ parents) and `--max-parents=-1` (negative numbers denote no upper limit).
 	Pretend as if all the refs in `refs/heads` are listed
 	on the command line as '<commit>'. If '<pattern>' is given, limit
 	branches to ones matching given shell glob. If pattern lacks '?',
-	'*', or '[', '/*' at the end is implied.
+	'{asterisk}', or '[', '/{asterisk}' at the end is implied.
 
 --tags[=<pattern>]::
 
 	Pretend as if all the refs in `refs/tags` are listed
 	on the command line as '<commit>'. If '<pattern>' is given, limit
-	tags to ones matching given shell glob. If pattern lacks '?', '*',
-	or '[', '/*' at the end is implied.
+	tags to ones matching given shell glob. If pattern lacks '?', '{asterisk}',
+	or '[', '/{asterisk}' at the end is implied.
 
 --remotes[=<pattern>]::
 
 	Pretend as if all the refs in `refs/remotes` are listed
 	on the command line as '<commit>'. If '<pattern>' is given, limit
 	remote-tracking branches to ones matching given shell glob.
-	If pattern lacks '?', '*', or '[', '/*' at the end is implied.
+	If pattern lacks '?', '{asterisk}', or '[', '/{asterisk}' at the end is implied.
 
 --glob=<glob-pattern>::
 	Pretend as if all the refs matching shell glob '<glob-pattern>'
 	are listed on the command line as '<commit>'. Leading 'refs/',
-	is automatically prepended if missing. If pattern lacks '?', '*',
-	or '[', '/*' at the end is implied.
+	is automatically prepended if missing. If pattern lacks '?', '{asterisk}',
+	or '[', '/{asterisk}' at the end is implied.
 
 --ignore-missing::
 

-- 
1.7.9.2.3.g4346f

On Tue, Feb 28, 2012 at 04:35:48PM +0100, Carlos Martín Nieto wrote:

Text between to '*' is emphasized in AsciiDoc which made the

s/to/two/

glob-related explanations in rev-list-options.txt very confusing, as
the rendered text would be missing two asterisks and the text between
them would be emphasized instead.

Use '{asterisk}' where needed to make them show up as asterisks in the
rendered text.
[...]
-	'*', or '[', '/*' at the end is implied.
+	'{asterisk}', or '[', '/{asterisk}' at the end is implied.

Ugh. I hate asciidoc more with each passing year. Readable source
documents are such a wonderful idea, but the markup makes it less and
less readable as we accumulate fixes like this.  I wonder if this has
always been a bug, or something that appeared in more recent versions of
the toolchain.

Anyway, that is not a problem with your patch. :) I confirmed that the
bug happens in my version of the toolchain, and your fix works (I also
tried using `*`, but backtick does not suppress markup. It would be nice
if there was an easy marker for "this is a literal name: no markup, tt
font, etc", but I don't think that exists).

Acked-by: Jeff King <redacted>

-Peff

On Tue, 2012-02-28 at 14:45 -0500, Jeff King wrote:

On Tue, Feb 28, 2012 at 04:35:48PM +0100, Carlos Martín Nieto wrote:

quoted

Text between to '*' is emphasized in AsciiDoc which made the

s/to/two/

Oops. Thanks. Can you squash that in, Junio?

quoted

glob-related explanations in rev-list-options.txt very confusing, as
the rendered text would be missing two asterisks and the text between
them would be emphasized instead.

Use '{asterisk}' where needed to make them show up as asterisks in the
rendered text.
[...]
-	'*', or '[', '/*' at the end is implied.
+	'{asterisk}', or '[', '/{asterisk}' at the end is implied.

Ugh. I hate asciidoc more with each passing year. Readable source
documents are such a wonderful idea, but the markup makes it less and
less readable as we accumulate fixes like this.  I wonder if this has
always been a bug, or something that appeared in more recent versions of
the toolchain.

The generated documentation in the 'html' branch shows the wrong
formatting as well even for 1.7.0 when the --glob feature and its
explanation was first introduced. So either nobody reads the
documentation or very few people actually care about --glob and use the
--remotes and friends, where that part of the explanation isn't that
interesting.

   cmn