[MLton] mlton-lib documentation

[Stephen Weeks]

> Layout?  Only because virtually every other module gives a layout
> function.

Yes.  Although another possibility is to not expose the layout
functions.  I'm hoping to have a better pretty printer and debugger
built in to MLton some day.

> Certainly lib/mlton is much too big.  One way of dealing with the
> size of signatures would be to revisit the design of the lib/mlton
> library.

Yes, I would like (all of us) to do this.  This is one reason why I
stressed erring on the side of going small, because I do not want the
revisiting to slow things down to the point where we spend all our
time designing and delay releasing the libraries.  Nevertheless, we
can start work today on extracting a subset of the modules and subsets
of the signatures, and making them more consistent.  Let the
discussion, and possibly even coding, begin.

> A thought I had, would be to make greater use of include. 

For pedagogical and documentation purposes, I think it is very helpful
to think in terms of shared concepts across signatures.  But from a
coding perspective, I'm not sure it's such a win, partially due to the
weaknesses of the SML signature language and partially due to deep
dependencies it creates.  Your approach is nice than what I've done in
the past, but there is still tycon namespace pollution and the
difficulty in reading a signature due to information being in other
places.  For one example that I consider at best a wash, and at worst
a mess, have a look at my many uses of include in the definition of
various algebraic structures (RING, FIELD, ORDERED_FIELD, ...).  Sure,
the code captures the dependencies, but as a programmer I find it more
than annoying that I can't just see the all the specs in the signature
all in one place.  True, tools might alleviate this, but they're not
here yet.  I think it may be better to strive for consistency in
naming conventions and signatures without any automated support.  The
SML Basis Library shows that that kind of consistency isn't too hard.