From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: Max Techter Newsgroups: gmane.lisp.guile.user Subject: Re: Doc organization (Re: Around again, and docs lead role) Date: 17 May 2003 05:02:24 +0200 Sender: guile-user-bounces+guile-user=m.gmane.org@gnu.org Message-ID: <86addm1dj3.fsf@520000401788.dialin.t-online.de> References: <3E92E1B4002B0632@pop3.tiscalinet.es> <3EAFE4EC000D9733@pop1.tiscalinet.es> <87d6its93b.fsf@raven.i.defaultvalue.org> <200305091152.EAA26081@cmn14.stanford.edu> <200305141429.HAA02633@cmn14.stanford.edu> NNTP-Posting-Host: main.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: main.gmane.org 1053140395 17054 80.91.224.249 (17 May 2003 02:59:55 GMT) X-Complaints-To: usenet@main.gmane.org NNTP-Posting-Date: Sat, 17 May 2003 02:59:55 +0000 (UTC) Cc: Neil Jerram Original-X-From: guile-user-bounces+guile-user=m.gmane.org@gnu.org Sat May 17 04:59:50 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 19GrvK-0004Qd-00 for ; Sat, 17 May 2003 04:59:50 +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 19GrvJ-0003j0-03 for guile-user@m.gmane.org; Fri, 16 May 2003 22:59:49 -0400 Original-Received: from list by monty-python.gnu.org with tmda-scanned (Exim 4.10.13) id 19Gruu-0003XC-00 for guile-user@gnu.org; Fri, 16 May 2003 22:59:24 -0400 Original-Received: from mail by monty-python.gnu.org with spam-scanned (Exim 4.10.13) id 19Gruo-00039W-00 for guile-user@gnu.org; Fri, 16 May 2003 22:59:22 -0400 Original-Received: from mail.gmx.net ([213.165.65.60]) by monty-python.gnu.org with smtp (Exim 4.10.13) id 19Grum-0002tB-00 for guile-user@gnu.org; Fri, 16 May 2003 22:59:17 -0400 Original-Received: (qmail 26863 invoked by uid 65534); 17 May 2003 02:59:12 -0000 Original-Received: from pD9E7648C.dip.t-dialin.net (EHLO 520000401788.dialin.t-online.de) (217.231.100.140) by mail.gmx.net (mp006-rz3) with SMTP; 17 May 2003 04:59:12 +0200 Original-Received: from max by 520000401788.dialin.t-online.de with local (Exim 3.35 #1 (Debian)) id 19Grxp-0002PS-00; Sat, 17 May 2003 05:02:25 +0200 Original-To: djurfeldt@nada.kth.se In-Reply-To: Original-Lines: 132 User-Agent: Gnus/5.09 (Gnus v5.9.0) Emacs/21.2 Original-cc: guile-user@gnu.org Original-cc: Bill Schottstaedt X-BeenThere: guile-user@gnu.org X-Mailman-Version: 2.1b5 Precedence: list List-Id: General Guile related discussions List-Help: List-Post: List-Subscribe: , List-Archive: List-Unsubscribe: , Errors-To: guile-user-bounces+guile-user=m.gmane.org@gnu.org Xref: main.gmane.org gmane.lisp.guile.user:1969 X-Report-Spam: http://spam.gmane.org/gmane.lisp.guile.user:1969 Mikael Djurfeldt writes: > Bill Schottstaedt writes: > > > My take on Guile (which seems to me to have stalled out over the last > > few years) is that the current developers think of it as an extended > > shell-based interpreter > > Maybe this is totally out of context and misplaced--- snip I don`t think so, Mikael. Part of this thread stayed on documentation issues. I promised, to use my current first dive into scheme and guile to produce * critical remarks on the documentation * a proposal for changes concerning the overall-layout of the documentation As I got it, Neil thinks that "high level questions" about documentation structure have to be dealt with. Your mentioning of once formulated goals for the guile project fits quite well. > I include below the stated goals of Guile. Even though I'm not a > particularly active developer right now, these are goals that I > support strongly, and I think most of the other developers do as well, ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ snip If this is the case, the introductory parts of the manual should directly reflect these goals, as you state below. (I would say the guile tutorial should do so too) This would have accelerated my efforts to grasp the guile concept and scope quite a bit. > My contribution to this discussion would be that there is no single > "canonical" way of using Guile. Rather, there is a small handful of > canonical ways (which are reflected in the goals below). snip > I therefore think that many of the ideas that were discussed before > initiating work on the current manual were very good: that the manual > should present Guile from a small set of viewpoints connected to the > small set of canonical ways to use Guile. snip I cut out your thoughts on the C API, because I have no opinion on this issue yet. > workbook/policy/goals.text > ---------------------------------------------------------------------- > This file states the goals of Guile. > > * Goals of Guile > > ** Guile as an extension language library > > ** Guile as a programming language > > ** Guile as an interface to the operating system > > ** Guile as an interactive shell > > ** Guile as an integration platform > > ** Guile as a basis for other languages > As a newbie I agree with Mikael's reasoning and conclusions. What goes against using this structure for the introduction part of the manual? Then --if possible-- reflecting it in the tutorial and maybe it could even be used as a pattern for subsequent parts of the manual. I am not sure about this, but I bet most of the existing (and valuable) stuff of the documentation could be fitted in such a layout. It would be a structure a guile newbie could hang on to (I miss such a lifeline in the current manual), when coping with all those "strange new scheme and guile" concepts at once. regards max. PS: We would have to change the order: programming language and interactive interpreter comes first, then interface to os then the advanced concepts: extension, integration, ... (already mentioned --in short-- at the top of cause) _______________________________________________ Guile-user mailing list Guile-user@gnu.org http://mail.gnu.org/mailman/listinfo/guile-user