Re: Documentation (mostly user manual) patches

From: Ramsay Jones <ramsay@ramsay1.demon.co.uk>
Date: Mar 7, 2007, 20:19 UTC
Message-ID: <45EF1E65.6000208@ramsay1.demon.co.uk>
In-Reply-To: <1173045556191-git-send-email-bfields@citi.umich.edu>

J. Bruce Fields wrote:

Show 7 quoted lines

> Sorry for the long silence.  You can also get these by pulling from
> 
> 	git://linux-nfs.org/~bfields/git.git
> 
> if you'd prefer.
> 
> --b.

I've just been reading the user manual (from the 1.5.0 tarball) for the first time and noticed a few things which might need fixing up. (Great work on the manual, BTW!)

Unfortunately, I don't have asciidoc or xmlto installed (I'm on Cygwin), so I can't re-build the documentation to test any changes; and I don't know how to use asciidoc markup anyway. ;-)

First, most history diagrams appear to be broken; this is due to the "\<lf>" combination in the diagrams being interpreted as a line continuation! I don't know what the asciidoc markup should be - \\ perhaps? The following indicates that there are nine diagrams needing fixup:

    $ grep '\\$' Documentation/user-manual.txt | wc
          9      12     118
    $

In the "Fetching branches from other repositories" section, the content of the configuration file displayed did not appear correct, given the text above. In fact, both the url and fetch keys seem to be wrong; I'm assuming something like the following was intended:

--->8---

@@ -596,8 +596,8 @@ a new stanza:
  $ cat .git/config
  ...
  [remote "linux-nfs"]
-        url = git://linux-nfs.org/~bfields/git.git
-	fetch = +refs/heads/*:refs/remotes/linux-nfs-read/*
+        url = git://linux-nfs.org/pub/nfs-2.6.git
+	fetch = +refs/heads/*:refs/remotes/linux-nfs/*
  ...
  -------------------------------------------------
---8<---

In chapter 4, "How to merge" section, a git pull invocation is demonstrated; I
suspect that a git merge was intended, thus:

--->8---
@@ -1128,7 +1128,7 @@ modified in two different ways in the remote branch and the local
  branch--then you are warned; the output may look something like this:

  -------------------------------------------------
-$ git pull . next
+$ git merge next
  Trying really trivial in-index merge...
  fatal: Merge requires file-level merging
  Nope.
---8<---

Having said that, does the command output need changing also?

In "Checking out an old version of a file", a git show invocation seems
to be missing a ":" between the <commit-ish> and the path, thus:

--->8---
@@ -1376,7 +1376,7 @@ modifying the working directory, you can do that with
  gitlink:git-show[1]:

  -------------------------------------------------
-$ git show HEAD^ path/to/file
+$ git show HEAD^:path/to/file
  -------------------------------------------------

  which will display the given version of the file.
---8<---

I haven't been following all the user-manual patches, so if you have already
fixed these up, sorry for the noise. ;-)

All the best,

Ramsay Jones