[E-Lang] Announcing Updoc

[Mark S. Miller]

At 3/29/01, Tyler Close wrote:
>Dan wrote:
>> but one thing I've really become a big fan of
>> lately is automated unit tests, where those tests are
>> meant, in a very real
>> sense, to be an effective "executable spec" for the code
>> (but not in the usual way that term is applied).
>
>When you say it like this, it reminds me that this is what updoc is
>for. MarkM, I couldn't find anything on the erights.org site about
>updoc. Are there any examples of how to use it?

There are now: http://www.erights.org/elang/tools/updoc.html .  This page is 
both an explanation of Updoc and an example Updoc script.


My wife Terry ( http://www.cocoon.com ) and I recently read about pair 
programming and (a bit about) Extreme Programming, so we decided to pair 
program the revival of CapTP (the old "proxy comm system").  Part of this 
methodology is supposed to be the constant creation of test cases while 
programming, so we found we needed an answer to Dan's and Tyler's question 
above.

We pulled the Updoc idea from the shelf, completed it, and have started 
using it.  Besides using on the revival of CapTP itself, the erights.org web 
site was already a tremendous potential regression test for E, as all the 
embedded code examples were already written in the format expected by Updoc, 
in anticipation of having an Updoc to run them through.

Well, with three years of history without such a tool, the web site doesn't 
yet pass.  The result of bringing it into closer conformance has not only 
caused many bugs in the documentation to be fixed, it has caused many 
annoyances and one serious bug in E to be identified and fixed.

The serious bug?  As a result of the new E-to-Java overload resolution 
mechanisms, "2.3 < 3.4" was throwing an exception complaining about an 
ambiguous overload.  While this is terribly broken, it wasn't caught by our 
usage of E, since we don't actually use floating point for anything.

It will be a while before the entire web site passes.  But once it does, it 
should be easy to maintain it's accuracy, while also using it to check E's 
correctness.  In the meantime, the list of pages that contain test cases and 
currently pass are:

http://www.erights.org/download/0-8-9/unix-bin.html:....
http://www.erights.org/download/0-8-9-1/unix-bin.html:....
http://www.erights.org/download/stl-0-8-9-k/unix-bin.html:....
http://www.erights.org/download/stl-0-8-9-s/unix-bin.html:..
http://www.erights.org/download/stl-0-8-9-p/unix-bin.html:..
http://www.erights.org/download/stl-0-8-9-t/unix-bin.html:..
http://www.erights.org/e/foo.txt:.............
http://www.erights.org/elang/blocks/defFunc.html:..........
http://www.erights.org/elang/blocks/defObject.html:............................
http://www.erights.org/elang/blocks/escapeExpr.html:....
http://www.erights.org/elang/blocks/forExpr.html:..
http://www.erights.org/elang/blocks/miranda.html:....
http://www.erights.org/elang/blocks/whileExpr.html:...
http://www.erights.org/elang/scalars/integer-ref.html:.............................
http://www.erights.org/elang/scalars/float64-ref.html:.................................
http://www.erights.org/elang/scalars/boolean-ref.html:..
http://www.erights.org/elang/scalars/char-ref.html:...
http://www.erights.org/elang/tools/updoc.html:.............
http://www.erights.org/elang/intro/finding-text.html:..............
http://www.erights.org/to-be-sorted/cvsfaq.html:.

Each of the dots after the URL indicate a passing test case.

Updoc has had a long history, starting at Agorics as part of the 
Tclio/Webmart project, maybe 5 or 6 years ago.  I remember Bill Frantz and I 
working on the idea back then, and again at Electric Communities.  No doubt 
there were other contributions at both companies I'm failing to acknowledge. 
At EC, Brian Marick contributed insights (briefly explained on the Updoc 
page) about how Updoc may address some of the traditional problems with 
regression testing. The current Updoc, to be part of the 0.8.10 release, is 
by Terry Stanley and Mark Miller.

And now, back to CapTP...

        Cheers,
        --MarkM