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

Jonathan Nieder [off-list ref] writes:

As explained in v1.7.3-rc0~13^2 (Work around em-dash handling in newer
AsciiDoc, 2010-08-23), outside of verbatim environments, newish
versions of AsciiDoc will convert double hyphens to en dashes.  Use
the litdd syntax introduced by that patch to avoid such misformatting
in sentences where "--" represents the two-character "end of options"
argument that separates revision names from filename patterns.

Thanks.

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.  And
even worse, there seem to be exceptions to this rule, like ...

... the one before "hard" above.

Hi,

Junio C Hamano wrote:

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`

And
even worse, there seem to be exceptions to this rule, like ...

quoted

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 —).
	# Space on both sides is translated to thin space characters.
	(^-- )=— 
	(\n-- )|( -- )|( --\n)= — 
	(\w)--(\w)=\1—\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—\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 `—` entity."