chicken-users
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[Chicken-users] A Proposal for Texinfo Reference Manual, was: Re: Chicke


From: Adhi Hargo
Subject: [Chicken-users] A Proposal for Texinfo Reference Manual, was: Re: Chicken manual in Texinfo format
Date: Mon, 21 May 2007 15:48:02 -0700 (PDT)

THE PROPOSAL:

Important point first: I propose, in the long run, to
spare the wiki for tutorials, introductions,
cookbooks, FAQs, installation problem, or anything
else any casual user could confidently contribute, and
let the maintainer or at least experienced programmers
(a number of you, I suppose) do the real manual in
Texinfo. The important chapters, I think, are:

* Overview

* Compiler usage
* Interpreter usage
* Interaction with Emacs through hen.el
* Modules(?) and Functions
* Foreign-Function Interface

* Functions index
* SRFI-support index

I'll give a serious try to merge extant work (based on
2.613, not the wiki. Can't mirror) this week and see
how it turned out. I'll learn an awful lot from the
process, anyway. I seldom write Texinfo, so it *might*
took longer to finish.

NOTE ABOUT THE STRUCTURE:

Of the two indices, the first any beginner will no
doubt constantly peek at, the second readily accessed
by more experienced Schemers. Each items in both
points to a specific subsection in the Functions
chapter.

SOME BACKGROUND:

I've tried MIT Scheme, Bigloo and PLT's (awesome)
Scheme coding environment. What I'm used to see in a
reference manual (GNU's especially), expect to (and
do) find in their docs, and found to be lacking in
Chicken's are (to say the least) a well-structured
index to programming concepts, and library-functions
supported by Chicken. Even hen.el's not described
(only Lispers could use it in its current state).
What's already provided is good, basically, but I find
it hard to comprehend the system as a whole without
looking at the source code and do regexp-search for
``^(define''s just to know what the codes could do
out-of-the-box and how they do that.

Even if no Texinfo version would ever exist, an
alphabetical index in the HTML docs' offline version
would suffice.

I don't use the other aforementioned systems anymore,
but still kept their docs to guess what I could expect
to find in Chicken. Only recently do I find that
Chicken (v2.6) barfs when I pass an output-port as the
last argument to write-string, unlike MIT Scheme (not
supposed to, according to the wiki. expected,
according to the source). Keeping a Bigloo/MIT Scheme
INFO file in a frame, R5RS INFO in another, and dired
frame of Chicken src sure helps but it could've been
better...

By the way, I'm concerned about the wiki->texinfo
thing. Wouldn't it be a dirty-hack kind of job,
knowing Texinfo's strictness, and HTML usage and wiki
engine's idiosyncracies? Don't know if it could be
done cleanly in a reusable manner in Scheme, though.
Now that's a good way to spend your hacking time.

--- Mario Domenech Goulart <address@hidden>
wrote:

> 
> I'm afraid I don't understand your point.  The
> User's Manual looks
> very good to me.  Can you provide more details about
> what you think
> could be improved (and how)?
> 



      
____________________________________________________________________________________Shape
 Yahoo! in your own image.  Join our Network Research Panel today!   
http://surveylink.yahoo.com/gmrs/yahoo_panel_invite.asp?a=7 






reply via email to

[Prev in Thread] Current Thread [Next in Thread]