From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: Neil Jerram Newsgroups: gmane.lisp.guile.devel Subject: Re: Doc organization (Re: Around again, and docs lead role) Date: 08 May 2003 23:57:02 +0100 Sender: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Message-ID: 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 1052434964 5393 80.91.224.249 (8 May 2003 23:02:44 GMT) X-Complaints-To: usenet@main.gmane.org NNTP-Posting-Date: Thu, 8 May 2003 23:02:44 +0000 (UTC) Cc: guile-devel@gnu.org Original-X-From: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Fri May 09 01:02:43 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 19DuOa-0001L7-00 for ; Fri, 09 May 2003 01:01:48 +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 19DuMT-0004kd-00 for guile-devel@m.gmane.org; Thu, 08 May 2003 18:59:37 -0400 Original-Received: from list by monty-python.gnu.org with tmda-scanned (Exim 4.10.13) id 19DuM4-0004Gh-00 for guile-devel@gnu.org; Thu, 08 May 2003 18:59:12 -0400 Original-Received: from mail by monty-python.gnu.org with spam-scanned (Exim 4.10.13) id 19DuLx-0003vi-00 for guile-devel@gnu.org; Thu, 08 May 2003 18:59:07 -0400 Original-Received: from mail.uklinux.net ([80.84.72.21] helo=s1.uklinux.net) by monty-python.gnu.org with esmtp (Exim 4.10.13) id 19DuLo-0003Rl-00 for guile-devel@gnu.org; Thu, 08 May 2003 18:58:56 -0400 Original-Received: from laruns.ossau.uklinux.net (bts-0938.dialup.zetnet.co.uk [194.247.51.170]) by s1.uklinux.net (8.11.6p2/8.11.6) with ESMTP id h48MwqE19439; Thu, 8 May 2003 23:58:53 +0100 Original-Received: from laruns.ossau.uklinux.net.ossau.uklinux.net (localhost [127.0.0.1])ESMTP id 4E1BADC4D5; Thu, 8 May 2003 23:57:02 +0100 (BST) Original-To: Max Techter In-Reply-To: <86wuh12yuc.fsf@520000401788.dialin.t-online.de> Original-Lines: 59 User-Agent: Gnus/5.0808 (Gnus v5.8.8) Emacs/20.7 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:2300 X-Report-Spam: http://spam.gmane.org/gmane.lisp.guile.devel:2300 >>>>> "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 .... 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? How would you improve it? >> , 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. >> - 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. 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. Thanks for your thoughts, Neil _______________________________________________ Guile-devel mailing list Guile-devel@gnu.org http://mail.gnu.org/mailman/listinfo/guile-devel