Re: Documentation/user-manual.txt, asciidoc and "--" escapes

From: Piotr Findeisen <piotr.findeisen@gmail.com>
Date: Nov 10, 2008, 07:38 UTC
Message-ID: <ddb82bf60811092338m3aad8041w20de23f18aa7d56e@mail.gmail.com>
In-Reply-To: <2c6b72b30811091052k77200785j722c8aed2beb7684@mail.gmail.com>

Hi!

>>> The attached file is a result of running `git diff HEAD~1`.
>
> Please read Documentation/SubmittingPatches for the preferred way to
> contribute patches.

Ok, I'll look there, when you tell me this patch is worth anything.

Show 18 quoted lines

>>> Asciidoc replaces "--" with "—" when not in verbatim mode. This is
>>> sometimes unwanted -- especially when citing command line options like
>>> "git diff --cached". This commit includes proper quotes in user-manual.txt.
>
> Newer asciidoc versions have the following "workaround". Maybe adding
> something like this to Documentation/asciidoc.conf would be more
> future proof.
>
> # -- Spaced and unspaced em dashes (entity reference &mdash;)
> # But disallow unspaced in man pages because double-dash option name prefixes
> # are pervasive.
> ifndef::doctype-manpage[]
> (^|[^-\\])--($|[^-])=\1&#8212;\2
> endif::doctype-manpage[]
> ifdef::doctype-manpage[]
> (^|\s*[^\S\\])--($|\s+)=\1&#8212;\2
> endif::doctype-manpage[]
> \\--(?!-)=--

Well, this doesn't solve the problem -- I'm not talking about manpages, the "--" where replaced with single "—" on the http://www.kernel.org/pub/software/scm/git/docs/user-manual.html page. Yes, we can disable such a replacement in the config file, but take a look at the sentence "...how to fetch and study a project using git—read these chapters...". In this case "--" in the source file was replaced with "—" and this is what we want.

I noticed that all substitutions "--" -> "—", where "—" is a part of sentence punctuation, match \w--\w pattern (e.g. no spaces on both sides) and probably this is how it should be written in English. But basing on this doesn't seem to me to be fool proof.

Best regards, Piotr