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

From: Piotr Findeisen <piotr.findeisen@gmail.com>
Date: Nov 14, 2008, 13:02 UTC
Message-ID: <ddb82bf60811140502y60987761g55fc959a3e246afe@mail.gmail.com>
In-Reply-To: <20081112000445.GB17662@diku.dk>

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 &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[]
    \\--(?!-)=--

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:

Show 24 quoted lines

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