user-manual: revise birdseye-view chapter

Some revisions suggested by Junio along with some minor style fixes and
one compile fix (asterisks need escaping).

Cc: Johannes Schindelin <Johannes.Schindelin@gmx.de>
Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 9e61798344dfc67ba99f481c139ace349097c49a..5f4e0a6e495d8f3c76e16cc94b80c3796561d1d8 100644 (file)
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -3161,43 +3161,33 @@ contrast, running "git prune" while somebody is actively changing the
 repository is a *BAD* idea).
 
 [[birdview-on-the-source-code]]
 repository is a *BAD* idea).
 
 [[birdview-on-the-source-code]]

-A birdview on Git's source code
------------------------------
+A birds-eye view of Git's source code
+-------------------------------------

 
 

-While Git's source code is quite elegant, it is not always easy for
-new  developers to find their way through it.  A good idea is to look
-at the contents of the initial commit:
-_e83c5163316f89bfbde7d9ab23ca2e25604af290_ (also known as _v0.99~954_).
+It is not always easy for new developers to find their way through Git's
+source code.  This section gives you a little guidance to show where to
+start.

 
 

-Tip: you can see what files are in there with
+A good place to start is with the contents of the initial commit, with:

 
 ----------------------------------------------------
 
 ----------------------------------------------------

-$ git show e83c5163316f89bfbde7d9ab23ca2e25604af290:
+$ git checkout e83c5163

 ----------------------------------------------------
 
 ----------------------------------------------------
 

-and look at those files with something like
-
------------------------------------------------------------
-$ git show e83c5163316f89bfbde7d9ab23ca2e25604af290:cache.h
------------------------------------------------------------
-
-Be sure to read the README in that revision _after_ you are familiar with
-the terminology (<<glossary>>), since the terminology has changed a little
-since then.  For example, we call the things "commits" now, which are
-described in that README as "changesets".
+The initial revision lays the foundation for almost everything git has
+today, but is small enough to read in one sitting.

 
 

-Actually a lot of the structure as it is now can be explained by that
-initial commit.
+Note that terminology has changed since that revision.  For example, the
+README in that revision uses the word "changeset" to describe what we
+now call a <<def_commit_object,commit>>.

 
 

-For example, we do not call it "cache" any more, but "index", however, the
+Also, we do not call it "cache" any more, but "index", however, the

 file is still called `cache.h`.  Remark: Not much reason to change it now,
 especially since there is no good single name for it anyway, because it is
 basically _the_ header file which is included by _all_ of Git's C sources.
 
 file is still called `cache.h`.  Remark: Not much reason to change it now,
 especially since there is no good single name for it anyway, because it is
 basically _the_ header file which is included by _all_ of Git's C sources.
 

-If you grasp the ideas in that initial commit (it is really small and you
-can get into it really fast, and it will help you recognize things in the
-much larger code base we have now), you should go on skimming `cache.h`,
-`object.h` and `commit.h` in the current version.
+If you grasp the ideas in that initial commit, you should check out a
+more recent version and skim `cache.h`, `object.h` and `commit.h`.

 
 In the early days, Git (in the tradition of UNIX) was a bunch of programs
 which were extremely simple, and which you used in scripts, piping the
 
 In the early days, Git (in the tradition of UNIX) was a bunch of programs
 which were extremely simple, and which you used in scripts, piping the


@@ -3320,11 +3310,11 @@ Two things are interesting here:
   negative numbers in case of different errors -- and 0 on success.
 
 - the variable `sha1` in the function signature of `get_sha1()` is `unsigned
   negative numbers in case of different errors -- and 0 on success.
 
 - the variable `sha1` in the function signature of `get_sha1()` is `unsigned

-  char *`, but is actually expected to be a pointer to `unsigned
+  char \*`, but is actually expected to be a pointer to `unsigned

   char[20]`.  This variable will contain the 160-bit SHA-1 of the given
   char[20]`.  This variable will contain the 160-bit SHA-1 of the given

-  commit.  Note that whenever a SHA-1 is passed as "unsigned char *", it
+  commit.  Note that whenever a SHA-1 is passed as `unsigned char \*`, it

   is the binary representation, as opposed to the ASCII representation in
   is the binary representation, as opposed to the ASCII representation in

-  hex characters, which is passed as "char *".
+  hex characters, which is passed as `char *`.

 
 You will see both of these things throughout the code.
 
 
 You will see both of these things throughout the code.