[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Git mirrors

From: Eli Zaretskii
Subject: Re: Git mirrors
Date: Mon, 17 Oct 2011 10:12:03 -0400

> 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

reply via email to

[Prev in Thread] Current Thread [Next in Thread]