[PATCH] Documentation: quote double-dash in "<commit> -- <filename>" for AsciiDoc

[PATCH] Documentation: quote double-dash in "<commit> -- <filename>" for AsciiDoc

[Jonathan Nieder]

As explained in v1.7.3-rc0~13^2 (Work around em-dash handling in newer
AsciiDoc, 2010-08-23), outside of verbatim environments, newish
versions of AsciiDoc will convert double hyphens to en dashes.  Use
the litdd syntax introduced by that patch to avoid such misformatting
in sentences where "--" represents the two-character "end of options"
argument that separates revision names from filename patterns.

Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
 Documentation/git-commit.txt |    2 +-
 Documentation/git-revert.txt |    2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
index 7951cb7b..1764cf10 100644
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt
@@ -284,7 +284,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 {litdd} <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-revert.txt b/Documentation/git-revert.txt
index ac10cfbb..a516d577 100644
--- 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> {litdd} <filename>` syntax.  Take care with these alternatives as
 both will discard uncommitted changes in your working directory.
 
 OPTIONS
-- 
1.7.6.rc3

Re: [PATCH] Documentation: quote double-dash in "<commit> -- <filename>" for AsciiDoc

[Junio C Hamano]

Jonathan Nieder <jrnieder@gmail.com> writes:

> As explained in v1.7.3-rc0~13^2 (Work around em-dash handling in newer
> AsciiDoc, 2010-08-23), outside of verbatim environments, newish
> versions of AsciiDoc will convert double hyphens to en dashes.  Use
> the litdd syntax introduced by that patch to avoid such misformatting
> in sentences where "--" represents the two-character "end of options"
> argument that separates revision names from filename patterns.

Thanks.

This looks very bad:

    $ cd $git/share/man
    $ grep -l '(em ' */*.?

even though we do want em-dash for some hits in the above output.  And
even worse, there seem to be exceptions to this rule, like ...

> diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt
> index ac10cfbb..a516d577 100644
> --- 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

... the one before "hard" above.

Re: [PATCH] Documentation: quote double-dash in "<commit> -- <filename>" for AsciiDoc

[Jonathan Nieder]

Hi,

Junio C Hamano wrote:

> This looks very bad:
> 
>     $ cd $git/share/man
>     $ grep -l '(em ' */*.?
>
> even though we do want em-dash for some hits in the above output.

True.  Based on a glance at /usr/share/man, the patch misses:

 git-submodule.1: "git submodule sync -- A"
 various: git web--browse, git-mergetool--lib, git sh-i18n--envsubst
 rev-list options: history `A--P`

> And
> even worse, there seem to be exceptions to this rule, like ...
>
>> diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt
>> index ac10cfbb..a516d577 100644
>> --- 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

Sloppy of me.  For reference, here's the rule from asciidoc.conf.

	# -- Spaced and unspaced em dashes (entity reference —).
	# Space on both sides is translated to thin space characters.
	(^-- )=— 
	(\n-- )|( -- )|( --\n)= — 
	(\w)--(\w)=\1—\2
	\\--(?!-)=--

So:

 - "\--" always represents two dashes, unless followed by another
   minus sign.  There is no obvious technical reason to prefer {litdd}
   over \-- or vice versa.

 - options like "--hard" are safe nowadays (though it's equally safe
   to escape them as "\--hard").  Likewise, the trailing "--" in
   "foo--" is left unmolested.

 - before version 8.3.0[*], no unescaped "--" was safe for HTML output.
   They all would be converted to em dashes.

Will prepare a new patch that takes care of the missed spots using \--
except in cases like "git web{litdd}browse", to roughly follow the
existing style.  If someone wants to change those to "git web\--browse"
with a patch on top, I won't mind.

Thanks, both.

Regards,
Jonathan

[*] Quick history:

 - asciidoc 8.4.1
 - [98be31f1] line 1 (^-- ) is added ("Emdash replacement recognized at
   start of block")
 - asciidoc 8.3.5
 - asciidoc 8.3.0
 - [6e71157d] line 3 ((\w)--(\w)) is introduced.  It replaces the
   previous regex (\n|[^-\s\\])--([^-\s]|\n), which had been guarded by
   "ifndef::doctype-manpage" to mitigate the effect of false positives.
 - [46fbb7b7] The overeager pattern ([^\n \\])--([^-\s])=\1—\2
   guarded by "ifdef::doctype-manpage" is removed, since it has too
   many false positives ("Allow unescaped -- option prefixes in man
   pages (was not working in all situations)")
 - [12032332] Patterns start to capture surrounding whitespace so it
   can be converted to thin space.  In this spirit, the second line
   ((\n-- )|( -- )| --\n)) is introduced, the pattern
   (^|[^-\\])--($|[^-]) guarded by "ifndef::doctype-manpage" changes
   to (\n|[^-\s\\])--([^-\s]|\n), and the pattern (^|\s*[^\S\\])--($|\s+)
   guarded by "ifdef::doctype-manpage" changes to ([^\n \\])--([^-\s]).
 - asciidoc 8.2.7
 - asciidoc 8.2.4
 - asciidoc migrates from svn to mercurial (i.e., beginning of
   history).

Pre-history (from CHANGELOG.txt):

 - asciidoc 7.0.0: "Manpage command names containing dashes (in the
   manpage NAME section) were misinterpreted as the spaced dash
   command name/purpose separator.  Bug report and patch supplied by
   David Greaves"
 - asciidoc 6.0.3: "Spaced and unspaced em dashes are now recognized
   (previously only spaced em dashes were recognized)."
 - asciidoc 5.0.6: "A replacement has been added to `asciidoc.conf` to
   replace inline double dashes with the `—` entity."

Re: [PATCH] Documentation: quote double-dash in "<commit> -- <filename>" for AsciiDoc

[Jeff King]

On Tue, Jun 28, 2011 at 12:17:49PM -0500, Jonathan Nieder wrote:

> As explained in v1.7.3-rc0~13^2 (Work around em-dash handling in newer
> AsciiDoc, 2010-08-23), outside of verbatim environments, newish
> versions of AsciiDoc will convert double hyphens to en dashes.  Use
> the litdd syntax introduced by that patch to avoid such misformatting
> in sentences where "--" represents the two-character "end of options"
> argument that separates revision names from filename patterns.

Ugh. I just did a similar thing for "->". I really wish asciidoc would
not expand symbols inside backticks in paragraph mode.

> -to that of the last commit with `git reset HEAD -- <file>`,
> +to that of the last commit with `git reset HEAD {litdd} <file>`,

Does \-- work? That seems way more readable to me for people viewing the
source.

-Peff

[PATCH v2 0/2] Documentation: quote double-dash for AsciiDoc

[Jonathan Nieder]

Hi,

Thanks to Peff and Junio for comments.  This version is split into two
patches: the first applies to "maint", the second "master".

Jonathan Nieder (2):
  Documentation: quote double-dash for AsciiDoc
  Documentation/i18n: quote double-dash for AsciiDoc

 Documentation/config.txt                |    2 +-
 Documentation/git-commit.txt            |    2 +-
 Documentation/git-mergetool--lib.txt    |    2 +-
 Documentation/git-revert.txt            |    2 +-
 Documentation/git-sh-i18n--envsubst.txt |    6 +++---
 Documentation/git-sh-i18n.txt           |    2 +-
 Documentation/git-submodule.txt         |    2 +-
 Documentation/git-web--browse.txt       |    2 +-
 Documentation/rev-list-options.txt      |    2 +-
 9 files changed, 11 insertions(+), 11 deletions(-)

-- 
1.7.6

[PATCH 1/2 maint] Documentation: quote double-dash for AsciiDoc

[Jonathan Nieder]

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>
---
Changes since v1:

 - clearer description
 - using "git checkout <commit> \-- <filename>" instead of litdd
   for easier reading (but still git-web{litdd}browse for consistency
   with existing markup)

Simplifications to the above description would be very welcome.

 Documentation/config.txt             |    2 +-
 Documentation/git-commit.txt         |    2 +-
 Documentation/git-mergetool--lib.txt |    2 +-
 Documentation/git-revert.txt         |    2 +-
 Documentation/git-submodule.txt      |    2 +-
 Documentation/git-web--browse.txt    |    2 +-
 Documentation/rev-list-options.txt   |    2 +-
 7 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index d1613621..4682fbbb 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -674,7 +674,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 d0534b8c..872cb04a 100644
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt
@@ -276,7 +276,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 63ededec..5b0d51f7 100644
--- 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 ac10cfbb..6a21b37f 100644
--- 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 1a16ff60..6ae6fd88 100644
--- 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 69d92fa0..9b0d1fe3 100644
--- 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 73111bb0..5b29ad39 100644
--- a/Documentation/rev-list-options.txt
+++ b/Documentation/rev-list-options.txt
@@ -309,7 +309,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
-- 
1.7.6

[PATCH 2/2] Documentation/i18n: quote double-dash for AsciiDoc

[Jonathan Nieder]

As explained in v1.7.3-rc0~13^2 (Work around em-dash handling in newer
AsciiDoc, 2010-08-23), if double dashes in names of commands are not
escaped, AsciiDoc renders them as em dashes.

While fixing that, spell the command name as "git sh-i18n--envsubst"
(2 words) instead of emphasizing the name of the binary (one
hyphenated name) and format it in italics.

Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
Thanks for reading.

 Documentation/git-sh-i18n--envsubst.txt |    6 +++---
 Documentation/git-sh-i18n.txt           |    2 +-
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/Documentation/git-sh-i18n--envsubst.txt b/Documentation/git-sh-i18n--envsubst.txt
index 61e4c08d..6e3a9539 100644
--- a/Documentation/git-sh-i18n--envsubst.txt
+++ b/Documentation/git-sh-i18n--envsubst.txt
@@ -10,8 +10,8 @@ SYNOPSIS
 [verse]
 eval_gettext () {
 	printf "%s" "$1" | (
-		export PATH $('git sh-i18n--envsubst' --variables "$1");
-		'git sh-i18n--envsubst' "$1"
+		export PATH $('git sh-i18n{litdd}envsubst' --variables "$1");
+		'git sh-i18n{litdd}envsubst' "$1"
 	)
 }
 
@@ -22,7 +22,7 @@ This is not a command the end user would want to run.  Ever.
 This documentation is meant for people who are studying the
 plumbing scripts and/or are writing new ones.
 
-git-sh-i18n--envsubst is Git's stripped-down copy of the GNU
+'git sh-i18n{litdd}envsubst' is Git's stripped-down copy of the GNU
 `envsubst(1)` program that comes with the GNU gettext package. It's
 used internally by linkgit:git-sh-i18n[1] to interpolate the variables
 passed to the the `eval_gettext` function.
diff --git a/Documentation/git-sh-i18n.txt b/Documentation/git-sh-i18n.txt
index 3b1f7ac7..eca69e3d 100644
--- a/Documentation/git-sh-i18n.txt
+++ b/Documentation/git-sh-i18n.txt
@@ -34,7 +34,7 @@ gettext::
 eval_gettext::
 	Currently a dummy fall-through function implemented as a wrapper
 	around `printf(1)` with variables expanded by the
-	linkgit:git-sh-i18n--envsubst[1] helper. Will be replaced by a
+	linkgit:git-sh-i18n{litdd}envsubst[1] helper. Will be replaced by a
 	real gettext implementation in a later version.
 
 GIT
-- 
1.7.6

Re: [PATCH 2/2] Documentation/i18n: quote double-dash for AsciiDoc

[Ævar Arnfjörð Bjarmason]

On Wed, Jun 29, 2011 at 07:36, Jonathan Nieder <jrnieder@gmail.com> wrote:
> As explained in v1.7.3-rc0~13^2 (Work around em-dash handling in newer
> AsciiDoc, 2010-08-23), if double dashes in names of commands are not
> escaped, AsciiDoc renders them as em dashes.
>
> While fixing that, spell the command name as "git sh-i18n--envsubst"
> (2 words) instead of emphasizing the name of the binary (one
> hyphenated name) and format it in italics.

Thanks for fixing this, looks good to me.

[PATCH] fixup! Documentation/i18n: quote double-dash for AsciiDoc

[Jonathan Nieder]

The double-dash in the title should be escaped, too, to avoid spurious
em dashes in the header:

	.TH "GIT\-SH\-I18N\(emENVSUB" "1" "06/26/2011" "Git 1\&.7\&.6" "Git Manual"

AsciiDoc 8.6.4 with DocBook XSL 1.76.0-RC1 copes fine and writes
"GIT\-SH\-I18N\-\-ENVSUB" even without this change, which is why it
was missed before.

Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
 Documentation/git-sh-i18n--envsubst.txt |    4 ++--
 1 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-sh-i18n--envsubst.txt b/Documentation/git-sh-i18n--envsubst.txt
index 6e3a9539..5c3ec327 100644
--- a/Documentation/git-sh-i18n--envsubst.txt
+++ b/Documentation/git-sh-i18n--envsubst.txt
@@ -1,5 +1,5 @@
-git-sh-i18n--envsubst(1)
-========================
+git-sh-i18n{litdd}envsubst(1)
+=============================
 
 NAME
 ----
-- 
1.7.6