guile-devel
[Top][All Lists]
Advanced

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

Re: r6rs library documentation


From: Ludovic Courtès
Subject: Re: r6rs library documentation
Date: Wed, 05 May 2010 23:12:57 +0200
User-agent: Gnus/5.13 (Gnus v5.13) Emacs/23.1 (gnu/linux)

Hi Julian!

Julian Graham <address@hidden> writes:

> As per Andy's suggestion, I'd like to start adding some documentation
> for the R6RS library code Ive been working on, and I wanted to get a
> sense of where that documentation should go.

Nice!

> My initial feeling is that there are two documentation sections to be
> created: A description of Guile's implementation of the R6RS `library'
> and `import' forms; and some notes on the bits of the R6RS "Standard
> Libraries" that Guile provides, along with pointers to more formal
> specs.  I'd say the first part should go in api-modules.texi (right
> after "R6RS Version References"),

Agreed.

> whereas the second should go into its own file and be included
> somewhere near "Standard Libraries" (which could be renamed to "Guile
> Standard Libraries") in guile.texi.

I think the main section could be “R6RS Standard Libraries”, right after
“SRFI Support”, and could be organized similarly to “SRFI Support”,
i.e., with one node per module.

Bytevectors and (rnrs io ports) are already documented in other places
because they provide functionality not available elsewhere in Guile.
These sections would stay where they are and would be linked to in “R6RS
Standard Libraries”.

There could be other R6RS modules deserving similar treatment, such as
fixnums & flonums, but their current implementation just builds upon
bignums and inexact numbers so it’s probably not worth promoting them at
this point.

Apart from that all R6RS modules seem to provide functionality more or
less available elsewhere so they could happily stay under “R6RS Standard
Libraries”.

What do you think?

Besides, I would find it convenient if there were xrefs between the
“R6RS Standard Libraries” sub-sections and the rest of the manual.  For
instance, the SRFI-9/record/R6RS record nodes could link to each other,
ideally with one sentence indicating how they differ.

Well, this is all quite ambitious and I’m glad you’re volunteering!  :-)

Thanks,
Ludo’.





reply via email to

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