Guile Mailing List Archive

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: New manual plan



On 11 Nov 1998, Jim Blandy wrote:

> > Yes, that was my point too. To restate, I think for the vast majority of
> > people who will be using Guile, they decide first what language domain
> > they want to work in for a specific task, and then think about what
> > functionality they need, and the manual should reflect that.
> 
> That's persuasive.  But I'm still hung up on the fact that I'll either
> have to document every Scheme-visible scm_ function twice, or have one
> section just be cheezy and refer the reader to another section of the
> manual.
> 
> That, combined with the appeal of organizing the manual strictly by
> functionality, and the thought that people can ignore the languages
> they don't care about, are what make me like the organization I
> proposed.

I'm more in favor of an organization by functionality as well. I guess,
many people (like it is true for me) will discover that they have to mix
different language domains. It may be a little bit inconvenient for
someone who knows that he will be programming in scheme-only to flip over
the pages with the description of the C API, but that's not a real
problem. 

It may even be helpful to see that correspondence. Provided there are
tutorial sections about how to use the different language domains
separately and even in combination, I suppose some people will appreciate
to know about the different possibilities to solve their particular
problem.

If there are functions regarding some topic 'x', there may even be some
introduction to the concepts behind the implementation and interface of
the features of 'x'. Such an introduction (in my point of view) fits very
nicely at the beginning of the chapter which describes the 'x'-API. With
scheme and C functions put in the same place, the crossreferencing is
minimal. Otherwise you will have to decide, where to put the introduction
or duplicate it. If you don't want to duplicate it, I guess people will
have to do quite a lot more of annoying crossref-tracing.

Best regards, 
Dirk Herrmann


Guile Home | Main Index | Thread Index