[Top][All Lists]

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

Re: Git mirrors

From: Óscar Fuentes
Subject: Re: Git mirrors
Date: Mon, 17 Oct 2011 14:36:16 +0200
User-agent: Gnus/5.13 (Gnus v5.13) Emacs/24.0.50 (gnu/linux)

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.


> Look at the Emacs documentation, for example.  Would it be sufficient
> to have just the TUTORIAL and then an alphabetical listing of all the
> commands and options, each one with its doc string?  I don't think so.

You were talking about the documentation for commands, you let's pick a
random instance:

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?)

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.

(Its "beginner-friendliness" character could be greatly improved with
tool-tips associated to some keywords, like in this case WINDOW and
frame. That would not cause annoyances to those more experienced users
who read the docstring for reference.)

reply via email to

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