r6rs library documentation

r6rs library documentation

[Julian Graham]

Hi Guilers,

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.  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"), 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.

Thoughts?


Regards,
Julian

Re: r6rs library documentation

[Ludovic Courtès]

Hi Julian!

Julian Graham <joolean@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’.

Re: r6rs library documentation

[Julian Graham]

Hi Ludovic,


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

I've just pushed a draft of this to Andy's `wip-library-and-import'
branch.  (Hope that's okay!)


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

Works for me.  I'll get started on these soon.


Regards,
Julian

Re: r6rs library documentation

[Julian Graham]

Hi all,


> Works for me.  I'll get started on these soon.

Status update: I'm still working on the standard libraries
documentation -- I'd say I'm about 70% done.  I should have a draft to
email out in the next week or so.


Regards,
Julian

Re: r6rs library documentation

[Julian Graham]

Hi Guilers,

As promised, I've got an initial draft of the standard libraries
documentation done.  Although I tried to avoid reproducing the content
of `r6rs-lib', it's still a bit more verbose, I think, than what we
discussed earlier in this thread (the Texinfo file clocks in at ~83k),
so I could certainly use some editorial feedback -- and tips on how
best to integrate it into the rest of the manual.

In lieu of spamming the list with an attachment, I've uploaded a copy
of the file to my web site [0].


Regards,
Julian

[0] - http://undecidable.net/joolean/r6rs-libraries.texi

Re: r6rs library documentation

[Andy Wingo]

Hi Julian,

On Sat 12 Jun 2010 21:32, Julian Graham <joolean@gmail.com> writes:

> As promised, I've got an initial draft of the standard libraries
> documentation done.

Very cool!

>  Although I tried to avoid reproducing the content
> of `r6rs-lib', it's still a bit more verbose, I think, than what we
> discussed earlier in this thread (the Texinfo file clocks in at ~83k),
> so I could certainly use some editorial feedback -- and tips on how
> best to integrate it into the rest of the manual.
>
> In lieu of spamming the list with an attachment, I've uploaded a copy
> of the file to my web site [0].

I think that Neil would probably have the most useful feedback, as I
think he has the most global view of the manual. I am inclined to think
that the level of detail is appropriate, though I imagine that Neil and
Brian are cringing at the weight of the extra pages on the press ;-) It
is an ongoing tension and I'm not sure how to resolve it.

One nit: idioms like "See (@pxref{Environments}) for documentation." are
probably better as "@xref{Environments}, for documentation." Or ", for
more information."

Cheers,

Andy
-- 
http://wingolog.org/

Re: r6rs library documentation

[Julian Graham]

Hey Andy,


> I think that Neil would probably have the most useful feedback, as I
> think he has the most global view of the manual. I am inclined to think
> that the level of detail is appropriate, though I imagine that Neil and
> Brian are cringing at the weight of the extra pages on the press ;-) It
> is an ongoing tension and I'm not sure how to resolve it.

Sure.  I haven't heard any opposition from Neil or Brian, though, so
I'm inclined to commit this sometime this week, possibly by adapting
it into the `R6RS Standard Libraries' node you created.  That sound
okay?


> One nit: idioms like "See (@pxref{Environments}) for documentation." are
> probably better as "@xref{Environments}, for documentation." Or ", for
> more information."

Will do.


Regards,
Julian

Re: r6rs library documentation

[Andy Wingo]

Heya,

On Sun 20 Jun 2010 23:23, Julian Graham <joolean@gmail.com> writes:

>> I think that Neil would probably have the most useful feedback, as I
>> think he has the most global view of the manual. I am inclined to think
>> that the level of detail is appropriate, though I imagine that Neil and
>> Brian are cringing at the weight of the extra pages on the press ;-) It
>> is an ongoing tension and I'm not sure how to resolve it.
>
> Sure.  I haven't heard any opposition from Neil or Brian, though, so
> I'm inclined to commit this sometime this week, possibly by adapting
> it into the `R6RS Standard Libraries' node you created.  That sound
> okay?

Sounds great to me, though Brian & Neil can always come in to correct me
:)

Andy
-- 
http://wingolog.org/

Re: r6rs library documentation

[Julian Graham]

> Sounds great to me, though Brian & Neil can always come in to correct me
> :)

Done!  See commit ea28e981342fd1d381e489e57cddde97eb390442.  In
addition to the main .texi payload, I adjusted the formatting on some
of your initial paragraphs and removed the descriptions of the base
and composite libraries -- let me know if those changes are
problematic.


Regards,
Julian

Re: r6rs library documentation

[Ludovic Courtès]

Hi Julian,

Julian Graham <joolean@gmail.com> writes:

>> Sounds great to me, though Brian & Neil can always come in to correct me
>> :)
>
> Done!  See commit ea28e981342fd1d381e489e57cddde97eb390442.  In
> addition to the main .texi payload, I adjusted the formatting on some
> of your initial paragraphs and removed the descriptions of the base
> and composite libraries -- let me know if those changes are
> problematic.

Great work!  I find it nice and convenient to have all this in the
manual.

Random remarks:

  +@deffn {Scheme Procedure} fold f lst1 lst2 ...
  +@deffnx {Scheme Procedure} for-each f lst1 lst2 ...
  +@xref{SRFI-1 Fold and Map}, for documentation.
  +@end deffn

There’s no ‘fold’ in R6RS-lib; it’s called ‘fold-left’.

  +@deffnx {Scheme Procedure} remq obj list
  +@code{remove}, @code{remv}, and @code{remq} are identical to the
  +@code{delete}, @code{delv}, and @code{delq} procedures provided by
  +Guile's core library; (@pxref{List Modification}) for their

Should be “Guile’s core library (@pxref{List Modification}).”

  +@deffn {Scheme Procedure} div x1 x2
  +@deffnx {Scheme Procedure} mod x1 x2
  +@deffnx {Scheme Procedure} div-and-mod x1 x2
  +These procedures implement number-theoretic division.

How about this instead:

  @code{div} is an alias for Guile’s @code{quotient} and @code{mod} is
  an alias for @code{modulo} (@pxref{Integer Operations}).


  +The manual sections below describe Guile's implementation of R6RS
  +records, which provide support for user-defined data types. The R6RS
  +records API provides a superset of the features provided by Guile's
  +``native'' records, as well as those of the SRFI-9 records API;
  +(@pxref{Records}) and (@pxref{SRFI-9}) for a description of those
  +interfaces.

This use of @pxref is incorrect and leads to broken rendering with all
back-ends (info "(texinfo) pxref").  The same problem appears in other
places.  Could you look into it?

  +@node rnrs conditions
  +@subsubsection rnrs conditions

Perhaps add an xref to SRFI-35, in pure TIMTOWTDI spirit.  ;-)

  +Compound conditions do not ``nest'' --- constructing a new compound

The ‘---’ should not be surrounded by spaces.  Though according to
https://secure.wikimedia.org/wikipedia/en/wiki/Dash#Em_dash you could
argue that you’re following the /The New York Times Manual of Style and
Usage/.  ;-)

  +@node rnrs arithmetic bitwise
  +@subsubsection rnrs arithmetic bitwise

Add link to SRFI-60?

Thanks!

Ludo’.

Re: r6rs library documentation

[Julian Graham]

Hi Ludovic!


> There’s no ‘fold’ in R6RS-lib; it’s called ‘fold-left’.

Fixed -- see commit 5b379729bb5f5d06ceb02c4e96ccc62cf61f9c62.


> Should be “Guile’s core library (@pxref{List Modification}).”

Fixed.


> How about this instead:
>
>  @code{div} is an alias for Guile’s @code{quotient} and @code{mod} is
>  an alias for @code{modulo} (@pxref{Integer Operations}).

Well, I don't know.  Those exports currently /are/ aliases for those
procedures, but that's a bug that I introduced because I had some
hesitation over how to implement the real procedures efficiently.  I
suppose I should revisit that problem...  :)


> This use of @pxref is incorrect and leads to broken rendering with all
> back-ends (info "(texinfo) pxref").  The same problem appears in other
> places.  Could you look into it?

Fixed as many of these as I could find.  Let me know if you notice other ones.


> Perhaps add an xref to SRFI-35, in pure TIMTOWTDI spirit.  ;-)

Done.  Off-topic: While poking around, I noticed that SRFI-35 is
implemented purely in terms of Guile structs; would it make sense
later to re-implement using a subset of the features of `(rnrs
conditions)'?  (Ditto for SRFI-9 and `(rnrs records)'.)


> The ‘---’ should not be surrounded by spaces.  Though according to
> https://secure.wikimedia.org/wikipedia/en/wiki/Dash#Em_dash you could
> argue that you’re following the /The New York Times Manual of Style and
> Usage/.  ;-)

I make no such claim!  Fixed.  :)


> Add link to SRFI-60?

Done.


Regards,
Julian

Re: r6rs library documentation

[Ludovic Courtès]

Hi Julian!

Julian Graham <joolean@gmail.com> writes:

>> How about this instead:
>>
>>  @code{div} is an alias for Guile’s @code{quotient} and @code{mod} is
>>  an alias for @code{modulo} (@pxref{Integer Operations}).
>
> Well, I don't know.  Those exports currently /are/ aliases for those
> procedures, but that's a bug that I introduced because I had some
> hesitation over how to implement the real procedures efficiently.  I
> suppose I should revisit that problem...  :)

Aah, OK.

>> This use of @pxref is incorrect and leads to broken rendering with all
>> back-ends (info "(texinfo) pxref").  The same problem appears in other
>> places.  Could you look into it?
>
> Fixed as many of these as I could find.  Let me know if you notice other ones.

Cool, thanks.

>> Perhaps add an xref to SRFI-35, in pure TIMTOWTDI spirit.  ;-)
>
> Done.  Off-topic: While poking around, I noticed that SRFI-35 is
> implemented purely in terms of Guile structs; would it make sense
> later to re-implement using a subset of the features of `(rnrs
> conditions)'?  (Ditto for SRFI-9 and `(rnrs records)'.)

Well, I’m sentimentally attached to the SRFI modules and I remain
R6-skeptical.  ;-)

So, I’d rather have the R6RS modules implemented in terms of the SRFI
modules rather than the other way round.

Now, I agree that SRFI-35 could be implemented in terms of SRFI-9,
especially since SRFI-9 accessors are inlined (initially SRFI-35 was
implemented for Guile 1.8, where it made a difference to use raw
structs.)

I don’t consider it important though since the SRFIs have no connection
to one another anyway.

>> The ‘---’ should not be surrounded by spaces.  Though according to
>> https://secure.wikimedia.org/wikipedia/en/wiki/Dash#Em_dash you could
>> argue that you’re following the /The New York Times Manual of Style and
>> Usage/.  ;-)
>
> I make no such claim!  Fixed.  :)

Cool!  :-)

Thanks!

Ludo’.