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

[Ivan Raikov]

Hi Adhi,

   Given the current arrangement, I really think that maintaining a
separate Texinfo manual will take a lot of (redundant) effort. The
wiki is _not_ in HTML format, HTML is generated from the wiki internal
representation. There is already code to generate fairly decent LaTeX
code from the wiki, and some code to generate individual Texinfo
pages, so I don't think you need to be concerned about idiosyncrasies
and dirty hacks. Actually, the basic code that generates LaTeX and
Texinfo code is quite simple, the only thing that seems to be missing
from the latter (as far as I can tell) is a function to generate
Texinfo contents and node pointers. 

   hen.el at least has mode documentation (C-h m); what kind of
additional documentation would you suggest? I do agree that it needs
to be at least mentioned in the manual. I would say that hen.el was a
lot more convenient back when you could look up a symbol in the
Chicken Texinfo manual from within a Hen buffer.

   How about this: I will try to generate an example Texinfo manual
from the wiki, using the existing wiki->texinfo code and the Emacs
Texinfo editor functions, and you can look at it and tell me what you
think about it.


      -Ivan


Adhi Hargo <address@hidden> writes:

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