From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: rm@fabula.de Newsgroups: gmane.lisp.guile.user Subject: State of Docs [was] Re: Around again, and docs lead role Date: Fri, 9 May 2003 00:32:42 +0200 Sender: guile-user-bounces+guile-user=m.gmane.org@gnu.org Message-ID: <20030508223242.GB3465@www> References: <3E92E1B40021F4D7@pop3.tiscalinet.es> <20030503113403.GC5407@www> NNTP-Posting-Host: main.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: main.gmane.org 1052429818 15158 80.91.224.249 (8 May 2003 21:36:58 GMT) X-Complaints-To: usenet@main.gmane.org NNTP-Posting-Date: Thu, 8 May 2003 21:36:58 +0000 (UTC) Cc: rm@fabula.de Original-X-From: guile-user-bounces+guile-user=m.gmane.org@gnu.org Thu May 08 23:36:51 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 19Dt3s-0003te-00 for ; Thu, 08 May 2003 23:36:20 +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 19Dt1o-0004M8-00 for guile-user@m.gmane.org; Thu, 08 May 2003 17:34:12 -0400 Original-Received: from list by monty-python.gnu.org with tmda-scanned (Exim 4.10.13) id 19Dt1Q-0004Ly-00 for guile-user@gnu.org; Thu, 08 May 2003 17:33:48 -0400 Original-Received: from mail by monty-python.gnu.org with spam-scanned (Exim 4.10.13) id 19Dt0u-0004HK-00 for guile-user@gnu.org; Thu, 08 May 2003 17:33:47 -0400 Original-Received: from [217.22.192.104] (helo=www.elogos.de) by monty-python.gnu.org with esmtp (Exim 4.10.13) id 19Dt0t-0004HG-00 for guile-user@gnu.org; Thu, 08 May 2003 17:33:16 -0400 Original-Received: by www.elogos.de (Postfix, from userid 5001) id 1707E1457F; Fri, 9 May 2003 00:32:42 +0200 (CEST) Original-To: Neil Jerram Content-Disposition: inline In-Reply-To: User-Agent: Mutt/1.5.3i Original-cc: Robert Uhl 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:1920 X-Report-Spam: http://spam.gmane.org/gmane.lisp.guile.user:1920 On Wed, May 07, 2003 at 11:52:46PM +0100, Neil Jerram wrote: > >>>>> "rm" == rm writes: > > rm> I started writing up some info last night but i'm not shure > rm> whether the lack of documentation actually manifests some > rm> public vs. private API issue. > > Now, no, it just manifests lack of documentation, I'm afraid :-) > In the future, though, I do think it would be nice to reach a > situation where > > documented <=> public and supported API Yes. Right now, whenever i stumble upon a usefull but undocumented part of the Guile API i'm somehow reluctant to use it since i fear that it's not as stable as the documented part. Who to consult in such a case? Guile-devel or Guile-user? > rm> Hmm, there a a handfull of pretty good Scheme intros > rm> available, why bother duplicating these efforts (better: write > rm> a Guile-specific addendum for one of these). > > Tricky one, but I think if we get the rest of the GUile docs right, > and bring more users on board, the need (or not) for this will become > clearer. Yes, i would assume that it's up to those who write the documentation for guile-embedding applications to provide helpfull intros/tutorials. After all: most general Scheme tutorials will present things like 'my-fact' or 'is-prime?' while users probably want to read about 'print-in-blue' or 'image-blur' .... > rm> Yes. And it would be _very_ helpfull if the documentation > rm> would mention what modules need to be "used" for certain > rm> functions [(ice-9 regexp) for regular expressions ...). > > Completely agree; it's just a bug if the necessary use-module isn't > documented. Patches welcome! Ok, next time i find one ... BTW, in case i have a documentation patch: where to send it to? Post it here? > rm> Another question: there's some very good information in the > rm> guile-workbook CVS module. But sometimes it's hard to tell > rm> whether a piece is documenting an existing fact of Guile or > rm> rather proposing a new impementation. > > IMO the starting assumption should be that workbook stuff is not > implemented and so not valid as documentation. If you can identify > any text that is valid, then ideally, please convert it to a patch > against the manual. Finally, a proposal: I think it would be rather helpfull if the documentation for C functions as well as CPP makros would include the type specifier. So, instead of: scm_make_vector (k, fill) give scm_c_make_vector (unsigned long int k, SCM fill) Not having the parameter types is sometimes missleading, esp. if the same parameter name sometimes stands for a C value and sometimes for a SCM value (see for ex.: 'scm_vector_set_x vector k obj', where 'k' stands for SCM value). I'm willing to take over that job and update the relevant parts over the next few weeks if people find this helpfull. Thanks, Ralf _______________________________________________ Guile-user mailing list Guile-user@gnu.org http://mail.gnu.org/mailman/listinfo/guile-user