Hi Julian! Julian Graham <jool...@gmail.com> 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’.