{"thread":{"id":"29777","subject":"[PATCH] Documentation: use {asterisk} in rev-list-options.txt when needed","startedAt":"2012-02-28T15:35:48Z","lastAt":"2012-02-29T21:38:09Z","messageCount":7,"participants":["Carlos Martín Nieto","Junio C Hamano","Jeff King","Thomas Rast"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"185628","messageId":"1330443348-5742-1-git-send-email-cmn@elego.de","threadId":"29777","inReplyTo":null,"subject":"[PATCH] Documentation: use {asterisk} in rev-list-options.txt when needed","fromName":"Carlos Martín Nieto","fromEmail":"cmn@elego.de","sentAt":"2012-02-28T15:35:48Z","receivedAt":"2012-02-28T15:35:48Z","isPatch":true,"sender":{"key":"cmn@elego.de","avatar":"https://avatars.githubusercontent.com/u/335443?v=4"},"body":"Text between to '*' is emphasized in AsciiDoc which made the\nglob-related explanations in rev-list-options.txt very confusing, as\nthe rendered text would be missing two asterisks and the text between\nthem would be emphasized instead.\n\nUse '{asterisk}' where needed to make them show up as asterisks in the\nrendered text.\n\nSigned-off-by: Carlos Martín Nieto \n---\n Documentation/rev-list-options.txt | 12 ++++++------\n 1 file changed, 6 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt\nindex 39e6207..6a4b635 100644\n--- a/Documentation/rev-list-options.txt\n+++ b/Documentation/rev-list-options.txt\n@@ -117,27 +117,27 @@ parents) and `--max-parents=-1` (negative numbers denote no upper limit).\n \tPretend as if all the refs in `refs/heads` are listed\n \ton the command line as ''. If '' is given, limit\n \tbranches to ones matching given shell glob. If pattern lacks '?',\n-\t'*', or '[', '/*' at the end is implied.\n+\t'{asterisk}', or '[', '/{asterisk}' at the end is implied.\n \n --tags[=]::\n \n \tPretend as if all the refs in `refs/tags` are listed\n \ton the command line as ''. If '' is given, limit\n-\ttags to ones matching given shell glob. If pattern lacks '?', '*',\n-\tor '[', '/*' at the end is implied.\n+\ttags to ones matching given shell glob. If pattern lacks '?', '{asterisk}',\n+\tor '[', '/{asterisk}' at the end is implied.\n \n --remotes[=]::\n \n \tPretend as if all the refs in `refs/remotes` are listed\n \ton the command line as ''. If '' is given, limit\n \tremote-tracking branches to ones matching given shell glob.\n-\tIf pattern lacks '?', '*', or '[', '/*' at the end is implied.\n+\tIf pattern lacks '?', '{asterisk}', or '[', '/{asterisk}' at the end is implied.\n \n --glob=::\n \tPretend as if all the refs matching shell glob ''\n \tare listed on the command line as ''. Leading 'refs/',\n-\tis automatically prepended if missing. If pattern lacks '?', '*',\n-\tor '[', '/*' at the end is implied.\n+\tis automatically prepended if missing. If pattern lacks '?', '{asterisk}',\n+\tor '[', '/{asterisk}' at the end is implied.\n \n --ignore-missing::\n \n-- \n1.7.9.2.3.g4346f\n"},{"id":"185664","messageId":"7v1upezr2f.fsf@alter.siamese.dyndns.org","threadId":"29777","inReplyTo":"1330443348-5742-1-git-send-email-cmn@elego.de","subject":"Re: [PATCH] Documentation: use {asterisk} in rev-list-options.txt when needed","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-02-28T19:38:32Z","receivedAt":"2012-02-28T19:38:32Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Thanks.\n"},{"id":"185666","messageId":"20120228194551.GC11725@sigill.intra.peff.net","threadId":"29777","inReplyTo":"1330443348-5742-1-git-send-email-cmn@elego.de","subject":"Re: [PATCH] Documentation: use {asterisk} in rev-list-options.txt when needed","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2012-02-28T19:45:51Z","receivedAt":"2012-02-28T19:45:51Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Tue, Feb 28, 2012 at 04:35:48PM +0100, Carlos Martín Nieto wrote:\n\n> Text between to '*' is emphasized in AsciiDoc which made the\n\ns/to/two/\n\n> glob-related explanations in rev-list-options.txt very confusing, as\n> the rendered text would be missing two asterisks and the text between\n> them would be emphasized instead.\n> \n> Use '{asterisk}' where needed to make them show up as asterisks in the\n> rendered text.\n> [...]\n> -\t'*', or '[', '/*' at the end is implied.\n> +\t'{asterisk}', or '[', '/{asterisk}' at the end is implied.\n\nUgh. I hate asciidoc more with each passing year. Readable source\ndocuments are such a wonderful idea, but the markup makes it less and\nless readable as we accumulate fixes like this. I wonder if this has\nalways been a bug, or something that appeared in more recent versions of\nthe toolchain.\n\nAnyway, that is not a problem with your patch. :) I confirmed that the\nbug happens in my version of the toolchain, and your fix works (I also\ntried using `*`, but backtick does not suppress markup. It would be nice\nif there was an easy marker for \"this is a literal name: no markup, tt\nfont, etc\", but I don't think that exists).\n\nAcked-by: Jeff King \n\n-Peff\n"},{"id":"185670","messageId":"1330460423.691.15.camel@centaur.lab.cmartin.tk","threadId":"29777","inReplyTo":"20120228194551.GC11725@sigill.intra.peff.net","subject":"Re: [PATCH] Documentation: use {asterisk} in rev-list-options.txt when needed","fromName":"Carlos Martín Nieto","fromEmail":"cmn@elego.de","sentAt":"2012-02-28T20:20:23Z","receivedAt":"2012-02-28T20:20:23Z","isPatch":true,"sender":{"key":"cmn@elego.de","avatar":"https://avatars.githubusercontent.com/u/335443?v=4"},"body":"On Tue, 2012-02-28 at 14:45 -0500, Jeff King wrote:\n> On Tue, Feb 28, 2012 at 04:35:48PM +0100, Carlos Martín Nieto wrote:\n> \n> > Text between to '*' is emphasized in AsciiDoc which made the\n> \n> s/to/two/\n\nOops. Thanks. Can you squash that in, Junio?\n\n> \n> > glob-related explanations in rev-list-options.txt very confusing, as\n> > the rendered text would be missing two asterisks and the text between\n> > them would be emphasized instead.\n> > \n> > Use '{asterisk}' where needed to make them show up as asterisks in the\n> > rendered text.\n> > [...]\n> > -\t'*', or '[', '/*' at the end is implied.\n> > +\t'{asterisk}', or '[', '/{asterisk}' at the end is implied.\n> \n> Ugh. I hate asciidoc more with each passing year. Readable source\n> documents are such a wonderful idea, but the markup makes it less and\n> less readable as we accumulate fixes like this. I wonder if this has\n> always been a bug, or something that appeared in more recent versions of\n> the toolchain.\n\nThe generated documentation in the 'html' branch shows the wrong\nformatting as well even for 1.7.0 when the --glob feature and its\nexplanation was first introduced. So either nobody reads the\ndocumentation or very few people actually care about --glob and use the\n--remotes and friends, where that part of the explanation isn't that\ninteresting.\n\n cmn\n\n\n"},{"id":"185674","messageId":"7vhayay7v7.fsf@alter.siamese.dyndns.org","threadId":"29777","inReplyTo":"1330460423.691.15.camel@centaur.lab.cmartin.tk","subject":"Re: [PATCH] Documentation: use {asterisk} in rev-list-options.txt when needed","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-02-28T21:18:36Z","receivedAt":"2012-02-28T21:18:36Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Carlos Martín Nieto writes:\n\n> On Tue, 2012-02-28 at 14:45 -0500, Jeff King wrote:\n>> On Tue, Feb 28, 2012 at 04:35:48PM +0100, Carlos Martín Nieto wrote:\n>> \n>> > Text between to '*' is emphasized in AsciiDoc which made the\n>> \n>> s/to/two/\n>\n> Oops. Thanks. Can you squash that in, Junio?\n\nThanks; done.\n"},{"id":"185679","messageId":"87hayar25i.fsf@thomas.inf.ethz.ch","threadId":"29777","inReplyTo":"20120228194551.GC11725@sigill.intra.peff.net","subject":"Re: [PATCH] Documentation: use {asterisk} in rev-list-options.txt when needed","fromName":"Thomas Rast","fromEmail":"trast@inf.ethz.ch","sentAt":"2012-02-28T23:03:53Z","receivedAt":"2012-02-28T23:03:53Z","isPatch":true,"sender":{"key":"tr@thomasrast.ch","avatar":"https://avatars.githubusercontent.com/u/153510?v=4"},"body":"Jeff King writes:\n\n> Anyway, that is not a problem with your patch. :) I confirmed that the\n> bug happens in my version of the toolchain, and your fix works (I also\n> tried using `*`, but backtick does not suppress markup.\n\nActually it would, if it weren't for our use of '-a no-inline-literal'.\nWhich we are using because the \"backticks do not interpret {stuff}\"\nfeature was introduced in a backwards-incompatible way in asciidoc\n8.4.1, see 71c020c (Disable asciidoc 8.4.1+ semantics for `{plus}` and\nfriends, 2009-07-25).\n\nSome googling tells me the distros are currently at\n\n openSuSE 8.4.5 (local)\n Debian (stable) 8.5.2 packages.debian.org\n Fedora 8.4.5 admin.fedoraproject.org/pkgdb/\n (but I can't discern whether it's actually in there...)\n Arch 8.6.6 www.archlinux.org/packages/\n Ubuntu 11.10 8.6.4 packages.ubuntu.com\n\nso perhaps the time has come to remove that switch?\n\n-- \nThomas Rast\ntrast@{inf,student}.ethz.ch\n"},{"id":"185748","messageId":"20120229213809.GC628@sigill.intra.peff.net","threadId":"29777","inReplyTo":"87hayar25i.fsf@thomas.inf.ethz.ch","subject":"Re: [PATCH] Documentation: use {asterisk} in rev-list-options.txt when needed","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2012-02-29T21:38:09Z","receivedAt":"2012-02-29T21:38:09Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, Feb 29, 2012 at 12:03:53AM +0100, Thomas Rast wrote:\n\n> > Anyway, that is not a problem with your patch. :) I confirmed that the\n> > bug happens in my version of the toolchain, and your fix works (I also\n> > tried using `*`, but backtick does not suppress markup.\n> \n> Actually it would, if it weren't for our use of '-a no-inline-literal'.\n> Which we are using because the \"backticks do not interpret {stuff}\"\n> feature was introduced in a backwards-incompatible way in asciidoc\n> 8.4.1, see 71c020c (Disable asciidoc 8.4.1+ semantics for `{plus}` and\n> friends, 2009-07-25).\n> \n> Some googling tells me the distros are currently at\n> \n> openSuSE 8.4.5 (local)\n> Debian (stable) 8.5.2 packages.debian.org\n> Fedora 8.4.5 admin.fedoraproject.org/pkgdb/\n> (but I can't discern whether it's actually in there...)\n> Arch 8.6.6 www.archlinux.org/packages/\n> Ubuntu 11.10 8.6.4 packages.ubuntu.com\n> \n> so perhaps the time has come to remove that switch?\n\nLooks like asciidoc 8.4.1 was introduced almost exactly 3 years ago. So\nyeah, I'd be OK with breaking compatibility if it means the sources\nbecome more readable[1]. It would be nice if there were an option (like\n\"-a inline-literal\") that older versions could set, but I don't think it\nexists. However, people on old systems always have the option of\npulling the pre-rendered documentation, which is what I assume people on\nancient proprietary systems do (or they just go without manpages).\n\nWe should also consider dropping the ASCIIDOC7 define in the\nDocumentation Makefile, too (it would be broken by the switch to inline\nliterals, and it is also ancient at this point). I wonder if we can also\ndrop some of the older docbook compatibility options. Even Debian\nstable[2] is on docbook 1.75, which is beyond the Makefile's table of\nwhich version needs which options. The last version to need any options\nwas docbook 1.72, which is from 2007.\n\nThe first step, though, would be auditing the whole Documentation\ndirectory for escaped text inside inline literals (i.e., `{asterisk}`\nwould have to go back to `*`). Which does not sound like a fun job.\n\n-Peff\n\n[1] The documentation for asciidoc claims that inline literals will not\n expand anything except \"special characters\". From what I understand\n of special characters, that does not mean stuff like \"*\", which\n would still be literal, but rather that \"<\" would be expanded into\n \"<\" when formatting to XML or HTML. So I think it would do what\n we want.\n\n[2] I usually use Debian stable as my gold standard of \"old\". But\n actually, RHEL5 will continue to get critical and security fixes\n until 2014, and is on an older toolchain. They are not likely\n to be picking up the latest git to package, of course, but there\n might still be devs on it who would install git from source. But I\n think we can be a little more cavalier about backwards compatibility\n in the doc toolchain because pre-rendered versions are available.\n"}]}