Hello!
I've been reading

http://www.kernel.org/pub/software/scm/git/docs/user-manual.html till

late night and found that "--" prefixing options names (like in "git

diff --cached") are replaced by asciidoc with a single unicode

character "=97" which makes them unsuitable for pasting them to a

terminal.
I've cloned the git repository from

git://git.kernel.org/pub/scm/git/git.git, made some changes to

Documentation/user-manual.txt, tested the results and commited my work

locally.

The attached file is a result of running `git diff HEAD~1`.
My local log message:

------------------

asciidoc escaping of "--"
Asciidoc replaces "--" with "=97" 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.

------------------
Hope that's of any use.
Best regards,

Piotr

Same thing done the right way.
regards,

P.
On Fri, Nov 7, 2008 at 04:09, Piotr Findeisen <piotr.findeisen@gmail.com> w=

Please read Documentation/SubmittingPatches for the preferred way to
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 —)

# But disallow unspaced in man pages because double-dash option name prefixes

# are pervasive.

ifndef::doctype-manpage[]

(^|[^-\\])--($|[^-])=\1—\2

endif::doctype-manpage[]

ifdef::doctype-manpage[]

(^|\s*[^\S\\])--($|\s+)=\1—\2

endif::doctype-manpage[]

\\--(?!-)=--
--

Jonas Fonseca

--

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

--

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

--

On my machine, make gittutorial.7 produces manpage that displays "--"
Anyway, this may be a good idea to use unambiguous "—" (though people

writing docs may be used to using "--" as a punctuation). I can run

through the Documentation replacing "\w--\w" with m-dash, if you want.
Regards,

Piotr

--

I would like to see such a patch.
--

Jonas Fonseca

--

I've investigated it a little.

It seems that this newet version of asciidoc (I'm running 8.2.2) has

the global asciidoc.conf file (placed in /etc/asciidoc/asciidoc.conf

on my computer) containing the previously cited section:
    # -- Spaced and unspaced em dashes (entity reference —)

    # But disallow unspaced in man pages because double-dash option

name prefixes

    # are pervasive.

    ifndef::doctype-manpage[]

    (^|[^-\\])--($|[^-])=\1—\2

    endif::doctype-manpage[]

    ifdef::doctype-manpage[]

    (^|\s*[^\S\\])--($|\s+)=\1—\2

    endif::doctype-manpage[]

    \\--(?!-)=--
Those replacements are run *before* any replacements defined in

user-provided files are taken into consideration. You can disable them

only by disabling all replacements, I think.
So the only thing we can do about automatic conversion "--" to "—" is putting

    [replacements]

    &8212;=--

in Documentation/asciidoc.conf file or similar. (8212 = x2014,

"\u2014" = "—"). This way the unwanted replacement is reverted.
However, this forbids literal "&8212;" in the source .txt files and

there is no way to enable it. This seems only little probable that

anyone would want to write "&8212;" until someone writes "writing

Documentation guide" where she would state that "&8212;" is

prohibited.
If this is good solution and we want to replace punctuation "--" with

unicode "—", I will do this.

However, this seems a bit messy -- fighting against asciidoc instead

of using it as it's designed to be used. IMHO, it's better to

explicitly escape non-punctuation "--" with "\" and write punctuation

"--" with spaces on both sides. Please note, writing literal "—" isn't

so simple -- there is no such key on the keyboard :)
Best regards,

Piotr
--