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] |
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