Re: Git mirrors

[Eli Zaretskii]

> From: Óscar Fuentes <address@hidden>
> Cc: Andreas Schwab <address@hidden>,  address@hidden, address@hidden,  
> address@hidden,  address@hidden
> Date: Mon, 17 Oct 2011 14:36:16 +0200
> 
> Eli Zaretskii <address@hidden> writes:
> 
> >> Manpages are not tutorials, they are reference documentation.  If you
> >> need a tutorial there are a lot of good ones available.
> >
> > Tutorial is not the issue here.  (Git does come with an official
> > tutorial man page.)  The issue here is that every command should be
> > explained in a way that is suitable both for the first reading by
> > someone inexperienced, and as reference material for someone
> > experienced who knows exactly what she is after.
> 
> So you want those manpages to be both informative for inexperienced
> users and a reference. That's unreasonable.

No, it isn't unreasonable.  The GNU manuals are an example: they are
good both for the first reading and as a reference.

> C-x k C-x 1
> 
> C-x 1 runs the command delete-other-windows, which is an interactive
> compiled Lisp function in `window.el'.
> 
> It is bound to C-x 1, <menu-bar> <file> <one-window>.
> 
> (delete-other-windows &optional WINDOW)
> 
> Make WINDOW fill its frame.
> WINDOW may be any window and defaults to the selected one.
> Return nil.
> 
> [... it goes on referencing variables, etc... ]
> 
> 
> It looks like a daunting piece of text for a beginner (what's a WINDOW?
> what's a frame? Should I care about what it returns? And What's that
> piece of text between the parenthesis, BTW?)

Exactly my point: having just the doc strings of the commands is not
good enough as user documentation.

> Actually, the docstring is a great reference. It's unreasonable to
> expect all the relevant concepts explained because it would become a
> mess as a reference, turning into a bad beginner's help text and as a
> bad reference.

Exactly.  We are in agreement.  All I'm saying is that there should be
some more documentation, either in the man pages or in another
document.  Without that, a package of git complexity is almost
impenetrable.