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 <[EMAIL PROTECTED]> 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. _______________________________________________ Guile-devel mailing list Guile-devel@gnu.org http://lists.gnu.org/mailman/listinfo/guile-devel
