From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: Git mirrors Date: Mon, 17 Oct 2011 10:12:03 -0400 Message-ID: References: <87lissh32y.fsf@wanadoo.es> <87zkh8e286.fsf@catnip.gol.com> <87d3e4gttq.fsf@wanadoo.es> <87ehyjrhxh.fsf@uwakimon.sk.tsukuba.ac.jp> <87d3e2rfte.fsf@uwakimon.sk.tsukuba.ac.jp> <878voqfiaw.fsf@wanadoo.es> <87zkh4bhho.fsf@wanadoo.es> <87zkh4nrcr.fsf@uwakimon.sk.tsukuba.ac.jp> <87zkh0ozjz.fsf@uwakimon.sk.tsukuba.ac.jp> <87d3dvyev3.fsf@wanadoo.es> Reply-To: Eli Zaretskii NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Trace: dough.gmane.org 1318860750 8806 80.91.229.12 (17 Oct 2011 14:12:30 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Mon, 17 Oct 2011 14:12:30 +0000 (UTC) Cc: lekktu@gmail.com, stephen@xemacs.org, schwab@linux-m68k.org, rms@gnu.org, emacs-devel@gnu.org To: =?utf-8?Q?=C3=93scar?= Fuentes Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Mon Oct 17 16:12:26 2011 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([140.186.70.17]) by lo.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1RFnvW-0007Bj-11 for ged-emacs-devel@m.gmane.org; Mon, 17 Oct 2011 16:12:26 +0200 Original-Received: from localhost ([::1]:39664 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1RFnvU-0003fZ-MB for ged-emacs-devel@m.gmane.org; Mon, 17 Oct 2011 10:12:24 -0400 Original-Received: from eggs.gnu.org ([140.186.70.92]:48377) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1RFnvP-0003f5-BW for emacs-devel@gnu.org; Mon, 17 Oct 2011 10:12:23 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1RFnvJ-0005K3-D4 for emacs-devel@gnu.org; Mon, 17 Oct 2011 10:12:19 -0400 Original-Received: from fencepost.gnu.org ([140.186.70.10]:58225) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1RFnvJ-0005Jy-7l for emacs-devel@gnu.org; Mon, 17 Oct 2011 10:12:13 -0400 Original-Received: from eliz by fencepost.gnu.org with local (Exim 4.71) (envelope-from ) id 1RFnv9-0006l0-D2; Mon, 17 Oct 2011 10:12:03 -0400 In-reply-to: <87d3dvyev3.fsf@wanadoo.es> (message from =?utf-8?Q?=C3=93sca?= =?utf-8?Q?r?= Fuentes on Mon, 17 Oct 2011 14:36:16 +0200) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 3) X-Received-From: 140.186.70.10 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:145257 Archived-At: > From: Óscar Fuentes > Cc: Andreas Schwab , stephen@xemacs.org, lekktu@gmail.com, rms@gnu.org, emacs-devel@gnu.org > Date: Mon, 17 Oct 2011 14:36:16 +0200 > > Eli Zaretskii 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, . > > (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.