bug#9973: Inconsistent documentation of repeated arguments

bug#9973: Inconsistent documentation of repeated arguments

[42toes]

Before making some changes to the docs, I just wanted to give a heads
up.  Recall the motivation behind Scheme

    "It was designed to have an exceptionally clear and simple semantics and
    few different ways to form expressions."

Why not tighten up notation in the docs as well as in the language?  My
hunch is that in the long run doing so will help those learning Guile.

Examples from the current Guile Reference:

(1) -- Scheme Procedure: string-append . args
(2) -- Scheme Procedure: append lst1 ... lstN
(3) -- Scheme Procedure: error msg args ...
(4) -- Scheme Procedure: error who message irritant1 ...

IMO, (4) is the right thing.  In software documentation '...' means
'repeated zero or more times', so 'arg ...' always includes 'args' as a
possibility, rendering 'args ...' redundant and potentially confusing.
Of course, in principle, we might intend 'args' to mean an aggregate
data structure such as list, but in that case 'arglist', 'list',
etc. would be clearer IMO.  Thus, I would fix (1-3) to be

(1) -- Scheme Procedure: string-append arg ...
(2) -- Scheme Procedure: append lst ... obj
(3) -- Scheme Procedure: error msg arg ...

(The 'obj' from (2) is particular to 'append'.)  FWIW, highly regarded
docs such as the RnRS reports, _The Scheme Programming Language_ by
Dybvig, CLtL2, etc. are consistent on such things.

Something like 'elem1 ... elemN' might be useful in a discussion of say
the Ith element and so on, but it not easy enough just to use 'elem ...'
in the definition header and then elaborate in the definition body w/
'elem1 ... elemN', etc.?

Thanks,
Bake

bug#9973: Inconsistent documentation of repeated arguments

[Andy Wingo]

On Sun 06 Nov 2011 20:10, 42toes@gmail.com writes:

> Before making some changes to the docs, I just wanted to give a heads
> up.  Recall the motivation behind Scheme
>
>     "It was designed to have an exceptionally clear and simple semantics and
>     few different ways to form expressions."
>
> Why not tighten up notation in the docs as well as in the language?  My
> hunch is that in the long run doing so will help those learning Guile.

Sounds great to me.  Care to submit a patch? :)

Andy
-- 
http://wingolog.org/

bug#9973: Inconsistent documentation of repeated arguments

[Andy Wingo]

On Sun 06 Nov 2011 20:10, 42toes@gmail.com writes:

> Why not tighten up notation in the docs as well as in the language?

> (4) -- Scheme Procedure: error who message irritant1 ...
>
> IMO, (4) is the right thing.

I just checked and I think we are OK (only simple-format has ". args",
and that only to be consistent with the following C prototype) -- thanks
to your patches, also.  Please submit a new patch if you find more
instances of foo . bar in prototypes.

Cheers :)

Andy
-- 
http://wingolog.org/