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 18:21:47 +0200 Sender: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Message-ID: <86wuh12yuc.fsf@520000401788.dialin.t-online.de> References: <3E92E1B4002B0632@pop3.tiscalinet.es> <3EAFE4EC000D9733@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 1052411364 20921 80.91.224.249 (8 May 2003 16:29:24 GMT) X-Complaints-To: usenet@main.gmane.org NNTP-Posting-Date: Thu, 8 May 2003 16:29:24 +0000 (UTC) Cc: guile-devel@gnu.org Original-X-From: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Thu May 08 18:29:22 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 19DoEX-0005DD-00 for ; Thu, 08 May 2003 18:27:01 +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 19DoFa-0000i2-01 for guile-devel@m.gmane.org; Thu, 08 May 2003 12:28:06 -0400 Original-Received: from list by monty-python.gnu.org with tmda-scanned (Exim 4.10.13) id 19DoEy-0000NC-00 for guile-devel@gnu.org; Thu, 08 May 2003 12:27:28 -0400 Original-Received: from mail by monty-python.gnu.org with spam-scanned (Exim 4.10.13) id 19DoEf-00005I-00 for guile-devel@gnu.org; Thu, 08 May 2003 12:27:10 -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 19Do74-0005Xy-00 for guile-devel@gnu.org; Thu, 08 May 2003 12:19:18 -0400 Original-Received: (qmail 23188 invoked by uid 65534); 8 May 2003 16:19:16 -0000 Original-Received: from pD9E75D24.dip.t-dialin.net (EHLO 520000401788.dialin.t-online.de) (217.231.93.36) by mail.gmx.net (mp013-rz3) with SMTP; 08 May 2003 18:19:16 +0200 Original-Received: from max by 520000401788.dialin.t-online.de with local (Exim 3.35 #1 (Debian)) id 19Do9T-0003fT-00; Thu, 08 May 2003 18:21:47 +0200 Original-To: Neil Jerram In-Reply-To: Original-Lines: 163 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:2292 X-Report-Spam: http://spam.gmane.org/gmane.lisp.guile.devel:2292 Neil Jerram writes: > >>>>> "Ricard" == Ricard Mira writes: > > > Ricard> As a user who is learning Scheme to customize and extend > Ricard> Guile-using programs, I expect the Guile documentation to > Ricard> contain a section for each programming language (C and > Ricard> Scheme for sure; translated languages maybe). Then I need ^^^^^^^^^^^ > Ricard> to read just the Scheme section (and maybe also a general ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ > Ricard> introduction). ^^^^^^^^^^^^^^^^^^^^^ snip What about a tutorial, Ricard? Hi, I am new to guile, my name is max. I came across guile, when I gathered information about: What makes up a GNU Package. As I got it: The decision was and is: The GNU Glue, should be GUILE. Being interested in providing my own stuff to the GNU Project and/or in giving help to another GNU Package, I accepted the need to dive into GUILE. Thus I naturally had an eye on this thread about the need of restructuring and improving the documentation. > 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.) My first impression was: Oops... such an important project, but obviously abandoned... The documentation is one of the first important impressions a (potential) user gets. I typically look out for a tutorial, immediately after installation. Not to learn, but to find out: is this something for me? > > Specifically, I think we should (**) promote doing as much programming > as possible in Scheme, Yeah. > and restrict documentation of the C API to the > parts needed for interfacing Scheme to C code. snip Yeah. > , I think the natural high level documentation structure > would then be: > I am missing, things like: * Tutorial * Introduction ** Background, History ** Advantages ... Basic Concepts, or whatever * Rational / Advocacy ** nothing you can`t do with lisp like languages, ** hackable, short path to C ** scientific background * GOOPS (proof of the `nothing you can`t do statement) * R5RS * Other freely available or even included documentation (Some of these sections need not be high volume but they serve important purposes.) > - 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: Task based structuring the meat of the documentation is an idea I like, Neil. That`s what we use software for: Solving Tasks (beside for having incredible fun, of cause =:) > - writing and exporting primitives (in modules) > - smobs, GC, lifetimes etc. > - Guile initialization from within a library > - how to call out to a Scheme-defined procedure > - how to look up a Scheme-defined variable > - how to evaluate user-supplied code and catch errors > - (anything else that I've missed). > Which has something in common with your thoughts. > > That's what I'm thinking now, anyway. I think (**) may be quite > controversial, > so that at least needs a lot more discussion first. Here we are... regards max. _______________________________________________ Guile-devel mailing list Guile-devel@gnu.org http://mail.gnu.org/mailman/listinfo/guile-devel