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: 08 May 2003 23:36:44 +0100 Sender: guile-user-bounces+guile-user=m.gmane.org@gnu.org Message-ID: References: <3E92E1B4002B0632@pop3.tiscalinet.es> <3EAFE4EC000D9733@pop1.tiscalinet.es> <87d6its93b.fsf@raven.i.defaultvalue.org> NNTP-Posting-Host: main.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: main.gmane.org 1052434955 5340 80.91.224.249 (8 May 2003 23:02:35 GMT) X-Complaints-To: usenet@main.gmane.org NNTP-Posting-Date: Thu, 8 May 2003 23:02:35 +0000 (UTC) Cc: guile-devel@gnu.org Original-X-From: guile-user-bounces+guile-user=m.gmane.org@gnu.org Fri May 09 01:02:32 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 19DuOn-0001MS-00 for ; Fri, 09 May 2003 01:02:01 +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 19DuO8-0005sj-07 for guile-user@m.gmane.org; Thu, 08 May 2003 19:01:20 -0400 Original-Received: from list by monty-python.gnu.org with tmda-scanned (Exim 4.10.13) id 19DuMK-0004mj-00 for guile-user@gnu.org; Thu, 08 May 2003 18:59:28 -0400 Original-Received: from mail by monty-python.gnu.org with spam-scanned (Exim 4.10.13) id 19DuMF-0004dp-00 for guile-user@gnu.org; Thu, 08 May 2003 18:59:27 -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 19DuLr-0003eH-00; Thu, 08 May 2003 18:58:59 -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 h48MwrE19441; Thu, 8 May 2003 23:58:54 +0100 Original-Received: from laruns.ossau.uklinux.net.ossau.uklinux.net (localhost [127.0.0.1])ESMTP id DF313DC4D3; Thu, 8 May 2003 23:36:44 +0100 (BST) Original-To: Rob Browning In-Reply-To: <87d6its93b.fsf@raven.i.defaultvalue.org> Original-Lines: 106 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:1922 gmane.lisp.guile.devel:2299 X-Report-Spam: http://spam.gmane.org/gmane.lisp.guile.user:1922 >>>>> "Rob" == Rob Browning writes: Rob> 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.) Rob> I'm not sure how commonly this is an issue, but how hard Rob> would this be on people who are just writing C code (say Rob> perhaps for a shared lib or an object file that was intended Rob> to be used by apache (or whatever) as a dynamic module, Rob> i.e. mod_guile)? Well yes, this is exactly what we need to establish. But, to take mod_guile as an example, surely it's much easier to pass the whole page out to Scheme and process it there, than to do processing mostly in C? Rob> In particular, are there cases where it's hard to support Rob> having (finding) any .scm file, There probably are - for example embedded OSs with no filesystem - but I doubt that it is a priority to cater for them. To me, if defeats the whole object of Guile if catering for this case means that it is harder to improve Guile and its docs for the other 99% of cases. To avoid this happening, I suggest that we could solve this problem by a mechanism that links Scheme code into a library or executable at build time. This could be something like unexec (in which case the source would already have been read and stored in tree code), or it could be a linker tool that just dumps plain source code into the binary - as though it was a big const char[], but more convenient to use at build time. Rob> and if so, in those cases, what's the preferred solution -- Rob> embedded scheme strings that are evaled at runtime, or when Rob> you need something with more dynamic content, building the Rob> scheme form representing your function (or whatever) and then Rob> calling eval on that? Embedded Scheme is OK for small code fragments, otherwise as just suggested above. As far as dynamic content is concerned, is there any kind of dynamic Scheme content that can't be generated and then eval'd by a chunk of static Scheme code? (I don't think so, if it could be generated by a chunk of static C code.) Rob> I'm not sure this applies to scm_internal_catch, but just Rob> wanted to make sure we had thought about the likelihood of Rob> such a situation. Absolutely. What I've half-proposed is quite radical, so it's crucial to think it through carefully. To throw out another example: libguile currently has a set of old-fashioned primitives for manipulating object properties (scm_set_object_properties_x etc.). These should be deprecated in favour of the make-object-property mechanism, but it's currently hard to do this because the functions are part of the C API and so might be being used by someone's C code. If, on the other hand, these primitives were officially provided only on the Scheme level, it would be trivial to replace them with Scheme implementations written using make-object-property. >> That's what I'm thinking now, anyway. I think (**) may be quite >> controversial, so that at least needs a lot more discussion first. Rob> I think one counter argument would be "where do people who want to Rob> write C extensions to Guile go for documentation?". C extensions are covered by the documentation I've suggested, I believe. Specifically, that doc would describe how to write and export C primitives, validate and convert parameters between C and Scheme forms etc., how to create smobs, handle lifetime issues, ... Rob> As an example, if you want to write a big complex smob for something Rob> that's a heterogeneous collection of both C and scheme data, you may Rob> well need to use any number of scm_* functions to manipulate the Rob> smob's data structures from the C side, and you'd certainly want to Rob> have documentation for those functions. Absolutely. I think that data substructure manipulation functions like scm_cons, SCM_CAR and SCM_CDR, should be included in the documented C API. Rob> If it weren't for the fact that it could be a lot of extra work Rob> (unless we could somehow automate much of the process), it seems like Rob> a solution would be to have one main section that was Scheme oriented, Rob> with a structure and composition similar to what you described, and Rob> one main section which was "Guile from the C side". Now that I've been involved for some time, I'm pretty sure that any extra work will be insignificant compared to the long term cost of not having the right overall focus and structure. So I wouldn't worry about the work yet. Rob> Of course there would be a lot of duplicated text between the sections Rob> since, for example, you'd have to document scm_list_p and list? in Rob> separate sections with essentially the same text. True, but I think it might make sense in context anyway. Thanks for your thoughts, Neil _______________________________________________ Guile-user mailing list Guile-user@gnu.org http://mail.gnu.org/mailman/listinfo/guile-user