Merge branch 'maint' of git://linux-nfs.org/~bfields/git into maint

* 'maint' of git://linux-nfs.org/~bfields/git:
  user-manual: introduce "branch" and "branch head" differently
  glossary: clean up cross-references
  glossary: stop generating automatically
  user-manual: Use def_ instead of ref_ for glossary references.
  user-manual.txt: fix a tiny typo.
  user-manual: run xsltproc without --nonet option

1 files changed, 22 insertions, 26 deletions

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 0919574fb4..3ed9f84524 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -288,21 +288,22 @@ collection of files.  It stores the history as a compressed
 collection of interrelated snapshots (versions) of the project's
 contents.
 
-A single git repository may contain multiple branches.  Each branch
-is a bookmark referencing a particular point in the project history.
-The gitlink:git-branch[1] command shows you the list of branches:
+A single git repository may contain multiple branches.  It keeps track
+of them by keeping a list of <<def_head,heads>> which reference the
+latest version on each branch; the gitlink:git-branch[1] command shows
+you the list of branch heads:
 
 ------------------------------------------------
 $ git branch
 * master
 ------------------------------------------------
 
-A freshly cloned repository contains a single branch, named "master",
-and the working directory contains the version of the project
-referred to by the master branch.
+A freshly cloned repository contains a single branch head, named
+"master", and working directory is initialized to the state of
+the project referred to by "master".
 
-Most projects also use tags.  Tags, like branches, are references
-into the project's history, and can be listed using the
+Most projects also use <<def_tag,tags>>.  Tags, like heads, are
+references into the project's history, and can be listed using the
 gitlink:git-tag[1] command:
 
 ------------------------------------------------
@@ -320,9 +321,9 @@ v2.6.13
 ------------------------------------------------
 
 Tags are expected to always point at the same version of a project,
-while branches are expected to advance as development progresses.
+while heads are expected to advance as development progresses.
 
-Create a new branch pointing to one of these versions and check it
+Create a new branch head pointing to one of these versions and check it
 out using gitlink:git-checkout[1]:
 
 ------------------------------------------------
@@ -346,10 +347,10 @@ the current branch to point at v2.6.17 instead, with
 $ git reset --hard v2.6.17
 ------------------------------------------------
 
-Note that if the current branch was your only reference to a
+Note that if the current branch head was your only reference to a
 particular point in history, then resetting that branch may leave you
-with no way to find the history it used to point to; so use this
-command carefully.
+with no way to find the history it used to point to; so use this command
+carefully.
 
 Understanding History: Commits
 ------------------------------
@@ -452,17 +453,15 @@ be replaced with another letter or number.
 Understanding history: What is a branch?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Though we've been using the word "branch" to mean a kind of reference
-to a particular commit, the word branch is also commonly used to
-refer to the line of commits leading up to that point.  In the
-example above, git may think of the branch named "A" as just a
-pointer to one particular commit, but we may refer informally to the
-line of three commits leading up to that point as all being part of
+When we need to be precise, we will use the word "branch" to mean a line
+of development, and "branch head" (or just "head") to mean a reference
+to the most recent commit on a branch.  In the example above, the branch
+head named "A" is a pointer to one particular commit, but we refer to
+the line of three commits leading up to that point as all being part of
 "branch A".
 
-If we need to make it clear that we're just talking about the most
-recent commit on the branch, we may refer to that commit as the
-"head" of the branch.
+However, when no confusion will result, we often just use the term
+"branch" both for branches and for branch heads.
 
 Manipulating branches
 ---------------------
@@ -1698,7 +1697,7 @@ If you and maintainer both have accounts on the same machine, then
 then you can just pull changes from each other's repositories
 directly; note that all of the commands (gitlink:git-clone[1],
 git-fetch[1], git-pull[1], etc.) that accept a URL as an argument
-will also accept a local file patch; so, for example, you can
+will also accept a local directory name; so, for example, you can
 use
 
 -------------------------------------------------
@@ -3013,9 +3012,6 @@ confusing and scary messages, but it won't actually do anything bad. In
 contrast, running "git prune" while somebody is actively changing the 
 repository is a *BAD* idea).
 
-Glossary of git terms
-=====================
-
 include::glossary.txt[]
 
 Notes and todo list for this manual