Re: Socket API improvement, patch #6

[Ludovic Courtès]

Hi Kevin,

I mostly agree with your remarks about the piece of documentation I
included---these were mostly errors unrelated to the point I was trying
to make.  :-)

Kevin Ryde <address@hidden> writes:

> A manual is not a specification (fortunately), so there's no need to
> be overly formal.

Agreed.  But you missed my point: the wording has to be consistent
across the manual (or, even better, across GNU manuals) and it has to be
non-ambiguous.

For instance, a sentence like "Return _a_ Scheme object." doesn't give a
lot of information.  What I like in GNU reference manuals is that
function descriptions usually start with a single sentence (or a couple
of sentences) that describes the return value and each argument.
Example:

   Apply PROC to each element of the list ARG1 (if only two arguments
   are given), or to the corresponding elements of the argument lists
   (if more than two arguments are given).  The result(s) of the
   procedure applications are saved and returned in a list.

Or (glibc):

   The `open' function creates and returns a new file descriptor for
   the file named by FILENAME. 

> A manual, even a reference manual, is essentially a teaching tool

I disagree: a tutorial is teaching material, a reference manual is,
well, a reference documentation.  Of course, a manual may very well
include a tutorial alongside the reference documentation: that's what
Guile's manual does in the nodes other than `API Reference' and `Guile
Modules'.

Thanks,
Ludovic.