Re: New manual plan

[thi <ttn@mingle.glug.org>]

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