all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
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.



  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.