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 proposal



[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



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