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: 09 May 2003 14:32:51 +0200 Sender: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Message-ID: <86znlwcnbg.fsf@520000401788.dialin.t-online.de> References: <3E92E1B4002B0632@pop3.tiscalinet.es> <3EAFE4EC000D9733@pop1.tiscalinet.es> <86wuh12yuc.fsf@520000401788.dialin.t-online.de> NNTP-Posting-Host: main.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: main.gmane.org 1052484142 5014 80.91.224.249 (9 May 2003 12:42:22 GMT) X-Complaints-To: usenet@main.gmane.org NNTP-Posting-Date: Fri, 9 May 2003 12:42:22 +0000 (UTC) Cc: guile-devel@gnu.org Original-X-From: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Fri May 09 14:42:20 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 19E7C4-0001GM-00 for ; Fri, 09 May 2003 14:41:44 +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 19E76S-0000PB-03 for guile-devel@m.gmane.org; Fri, 09 May 2003 08:35:56 -0400 Original-Received: from list by monty-python.gnu.org with tmda-scanned (Exim 4.10.13) id 19E75p-0000Kw-00 for guile-devel@gnu.org; Fri, 09 May 2003 08:35:18 -0400 Original-Received: from mail by monty-python.gnu.org with spam-scanned (Exim 4.10.13) id 19E73h-0007DC-00 for guile-devel@gnu.org; Fri, 09 May 2003 08:33:06 -0400 Original-Received: from imap.gmx.net ([213.165.64.20] helo=mail.gmx.net) by monty-python.gnu.org with smtp (Exim 4.10.13) id 19E730-0006nC-00 for guile-devel@gnu.org; Fri, 09 May 2003 08:32:22 -0400 Original-Received: (qmail 17876 invoked by uid 65534); 9 May 2003 12:30:16 -0000 Original-Received: from pD9E75B9D.dip.t-dialin.net (EHLO 520000401788.dialin.t-online.de) (217.231.91.157) by mail.gmx.net (mp023-rz3) with SMTP; 09 May 2003 14:30:16 +0200 Original-Received: from max by 520000401788.dialin.t-online.de with local (Exim 3.35 #1 (Debian)) id 19E73U-00013d-00; Fri, 09 May 2003 14:32:52 +0200 Original-To: Neil Jerram In-Reply-To: Original-Lines: 193 User-Agent: Gnus/5.09 (Gnus v5.9.0) Emacs/21.2 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:2303 X-Report-Spam: http://spam.gmane.org/gmane.lisp.guile.devel:2303 Neil Jerram writes: > >>>>> "Max" == Max Techter writes: > > >> My latest thinking is that we could be a lot more concrete, even > >> proscriptive, about what Guile is for and how people should use it, > >> and that if we did so it would be a lot easier to clearly assess the > >> state of the documentation and to finish it off. > > >> (Right now, IMO, it is difficult even to describe the > >> documentation status.) > > Max> My first impression was: > Max> Oops... > Max> such an important project, but obviously > Max> abandoned... > > I don't see how you can conclude that the project is abandoned when > we're right in the middle of a thread about it .... > I installed the guile package, had a look at the manual and at the tutorial before I subscribed and read the mailing list. > Max> I typically look out for a tutorial, immediately > Max> after installation. Not to learn, but to find out: > > Max> is this something for me? > > Did you look at the Guile Tutorial? Yes, I did. That`s what I do as one of my first steps, when exploring s.th. new to me. And this was part of the things that caused my _first_ and _wrong_ impression. Oops, abandoned. Important GNU Packages, have excellent doc, guile doc is not bad, but not excellent either. (although it is an important Package, as I got it now, and not abandoned... :-) > How would you improve it? > Too much to say about this, to be appropriate for this reply. I`ll tell you in a couple of days, more precisely. So far only this: As an example: There is a section Using recursion to process a list. Before anything was said about pairs, and lists, and the concept of the null in scheme. If this is an tutorial about scheme, you can`t ask the (potential) user, to take such a leap. You can do this in a preview, but not in a tutorial. Now if this is not a scheme tutorial, (the Title says `Guile tutorial'), there is no need to supply such an example, because it is a standard scheme construct. The problem is: the parts of the documentation seen as isolated pieces of knowledge, are good, though not complete. But being new to guile, and to scheme I had problems to grasp the context (and the rational). > >> , I think the natural high level documentation structure > >> would then be: > >> > > Max> I am missing, things like: [...] > > I agree, and some of these pieces are already in place - see the Guile > Reference manual. But I was really focussing on the issue of Scheme > and C API documentation in my last message. > Ok, obviously I missed your focus. That is because I am still struggling to get the big picture: The Algorithmic Language Scheme * GOOPS: (goops). The GOOPS reference manual. * Guile Reference: (guile). The Guile reference manual. * Guile Tutorial: (guile-tut). The Guile tutorial. * R5RS: (r5rs). The Revised(5) Report on Scheme. (slib is missing in my local installation, what else is missing?) > >> - Scheme reference documentation - more or less like the current Part > >> IV, but Scheme only, not C. > > >> - Task-based documentation describing everything needed for aspects of > >> interfacing with C code: > > Max> Task based structuring the meat of the documentation > Max> is an idea I like, Neil. > > Max> That`s what we use software for: > Max> Solving Tasks > Max> (beside for having incredible fun, of cause =:) > > OK, but given a general purpose language like Scheme, there's a limit > to how fully you can document it in a task-based way. > For Scheme you > need a combination of reference documentation and examples. > I agree. It is clear that this task-based way has advantages and has tight limits on the other hand. And may I add: Reference with short examples. Tutorial with intermediate examples, Introduction / Basic Concepts by the way, IMHO there should be a section * `Basic Concepts of Scheme' as there already is __and__ * `Basic Concepts of Guile' maybe the Whirlwind tour could be extended to such a section, and later on this extension could be boiled down again to an improved Whirlwind tour both with longer examples (like the one in `An Example of Non-Lexical Scoping' which helped me quite a lot, to dig one of the not so simple concepts.) > The C API on the other hand - at least as I think we should see it - > is not general purpose. > It has the specific job of interfacing C to > Scheme and so can be fully covered in a task-based way. > I am definitely not the one to comment on this, not yet ;-) regards max. PS: I would like to help in formulating the overall layout, and I am prepared to get my hands on real work, concerning the tutorials, if it is decided on having (or keeping) them. _______________________________________________ Guile-devel mailing list Guile-devel@gnu.org http://mail.gnu.org/mailman/listinfo/guile-devel