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]

Re: New manual plan


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