Re: base

[Stephen J. Turnbull]

Eli Zaretskii writes:

 > I'm not sure I understand what is a ``teachable mental model'',

A "teachable mental model" is a simple way of thinking about the
software's behavior.  It might be an equation or an algorithm or data
structure.  To be simple, it needs to be abstract, and probably is
more general than the software can actually handle.  Well-designed
software will emit errors or warnings when its limits are exceeded,
even though they are compatible with the simple model.  Within those
limits, the software's behavior will be predictable using the model,
including undocumented behavior (ie, in debugging).

 > and where do you see such a model explained in, e.g., git's or hg's
 > docs.

For git, it's in the Community Book,
http://book.git-scm.com/1_the_git_object_model.html, and following
chapters.

Actually, for git the most concise explanations were in the original
"git" man page, back in the early 1.x days (1.1, 1.2-ish).  Much of
that material is in the "gittutorial-2" man page as of git 1.7.x.x,
but it's been rehashed into tutorial form so the model has been kinda
buried.  However, if you look closely, maybe you can see the structure
of the object database (which contains history DAG, directory
structure of the project, and file content, plus some auxiliary object
types), and the relations of the object database, the index (the next
commit under construction), and the workspace.

For Mercurial, the structure of a branch and its associated databases
is described in The Book,
http://hgbook.red-bean.com/read/behind-the-scenes.html.

I don't think any such thing exists for bzr.  One problem is that the
basic storage model for bazaar branches has changed many times.  See
"bzr help current-formats", with four currently listed.  I believe
that I've seen as many as seven there.  I believe repo format has also
changed at least once.

BTW, I have zero sympathy for the point of view that printed books and
HTML don't count as documentation unless they're distributed with the
program.