Re: Apologia for bzr

[Eli Zaretskii]

> From: Tassilo Horn <address@hidden>
> Cc: address@hidden,  address@hidden,  address@hidden
> Date: Fri, 03 Jan 2014 10:44:17 +0100
> 
> Eli Zaretskii <address@hidden> writes:
> 
> > They are impenetrable.  The very first words will get you in a "WTF?"
> > mode.
> 
> All the terminology that's referred to in the git command man pages is
> defined in one central place, the gitglossary(7) man page.

First, there are no references to glossary in these places, and, as
you know well, references in man pages are a PITA to use (unlike in
Info).

More importantly, the glossary, at least git's glossary, is not going
to help here.  Let's take this example I showed earlier:

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

Clearly, what I need to know here, and is never explained, is how do I
_reference_ a commit object.  Now, here's what the glossary tells me:

  commit object 
       An object which contains the information about a particular
       revision, such as parents, committer, author, date and the tree
       object which corresponds to the top directory of the stored
       revision.

I hope you will agree with me that after reading this, I'm none the
wiser.  (There are a few hyperlinks in the text I show above, but none
of them helps, either.)  It actually tells me things that I could
easily guessed myself, but never even hints at what I'm looking for.
Reminds me of Microsoft documentation: to open a file click File->Open.

> But in fact, basically every git command man page should list that
> under SEE ALSO but doesn't.

That's impractical: it would make the See Also section be of infinite
length.  Instead, the man page should either use a less formal style,
or give examples (e.g., in parentheses) showing how the formal
abstract terminology is related to practical issues.

IOW, the authors should recognize that when I'm reading a man page, I
usually look for answers to very practical questions, I'm not very
interested in abstract relations between abstract opaque objects and
concepts.