Re: Git mirrors

[Óscar Fuentes]

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.

[snip]

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