Documentation: quote double-dash for AsciiDoc

AsciiDoc versions since 5.0.6 treat a double-dash surrounded by spaces
(outside of verbatim environments) as a request to insert an em dash.
Such versions also treat the three-character sequence "\--", when not
followed by another dash, as a request to insert two literal minus
signs.  Thus from time to time there have been patches to add
backslashes to AsciiDoc markup to escape double-dashes that are meant
to be represent '--' characters used literally on the command line;
see v1.4.0-rc1~174, Fix up docs where "--" isn't displayed correctly,
2006-05-05, for example.

AsciiDoc 6.0.3 (2005-04-20) made life harder by also treating
double-dashes without surrounding whitespace as markup for an em dash,
though only when formatting for backends other than the manpages
(e.g., HTML).  Many pages needed to be changed to use a backslash
before the "--" in names of command-line flags like "--add" (see
v0.99.6~37, Update tutorial, 2005-08-30).

AsciiDoc 8.3.0 (2008-11-29) refined the em-dash rule to avoid that
requirement.  Double-dashes without surrounding spaces are not
rendered as em dashes any more unless bordered on both sides by
alphanumeric characters.  The unescaped markup for option names (e.g.,
"--add") works fine, and many instances of this style have leaked into
Documentation/; git's HTML documentation contains many spurious em
dashes when formatted by an older toolchain.  (This patch will not
change that.)

The upshot: "--" as an isolated word and in phrases like "git
web--browse" must be escaped if it is not to be rendered as an em dash
by current asciidoc.  Use "\--" to avoid such misformatting in
sentences in which "--" represents a literal double-minus command line
argument that separates options and revs from pathspecs, and use
"{litdd}" in cases where the double-dash is embedded in the command
name.  The latter is just for consistency with v1.7.3-rc0~13^2 (Work
around em-dash handling in newer AsciiDoc, 2010-08-23).

List of lines to fix found by grepping manpages for "(em".

Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
Improved-by: Junio C Hamano <gitster@pobox.com>
Improved-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/config.txt b/Documentation/config.txt
index 6babbc78375e0c4e4e6ef4bdff8511b53c8cf9d1..c2ba535a0d1c823ca3200705100c62be3d9990a9 100644 (file)
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -676,7 +676,7 @@ branch.<name>.rebase::
 browser.<tool>.cmd::
        Specify the command to invoke the specified browser. The
        specified command is evaluated in shell with the URLs passed
-       as arguments. (See linkgit:git-web--browse[1].)
+       as arguments. (See linkgit:git-web{litdd}browse[1].)
 
 browser.<tool>.path::
        Override the path for the given tool that may be used to

diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
index 8f89f6f08c57335ea6606dd1eaddde98477e9c9e..b9aa220db8fa1d0eb23535c15ef2350e44cd545c 100644 (file)
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt
@@ -275,7 +275,7 @@ When recording your own work, the contents of modified files in
 your working tree are temporarily stored to a staging area
 called the "index" with 'git add'.  A file can be
 reverted back, only in the index but not in the working tree,
-to that of the last commit with `git reset HEAD -- <file>`,
+to that of the last commit with `git reset HEAD \-- <file>`,
 which effectively reverts 'git add' and prevents the changes to
 this file from participating in the next commit.  After building
 the state to be committed incrementally with these commands,

diff --git a/Documentation/git-mergetool--lib.txt b/Documentation/git-mergetool--lib.txt
index d8df55362ce653516006b02df2950c325f1176b7..1441aec2426363eeab9e4de6aae20f0d1bc400b8 100644 (file)
--- a/Documentation/git-mergetool--lib.txt
+++ b/Documentation/git-mergetool--lib.txt
@@ -7,7 +7,7 @@ git-mergetool--lib - Common git merge tool shell scriptlets
 
 SYNOPSIS
 --------
-'TOOL_MODE=(diff|merge) . "$(git --exec-path)/git-mergetool--lib"'
+'TOOL_MODE=(diff|merge) . "$(git --exec-path)/git-mergetool{litdd}lib"'
 
 DESCRIPTION
 -----------

diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt
index 752fc88e768e4b8e1afddad4bdd7833cf20978c7..ab994abdbd586bab87f6f37a39a9da576bd03c2f 100644 (file)
--- a/Documentation/git-revert.txt
+++ b/Documentation/git-revert.txt
@@ -23,7 +23,7 @@ throw away all uncommitted changes in your working directory, you
 should see linkgit:git-reset[1], particularly the '--hard' option.  If
 you want to extract specific files as they were in another commit, you
 should see linkgit:git-checkout[1], specifically the `git checkout
-<commit> -- <filename>` syntax.  Take care with these alternatives as
+<commit> \-- <filename>` syntax.  Take care with these alternatives as
 both will discard uncommitted changes in your working directory.
 
 OPTIONS

diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index e8ed2f2c0f440455443521d35989be7d7ff53c10..1649b9fee94759f94e2c11577f4c68426cea8d8c 100644 (file)
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -172,7 +172,7 @@ sync::
        repositories accordingly.
 +
 "git submodule sync" synchronizes all submodules while
-"git submodule sync -- A" synchronizes submodule "A" only.
+"git submodule sync \-- A" synchronizes submodule "A" only.
 
 OPTIONS
 -------

diff --git a/Documentation/git-web--browse.txt b/Documentation/git-web--browse.txt
index c0416e5e1a5243ef228173a3a45bb47bf1f3a840..a7b1201bbb18453ef6ba4f3db20901438d7086d9 100644 (file)
--- a/Documentation/git-web--browse.txt
+++ b/Documentation/git-web--browse.txt
@@ -68,7 +68,7 @@ browser.<tool>.path
 You can explicitly provide a full path to your preferred browser by
 setting the configuration variable 'browser.<tool>.path'. For example,
 you can configure the absolute path to firefox by setting
-'browser.firefox.path'. Otherwise, 'git web--browse' assumes the tool
+'browser.firefox.path'. Otherwise, 'git web{litdd}browse' assumes the tool
 is available in PATH.
 
 browser.<tool>.cmd

diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
index a9de9a74dc71e71e776cf1b7acd667d5c01582f7..97fd1d0e908b6d0f711147cf13604d1ac475faa0 100644 (file)
--- a/Documentation/rev-list-options.txt
+++ b/Documentation/rev-list-options.txt
@@ -268,7 +268,7 @@ that you are filtering for a file `foo` in this commit graph:
         \   /   /   /   /
          `-------------'
 -----------------------------------------------------------------------
-The horizontal line of history A--P is taken to be the first parent of
+The horizontal line of history A---P is taken to be the first parent of
 each merge.  The commits are:
 
 * `I` is the initial commit, in which `foo` exists with contents