Re: api differences between 1.4 and 1.6

[Thien-Thi Nguyen]

   From: Neil Jerram <address@hidden>
   Date: 09 Mar 2002 20:18:59 +0000

   Yes, as Dirk has also pointed out.  So now we are thinking instead of
   being more rigorous about using scm_i_ and SCM_I_ prefixes (as
   discussed on the list some time back).

this decision is partially expanded in devel/policy/names.text.  (if the
unresolved issues mentioned there have been resolved, we need to record
those decisions at some point.  if not, someone needs to periodically
tickle the issue until it is resolved.)

clearly there are separate types of grouping required, for different
audiences.  how to define a group and how to recognize members of the
group are likewise two different problems whose efforts need not be
serialized.  making definition dependent on method allows method bugs to
re-burden definitions more than necessary.

all of this means that we need to (think a bit and then) publish groups
as a triple of name, semantics, and members.  over time, we also write
tools to recognize group members, perhaps by exploiting some part of the
semantics.  when the tools are able to exactly produce what we published
manually, we can switch over to using tools exclusively, and celebrate
the ratchet tick in process.

to suggest a way towards more joyful maintenance, below is a file i
would like to add as doc/groupings.alist.  it's not in final form yet
(scan-api needs to change so that guile-api.alist represents Scheme/C
origin as a sub-alist member rather than a pre-formed group -- this
flattened regularity facilitates annotation, subsetting, and the
grouping engine design), but pretty close.

comments are appreciated, particularly on schemes to compose grouping
grok procedures.  (maybe we'll get an sql front end out of this...)

thi


_______________________________________
;; groupings.alist
;; -*-scheme-*-

;; This file describes groupings of available bindings (both Scheme and C).
;; The overall structure is an alist.  Each entry has the form:
;;
;;   (NAME (description "DESCRIPTION") (members SYM...))
;;
;; All of these should be proper subsets of guile-api.alist.
;; In addition to `description' and `members' forms, the entry may
;; optionally include:
;;
;;   (grok USE-MODULES (lambda (guile-api-alist) CODE))
;;
;; where CODE returns a subset of guile-api-alist.  If this "grok procedure"
;; produces the same set as the `members' form, you can omit the `members'
;; form entirely.  When evaluated, CODE can assume (use-modules MODULE) has
;; been executed where MODULE is an element of USE-MODULES, a list.

(

(scheme
 (description "visible to top-level repl")
 (grok ((ice-9 common-list))
       (lambda (all)
         (pick (lambda (b) (assq 'scheme b)) all))))

(C
 (description "public libguile")
 (grok ((ice-9 common-list))
       (lambda (all)
         (pick (lambda (b) (assq 'C b)) all))))

(guile-ref
  (description "documented in guile reference manual")
  (members [TODO TODO TODO ...])
  ;; grok should be some fancy grep (everything is fancy grep :-)
  )

;; Add new grouping descriptions here.
)

;; groupings.alist ends here