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

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

[Piotr Findeisen]

[-- Attachment #1: Type: text/plain, Size: 918 bytes --]

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

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: user-manual.txt.patch --]
[-- Type: text/x-diff; name=user-manual.txt.patch, Size: 7018 bytes --]

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 645d752..66d0cca 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -527,8 +527,8 @@ $ git reset --hard fb47ddb2db...
 then test, run "bisect good" or "bisect bad" as appropriate, and
 continue.
 
-Instead of "git bisect visualize" and then "git reset --hard
-fb47ddb2db...", you might just want to tell git that you want to skip
+Instead of "git bisect visualize" and then "+++git reset --hard
+fb47ddb2db...+++", you might just want to tell git that you want to skip
 the current commit:
 
 -------------------------------------------------
@@ -660,7 +660,7 @@ You can also ask git log to show patches:
 $ git log -p
 -------------------------------------------------
 
-See the "--pretty" option in the linkgit:git-log[1] man page for more
+See the "+++--pretty+++" option in the linkgit:git-log[1] man page for more
 display options.
 
 Note that git log starts with the most recent commit and works
@@ -900,7 +900,7 @@ $ gitk $( git show-ref --heads ) --not  $( git show-ref --tags )
 -------------------------------------------------
 
 (See linkgit:git-rev-parse[1] for explanations of commit-selecting
-syntax such as `--not`.)
+syntax such as `+++--not+++`.)
 
 [[making-a-release]]
 Creating a changelog and tarball for a software release
@@ -1024,7 +1024,7 @@ at step 3, git maintains a snapshot of the tree's contents in a
 special staging area called "the index."
 
 At the beginning, the content of the index will be identical to
-that of the HEAD.  The command "git diff --cached", which shows
+that of the HEAD.  The command "+++git diff --cached+++", which shows
 the difference between the HEAD and the index, should therefore
 produce no output at that point.
 
@@ -1572,7 +1572,7 @@ Recovering lost changes
 Reflogs
 ^^^^^^^
 
-Say you modify a branch with `linkgit:git-reset[1] --hard`, and then
+Say you modify a branch with `linkgit:git-reset[1] +++--hard+++`, and then
 realize that the branch was the only reference you had to that point in
 history.
 
@@ -1701,7 +1701,7 @@ $ git pull
 More generally, a branch that is created from a remote branch will pull
 by default from that branch.  See the descriptions of the
 branch.<name>.remote and branch.<name>.merge options in
-linkgit:git-config[1], and the discussion of the `--track` option in
+linkgit:git-config[1], and the discussion of the `+++--track+++` option in
 linkgit:git-checkout[1], to learn how to control these defaults.
 
 In addition to saving you keystrokes, "git pull" also helps you by
@@ -1978,8 +1978,8 @@ error: failed to push to 'ssh://yourserver.com/~you/proj.git'
 
 This can happen, for example, if you:
 
-	- use `git-reset --hard` to remove already-published commits, or
-	- use `git-commit --amend` to replace already-published commits
+	- use `+++git-reset --hard+++` to remove already-published commits, or
+	- use `+++git-commit --amend+++` to replace already-published commits
 	  (as in <<fixing-a-mistake-by-rewriting-history>>), or
 	- use `git-rebase` to rebase any already-published commits (as
 	  in <<using-git-rebase>>).
@@ -2088,7 +2088,7 @@ linkgit:git-fetch[1] to keep them up-to-date; see
 
 Now create the branches in which you are going to work; these start out
 at the current tip of origin/master branch, and should be set up (using
-the --track option to linkgit:git-branch[1]) to merge changes in from
+the +++--track+++ option to linkgit:git-branch[1]) to merge changes in from
 Linus by default.
 
 -------------------------------------------------
@@ -2468,7 +2468,7 @@ $ git rebase --continue
 
 and git will continue applying the rest of the patches.
 
-At any point you may use the `--abort` option to abort this process and
+At any point you may use the `+++--abort+++` option to abort this process and
 return mywork to the state it had before you started the rebase:
 
 -------------------------------------------------
@@ -2539,7 +2539,7 @@ $ gitk origin..mywork &
 
 and browse through the list of patches in the mywork branch using gitk,
 applying them (possibly in a different order) to mywork-new using
-cherry-pick, and possibly modifying them as you go using `commit --amend`.
+cherry-pick, and possibly modifying them as you go using `+++commit --amend+++`.
 The linkgit:git-gui[1] command may also help as it allows you to
 individually select diff hunks for inclusion in the index (by
 right-clicking on the diff hunk and choosing "Stage Hunk for Commit").
@@ -2897,7 +2897,7 @@ Commit Object
 ~~~~~~~~~~~~~
 
 The "commit" object links a physical state of a tree with a description
-of how we got there and why.  Use the --pretty=raw option to
+of how we got there and why.  Use the +++--pretty=raw+++ option to
 linkgit:git-show[1] or linkgit:git-log[1] to examine your favorite
 commit:
 
@@ -3700,16 +3700,16 @@ i.e. it will normally just update existing cache entries.
 
 To tell git that yes, you really do realize that certain files no
 longer exist, or that new files should be added, you
-should use the `--remove` and `--add` flags respectively.
+should use the `+++--remove+++` and `+++--add+++` flags respectively.
 
-NOTE! A `--remove` flag does 'not' mean that subsequent filenames will
+NOTE! A `+++--remove+++` flag does 'not' mean that subsequent filenames will
 necessarily be removed: if the files still exist in your directory
 structure, the index will be updated with their new status, not
-removed. The only thing `--remove` means is that update-index will be
+removed. The only thing `+++--remove+++` means is that update-index will be
 considering a removed file to be a valid thing, and if the file really
 does not exist any more, it will update the index accordingly.
 
-As a special case, you can also do `git update-index --refresh`, which
+As a special case, you can also do `+++git update-index --refresh+++`, which
 will refresh the "stat" information of each index to match the current
 stat information. It will 'not' update the object status itself, and
 it will only update the fields that are used to quickly test whether
@@ -3956,7 +3956,7 @@ entries" in it. Such an index tree can 'NOT' be written out to a tree
 object, and you will have to resolve any such merge clashes using
 other tools before you can write out the result.
 
-You can examine such index state with `git ls-files --unmerged`
+You can examine such index state with `+++git ls-files --unmerged+++`
 command.  An example:
 
 ------------------------------------------------
@@ -3967,7 +3967,7 @@ $ git ls-files --unmerged
 100644 cc44c73eb783565da5831b4d820c962954019b69 3	hello.c
 ------------------------------------------------
 
-Each line of the `git ls-files --unmerged` output begins with
+Each line of the `+++git ls-files --unmerged+++` output begins with
 the blob mode bits, blob SHA1, 'stage number', and the
 filename.  The 'stage number' is git's way to say which tree it
 came from: stage 1 corresponds to `$orig` tree, stage 2 `HEAD`

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

[Piotr Findeisen]

[-- Attachment #1: Type: text/plain, Size: 1103 bytes --]

Same thing done the right way.

regards,
P.

On Fri, Nov 7, 2008 at 04:09, Piotr Findeisen <piotr.findeisen@gmail.com> wrote:
>
> 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 "—" 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 "—" 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

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: user-manual.txt.patch --]
[-- Type: text/x-diff; name=user-manual.txt.patch, Size: 6445 bytes --]

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 645d752..d200759 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -527,7 +527,7 @@ $ git reset --hard fb47ddb2db...
 then test, run "bisect good" or "bisect bad" as appropriate, and
 continue.
 
-Instead of "git bisect visualize" and then "git reset --hard
+Instead of "git bisect visualize" and then "git reset \--hard
 fb47ddb2db...", you might just want to tell git that you want to skip
 the current commit:
 
@@ -900,7 +900,7 @@ $ gitk $( git show-ref --heads ) --not  $( git show-ref --tags )
 -------------------------------------------------
 
 (See linkgit:git-rev-parse[1] for explanations of commit-selecting
-syntax such as `--not`.)
+syntax such as `\--not`.)
 
 [[making-a-release]]
 Creating a changelog and tarball for a software release
@@ -1024,7 +1024,7 @@ at step 3, git maintains a snapshot of the tree's contents in a
 special staging area called "the index."
 
 At the beginning, the content of the index will be identical to
-that of the HEAD.  The command "git diff --cached", which shows
+that of the HEAD.  The command "git diff \--cached", which shows
 the difference between the HEAD and the index, should therefore
 produce no output at that point.
 
@@ -1572,7 +1572,7 @@ Recovering lost changes
 Reflogs
 ^^^^^^^
 
-Say you modify a branch with `linkgit:git-reset[1] --hard`, and then
+Say you modify a branch with `linkgit:git-reset[1] \--hard`, and then
 realize that the branch was the only reference you had to that point in
 history.
 
@@ -1701,7 +1701,7 @@ $ git pull
 More generally, a branch that is created from a remote branch will pull
 by default from that branch.  See the descriptions of the
 branch.<name>.remote and branch.<name>.merge options in
-linkgit:git-config[1], and the discussion of the `--track` option in
+linkgit:git-config[1], and the discussion of the `\--track` option in
 linkgit:git-checkout[1], to learn how to control these defaults.
 
 In addition to saving you keystrokes, "git pull" also helps you by
@@ -1978,8 +1978,8 @@ error: failed to push to 'ssh://yourserver.com/~you/proj.git'
 
 This can happen, for example, if you:
 
-	- use `git-reset --hard` to remove already-published commits, or
-	- use `git-commit --amend` to replace already-published commits
+	- use `git-reset \--hard` to remove already-published commits, or
+	- use `git-commit \--amend` to replace already-published commits
 	  (as in <<fixing-a-mistake-by-rewriting-history>>), or
 	- use `git-rebase` to rebase any already-published commits (as
 	  in <<using-git-rebase>>).
@@ -2088,7 +2088,7 @@ linkgit:git-fetch[1] to keep them up-to-date; see
 
 Now create the branches in which you are going to work; these start out
 at the current tip of origin/master branch, and should be set up (using
-the --track option to linkgit:git-branch[1]) to merge changes in from
+the \--track option to linkgit:git-branch[1]) to merge changes in from
 Linus by default.
 
 -------------------------------------------------
@@ -2468,7 +2468,7 @@ $ git rebase --continue
 
 and git will continue applying the rest of the patches.
 
-At any point you may use the `--abort` option to abort this process and
+At any point you may use the `\--abort` option to abort this process and
 return mywork to the state it had before you started the rebase:
 
 -------------------------------------------------
@@ -2539,7 +2539,7 @@ $ gitk origin..mywork &
 
 and browse through the list of patches in the mywork branch using gitk,
 applying them (possibly in a different order) to mywork-new using
-cherry-pick, and possibly modifying them as you go using `commit --amend`.
+cherry-pick, and possibly modifying them as you go using `commit \--amend`.
 The linkgit:git-gui[1] command may also help as it allows you to
 individually select diff hunks for inclusion in the index (by
 right-clicking on the diff hunk and choosing "Stage Hunk for Commit").
@@ -2897,7 +2897,7 @@ Commit Object
 ~~~~~~~~~~~~~
 
 The "commit" object links a physical state of a tree with a description
-of how we got there and why.  Use the --pretty=raw option to
+of how we got there and why.  Use the \--pretty=raw option to
 linkgit:git-show[1] or linkgit:git-log[1] to examine your favorite
 commit:
 
@@ -3700,16 +3700,16 @@ i.e. it will normally just update existing cache entries.
 
 To tell git that yes, you really do realize that certain files no
 longer exist, or that new files should be added, you
-should use the `--remove` and `--add` flags respectively.
+should use the `\--remove` and `\--add` flags respectively.
 
-NOTE! A `--remove` flag does 'not' mean that subsequent filenames will
+NOTE! A `\--remove` flag does 'not' mean that subsequent filenames will
 necessarily be removed: if the files still exist in your directory
 structure, the index will be updated with their new status, not
-removed. The only thing `--remove` means is that update-index will be
+removed. The only thing `\--remove` means is that update-index will be
 considering a removed file to be a valid thing, and if the file really
 does not exist any more, it will update the index accordingly.
 
-As a special case, you can also do `git update-index --refresh`, which
+As a special case, you can also do `git update-index \--refresh`, which
 will refresh the "stat" information of each index to match the current
 stat information. It will 'not' update the object status itself, and
 it will only update the fields that are used to quickly test whether
@@ -3956,7 +3956,7 @@ entries" in it. Such an index tree can 'NOT' be written out to a tree
 object, and you will have to resolve any such merge clashes using
 other tools before you can write out the result.
 
-You can examine such index state with `git ls-files --unmerged`
+You can examine such index state with `git ls-files \--unmerged`
 command.  An example:
 
 ------------------------------------------------
@@ -3967,7 +3967,7 @@ $ git ls-files --unmerged
 100644 cc44c73eb783565da5831b4d820c962954019b69 3	hello.c
 ------------------------------------------------
 
-Each line of the `git ls-files --unmerged` output begins with
+Each line of the `git ls-files \--unmerged` output begins with
 the blob mode bits, blob SHA1, 'stage number', and the
 filename.  The 'stage number' is git's way to say which tree it
 came from: stage 1 corresponds to `$orig` tree, stage 2 `HEAD`

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

[Jonas Fonseca]

> On Fri, Nov 7, 2008 at 04:09, Piotr Findeisen <piotr.findeisen@gmail.com> wrote:
>> Hello!

Hello,

>> The attached file is a result of running `git diff HEAD~1`.

Please read Documentation/SubmittingPatches for the preferred way to
contribute patches.

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

-- 
Jonas Fonseca

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

[Piotr Findeisen]

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.


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

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

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

[Jonas Fonseca]

Piotr Findeisen <piotr.findeisen@gmail.com> wrote Mon, Nov 10, 2008:
> >>> 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

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

[Piotr Findeisen]

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

On my machine, make gittutorial.7 produces manpage that displays "--"
in this place :)

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

Regards,
Piotr

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

[Jonas Fonseca]

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

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

[Piotr Findeisen]

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
>

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

[Junio C Hamano]

"Piotr Findeisen" <piotr.findeisen@gmail.com> writes:

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

Thanks for digging.  I agree with that.