Re: Apologia for bzr

[Eli Zaretskii]

> Date: Thu, 2 Jan 2014 21:14:52 +0000
> From: Toby Cubitt <address@hidden>
> Cc: address@hidden, address@hidden, address@hidden
> 
> > They are impenetrable.  The very first words will get you in a "WTF?"
> > mode.  Just try to read the first sentences of any random man page
> > through a newbie's eyes.  No term is ever explained before used -- do
> > these guys even understand what it means to _explain_ things?  It's as
> > if you need to learn a whole new language.
> 
> This is the Emacs mailing list I'm on, right? Emacs of "find" a file to
> open it, files live in "buffers", "windows" aren't windows but "frames"
> are, "kill" to cut and "yank" to paste fame? ;-)

Indeed, and we all know that these are obstacles to newbies, so wise
people (and git development is full of them, right?) shouldn't have
gone that way.  At least in Emacs we have an excuse that the bulk of
the terminology developed when no other software provided any similar
features; there's no such excuse for git (or bzr or hg).

Anyway, there's a big difference here: in Emacs documentation, every
term is explained before it is used, and rarely used terms have
cross-references to where they are described.

> > Here, a typical example from git-commit:
> > 
> >   DESCRIPTION 
> > 
> >   Stores the current contents of the index in a new commit along with
> >    a log message from the user describing the changes.
> > 
> > Huh?  "Contents of the index"?  I used to know what commit was, now I
> > don't.
> 
> The same could be said of most unix man pages.

I'm reading Unix man pages for many years, and I must disagree: they
are generally quite self-explanatory.  Git is exceptional in this
regard.

> Good man pages aren't supposed to be tutorials. They're supposed to
> be reference manuals, for looking up a terse and comprehensive
> description of usage, options, switches, flags etc. Or at least,
> that's how I've always understood (and used) them.

You are missing the point: I didn't want a tutorial.  I use VCSes for
many years, and dVCSes for some; I already know what it means to
commit a changeset and what is the basic workflow of using a dVCS.  I
wanted a "terse and comprehensive description" of the git's commit
command, including all of its options.  But when I read the above
"Description" line, I start to question the correctness of my notion
of what a commit is.  Here, look at these "descriptions" of options:

  -a 
  --all 
    Tell the command to automatically stage files that have been
    modified and deleted, but new files you have not told Git about are
    not affected.

If you don't already know what is "staging", you will never understand
that this is one of the most important and useful options.  Also,
"haven't told Git about new files" fails to mention "git add".  Once
I've managed to grasp all that, I've made an alias for "commit -a",
because that's what I almost always want.  (And why isn't that the
default, dammit?)

  --reuse-message=<commit> 
    Take an existing commit object, and reuse the log message and the
    authorship information (including the timestamp) when creating the
    commit.

"Commit object"? what's that?  There's no reference to where this is
explained; without such a reference, this "description" is
non-instrumental, and thus useless.  This problem is, of course,
common to all the other options that refer to a "commit object", of
which there are many on this page.

  --allow-empty 
    Usually recording a commit that has the exact same tree as its
    sole parent commit is a mistake, and the command prevents you from
    making such a commit. This option bypasses the safety, and is
    primarily for use by foreign SCM interface scripts.

"Recording a commit"? what's that?  And is "commit that has the exact
same tree as its sole parent commit" a complicated way of saying "no
changes since the last commit", or is there some important subtlety
here that I'm missing?  Even bzr's commit docs does much better:

  --unchanged   Commit even if nothing has changed.

Etc., etc. -- I could go for hours on end with these examples.

Mind you, I have this and other important git man pages open on my
desktop at all times, and I consult them all the time.  And I still
don't get some of the details.

And if you are still not convinced, let me show you what this
"documentation" style would mean if the Emacs manual would use it.
Let's take for example what the C-f key does in Emacs.  You think you
know what it does?  Here's what the Emacs manual says:

  `C-f'
       Move forward one character (`forward-char').

Simple, self-explanatory, and concise.  Also inaccurate, because
that's not what really happens when you press C-f.  Here's what does
happen:

  `C-f'
       Move forward to the next visible buffer position, skipping any
       invisible text and lines hidden by selective display.  The next
       redisplay cycle will display the cursor on the grapheme cluster
       to which the new buffer position belongs.  If the new buffer
       position is the newline character, display the cursor on the
       empty glyph beyond the end of the line.  If the new buffer
       position has a display property defined for it, display the
       cursor on the first glyph produced from that display property,
       or on the glyph that has the 'cursor' property defined for it.

This is the accurate description of what C-f does, complete with
references to about half a dozen of highly technical terms that I
didn't bother to explain.  I managed to be an efficient and happy
Emacs user and hacker for 15 years without knowing most of this.  It's
not until I started seriously hacking the display engine 5 years ago
that I became aware of all those details -- because I needed them then
to be able to make the changes in the Emacs display.

> And there *are* decent git tutorials available from the official web site
> that explain things without assuming you already know how git works
> (e.g. http://git-scm.com/book isn't bad).

I DON'T WANT TUTORIALS, I've already read them.  I want some decent
reference documentation.  I just don't want all the details about
what's going on under the hood crammed down my throat every time I
want to learn what some option does, or find an option that does what
I need to accomplish.

> Or maybe my problem is I'm a maths professor :)

I didn't say that ;-)