[MLton] SML documentation tool(s)

[Jesper Louis Andersen]

Stephen Weeks wrote:
> I think the SML basis library is a perfect example of what's wrong
> with having a library owned by a small group of people attempting to
> stabilize too soon in the absence of lots of practical experience and
> community input.  The basis has taken ~10 years to develop; it has
> been ridiculously difficult to get even simple fixes made, and there
> are lots of things missing because the development process is too
> focused on perfection. 

I agree with this statement. The problem of Standard ML in general is 
not that the language is hard to learn, not that it is not used widely 
enough, not even that its type system is too restrictive and the 
language is too simple. The problem currently is solely the lack of 
standard library facilities.

The world changes too fast and it takes a lot of flexibility to keep up 
with standards A, B and C coming from left and right. 10 years is simply 
to inflexible to even have a chance in the world today. What were the 
things you had to support 10 years ago? Certainly not the things in need 
today.

While I think the SML Basis library is one of the most worked through 
standard libraries out there it lacks breadth. I'll try to comment 
further on this later in this mail.

> I would like to avoid these problems with our
> library development by adopting the following principles:
> 
>  * welcome community input

This is of course important. You may have a person who wrote an XML 
library. Even if this is not the perfect library it should be included 
if it at least have some quality. Refinement can then come later.

>  * avoid ownership of code

Good idea. But note that bit-rot may happen to code, wether it is owned 
or not. You want many eyes to look and read code in the standard 
library. You want patches. Lots of patches.

>  * focus on practical needs of developers

Oh yes. Almost all of my projects in SML starts with me including my 
Red-black map from Chris Okasaki, my pairing heap, my (imperative) graph 
library, my (naive, list-based) Set implementation etc. 2 things to 
note: My implementations are not effective, since they have never been 
the central aspects of projects done in SML. I waste time importing and 
tailoring these implementations all the time.

Maybe a survey will help. I am for from convinced, however.

>  * breadth of libraries is more important than depth

This is important. Take a look at the Haskell Basis Library for GHC 6.4:

http://www.haskell.org/ghc/docs/latest/html/libraries/index.html

Note the amount of general utility libraries: Debugging, 
data-structures, parsing (monadic parser-combinators are a treat to work 
with when you have to cook up a little fast parser), HTML output etc. 
Things do change all the time. GHC6.2 had Data.FiniteMap which is gone 
in favor for Data.Map in GHC6.4. But now it is consistent with rest of 
the hierachial libraries. Adapting code takes time yes, but not 
extremely much so.

> I am not so interested in the following:
> 
>  * portability across SML implementations (too hard)

I think you are right here. The more low-level a library becomes, the 
harder it is to hammer into shape. Apart from that, there is the 
performance considerations across compilers. I know for one how 
differently compilers handle your ''performance optimizations'' when 
changing compiler. That said, increasing sharing where it is possible is 
not a bad idea. The SML community might be too small to even sustain a 
library extension and splitting across implementations just seems to 
make it even more infeasible to pull through.

On the other hand, despotism is good for action. So this might actually 
be a good idea.

>  * stable interfaces (not necessary, use a package system)

You are right, but I think this is the hardest point to convince people 
about.

> I agree with Vesa's point that the way development works in practice
> is that the library is built first and then refined, with
> documentation growing along the way.  

Also, systems are better when built prototypical, than built by careful 
planning. This goes hand-in-hand with the point.