[PATCH 1/2] Documentation/branch: split description into subsections

[Jonathan Nieder <jrnieder@gmail.com>]

Add headings for each form of the "git branch" command.  Hopefully
this will make the description easier to read straight through without
getting lost and help technical writers to see what needs improvement
in the treatment of each form.

Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
 Documentation/git-branch.txt |   53 +++++++++++++++++++++++------------------
 1 files changed, 30 insertions(+), 23 deletions(-)

diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
index 9106d38..d3eeb94 100644
--- a/Documentation/git-branch.txt
+++ b/Documentation/git-branch.txt
@@ -18,25 +18,30 @@ SYNOPSIS
 DESCRIPTION
 -----------
 
-With no arguments, existing branches are listed and the current branch will
-be highlighted with an asterisk.  Option `-r` causes the remote-tracking
-branches to be listed, and option `-a` shows both.
+'git branch' [-r | -a]::
+	With no arguments, existing branches are listed and the current
+	branch will be highlighted with an asterisk.
+	Option `-r` causes the remote-tracking branches to be listed,
+	and option `-a` shows both.
 
-With `--contains`, shows only the branches that contain the named commit
-(in other words, the branches whose tip commits are descendants of the
-named commit).  With `--merged`, only branches merged into the named
-commit (i.e. the branches whose tip commits are reachable from the named
-commit) will be listed.  With `--no-merged` only branches not merged into
-the named commit will be listed.  If the <commit> argument is missing it
-defaults to 'HEAD' (i.e. the tip of the current branch).
-
-The command's second form creates a new branch head named <branchname>
-which points to the current 'HEAD', or <start-point> if given.
+'git branch' (--contains | --merged | --no-merged) [<commit>]::
+	With `--contains`, shows only the branches that contain the
+	named commit (in other words, the branches whose tip commits are
+	descendants of the named commit).  With `--merged`, only
+	branches merged into the named commit (i.e. the branches whose
+	tip commits are reachable from the named commit) will be listed.
+	With `--no-merged` only branches not merged into the named
+	commit will be listed.  If the <commit> argument is missing it
+	defaults to 'HEAD' (i.e.  the tip of the current branch).
 
+'git branch' <branchname> [<start-point>]::
+	The command's second form creates a new branch head named <branchname>
+	which points to the current 'HEAD', or <start-point> if given.
++
 Note that this will create the new branch, but it will not switch the
 working tree to it; use "git checkout <newbranch>" to switch to the
 new branch.
-
++
 When a local branch is started off a remote-tracking branch, git sets up the
 branch so that 'git pull' will appropriately merge from
 the remote-tracking branch. This behavior may be changed via the global
@@ -44,16 +49,18 @@ the remote-tracking branch. This behavior may be changed via the global
 overridden by using the `--track` and `--no-track` options, and
 changed later using `git branch --set-upstream`.
 
-With a '-m' or '-M' option, <oldbranch> will be renamed to <newbranch>.
-If <oldbranch> had a corresponding reflog, it is renamed to match
-<newbranch>, and a reflog entry is created to remember the branch
-renaming. If <newbranch> exists, -M must be used to force the rename
-to happen.
-
-With a `-d` or `-D` option, `<branchname>` will be deleted.  You may
-specify more than one branch for deletion.  If the branch currently
-has a reflog then the reflog will also be deleted.
+'git branch' (-m | -M) <oldbranch> <newbranch>::
+	With a '-m' or '-M' option, <oldbranch> will be renamed to <newbranch>.
+	If <oldbranch> had a corresponding reflog, it is renamed to match
+	<newbranch>, and a reflog entry is created to remember the branch
+	renaming. If <newbranch> exists, -M must be used to force the rename
+	to happen.
 
+'git branch' (-d | -D) <branchname>::
+	With a `-d` or `-D` option, `<branchname>` will be deleted.  You may
+	specify more than one branch for deletion.  If the branch currently
+	has a reflog then the reflog will also be deleted.
++
 Use -r together with -d to delete remote-tracking branches. Note, that it
 only makes sense to delete remote-tracking branches if they no longer exist
 in the remote repository or if 'git fetch' was configured not to fetch
-- 
1.7.4.rc3