[ANSI-Smalltalk] Writing the standard in Smalltalk [long]

[Martin McClure]

Hi all,

When I started the "Editing and executable specification" thread on Nov. 
15, I had only a vague idea of what I wanted. After reading the comments 
on that thread, and thinking about it some more, I wrote up an initial 
framework this weekend.

Although it's not what I initially had in mind, and I certainly make no 
claims that this is anything approaching the best possible system, it 
works pretty well so far, and it can grow incrementally from here. I'm 
hoping that you'll find that it has enough advantages to start using 
right away, so we have one system from the beginning (since there is 
almost nothing specific in the Wiki yet).

My initial goals:

* write a representative chunk of the standard in Smalltalk
* only write each piece of text once, though it might appear in more 
than one place
* write a framework that would output the standard so that it looked as 
much like the '98 standard as possible
* let the framework deal with the details of the structure, so my 
Smalltalk code could focus on the content

I chose section 5.10 of the standard, the file stream protocols, as my 
test data. For now, you can see the output at 
http://pigeonlakeglass.org/FileStream. This looks a quite a bit like the 
standard. The chief differences:
* Body text is not yet formatted. That's the next thing to get implemented.
* At least three structural errors in the '98 standard are corrected:
   1. The extraneous heading "Rational" (intended to be hidden text) is 
removed.
   2. Section 5.10.1.1's heading was "Message:" when it should have been 
"Message Refinement:".
   3. Section 5.10.1.1's Errors section said "None" when it should have 
said "none".

The structural errors no longer occur because all of this text is now 
automatically generated. The fact that there were this many errors in 
one short section indicates how hard it is to do this consistently in 
plain text.

As an example of what the code looks like, here's a method in the 
Smalltalk representation of the standard:

---

AnsireadFileStream>>next: amount
	^ self messageDescription definition: 'The result collection will 
conform to the same protocols as the object that would result if the 
message #contents was sent to the receiver.'

---

The presence of this method causes the framework to generate the 
following section (with formatting not shown in a plaintext email):

-----

5.10.2.1 Message Refinement:     next: amount

   Synopsis
     Returns a collection of the next amount objects in the stream.

   Definition: <gettableStream>
     A number of objects equal to amount are removed from the receiver's
     future sequence values and appended, in order, to the end of the
     receiver's past sequence values. A collection whose elements consist
     of those objects, in the same order, is returned. If amount is equal
     to 0 an empty collection is returned. The result is undefined if
     amount is larger than the number of objects in the receiver's future
     sequence values.

   Refinement: <readFileStream>
     The result collection will conform to the same protocols as the
     object that would result if the message #contents was sent to the
     receiver.

   Parameters
     amount <integer> uncaptured

   Return Value
     <sequencedReadableCollection> new

   Errors
     amount < 0

-----

"Wait a minute!" you say? "Where did all the rest of that text come 
from?" It's either structural, or automatically inherited from 
AnsigettableStream>>next:, which looks like this:

---

next: amount
	^ self messageDescription
		 synopsis: 'Returns a collection of the next amount objects in the 
stream.';
		 definition: 'A number of objects equal to amount are removed from the 
receiver''s future sequence values and appended, in order, to the end of 
the receiver''s past sequence values. A collection whose elements 
consist of those objects, in the same order, is returned. If amount is 
equal to 0 an empty collection is returned.
The result is undefined if amount is larger than the number of objects 
in the receiver''s future sequence values. ';
		 returnValues: #('<sequencedReadableCollection>	new' );
		 parameters: #('amount	<integer>	uncaptured' );
		 errors: #('amount < 0' )

---

Hopefully this gives you the idea of what this framework does. You can 
(and I hope many of you will) get the code from the GemSource public 
Monticello repository, http://seaside.gemstone.com/ss. The project name 
is "Smalltalk ANSI Standard". It contains two packages, ANSI-Framework 
and ANSI-Protocols.

The framework uses Seaside to render the standard to HTML, and is 
written in Squeak. The initial version is based on the Seaside 2.8 
one-click experience, available at 
http://www.seaside.st/resources/distributions/Seaside-2.8-final.app.zip. 
I chose Seaside because I needed something written in Smalltalk that 
could render structured styled text, and Seaside is either supported or 
about to be supported in most Smalltalk dialects. I gave up on writing 
the framework in pure ANSI Smalltalk when I realized that I needed to 
use reflection fairly heavily.

Since I couldn't write this in strictly portable code, I had to choose 
an initial Smalltalk dialect. I wanted to use a dialect that everyone 
had access to. This largely ruled out commercial Smalltalks and 
single-platform Smalltalks. Of the remaining choices, Squeak was the one 
I was most familiar with, and has excellent Seaside support. The 
ANSI-Protocols package should be fully portable across dialects, and 
I'll certainly cooperate with anyone who wants to port ANSI-framework to 
other dialects.

How do I envision this being used? If we write the standard (or at least 
the protocols, which is the main thing we'll be changing anyway) in 
Smalltalk, we need a way to share Smalltalk code, and see who has 
changed what. There are a number of systems for managing Smalltalk code 
that would meet these requirements, but most of them are proprietary.

I propose that we use Monticello. It's distributed, it's open-source, it 
does diffs between versions, and keeps track of who checked in each 
version. It is also the only such system I'm aware of that is supported 
by multiple Smalltalk dialects. Unfortunately, Monticello is not yet 
supported in all dialects. However, Monticello's underlying base is 
chunk format files, the basis for the ANSI Smalltalk Interchange Format, 
so it shouldn't be too hard to add Monticello capabilities to other 
dialects.

I'll give write access to the Smalltalk ANSI Standard on GemSource to 
any of this group who is going to be generating material for the 
standard. I'll also set up a way to view the most recent version of the 
standard in a web browser. I may even be able to make it possible to 
view older versions as well.

Well, that's more than enough to cram into one email. I hope you all had 
a good weekend. I've been having a lot of fun writing this framework.

Regards,

-Martin