RE: New manual plan

["Reynolds, Gregg" <greynolds@datalogics.com>]

I suggest functional organization with lots of indices and xref lists;
use XML if you want to avoid duplicate data; and most importantly, drop
the Grand Plan of The Manual approach in favor of a pamphlet approach
(or: prefer the bazar to the cathedral) - make it the Guile
Documentation Library.  Establish editorial policies, an XML DTD, some
categories, and maybe guidelines on how to classify a pamphlet and write
a synopsis for inclusion in the master index, etc.  I think it would be
much easier then to get others to write doc about their favorite little
corner of Guile, and you wouldn't need to worry to much about
integrating things.

I'd especially like to see a detailed "How Guile Stacks Up to
(perl/python/vb/you-name-it)" pamphlet or series of pamphlets.  I could
have used one a few weeks ago when my boss was looking at Scheme v.
Python as an extension language.  

gregg

-----Original Message-----
From: Jim Blandy [mailto:jimb@red-bean.com]
Sent: Wednesday, November 11, 1998 8:56 PM
To: Maciej Stachowiak
Cc: guile@cygnus.com
Subject: Re: New manual plan



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

If you can suggest a good solution to the duplication problem, I might
change my mind.