This is the mail archive of the
guile@sourceware.cygnus.com
mailing list for the Guile project.
Re: Documentation proposal
- To: mgrabmue at cs dot tu-berlin dot de
- Subject: Re: Documentation proposal
- From: Michael Vanier <mvanier at bbb dot caltech dot edu>
- Date: Thu, 2 Dec 1999 16:51:31 -0800 (PST)
- Cc: guile at sourceware dot cygnus dot com
- References: <E11tcxF-00006V-00@tortoise.home.de>
[Martin Grabmueller]
> This leads to my intention for this posting. It would be great to have
> some HOWTO-style documentation covering things like scripting, network
> programming or text file processing. Of course, these are not the
> things computer scientists are too excited about, but the majority of
> programming tasks depend on stuff like that.
>
> Now that I have figured out the basics of Scheme programming and how
> to do basic system programming using Guile I would like to share my
> experiences with all people out there. Right now, I haven't written
> anything, but I have some ideas on my mind how to write a kind of
> "Pragmatic Guile Programming Guide".
>
> I don't feel very qualified neither in Scheme programming nor in
> writing documentation, so I wanted to ask you for your opinion about
> my idea before starting. Do you think this plan is worth it, and do
> you think whether there is any sense in writing a tutorial "on the
> fly", which means that I want to dig into this and while I do so, I
> want to document my steps and experiences, and finally merge
> everything into a kind of tutorial.
>
> This is not meant to be a general Scheme tutorial, because there are
> plenty of them out there, but merely a tutorial which covers the
> non-standard issues of writing programs using Guile.
This is a great idea; please pursue it. I would also really like to see:
-- examples of simple text-munging scripts using guile (e.g. read all lines
from a file, print those that meet certain criteria);
-- a detailed description of how the evaluator works. Why should everyone
have to rediscover this for themselves?
-- description of how to extend guile in C/C++, including adding new data
types;
-- a texinfo version of the reference manual, with all functions
described. IMO this is much more valuable than docstrings, though of
course the two aren't mutually exclusive.
I don't have the time (or the competence) to write this documentation
myself, but I do have the time to proofread documents, and maybe even to
help put them into texinfo format. I can also help test the test scripts.
Mike