From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: Neil Jerram Newsgroups: gmane.lisp.guile.user,gmane.lisp.guile.devel Subject: Re: Doc organization (Re: Around again, and docs lead role) Date: 07 May 2003 22:06:57 +0100 Sender: guile-user-bounces+guile-user=m.gmane.org@gnu.org Message-ID: 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 1052374830 16287 80.91.224.249 (8 May 2003 06:20:30 GMT) X-Complaints-To: usenet@main.gmane.org NNTP-Posting-Date: Thu, 8 May 2003 06:20:30 +0000 (UTC) Cc: guile-user@gnu.org Original-X-From: guile-user-bounces+guile-user=m.gmane.org@gnu.org Thu May 08 08:20:24 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 19DelU-0004EY-00 for ; Thu, 08 May 2003 08:20:24 +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 19Demj-0005r2-00 for guile-user@m.gmane.org; Thu, 08 May 2003 02:21:41 -0400 Original-Received: from list by monty-python.gnu.org with tmda-scanned (Exim 4.10.13) id 19Dem4-0005SI-00 for guile-user@gnu.org; Thu, 08 May 2003 02:21:00 -0400 Original-Received: from mail by monty-python.gnu.org with spam-scanned (Exim 4.10.13) id 19Dem1-0005Nw-00 for guile-user@gnu.org; Thu, 08 May 2003 02:20:58 -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 19Dem0-0005Lq-00; Thu, 08 May 2003 02:20:56 -0400 Original-Received: from laruns.ossau.uklinux.net (bts-0859.dialup.zetnet.co.uk [194.247.51.91]) by s1.uklinux.net (8.11.6p2/8.11.6) with ESMTP id h486Kqt04046; Thu, 8 May 2003 07:20:53 +0100 Original-Received: from laruns.ossau.uklinux.net.ossau.uklinux.net (localhost [127.0.0.1])ESMTP id 59A56DC4D3; Wed, 7 May 2003 22:06:57 +0100 (BST) Original-To: ricardmm@tiscali.es In-Reply-To: <3EAFE4EC000D9733@pop1.tiscalinet.es> Original-Lines: 67 User-Agent: Gnus/5.0808 (Gnus v5.8.8) Emacs/20.7 Original-cc: guile-devel@gnu.org 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:1914 gmane.lisp.guile.devel:2288 X-Report-Spam: http://spam.gmane.org/gmane.lisp.guile.devel:2288 >>>>> "Ricard" == Ricard Mira writes: Ricard> Thanks. I think that I need to learn more about Guile in Ricard> order to be able to propose something sound, but I can Ricard> give my opinion as a user. 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). Interesting. It was my idea to document the whole Guile API in the current unified way, covering both C and Scheme together, but I have been wondering about whether that was a good decision. In many cases it seems to result in adding a subsection saying "And there are also these related C functions and macros ...", which feels unsatisfactory. Ricard> Neil, are your half-formed thoughts the same as my Ricard> half-formed thoughts? :-) Not obviously, no, but it may be that there is some underlying overlap between them. 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, a it is difficult even to describe the documentation status.) Specifically, I think we should (**) promote doing as much programming as possible in Scheme, and restrict documentation of the C API to the parts needed for interfacing Scheme to C code. (To give a concrete example from another thread, I see no need for people to write C code that uses scm_internal_catch.) If we did this, I think the natural high level documentation structure would then be: - 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: - 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. Regards, Neil _______________________________________________ Guile-user mailing list Guile-user@gnu.org http://mail.gnu.org/mailman/listinfo/guile-user