#12 poor documentation, rest/key parameters

closed-accepted
nobody
None
5
2002-03-25
2002-02-13
Jörg Höhle
No

I'm not too happy with the current state of the
documentation (what
documentation? ;) of the series package.

The implementation has more features than CLtL2
describes.
http://www-2.cs.cmu.edu/Groups/AI/html/cltl/clm/node347
.html

For example, the following are undocumented:
scan*
every-nth
scan-stream
collect-stream
collect-ignore
literal-series

scan-range specifies :start but example &
implementation are using :from

The often cited AI-memos 1082 and 1083
ftp://publications.ai.mit.edu/ai-publications/1000-1499
/AIM-1082.ps (7MB)
ftp://publications.ai.mit.edu/ai-publications/1000-1499
/AIM-1083.ps (5MB)
are poor quality scans (.tiff embedded in .ps) of old
papers by
Richard Waters. Precious, but possibly inaccurate, out
of date (1989).

They contain valuable information. For example, the
user report
mentions why I couldn't define my own transducer as a
function using
&key or &rest parameters. &optional is all that is
possible. Using a
macro is suggested instead. This failed attempt cost
me (and Raymond
Toy) time and e-mail trafic.

I should have read the memo first, but it was not
trivial to
find. Neither of
http://series.sourceforge.net
http://sourceforge.net/projects/series/
links to the MIT memos, or anything newer.

There are rumours about papers from 1991 (ACM) or
1992(?).

I volunteer to participate in updating an eletronic
documentation --
R.toy wrote: "I should ask Dr. Waters if he still has
the original sources for the
documents." -- with what shall we start?

Discussion

    • status: open --> open-accepted
     
  • Raymond Toy
    Raymond Toy
    2002-02-18

    Logged In: YES
    user_id=28849

    Dr. Waters has sent me his text documentation. I'll add it
    to the repository.

     
  • Raymond Toy
    Raymond Toy
    2002-03-25

    Logged In: YES
    user_id=28849

    I've uploaded Richard Waters original documentation for
    series. Look in s-doc.txt. I'm open to suggestions on
    formatting this in any desirable way.

     
  • Raymond Toy
    Raymond Toy
    2002-03-25

    • status: open-accepted --> closed-accepted
     
  • Raymond Toy
    Raymond Toy
    2002-03-26

    Logged In: YES
    user_id=28849

    I've uploaded Richard Waters original documentation for
    series. Look in s-doc.txt. I'm open to suggestions on
    formatting this in any desirable way.

     
  • Raymond Toy
    Raymond Toy
    2002-03-26

    Logged In: YES
    user_id=28849

    I've uploaded Richard Waters original documentation for
    series. Look in s-doc.txt. I'm open to suggestions on
    formatting this in any desirable way.

     
  • Raymond Toy
    Raymond Toy
    2002-03-26

    Logged In: YES
    user_id=28849

    I've uploaded Richard Waters original documentation for
    series. Look in s-doc.txt. I'm open to suggestions on
    formatting this in any desirable way.

     
  • Raymond Toy
    Raymond Toy
    2002-03-26

    Logged In: YES
    user_id=28849

    I've uploaded Richard Waters original documentation for
    series. Look in s-doc.txt. I'm open to suggestions on
    formatting this in any desirable way.