Re: [PATCH] Documentation: quote double-dash in "<commit> -- <filename>" for AsciiDoc

From: Jonathan Nieder <jrnieder@gmail.com>
Date: Jun 29, 2011, 04:15 UTC
Message-ID: <20110629041432.GA28690@elie>
In-Reply-To: <7vaad1tzve.fsf@alter.siamese.dyndns.org>

Hi,

Junio C Hamano wrote:

Show 6 quoted lines

> This looks very bad:
> 
>     $ cd $git/share/man
>     $ grep -l '(em ' */*.?
>
> even though we do want em-dash for some hits in the above output.

True.  Based on a glance at /usr/share/man, the patch misses:

 git-submodule.1: "git submodule sync -- A"
 various: git web--browse, git-mergetool--lib, git sh-i18n--envsubst
 rev-list options: history `A--P`

Show 9 quoted lines

> And
> even worse, there seem to be exceptions to this rule, like ...
>
>> diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt
>> index ac10cfbb..a516d577 100644
>> --- a/Documentation/git-revert.txt
>> +++ b/Documentation/git-revert.txt
>> @@ -23,7 +23,7 @@ throw away all uncommitted changes in your working directory, you
>>  should see linkgit:git-reset[1], particularly the '--hard' option.  If

Sloppy of me.  For reference, here's the rule from asciidoc.conf.

	# -- Spaced and unspaced em dashes (entity reference &mdash;).
	# Space on both sides is translated to thin space characters.
	(^-- )=&#8212;&#8201;
	(\n-- )|( -- )|( --\n)=&#8201;&#8212;&#8201;
	(\w)--(\w)=\1&#8212;\2
	\\--(?!-)=--

So:

 - "\--" always represents two dashes, unless followed by another
   minus sign.  There is no obvious technical reason to prefer {litdd}
   over \-- or vice versa.

 - options like "--hard" are safe nowadays (though it's equally safe
   to escape them as "\--hard").  Likewise, the trailing "--" in
   "foo--" is left unmolested.

 - before version 8.3.0[*], no unescaped "--" was safe for HTML output.
   They all would be converted to em dashes.

Will prepare a new patch that takes care of the missed spots using \-- except in cases like "git web{litdd}browse", to roughly follow the existing style. If someone wants to change those to "git web\--browse" with a patch on top, I won't mind.

Thanks, both.

Regards, Jonathan

[*] Quick history:

 - asciidoc 8.4.1
 - [98be31f1] line 1 (^-- ) is added ("Emdash replacement recognized at
   start of block")
 - asciidoc 8.3.5
 - asciidoc 8.3.0
 - [6e71157d] line 3 ((\w)--(\w)) is introduced.  It replaces the
   previous regex (\n|[^-\s\\])--([^-\s]|\n), which had been guarded by
   "ifndef::doctype-manpage" to mitigate the effect of false positives.
 - [46fbb7b7] The overeager pattern ([^\n \\])--([^-\s])=\1&#8212;\2
   guarded by "ifdef::doctype-manpage" is removed, since it has too
   many false positives ("Allow unescaped -- option prefixes in man
   pages (was not working in all situations)")
 - [12032332] Patterns start to capture surrounding whitespace so it
   can be converted to thin space.  In this spirit, the second line
   ((\n-- )|( -- )| --\n)) is introduced, the pattern
   (^|[^-\\])--($|[^-]) guarded by "ifndef::doctype-manpage" changes
   to (\n|[^-\s\\])--([^-\s]|\n), and the pattern (^|\s*[^\S\\])--($|\s+)
   guarded by "ifdef::doctype-manpage" changes to ([^\n \\])--([^-\s]).
 - asciidoc 8.2.7
 - asciidoc 8.2.4
 - asciidoc migrates from svn to mercurial (i.e., beginning of
   history).

Pre-history (from CHANGELOG.txt):

 - asciidoc 7.0.0: "Manpage command names containing dashes (in the
   manpage NAME section) were misinterpreted as the spaced dash
   command name/purpose separator.  Bug report and patch supplied by
   David Greaves"
 - asciidoc 6.0.3: "Spaced and unspaced em dashes are now recognized
   (previously only spaced em dashes were recognized)."
 - asciidoc 5.0.6: "A replacement has been added to `asciidoc.conf` to
   replace inline double dashes with the `&mdash;` entity."