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

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

[Carlos Martín Nieto]

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 <cmn@elego.de>
---
 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

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

[Junio C Hamano]

Thanks.

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

[Jeff King]

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 <peff@peff.net>

-Peff

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

[Carlos Martín Nieto]

[-- Attachment #1: Type: text/plain, Size: 1363 bytes --]

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:
> 
> > Text between to '*' is emphasized in AsciiDoc which made the
> 
> s/to/two/

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

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



[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 490 bytes --]

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

[Junio C Hamano]

Carlos Martín Nieto <cmn@elego.de> writes:

> 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:
>> 
>> > Text between to '*' is emphasized in AsciiDoc which made the
>> 
>> s/to/two/
>
> Oops. Thanks. Can you squash that in, Junio?

Thanks; done.

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

[Thomas Rast]

Jeff King <peff@peff.net> writes:

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

Actually it would, if it weren't for our use of '-a no-inline-literal'.
Which we are using because the "backticks do not interpret {stuff}"
feature was introduced in a backwards-incompatible way in asciidoc
8.4.1, see 71c020c (Disable asciidoc 8.4.1+ semantics for `{plus}` and
friends, 2009-07-25).

Some googling tells me the distros are currently at

  openSuSE         8.4.5   (local)
  Debian (stable)  8.5.2   packages.debian.org
  Fedora           8.4.5   admin.fedoraproject.org/pkgdb/
                           (but I can't discern whether it's actually in there...)
  Arch             8.6.6   www.archlinux.org/packages/
  Ubuntu 11.10     8.6.4   packages.ubuntu.com

so perhaps the time has come to remove that switch?

-- 
Thomas Rast
trast@{inf,student}.ethz.ch

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

[Jeff King]

On Wed, Feb 29, 2012 at 12:03:53AM +0100, Thomas Rast wrote:

> > 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.
> 
> Actually it would, if it weren't for our use of '-a no-inline-literal'.
> Which we are using because the "backticks do not interpret {stuff}"
> feature was introduced in a backwards-incompatible way in asciidoc
> 8.4.1, see 71c020c (Disable asciidoc 8.4.1+ semantics for `{plus}` and
> friends, 2009-07-25).
> 
> Some googling tells me the distros are currently at
> 
>   openSuSE         8.4.5   (local)
>   Debian (stable)  8.5.2   packages.debian.org
>   Fedora           8.4.5   admin.fedoraproject.org/pkgdb/
>                            (but I can't discern whether it's actually in there...)
>   Arch             8.6.6   www.archlinux.org/packages/
>   Ubuntu 11.10     8.6.4   packages.ubuntu.com
> 
> so perhaps the time has come to remove that switch?

Looks like asciidoc 8.4.1 was introduced almost exactly 3 years ago. So
yeah, I'd be OK with breaking compatibility if it means the sources
become more readable[1]. It would be nice if there were an option (like
"-a inline-literal") that older versions could set, but I don't think it
exists. However, people on old systems always have the option of
pulling the pre-rendered documentation, which is what I assume people on
ancient proprietary systems do (or they just go without manpages).

We should also consider dropping the ASCIIDOC7 define in the
Documentation Makefile, too (it would be broken by the switch to inline
literals, and it is also ancient at this point). I wonder if we can also
drop some of the older docbook compatibility options. Even Debian
stable[2] is on docbook 1.75, which is beyond the Makefile's table of
which version needs which options. The last version to need any options
was docbook 1.72, which is from 2007.

The first step, though, would be auditing the whole Documentation
directory for escaped text inside inline literals (i.e., `{asterisk}`
would have to go back to `*`). Which does not sound like a fun job.

-Peff

[1] The documentation for asciidoc claims that inline literals will not
    expand anything except "special characters". From what I understand
    of special characters, that does not mean stuff like "*", which
    would still be literal, but rather that "<" would be expanded into
    "&lt;" when formatting to XML or HTML. So I think it would do what
    we want.

[2] I usually use Debian stable as my gold standard of "old". But
    actually, RHEL5 will continue to get critical and security fixes
    until 2014, and is on an older toolchain. They are not likely
    to be picking up the latest git to package, of course, but there
    might still be devs on it who would install git from source. But I
    think we can be a little more cavalier about backwards compatibility
    in the doc toolchain because pre-rendered versions are available.