This is the mail archive of the guile@sourceware.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]

Re: Documentation [Was: I resign as Guile maintainer]


Andrew Chadwick <andrew.chadwick@symbian.com> writes:

> guile-owner@sourceware.cygnus.com writes:
> 
> Dratted Notes servers. I hope I'm replying to the right Greg here... :)
> 
> > Andrew Chadwick <andrew.chadwick@symbian.com> writes:
> > > guile-owner@sourceware.cygnus.com writes:
> > > [snip]
> > > > I'll also briefly take this opportunity to state what I claim is the
> > > > most significant problem with Guile:
> > > > Lack of reasonable documentation.
> [...]
> > > Well, the only reasonable thing I could do at this point would be to
> > > volunteer some of my spare time. Please, who is coordinating the
> > > documentation effort?
> > 
> > Excellent-- volunteers are tremendously appreciated, and no contribution
> > is to small.
> > 
> > I believe I'm coordinating the documentation effort (though if someone
> > has more time, I'm happy to just manage the docstrings).  My first goal
> > is a docstring extraction system similar to Scwm's.  In parallel,
> > plain-text documentation can be written by any who would like.  We can
> > add markup or convert to TeXInfo later.
> 
> Where would be a good place to start? I could start with writing that
> 10-minute tour of scheme I mentioned and then more on to the more
> detailed stuff (<uzovsqk6k.fsf@symbian.com>), or equally I could begin
> to mash docstrings and comments into boot-9 and friends via CVS. Which
> do you think is needed first?

Well, the docstring system won't be ready in Guile until next Monday at
the earliest.  If you want to try your hand at a ten minute introduction 
to Scheme, that might be helpful, but you should first check the
existing tutorials and ensure that you're making a novel contribution.
I'm not familiar enough with the intro stuff that's available to say for 
sure, but there are several introductory Scheme pieces on the web that
we might be able to use for Guile.  Another need is an outline of the
full Guile manual (probably modeled off of the Emacs Lisp Manual).

After I've got the doc system in place, it'd be great to have folks
moving the existing documentation into the docstrings.  I'll do a file
or two to gain experience and debug, but would love help in getting the
rest migrated.

> I think any kind of SCWM-like approach that can get docstrings for
> builtins visible from an interactive guile session is a good thing.

Agreed.  That's my first goal; I've updated Scwm to use a slightly
different system that I think is better for Guile and will migrate that
stuff next weekend, I hope.

Thanks,
Greg

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]