This is the mail archive of the guile@cygnus.com mailing list for the guile project.
Index Nav: | [Date Index] [Subject Index] [Author Index] [Thread Index] | |
---|---|---|
Message Nav: | [Date Prev] [Date Next] | [Thread Prev] [Thread Next] |
Jim Blandy writes: > Issue: what's the best way to document the (many) functions that are > written in C, and visible to Scheme via the SCM_PROC macros? It's > silly to document them twice --- they're exactly the same function. > With the organization I posted, there's a consistent, easy-to- > understand answer. Your info file will look like this: > > - Scheme Function: eof-object? OBJ > - C Function: SCM scm_eof_object_p (SCM OBJ) > Return true iff OBJ is the end-of-file object. > > And your printed manual will look like this: > > eof-object? obj Scheme Function > SCM scm_eof_object_p (SCM obj) C Function > Return true iff OBJ is the end-of-file object. > > This is the formatting used in the Emacs Lisp manual and the GNU C > library manual, both of which I like a lot. This organization seems fairly pleasant to me. When programming requires a particular language domain, it is easy to ignore the other stuff. I also like the focus on functionality, rather than language. We should remember that cross-referencing can make one organization look like another, at least superficially. thi