Re: r6rs library documentation

[ludo@gnu.org (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’.