From: Eli Zaretskii <eliz@gnu.org>
To: "Óscar Fuentes" <ofv@wanadoo.es>
Cc: lekktu@gmail.com, stephen@xemacs.org, schwab@linux-m68k.org,
rms@gnu.org, emacs-devel@gnu.org
Subject: Re: Git mirrors
Date: Mon, 17 Oct 2011 10:12:03 -0400 [thread overview]
Message-ID: <E1RFnv9-0006l0-D2@fencepost.gnu.org> (raw)
In-Reply-To: <87d3dvyev3.fsf@wanadoo.es> (message from Óscar Fuentes on Mon, 17 Oct 2011 14:36:16 +0200)
> From: Óscar Fuentes <ofv@wanadoo.es>
> Cc: Andreas Schwab <schwab@linux-m68k.org>, stephen@xemacs.org, lekktu@gmail.com, rms@gnu.org, emacs-devel@gnu.org
> Date: Mon, 17 Oct 2011 14:36:16 +0200
>
> 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.
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.
next prev parent reply other threads:[~2011-10-17 14:12 UTC|newest]
Thread overview: 226+ 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
2011-10-17 14:12 ` Eli Zaretskii [this message]
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
-- strict thread matches above, loose matches on Subject: below --
2012-05-22 5:22 François Pinard
2012-05-22 6:58 ` Nick Dokos
2012-05-22 23:08 ` 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
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=E1RFnv9-0006l0-D2@fencepost.gnu.org \
--to=eliz@gnu.org \
--cc=emacs-devel@gnu.org \
--cc=lekktu@gmail.com \
--cc=ofv@wanadoo.es \
--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 external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.