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

From: Jonas Fonseca <fonseca@diku.dk>
Date: Nov 10, 2008, 10:07 UTC
Message-ID: <20081110100757.GA12868@diku.dk>
In-Reply-To: <ddb82bf60811092338m3aad8041w20de23f18aa7d56e@mail.gmail.com>

Piotr Findeisen <piotr.findeisen@gmail.com> wrote Mon, Nov 10, 2008:

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

Sorry I didn't read your mail carefully enough.

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

True.

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

So another option is to disable all substitution of "--" and just use the "—" character when it is explicitly needed. The documentation is using UTF-8 after all. This would also fix the usage of "--" in the manpages, e.g.

	You've now initialized the working directory--you may notice ...

in gittutorial(7). On my setup, with "--" replaced with "—", I get the following nroff code:

	You've now initialized the working directory\(emyou may notice
	...

-- 
Jonas Fonseca