[PATCH] Random documentation fixes

The fixes focuses on improving the HTML output. Most noteworthy:

 - Fix the Makefile to also make various *.html files depend on
   included files.

 - Consistently use 'NOTE: ...' instead of '[ ... ]' for additional
   info.

 - Fix ending '::' for description lists in OPTION section etc.

 - Fix paragraphs in description lists ending up as preformated text.

 - Always use listingblocks (preformatted text wrapped in lines with -----)
   for examples that span empty lines, so they are put in only one HTML
   block.

 - Use '1.' instead of '(1)' for numbered lists.

 - Fix linking to other GIT docs.

 - git-rev-list.txt: put option descriptions in an OPTION section.

Signed-off-by: Jonas Fonseca <fonseca@diku.dk>
Signed-off-by: Junio C Hamano <junkio@cox.net>

Documentation/Makefile

@@ -53,6 +53,9 @@ install: man
 $(patsubst %.txt,%.1,$(wildcard git-diff-*.txt)): \
 	diff-format.txt diff-options.txt
 $(patsubst %,%.1,git-fetch git-pull git-push): pull-fetch-param.txt
+$(patsubst %.txt,%.html,$(wildcard git-diff-*.txt)): \
+	diff-format.txt diff-options.txt
+$(patsubst %,%.html,git-fetch git-pull git-push): pull-fetch-param.txt
 git.7: ../README
 
 clean:

Documentation/cvs-migration.txt

@@ -229,10 +229,10 @@ does rename or copy would not show in the output, and if the
 "o-file.c", it would find the commit that changed the statement
 when it was in "o-file.c".
 
-[ BTW, the current versions of "git-diff-tree -C" is not eager
+NOTE: The current versions of "git-diff-tree -C" is not eager
   enough to find copies, and it will miss the fact that a-file.c
   was created by copying o-file.c unless o-file.c was somehow
-  changed in the same commit.]
+  changed in the same commit.
 
 You can use the --pickaxe-all flag in addition to the -S flag.
 This causes the differences from all the files contained in
@@ -243,6 +243,6 @@ that contain this changed "if" statement:
 		nitfol();
 	}' --pickaxe-all
 
-[ Side note.  This option is called "--pickaxe-all" because -S
+NOTE: This option is called "--pickaxe-all" because -S
   option is internally called "pickaxe", a tool for software
-  archaeologists.]
+  archaeologists.

Documentation/diffcore.txt

@@ -254,11 +254,11 @@ As an example, typical orderfile for the core GIT probably
 would look like this:
 
 ------------------------------------------------
-    README
-    Makefile
-    Documentation
-    *.h
-    *.c
-    t
+README
+Makefile
+Documentation
+*.h
+*.c
+t
 ------------------------------------------------
 

Documentation/git-applypatch.txt

@@ -30,7 +30,7 @@ OPTIONS
 <patch>::
 	The patch to apply.
 
-<info>:
+<info>::
 	Author and subject information extracted from e-mail,
 	used on "author" line and as the first line of the
 	commit log message.

Documentation/git-bisect.txt

@@ -91,7 +91,7 @@ Author
 Written by Linus Torvalds <torvalds@osdl.org>
 
 Documentation
---------------
+-------------
 Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
 
 GIT

Documentation/git-cherry-pick.txt

@@ -38,9 +38,9 @@ OPTIONS
 	option is used, your working tree does not have to match
 	the HEAD commit.  The cherry-pick is done against the
 	beginning state of your working tree.
-
-	This is useful when cherry-picking more than one commits'
-	effect to your working tree in a row.
++
+This is useful when cherry-picking more than one commits'
+effect to your working tree in a row.
 
 
 Author

Documentation/git-commit-tree.txt

@@ -58,11 +58,11 @@ following environment variables.
 	GIT_COMMITTER_NAME
 	GIT_COMMITTER_EMAIL
 
-(nb <,> and '\n's are stripped)
+(nb "<", ">" and "\n"s are stripped)
 
 A commit comment is read from stdin (max 999 chars). If a changelog
-entry is not provided via '<' redirection, "git-commit-tree" will just wait
-for one to be entered and terminated with ^D
+entry is not provided via "<" redirection, "git-commit-tree" will just wait
+for one to be entered and terminated with ^D.
 
 Diagnostics
 -----------

Documentation/git-cvsimport.txt

@@ -51,15 +51,15 @@ OPTIONS
 	The 'HEAD' branch from CVS is imported to the 'origin' branch within
 	the git repository, as 'HEAD' already has a special meaning for git.
 	Use this option if you want to import into a different branch.
-
-	Use '-o master' for continuing an import that was initially done by
-	the old cvs2git tool.
++
+Use '-o master' for continuing an import that was initially done by
+the old cvs2git tool.
 
 -p <options-for-cvsps>::
 	Additional options for cvsps.
 	The options '-u' and '-A' are implicit and should not be used here.
-
-	If you need to pass multiple options, separate them with a comma.
++
+If you need to pass multiple options, separate them with a comma.
 
 -m::    
 	Attempt to detect merges based on the commit message. This option

Documentation/git-diff-index.txt

@@ -86,8 +86,8 @@ the more useful of the two in that what it does can't be emulated with
 a "git-write-tree" + "git-diff-tree". Thus that's the default mode.
 The non-cached version asks the question:
 
-   show me the differences between HEAD and the currently checked out
-   tree - index contents _and_ files that aren't up-to-date
+  show me the differences between HEAD and the currently checked out
+  tree - index contents _and_ files that aren't up-to-date
 
 which is obviously a very useful question too, since that tells you what
 you *could* commit. Again, the output matches the "git-diff-tree -r"
@@ -107,13 +107,13 @@ not up-to-date and may contain new stuff. The all-zero sha1 means that to
 get the real diff, you need to look at the object in the working directory
 directly rather than do an object-to-object diff.
 
-NOTE! As with other commands of this type, "git-diff-index" does not
+NOTE: As with other commands of this type, "git-diff-index" does not
 actually look at the contents of the file at all. So maybe
 `kernel/sched.c` hasn't actually changed, and it's just that you
 touched it. In either case, it's a note that you need to
 "git-upate-cache" it to make the cache be in sync.
 
-NOTE 2! You can have a mixture of files show up as "has been updated"
+NOTE: You can have a mixture of files show up as "has been updated"
 and "is still dirty in the working directory" together. You can always
 tell which file is in which state, since the "has been updated" ones
 show a valid sha1, and the "not in sync with the index" ones will

Documentation/git-diff-tree.txt

@@ -101,16 +101,18 @@ An example of normal usage is:
 which tells you that the last commit changed just one file (it's from
 this one:
 
-  commit 3c6f7ca19ad4043e9e72fa94106f352897e651a8
-  tree 5319e4d609cdd282069cc4dce33c1db559539b03
-  parent b4e628ea30d5ab3606119d2ea5caeab141d38df7
-  author Linus Torvalds <torvalds@ppc970.osdl.org> Sat Apr 9 12:02:30 2005
-  committer Linus Torvalds <torvalds@ppc970.osdl.org> Sat Apr 9 12:02:30 2005
-
-  Make "git-fsck-objects" print out all the root commits it finds.
-
-  Once I do the reference tracking, I'll also make it print out all the
-  HEAD commits it finds, which is even more interesting.
+-----------------------------------------------------------------------------
+commit 3c6f7ca19ad4043e9e72fa94106f352897e651a8
+tree 5319e4d609cdd282069cc4dce33c1db559539b03
+parent b4e628ea30d5ab3606119d2ea5caeab141d38df7
+author Linus Torvalds <torvalds@ppc970.osdl.org> Sat Apr 9 12:02:30 2005
+committer Linus Torvalds <torvalds@ppc970.osdl.org> Sat Apr 9 12:02:30 2005
+
+Make "git-fsck-objects" print out all the root commits it finds.
+
+Once I do the reference tracking, I'll also make it print out all the
+HEAD commits it finds, which is even more interesting.
+-----------------------------------------------------------------------------
 
 in case you care).
 

Documentation/git-fetch.txt

@@ -39,7 +39,7 @@ Written by Linus Torvalds <torvalds@osdl.org> and
 Junio C Hamano <junkio@cox.net>
 
 Documentation
---------------
+-------------
 Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
 
 GIT

Documentation/git-fsck-objects.txt

@@ -19,9 +19,9 @@ OPTIONS
 -------
 <object>::
 	An object to treat as the head of an unreachability trace.
-
-	If no objects are given, git-fsck-objects defaults to using the
-	index file and all SHA1 references in .git/refs/* as heads.
++
+If no objects are given, git-fsck-objects defaults to using the
+index file and all SHA1 references in .git/refs/* as heads.
 
 --unreachable::
 	Print out objects that exist but that aren't readable from any
@@ -128,7 +128,7 @@ GIT_OBJECT_DIRECTORY::
 GIT_INDEX_FILE::
 	used to specify the index file of the cache
 
-GIT_ALTERNATE_OBJECT_DIRECTORIES:
+GIT_ALTERNATE_OBJECT_DIRECTORIES::
 	used to specify additional object database roots (usually unset)
 
 Author

Documentation/git-ls-files.txt

@@ -70,11 +70,11 @@ OPTIONS
 -t::
 	Identify the file status with the following tags (followed by
 	a space) at the start of each line:
-	H	cached
-	M	unmerged
-	R	removed/deleted
-	C	modifed/changed
-	K	to be killed
+	H::	cached
+	M::	unmerged
+	R::	removed/deleted
+	C::	modifed/changed
+	K::	to be killed
 	?	other
 
 --::
@@ -110,13 +110,13 @@ flags --others or --ignored are specified.
 
 These exclude patterns come from these places:
 
- (1) command line flag --exclude=<pattern> specifies a single
+  1. command line flag --exclude=<pattern> specifies a single
      pattern.
 
- (2) command line flag --exclude-from=<file> specifies a list of
+  2. command line flag --exclude-from=<file> specifies a list of
      patterns stored in a file.
 
- (3) command line flag --exclude-per-directory=<name> specifies
+  3. command line flag --exclude-per-directory=<name> specifies
      a name of the file in each directory 'git-ls-files'
      examines, and if exists, its contents are used as an
      additional list of patterns.
@@ -168,12 +168,13 @@ An exclude pattern is of the following format:
  - otherwise, it is a shell glob pattern, suitable for
    consumption by fnmatch(3) with FNM_PATHNAME flag.  I.e. a
    slash in the pattern must match a slash in the pathname.
-   "Documentation/*.html" matches "Documentation/git.html" but
+   "Documentation/\*.html" matches "Documentation/git.html" but
    not "ppc/ppc.html".  As a natural exception, "/*.c" matches
    "cat-file.c" but not "mozilla-sha1/sha1.c".
 
 An example:
 
+--------------------------------------------------------------
     $ cat .git/ignore
     # ignore objects and archives, anywhere in the tree.
     *.[oa]
@@ -186,6 +187,7 @@ An example:
         --exclude='Documentation/*.[0-9]' \
         --exclude-from=.git/ignore \
         --exclude-per-directory=.gitignore
+--------------------------------------------------------------
 
 
 See Also

Documentation/git-pack-objects.txt

@@ -76,7 +76,8 @@ Documentation by Junio C Hamano
 
 See-Also
 --------
-git-repack(1) git-prune-packed(1)
+gitlink:git-repack[1]
+gitlink:git-prune-packed[1]
 
 GIT
 ---

Documentation/git-prune-packed.txt

@@ -34,7 +34,8 @@ Documentation by Ryan Anderson <ryan@michonline.com>
 
 See-Also
 --------
-git-pack-objects(1) git-repack(1)
+gitlink:git-pack-objects[1]
+gitlink:git-repack[1]
 
 GIT
 ---

Documentation/git-read-tree.txt

@@ -84,10 +84,10 @@ fast forward situation).
 When two trees are specified, the user is telling git-read-tree
 the following:
 
-    (1) The current index and work tree is derived from $H, but
+     1. The current index and work tree is derived from $H, but
         the user may have local changes in them since $H;
 
-    (2) The user wants to fast-forward to $M.
+     2. The user wants to fast-forward to $M.
 
 In this case, the "git-read-tree -m $H $M" command makes sure
 that no local change is lost as the result of this "merge".

Documentation/git-repack.txt

@@ -51,7 +51,8 @@ Documentation by Ryan Anderson <ryan@michonline.com>
 
 See-Also
 --------
-git-pack-objects(1) git-prune-packed(1)
+gitlink:git-pack-objects[1]
+gitlink:git-prune-packed[1]
 
 GIT
 ---