[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Apologia for bzr
From: |
Eli Zaretskii |
Subject: |
Re: Apologia for bzr |
Date: |
Fri, 03 Jan 2014 12:26:05 +0200 |
> 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.
- Re: Apologia for bzr, (continued)
- Re: Apologia for bzr, Yuri Khan, 2014/01/05
- Re: Apologia for bzr, Michael Albinus, 2014/01/06
- Re: Apologia for bzr, chad, 2014/01/06
- Re: Apologia for bzr, James Cloos, 2014/01/06
- Re: Apologia for bzr, Eric Brown, 2014/01/06
- Re: Apologia for bzr, Rogerio Senna, 2014/01/09
- RE: Apologia for bzr, Drew Adams, 2014/01/09
- Re: Apologia for bzr, Tassilo Horn, 2014/01/03
- Re: Apologia for bzr,
Eli Zaretskii <=
- Re: Apologia for bzr, Nathan Trapuzzano, 2014/01/03
- Re: Apologia for bzr, Eli Zaretskii, 2014/01/03
- Re: Apologia for bzr, Nathan Trapuzzano, 2014/01/03
- Re: Apologia for bzr, Eli Zaretskii, 2014/01/03
- Re: Apologia for bzr, Eli Zaretskii, 2014/01/04
- Re: Apologia for bzr, Óscar Fuentes, 2014/01/03
- Re: Apologia for bzr, Eli Zaretskii, 2014/01/03
- Re: Apologia for bzr, Leo Liu, 2014/01/03
- Re: Apologia for bzr, Eli Zaretskii, 2014/01/03
- Re: Apologia for bzr, Óscar Fuentes, 2014/01/03