@matheusbsbs / matheus-bagliano / commits / 565e135a1e

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>

Jonathan Nieder committed Jun 29, 2011 at 00:35 UTC 565e135a1e5fc393f764415a4724f43cc07f4da6

7 files changed +7 -7

Documentation/config.txt

+1 -1

@@ -676,7 +676,7 @@ branch.<name>.rebase::

676 browser.<tool>.cmd::

677 Specify the command to invoke the specified browser. The

678 specified command is evaluated in shell with the URLs passed

679 - as arguments. (See linkgit:git-web--browse[1].)

679 + as arguments. (See linkgit:git-web{litdd}browse[1].)

680

681 browser.<tool>.path::

682 Override the path for the given tool that may be used to

Documentation/git-commit.txt

+1 -1

@@ -275,7 +275,7 @@ When recording your own work, the contents of modified files in

275 your working tree are temporarily stored to a staging area

276 called the "index" with 'git add'. A file can be

277 reverted back, only in the index but not in the working tree,

278 -to that of the last commit with `git reset HEAD -- <file>`,

278 +to that of the last commit with `git reset HEAD \-- <file>`,

279 which effectively reverts 'git add' and prevents the changes to

280 this file from participating in the next commit. After building

281 the state to be committed incrementally with these commands,

Documentation/git-mergetool--lib.txt

+1 -1

@@ -7,7 +7,7 @@ git-mergetool--lib - Common git merge tool shell scriptlets

8 SYNOPSIS

9 --------

10 -'TOOL_MODE=(diff|merge) . "$(git --exec-path)/git-mergetool--lib"'

10 +'TOOL_MODE=(diff|merge) . "$(git --exec-path)/git-mergetool{litdd}lib"'

12 DESCRIPTION

13 -----------

Documentation/git-revert.txt

+1 -1

@@ -23,7 +23,7 @@ throw away all uncommitted changes in your working directory, you

23 should see linkgit:git-reset[1], particularly the '--hard' option. If

24 you want to extract specific files as they were in another commit, you

25 should see linkgit:git-checkout[1], specifically the `git checkout

26 -<commit> -- <filename>` syntax. Take care with these alternatives as

26 +<commit> \-- <filename>` syntax. Take care with these alternatives as

27 both will discard uncommitted changes in your working directory.

29 OPTIONS

Documentation/git-submodule.txt

+1 -1

@@ -172,7 +172,7 @@ sync::

172 repositories accordingly.

173 +

174 "git submodule sync" synchronizes all submodules while

175 -"git submodule sync -- A" synchronizes submodule "A" only.

175 +"git submodule sync \-- A" synchronizes submodule "A" only.

176

177 OPTIONS

178 -------

Documentation/git-web--browse.txt

+1 -1

@@ -68,7 +68,7 @@ browser.<tool>.path

68 You can explicitly provide a full path to your preferred browser by

69 setting the configuration variable 'browser.<tool>.path'. For example,

70 you can configure the absolute path to firefox by setting

71 -'browser.firefox.path'. Otherwise, 'git web--browse' assumes the tool

71 +'browser.firefox.path'. Otherwise, 'git web{litdd}browse' assumes the tool

72 is available in PATH.

74 browser.<tool>.cmd

Documentation/rev-list-options.txt

+1 -1

@@ -268,7 +268,7 @@ that you are filtering for a file `foo` in this commit graph:

268 \ / / / /

269 `-------------'

270 -----------------------------------------------------------------------

271 -The horizontal line of history A--P is taken to be the first parent of

271 +The horizontal line of history A---P is taken to be the first parent of

272 each merge. The commits are:

273

274 * `I` is the initial commit, in which `foo` exists with contents