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 Subject: Re: State of Docs [was] Re: Around again, and docs lead role Date: 09 May 2003 00:11:42 +0100 Sender: guile-user-bounces+guile-user=m.gmane.org@gnu.org Message-ID: References: <3E92E1B40021F4D7@pop3.tiscalinet.es> <20030503113403.GC5407@www> <20030508223242.GB3465@www> NNTP-Posting-Host: main.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: main.gmane.org 1052436290 11070 80.91.224.249 (8 May 2003 23:24:50 GMT) X-Complaints-To: usenet@main.gmane.org NNTP-Posting-Date: Thu, 8 May 2003 23:24:50 +0000 (UTC) Cc: Robert Uhl Original-X-From: guile-user-bounces+guile-user=m.gmane.org@gnu.org Fri May 09 01:24:47 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 19Duko-0002rs-00 for ; Fri, 09 May 2003 01:24:46 +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 19DulE-0004el-01 for guile-user@m.gmane.org; Thu, 08 May 2003 19:25:12 -0400 Original-Received: from list by monty-python.gnu.org with tmda-scanned (Exim 4.10.13) id 19DukJ-0003hH-00 for guile-user@gnu.org; Thu, 08 May 2003 19:24:15 -0400 Original-Received: from mail by monty-python.gnu.org with spam-scanned (Exim 4.10.13) id 19Dujm-0002eT-00 for guile-user@gnu.org; Thu, 08 May 2003 19:23:42 -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 19DufO-00013i-00 for guile-user@gnu.org; Thu, 08 May 2003 19:19:10 -0400 Original-Received: from laruns.ossau.uklinux.net (bts-0048.dialup.zetnet.co.uk [194.247.48.48]) by s1.uklinux.net (8.11.6p2/8.11.6) with ESMTP id h48NJ0j22561; Fri, 9 May 2003 00:19:01 +0100 Original-Received: from laruns.ossau.uklinux.net.ossau.uklinux.net (localhost [127.0.0.1])ESMTP id C6B24DC4D3; Fri, 9 May 2003 00:11:42 +0100 (BST) Original-To: rm@fabula.de In-Reply-To: <20030508223242.GB3465@www> Original-Lines: 54 User-Agent: Gnus/5.0808 (Gnus v5.8.8) Emacs/20.7 Original-cc: guile-user@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:1923 X-Report-Spam: http://spam.gmane.org/gmane.lisp.guile.user:1923 >>>>> "rm" == rm writes: rm> Yes. Right now, whenever i stumble upon a usefull but undocumented rm> part of the Guile API i'm somehow reluctant to use it since i fear rm> that it's not as stable as the documented part. rm> Who to consult in such a case? Guile-devel or Guile-user? guile-devel, I'd say. Although arguably you will always get the answer yes, as the current position (I think) is that everything exported by libguile is part of the API and therefore usable. rm> Yes, i would assume that it's up to those who write the documentation rm> for guile-embedding applications to provide helpfull intros/tutorials. rm> After all: most general Scheme tutorials will present things like rm> 'my-fact' or 'is-prime?' while users probably want to read about rm> 'print-in-blue' or 'image-blur' .... Agreed. rm> BTW, in case i have a documentation patch: where to send it to? rm> Post it here? Strictly, bug-guile@gnu.org. But I don't think it would get lost if you sent it to guile-devel instead. rm> Finally, a proposal: I think it would be rather helpfull if the rm> documentation for C functions as well as CPP makros would include rm> the type specifier. So, instead of: rm> scm_make_vector (k, fill) rm> give rm> scm_c_make_vector (unsigned long int k, SCM fill) rm> Not having the parameter types is sometimes missleading, rm> esp. if the same parameter name sometimes stands for a C value rm> and sometimes for a SCM value (see for ex.: 'scm_vector_set_x rm> vector k obj', where 'k' stands for SCM value). I'm willing rm> to take over that job and update the relevant parts over the rm> next few weeks if people find this helpfull. I may be wrong, but I don't think there's any ambiguity in the current docs. Wherever a type specifier is omitted, it should be understood as SCM. (The reason for this is a makeinfo restriction: makeinfo can't handle a @deffn followed by a @deftypefnx.) I think the real problem is that, in many cases, the C level function like scm_c_make_vector isn't documented. I completely agree that it should be, and that its type specifiers should be shown explicitly. Does this make sense? Neil _______________________________________________ Guile-user mailing list Guile-user@gnu.org http://mail.gnu.org/mailman/listinfo/guile-user