Re: [Chicken-users] srfi-19 'date?'

[John J Foerch]

Matt Gushee <address@hidden> writes:
> Hmm ...
>
> On Sun, Oct 13, 2013 at 11:11 AM, John J Foerch <address@hidden> wrote:
>
>> I noticed that srfi-19-date (version 3.3.4) does not export 'date?'.  I
>> think that perhaps it should.
>
> On my system:
>
> csi> (use srfi-19)
> ; loading /usr/lib/chicken/6/srfi-19.import.so ...
> ; loading /usr/lib/chicken/6/srfi-19-timezone.import.so ...
> ; loading /usr/lib/chicken/6/miscmacros.import.so ...
> ... and so on
>
> csi> date?
> #<procedure>
>
> Note that I loaded 'srfi-19', not 'srfi-19-date'. So there is not an
> SRFI-conformance issue. But if your point is about having a logically
> consistent API,  ... yes, I see that srfi-19-time exports time?, and
> srfi-19-period exports time-period?, so you seem to have a valid
> point.
>
>> Also, 'date?' is not documented in the
>> egg docs (http://wiki.call-cc.org/eggref/4/srfi-19).
>
> If you read the intro to the egg doc, it states that "This document
> only describes the extensions [to the spec]."
>
> I'm not claiming this is not a problem. The way Scheme is modularized
> leads to a situation where documentation for closely-related functions
> can be scattered all over the four corners of the internet. I have
> long believed that this is a serious obstacle for anyone trying to
> master the language, and I haven't seen anyone deny that ... but I
> don't think anyone knows how to fix the problem. I have envisioned a
> sort of 'smart documentation aggregator' that would enable you to view
> in one place all the documents that logically go together. But that
> would require either (a) an insanely good search engine; (b) a
> Scheme-community-wide agreement to add certain kinds of metadata to
> all the docs everywhere (which would not be technically difficult, but
> would require an awful lot of work, and ... sounds like a herding-cats
> problem to me). Or you could screen-scrape everything, but then the
> system would break whenever anyone decided to change their
> documentation format.
>
> --
> Matt Gushee

Hello Matt,

Thank you, I confess I had glossed over that description paragraph, or
may have read it a long time ago and forgotten it.  I generally bring an
assumption to the chicken docs that they can be read in 'reference'
fashion, jumping here and there to find the information I'm after, not
having to worry about reading everything in sequence.  Then again, maybe
the document's title is misleading, since one assumes with a title of
"srfi-19" that the document would be about all of srfi-19, and if it's
not, a more descriptive title like "Chicken Extensions to SRFI-19" would
be more helpful.  However...

I think it would be a good idea for this document, and others like it,
to include entries for every one of the egg's exported symbols.  Even if
many of them were simply stubs like "See SRFI-19", this would help
readers avoid confusion.

As for 'date?', I was simply doing this:

  (use srfi-19-date)

The egg doc suggests this in the section "Core Procedures".  ("The core
procedures can be separately accessed: ... (require-extension
srfi-19-date)") This is why I think that srfi-19-date should export
'date?' - because it would be consistent with what is suggested by the
documentation.

Thank you!

-- 
John Foerch