From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: Max Techter Newsgroups: gmane.lisp.guile.devel Subject: Re: Doc organization (Re: Around again, and docs lead role) Date: 08 May 2003 23:12:54 +0200 Sender: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Message-ID: <86znlxdtwp.fsf@520000401788.dialin.t-online.de> References: <86wuh12yuc.fsf@520000401788.dialin.t-online.de> <3EB9828B00021495@pop1.tiscalinet.es> NNTP-Posting-Host: main.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: main.gmane.org 1052428681 9645 80.91.224.249 (8 May 2003 21:18:01 GMT) X-Complaints-To: usenet@main.gmane.org NNTP-Posting-Date: Thu, 8 May 2003 21:18:01 +0000 (UTC) Cc: guile-devel@gnu.org Original-X-From: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Thu May 08 23:17:58 2003 Return-path: Original-Received: from monty-python.gnu.org ([199.232.76.173]) by main.gmane.org with esmtp (Exim 3.35 #1 (Debian)) id 19Dsfh-00029h-00 for ; Thu, 08 May 2003 23:11:21 +0200 Original-Received: from localhost ([127.0.0.1] helo=monty-python.gnu.org) by monty-python.gnu.org with esmtp (Exim 4.10.13) id 19Dsfq-0005gV-07 for guile-devel@m.gmane.org; Thu, 08 May 2003 17:11:30 -0400 Original-Received: from list by monty-python.gnu.org with tmda-scanned (Exim 4.10.13) id 19DsfJ-00052l-00 for guile-devel@gnu.org; Thu, 08 May 2003 17:10:57 -0400 Original-Received: from mail by monty-python.gnu.org with spam-scanned (Exim 4.10.13) id 19Dsf6-0004qB-00 for guile-devel@gnu.org; Thu, 08 May 2003 17:10:45 -0400 Original-Received: from mail.gmx.de ([213.165.64.20] helo=mail.gmx.net) by monty-python.gnu.org with smtp (Exim 4.10.13) id 19Dsem-0004cm-00 for guile-devel@gnu.org; Thu, 08 May 2003 17:10:24 -0400 Original-Received: (qmail 26512 invoked by uid 65534); 8 May 2003 21:10:23 -0000 Original-Received: from pD9E769CA.dip.t-dialin.net (EHLO 520000401788.dialin.t-online.de) (217.231.105.202) by mail.gmx.net (mp020-rz3) with SMTP; 08 May 2003 23:10:23 +0200 Original-Received: from max by 520000401788.dialin.t-online.de with local (Exim 3.35 #1 (Debian)) id 19DshC-00027M-00; Thu, 08 May 2003 23:12:54 +0200 Original-To: ricardmm@tiscali.es In-Reply-To: <3EB9828B00021495@pop1.tiscalinet.es> (added by postmaster@netmail.tiscalinet.es) Original-Lines: 79 User-Agent: Gnus/5.09 (Gnus v5.9.0) Emacs/21.2 Original-cc: Neil Jerram X-BeenThere: guile-devel@gnu.org X-Mailman-Version: 2.1b5 Precedence: list List-Id: Developers list for Guile, the GNU extensibility library List-Help: List-Post: List-Subscribe: , List-Archive: List-Unsubscribe: , Errors-To: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Xref: main.gmane.org gmane.lisp.guile.devel:2297 X-Report-Spam: http://spam.gmane.org/gmane.lisp.guile.devel:2297 Ricard Mira writes: > Max Techter wrote: > > What about a tutorial, Ricard? > > There is already a Guile tutorial, but it's quite incomplete. On the > other hand, it seems that most of the material in parts I, II and III > of the Guile reference manual are introductory. > I agree on this. But IMHO a tutorial and an introduction is definitely not an exclusive alternative. > I guess it's not clear yet whether Guile should have a separate > tutorial, or an introductory section (or some introductory sections) > in the reference manual. > Sure. Anyway, keeping a tutorial separated and on a different level(*) is a good idea. (Same principle as in python documentation). (*) concerning what you suppose about the knowledge of the audience, you are aiming at; concerning what you want to communicate,... If you keep the tutorial (which) should be practical, the whirlwind tour should be theoretical. Introductory stuff should be kept formal. Tutorial may be informal, if necessary even a little bit unprecise, but it has to get you going immediately. We should not bother too much about the structure already there, if it is clear that there has to be done some restructuring. There are well known principles how to document a system. ( And a standalone- (python), or integrated-tutorial (bison) is a good ingredient for the doc of every non trivial system) ;-) The problem is not so much in finding a suitable structure but in writing and maintaining, without washing the structure away again. Keeping the proportions is a problem too, but we do not have to bother about this, now. ( The work already done, is a fine prototype. We may infer the structure needed, from the problems this documentation posed. ). Maybe I underestimate the complexity, of the needed guile documentation. I`ll try to work out a proposal. I am engaged in scheme and guile anyway, and this will force me to have a structured go. (Guess I`ll need =< a fortnight) regards max. _______________________________________________ Guile-devel mailing list Guile-devel@gnu.org http://mail.gnu.org/mailman/listinfo/guile-devel