From 6cf378f0cbe7c7f944637892caeb9058c90a185a Mon Sep 17 00:00:00 2001 From: Jeff King Date: Thu, 26 Apr 2012 04:51:57 -0400 Subject: docs: stop using asciidoc no-inline-literal In asciidoc 7, backticks like `foo` produced a typographic effect, but did not otherwise affect the syntax. In asciidoc 8, backticks introduce an "inline literal" inside which markup is not interpreted. To keep compatibility with existing documents, asciidoc 8 has a "no-inline-literal" attribute to keep the old behavior. We enabled this so that the documentation could be built on either version. It has been several years now, and asciidoc 7 is no longer in wide use. We can now decide whether or not we want inline literals on their own merits, which are: 1. The source is much easier to read when the literal contains punctuation. You can use `master~1` instead of `master{tilde}1`. 2. They are less error-prone. Because of point (1), we tend to make mistakes and forget the extra layer of quoting. This patch removes the no-inline-literal attribute from the Makefile and converts every use of backticks in the documentation to an inline literal (they must be cleaned up, or the example above would literally show "{tilde}" in the output). Problematic sites were found by grepping for '`.*[{\\]' and examined and fixed manually. The results were then verified by comparing the output of "html2text" on the set of generated html pages. Doing so revealed that in addition to making the source more readable, this patch fixes several formatting bugs: - HTML rendering used the ellipsis character instead of literal "..." in code examples (like "git log A...B") - some code examples used the right-arrow character instead of '->' because they failed to quote - api-config.txt did not quote tilde, and the resulting HTML contained a bogus snippet like: foo bar which caused some parsers to choke and omit whole sections of the page. - git-commit.txt confused ``foo`` (backticks inside a literal) with ``foo'' (matched double-quotes) - mentions of `A U Thor ` used to erroneously auto-generate a mailto footnote for author@example.com - the description of --word-diff=plain incorrectly showed the output as "[-removed-] and {added}", not "{+added+}". - using "prime" notation like: commit `C` and its replacement `C'` confused asciidoc into thinking that everything between the first backtick and the final apostrophe were meant to be inside matched quotes - asciidoc got confused by the escaping of some of our asterisks. In particular, `credential.\*` and `credential..\*` properly escaped the asterisk in the first case, but literally passed through the backslash in the second case. Signed-off-by: Jeff King Signed-off-by: Junio C Hamano --- Documentation/gitworkflows.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation/gitworkflows.txt') diff --git a/Documentation/gitworkflows.txt b/Documentation/gitworkflows.txt index 5e4f362ff8..8b8c6ae5d3 100644 --- a/Documentation/gitworkflows.txt +++ b/Documentation/gitworkflows.txt @@ -39,8 +39,8 @@ To achieve this, try to split your work into small steps from the very beginning. It is always easier to squash a few commits together than to split one big commit into several. Don't be afraid of making too small or imperfect steps along the way. You can always go back later -and edit the commits with `git rebase \--interactive` before you -publish them. You can use `git stash save \--keep-index` to run the +and edit the commits with `git rebase --interactive` before you +publish them. You can use `git stash save --keep-index` to run the test suite independent of other uncommitted changes; see the EXAMPLES section of linkgit:git-stash[1]. -- cgit v1.2.1 From 48a8c26c625a4d3631c4f614bceb38933e741408 Mon Sep 17 00:00:00 2001 From: Thomas Ackermann Date: Mon, 21 Jan 2013 20:16:20 +0100 Subject: Documentation: avoid poor-man's small caps GIT In the earlier days, we used to spell the name of the system as GIT, to simulate as if it were typeset with capital G and IT in small caps. Later we stopped doing so at around 1.6.5 days. Let's stop doing so throughout the documentation. The name to refer to the whole system (and the concept it embodies) is "Git"; the command end-users type is "git". And document this in the coding guideline. Signed-off-by: Thomas Ackermann Signed-off-by: Junio C Hamano --- Documentation/gitworkflows.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/gitworkflows.txt') diff --git a/Documentation/gitworkflows.txt b/Documentation/gitworkflows.txt index 8b8c6ae5d3..e2e7d65c08 100644 --- a/Documentation/gitworkflows.txt +++ b/Documentation/gitworkflows.txt @@ -242,7 +242,7 @@ tag to the tip of 'master' indicating the release version: .Release tagging [caption="Recipe: "] ===================================== -`git tag -s -m "GIT X.Y.Z" vX.Y.Z master` +`git tag -s -m "Git X.Y.Z" vX.Y.Z master` ===================================== You need to push the new tag to a public git server (see -- cgit v1.2.1 From 2de9b71138171dca7279db3b3fe67e868c76d921 Mon Sep 17 00:00:00 2001 From: Thomas Ackermann Date: Mon, 21 Jan 2013 20:17:53 +0100 Subject: Documentation: the name of the system is 'Git', not 'git' Signed-off-by: Thomas Ackermann Signed-off-by: Junio C Hamano --- Documentation/gitworkflows.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'Documentation/gitworkflows.txt') diff --git a/Documentation/gitworkflows.txt b/Documentation/gitworkflows.txt index e2e7d65c08..f16c414ea7 100644 --- a/Documentation/gitworkflows.txt +++ b/Documentation/gitworkflows.txt @@ -3,7 +3,7 @@ gitworkflows(7) NAME ---- -gitworkflows - An overview of recommended workflows with git +gitworkflows - An overview of recommended workflows with Git SYNOPSIS -------- @@ -245,7 +245,7 @@ tag to the tip of 'master' indicating the release version: `git tag -s -m "Git X.Y.Z" vX.Y.Z master` ===================================== -You need to push the new tag to a public git server (see +You need to push the new tag to a public Git server (see "DISTRIBUTED WORKFLOWS" below). This makes the tag available to others tracking your project. The push could also trigger a post-update hook to perform release-related items such as building -- cgit v1.2.1