From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: Rob Browning Newsgroups: gmane.lisp.guile.devel,gmane.lisp.guile.user Subject: Re: Doc organization (Re: Around again, and docs lead role) Date: Thu, 08 May 2003 11:21:12 -0500 Sender: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Message-ID: <87d6its93b.fsf@raven.i.defaultvalue.org> 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 1052411092 19230 80.91.224.249 (8 May 2003 16:24:52 GMT) X-Complaints-To: usenet@main.gmane.org NNTP-Posting-Date: Thu, 8 May 2003 16:24:52 +0000 (UTC) Cc: guile-devel@gnu.org Original-X-From: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Thu May 08 18: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 19DoBR-0004tN-00 for ; Thu, 08 May 2003 18:23:49 +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 19DoCJ-0007Yp-04 for guile-devel@m.gmane.org; Thu, 08 May 2003 12:24:43 -0400 Original-Received: from list by monty-python.gnu.org with tmda-scanned (Exim 4.10.13) id 19DoAN-0006lI-00 for guile-devel@gnu.org; Thu, 08 May 2003 12:22:43 -0400 Original-Received: from mail by monty-python.gnu.org with spam-scanned (Exim 4.10.13) id 19Do9b-0006Do-00 for guile-devel@gnu.org; Thu, 08 May 2003 12:21:56 -0400 Original-Received: from dsl093-098-016.wdc1.dsl.speakeasy.net ([66.93.98.16] helo=defaultvalue.org) by monty-python.gnu.org with esmtp (Exim 4.10.13) id 19Do8y-00060l-00; Thu, 08 May 2003 12:21:16 -0400 Original-Received: from raven.i.defaultvalue.org (raven.i.defaultvalue.org [192.168.1.7]) by defaultvalue.org (Postfix) with ESMTP id 7665741D1; Thu, 8 May 2003 11:21:12 -0500 (CDT) Original-Received: by raven.i.defaultvalue.org (Postfix, from userid 1000) id 429EA2150F7; Thu, 8 May 2003 11:21:12 -0500 (CDT) Original-To: Neil Jerram In-Reply-To: (Neil Jerram's message of "07 May 2003 22:06:57 +0100") User-Agent: Gnus/5.1001 (Gnus v5.10.1) Emacs/21.3 (gnu/linux) Original-cc: guile-user@gnu.org 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:2291 gmane.lisp.guile.user:1918 X-Report-Spam: http://spam.gmane.org/gmane.lisp.guile.devel:2291 Neil Jerram writes: > 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.) I'm not sure how commonly this is an issue, but how hard would this be on people who are just writing C code (say perhaps for a shared lib or an object file that was intended to be used by apache (or whatever) as a dynamic module, i.e. mod_guile)? In particular, are there cases where it's hard to support having (finding) any .scm file, and if so, in those cases, what's the preferred solution -- embedded scheme strings that are evaled at runtime, or when you need something with more dynamic content, building the scheme form representing your function (or whatever) and then calling eval on that? I'm not sure this applies to scm_internal_catch, but just wanted to make sure we had thought about the likelihood of such a situation. > That's what I'm thinking now, anyway. I think (**) may be quite > controversial, so that at least needs a lot more discussion first. I think one counter argument would be "where do people who want to write C extensions to Guile go for documentation?". As an example, if you want to write a big complex smob for something that's a heterogeneous collection of both C and scheme data, you may well need to use any number of scm_* functions to manipulate the smob's data structures from the C side, and you'd certainly want to have documentation for those functions. If it weren't for the fact that it could be a lot of extra work (unless we could somehow automate much of the process), it seems like a solution would be to have one main section that was Scheme oriented, with a structure and composition similar to what you described, and one main section which was "Guile from the C side". Of course there would be a lot of duplicated text between the sections since, for example, you'd have to document scm_list_p and list? in separate sections with essentially the same text. -- Rob Browning rlb @defaultvalue.org, @linuxdevel.com, and @debian.org Previously @cs.utexas.edu GPG starting 2002-11-03 = 14DD 432F AE39 534D B592 F9A0 25C8 D377 8C7E 73A4 _______________________________________________ Guile-devel mailing list Guile-devel@gnu.org http://mail.gnu.org/mailman/listinfo/guile-devel