From 565e135a1e5fc393f764415a4724f43cc07f4da6 Mon Sep 17 00:00:00 2001 From: Jonathan Nieder Date: Wed, 29 Jun 2011 00:35:10 -0500 Subject: [PATCH 1/2] 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 Improved-by: Junio C Hamano Improved-by: Jeff King Signed-off-by: Junio C Hamano --- 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 6babbc7837..c2ba535a0d 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -676,7 +676,7 @@ branch..rebase:: browser..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..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 8f89f6f08c..b9aa220db8 100644 --- 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 -- `, +to that of the last commit with `git reset HEAD \-- `, 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 d8df55362c..1441aec242 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 752fc88e76..ab994abdbd 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 - -- ` syntax. Take care with these alternatives as + \-- ` 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 e8ed2f2c0f..1649b9fee9 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 c0416e5e1a..a7b1201bbb 100644 --- a/Documentation/git-web--browse.txt +++ b/Documentation/git-web--browse.txt @@ -68,7 +68,7 @@ browser..path You can explicitly provide a full path to your preferred browser by setting the configuration variable 'browser..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..cmd diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index a9de9a74dc..97fd1d0e90 100644 --- 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 From 27269fc5f2781cd8f6e832043f9abf7305aa3d49 Mon Sep 17 00:00:00 2001 From: Jonathan Nieder Date: Wed, 29 Jun 2011 00:36:48 -0500 Subject: [PATCH 2/2] Documentation/i18n: quote double-dash for AsciiDoc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. 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 Acked-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano --- Documentation/git-sh-i18n--envsubst.txt | 10 +++++----- Documentation/git-sh-i18n.txt | 2 +- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/Documentation/git-sh-i18n--envsubst.txt b/Documentation/git-sh-i18n--envsubst.txt index 61e4c08dac..5c3ec327bb 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 ---- @@ -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 3b1f7ac7b5..eca69e3d82 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