From: "Óscar Fuentes" <ofv@wanadoo.es>
To: Eli Zaretskii <eliz@gnu.org>
Cc: lekktu@gmail.com, stephen@xemacs.org,
Andreas Schwab <schwab@linux-m68k.org>,
rms@gnu.org, emacs-devel@gnu.org
Subject: Re: Git mirrors
Date: Mon, 17 Oct 2011 14:36:16 +0200 [thread overview]
Message-ID: <87d3dvyev3.fsf@wanadoo.es> (raw)
In-Reply-To: <E1RFj7X-0006Iz-Sg@fencepost.gnu.org> (Eli Zaretskii's message of "Mon, 17 Oct 2011 05:04:31 -0400")
Eli Zaretskii <eliz@gnu.org> 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.)
next prev parent reply other threads:[~2011-10-17 12:36 UTC|newest]
Thread overview: 223+ messages / expand[flat|nested] mbox.gz Atom feed top
2011-10-06 20:50 Git mirrors Lars Magne Ingebrigtsen
2011-10-06 20:58 ` Glenn Morris
2011-10-06 21:16 ` chad
2011-10-06 21:58 ` John Wiegley
2011-10-06 22:05 ` David Reitter
2011-10-07 0:06 ` Glenn Morris
2011-10-07 9:26 ` Julien Danjou
2011-10-09 6:19 ` Tim Cross
2011-10-07 18:43 ` Burton Samograd
2011-10-07 19:15 ` Eli Zaretskii
2011-10-07 19:31 ` Burton Samograd
2011-10-06 22:30 ` Óscar Fuentes
2011-10-06 22:39 ` Lars Magne Ingebrigtsen
2011-10-06 23:11 ` Juanma Barranquero
2011-10-06 23:50 ` Óscar Fuentes
2011-10-07 0:05 ` Glenn Morris
2011-10-07 0:13 ` Glenn Morris
2011-10-07 0:45 ` John Wiegley
2011-10-07 1:38 ` Stefan Monnier
2011-10-07 15:35 ` Ted Zlatanov
2011-10-07 16:37 ` Glenn Morris
2011-10-07 18:23 ` Ted Zlatanov
2011-10-08 8:50 ` Richard Stallman
2011-10-10 22:02 ` Ted Zlatanov
2011-10-10 22:52 ` Óscar Fuentes
2011-10-11 0:35 ` Juanma Barranquero
2011-10-11 1:12 ` Óscar Fuentes
2011-10-11 1:38 ` Juanma Barranquero
2011-10-11 1:39 ` Miles Bader
2011-10-11 1:42 ` Juanma Barranquero
2011-10-11 2:12 ` Óscar Fuentes
2011-10-11 2:23 ` Juanma Barranquero
2011-10-11 3:07 ` Óscar Fuentes
2011-10-11 3:25 ` Juanma Barranquero
2011-10-11 3:45 ` Óscar Fuentes
2011-10-11 4:22 ` Juanma Barranquero
2011-10-11 7:17 ` Eli Zaretskii
2011-10-11 8:14 ` Eli Zaretskii
2011-10-11 13:19 ` Ted Zlatanov
2011-10-11 14:48 ` Eli Zaretskii
2011-10-11 9:33 ` Stephen J. Turnbull
2011-10-11 11:33 ` Juanma Barranquero
2011-10-12 4:31 ` Stephen J. Turnbull
2011-10-12 9:18 ` Juanma Barranquero
2011-10-12 13:31 ` Óscar Fuentes
2011-10-12 14:47 ` Eli Zaretskii
2011-10-12 15:12 ` Richard Riley
2011-10-12 15:29 ` Eli Zaretskii
2011-10-12 15:23 ` Óscar Fuentes
2011-10-12 15:43 ` Eli Zaretskii
2011-10-12 16:02 ` Jambunathan K
2011-10-12 15:32 ` Vijay Lakshminarayanan
2011-10-12 16:09 ` Óscar Fuentes
2011-10-12 17:19 ` Vijay Lakshminarayanan
2011-10-12 18:21 ` Helmut Eller
2011-10-12 18:30 ` Jambunathan K
2011-10-12 19:25 ` Helmut Eller
2011-10-13 12:35 ` Ted Zlatanov
2011-10-12 19:54 ` Giuseppe Scrivano
2011-10-12 20:12 ` Burton Samograd
2011-10-13 3:21 ` Vijay Lakshminarayanan
2011-10-13 4:06 ` Stephen J. Turnbull
2011-10-13 14:08 ` Burton Samograd
2011-10-13 16:38 ` Stephen J. Turnbull
2011-10-13 14:00 ` Richard Stallman
2011-10-13 22:13 ` Richard Stallman
2011-10-13 23:26 ` Óscar Fuentes
2011-10-14 1:01 ` Juanma Barranquero
2011-10-14 2:39 ` Óscar Fuentes
2011-10-14 3:13 ` Juanma Barranquero
2011-10-14 5:22 ` Jambunathan K
2011-10-14 12:32 ` Jambunathan K
2011-10-14 4:12 ` Stephen J. Turnbull
2011-10-14 9:09 ` Juanma Barranquero
2011-10-14 9:28 ` Miles Bader
2011-10-14 11:35 ` Juanma Barranquero
2011-10-14 17:19 ` Andreas Schwab
2011-10-17 7:19 ` Stephen J. Turnbull
2011-10-17 8:25 ` Eli Zaretskii
2011-10-17 8:31 ` Andreas Schwab
2011-10-17 9:04 ` Eli Zaretskii
2011-10-17 12:09 ` Stephen J. Turnbull
2011-10-17 12:36 ` Óscar Fuentes [this message]
2011-10-17 14:12 ` Eli Zaretskii
2011-10-17 14:44 ` John Yates
2011-10-17 11:57 ` Stephen J. Turnbull
2011-10-17 13:55 ` Eli Zaretskii
2011-10-17 15:45 ` Stephen J. Turnbull
2011-10-17 14:10 ` Looming colocation [Was: Git mirrors] Alan Mackenzie
2011-10-17 16:59 ` Stephen J. Turnbull
2011-10-17 19:04 ` Barry Warsaw
2011-10-17 18:49 ` Looms and Pipelines (was Re: Git mirrors) Barry Warsaw
2011-10-14 4:50 ` Git mirrors Stephen J. Turnbull
2011-10-14 9:27 ` Juanma Barranquero
2011-10-14 12:29 ` Bastien
2011-10-14 13:08 ` Juanma Barranquero
2011-10-14 14:00 ` Bastien
2011-10-14 17:31 ` Eli Zaretskii
2011-11-29 15:29 ` Bastien
2011-10-17 9:44 ` Stephen J. Turnbull
2011-10-17 16:41 ` Vijay Lakshminarayanan
2011-10-17 18:39 ` Óscar Fuentes
2011-10-17 18:52 ` Juanma Barranquero
2011-10-17 19:23 ` Stefan Monnier
2011-10-18 10:56 ` Richard Stallman
2011-10-18 3:39 ` Vijay Lakshminarayanan
2011-10-18 2:46 ` Stephen J. Turnbull
2011-10-18 5:13 ` Jambunathan K
2011-10-18 10:56 ` Richard Stallman
2011-10-14 21:41 ` Richard Stallman
2011-10-17 11:25 ` Michael Raitza
2011-10-13 4:55 ` Miles Bader
2011-10-13 8:49 ` Eli Zaretskii
2011-10-11 11:49 ` Eli Zaretskii
2011-10-12 4:55 ` Stephen J. Turnbull
2011-10-12 8:35 ` Eli Zaretskii
2011-10-12 10:51 ` Stephen J. Turnbull
2011-10-12 10:54 ` Eli Zaretskii
2011-10-12 14:01 ` Óscar Fuentes
2011-10-12 14:42 ` Eli Zaretskii
2011-10-12 21:54 ` Richard Stallman
2011-10-11 12:56 ` Óscar Fuentes
2011-10-11 15:02 ` Eli Zaretskii
2011-10-11 19:34 ` Óscar Fuentes
2011-10-11 22:03 ` Richard Stallman
2011-10-13 5:10 ` Miles Bader
2011-10-11 12:34 ` Richard Stallman
2011-10-11 16:39 ` What about Python? (was: Git mirrors) Barry Fishman
2011-10-11 22:03 ` Richard Stallman
2011-10-11 4:08 ` Git mirrors Eli Zaretskii
2011-10-11 13:39 ` Ted Zlatanov
2011-10-11 13:48 ` Lars Magne Ingebrigtsen
2011-10-11 15:35 ` Stefan Monnier
2011-10-11 20:13 ` John Wiegley
2011-10-11 21:39 ` Óscar Fuentes
2011-10-12 0:32 ` John Wiegley
2011-10-12 1:07 ` Stefan Monnier
2011-10-12 2:51 ` John Wiegley
2011-10-12 9:23 ` Andreas Schwab
2011-10-12 14:12 ` Dave Abrahams
2011-10-12 18:56 ` John Wiegley
2011-10-12 19:24 ` Andreas Schwab
2011-10-12 1:16 ` Óscar Fuentes
2011-10-12 1:34 ` Óscar Fuentes
2011-10-12 21:54 ` Richard Stallman
2011-10-12 22:18 ` John Wiegley
2011-10-12 22:48 ` Karl Fogel
2011-10-13 5:09 ` Stephen J. Turnbull
2011-10-13 8:23 ` Bastien
2011-10-13 22:13 ` Richard Stallman
2011-10-14 11:55 ` Bastien
2011-10-13 13:41 ` Vijay Lakshminarayanan
2011-10-13 16:16 ` Stephen J. Turnbull
2011-10-14 1:03 ` Vijay Lakshminarayanan
2011-10-14 13:40 ` Richard Stallman
2011-10-13 22:13 ` Richard Stallman
2011-10-14 3:14 ` Barry Warsaw
2011-10-14 5:40 ` Stephen J. Turnbull
2011-10-13 12:46 ` Ted Zlatanov
2011-10-13 0:08 ` John Wiegley
2011-10-13 15:39 ` Andreas Schwab
2011-10-13 16:39 ` Lars Magne Ingebrigtsen
2011-10-13 17:37 ` Andreas Schwab
2011-10-13 16:21 ` Stefan Monnier
2011-10-13 17:35 ` Andreas Schwab
2011-10-12 14:46 ` Lars Magne Ingebrigtsen
2011-10-12 18:57 ` John Wiegley
2011-10-12 20:44 ` Lars Magne Ingebrigtsen
2011-10-11 22:09 ` Eli Zaretskii
2011-10-11 23:33 ` James Cloos
2011-10-11 23:37 ` John Wiegley
2011-10-12 8:45 ` Eli Zaretskii
2011-10-12 18:58 ` John Wiegley
2011-10-12 20:14 ` Eli Zaretskii
2011-10-12 20:32 ` John Wiegley
2011-10-12 20:56 ` Óscar Fuentes
2011-10-12 21:03 ` John Wiegley
2011-10-12 21:15 ` Óscar Fuentes
2011-10-12 20:50 ` Andreas Schwab
2011-10-12 20:56 ` John Wiegley
2011-10-12 21:05 ` Andreas Schwab
2011-10-12 21:09 ` John Wiegley
2011-10-12 21:14 ` Andreas Schwab
2011-10-12 21:37 ` Óscar Fuentes
2011-10-12 22:01 ` Eli Zaretskii
2011-10-12 22:35 ` John Wiegley
2011-10-12 23:06 ` Óscar Fuentes
2011-10-12 23:16 ` John Wiegley
2011-10-12 23:37 ` Óscar Fuentes
2011-10-12 23:57 ` John Wiegley
2011-10-13 0:10 ` Óscar Fuentes
2011-10-13 0:14 ` John Wiegley
2011-10-13 0:24 ` Óscar Fuentes
2011-10-13 9:01 ` Eli Zaretskii
2011-10-13 8:02 ` Eli Zaretskii
2011-10-12 22:05 ` Óscar Fuentes
2011-10-11 18:58 ` Ted Zlatanov
2011-10-11 9:00 ` Stephen J. Turnbull
2011-10-11 22:02 ` Richard Stallman
2011-10-12 1:44 ` Ted Zlatanov
2011-10-08 9:26 ` Richard Riley
2011-10-08 9:52 ` Eli Zaretskii
2011-10-07 4:58 ` Thierry Volpiatto
2011-10-07 7:45 ` John Wiegley
2011-10-07 8:15 ` Thierry Volpiatto
2011-10-07 8:25 ` John Wiegley
2011-10-07 13:33 ` Thierry Volpiatto
2011-10-07 16:47 ` James Cloos
2011-10-07 20:40 ` John Wiegley
2011-10-07 17:36 ` Stephen J. Turnbull
2011-10-07 8:26 ` Andreas Schwab
2011-10-07 9:06 ` John Wiegley
2011-10-07 10:36 ` Lars Magne Ingebrigtsen
2011-10-07 13:19 ` Thierry Volpiatto
2011-10-07 7:04 ` Stephen J. Turnbull
2011-10-07 7:36 ` John Wiegley
2011-10-07 8:00 ` Andreas Schwab
2011-10-07 8:13 ` John Wiegley
2011-10-07 9:02 ` John Wiegley
2011-10-07 10:14 ` Paul Michael Reilly
2011-10-07 17:39 ` Stephen J. Turnbull
2011-10-07 0:49 ` Leo
2011-10-12 10:05 ` Bastien
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.gnu.org/software/emacs/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87d3dvyev3.fsf@wanadoo.es \
--to=ofv@wanadoo.es \
--cc=eliz@gnu.org \
--cc=emacs-devel@gnu.org \
--cc=lekktu@gmail.com \
--cc=rms@gnu.org \
--cc=schwab@linux-m68k.org \
--cc=stephen@xemacs.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).