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

["Piotr Findeisen" <piotr.findeisen@gmail.com>]

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



On Wed, Nov 12, 2008 at 01:04, Jonas Fonseca <fonseca@diku.dk> wrote:
> Piotr Findeisen <piotr.findeisen@gmail.com> wrote Mon, Nov 10, 2008:
>> > 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:
>>
>> On my machine, make gittutorial.7 produces manpage that displays "--"
>> in this place :)
>
> At least you don't loose anything compared to the current behavior. ;)
>
>> >        You've now initialized the working directory\(emyou may notice
>>
>> 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.
>
> I would like to see such a patch.
>
> --
> Jonas Fonseca
>