Re: Doc organization (Re: Around again, and docs lead role)

[Rob Browning]

Neil Jerram <address@hidden> 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.)

I'm not sure how commonly this is an issue, but how hard would this be
on people who are just writing C code (say perhaps for a shared lib or
an object file that was intended to be used by apache (or whatever) as
a dynamic module, i.e. mod_guile)?

In particular, are there cases where it's hard to support having
(finding) any .scm file, and if so, in those cases, what's the
preferred solution -- embedded scheme strings that are evaled at
runtime, or when you need something with more dynamic content,
building the scheme form representing your function (or whatever) and
then calling eval on that?  I'm not sure this applies to
scm_internal_catch, but just wanted to make sure we had thought about
the likelihood of such a situation.

> That's what I'm thinking now, anyway.  I think (**) may be quite
> controversial, so that at least needs a lot more discussion first.

I think one counter argument would be "where do people who want to
write C extensions to Guile go for documentation?".

As an example, if you want to write a big complex smob for something
that's a heterogeneous collection of both C and scheme data, you may
well need to use any number of scm_* functions to manipulate the
smob's data structures from the C side, and you'd certainly want to
have documentation for those functions.

If it weren't for the fact that it could be a lot of extra work
(unless we could somehow automate much of the process), it seems like
a solution would be to have one main section that was Scheme oriented,
with a structure and composition similar to what you described, and
one main section which was "Guile from the C side".

Of course there would be a lot of duplicated text between the sections
since, for example, you'd have to document scm_list_p and list? in
separate sections with essentially the same text.

-- 
Rob Browning
rlb @defaultvalue.org, @linuxdevel.com, and @debian.org
Previously @cs.utexas.edu
GPG starting 2002-11-03 = 14DD 432F AE39 534D B592  F9A0 25C8 D377 8C7E 73A4