[squeak-dev] self error: 'comment only'

Eliot Miranda eliot.miranda at gmail.com
Tue Mar 24 14:54:43 UTC 2020

> On Mar 23, 2020, at 9:57 PM, K K Subbu <kksubbu.ml at gmail.com> wrote:
> On 23/03/20 12:20 PM, Nicolas Cellier wrote:
>> Hi all,
>> since Tim raised the subject, let's return to caesar https://en.wikipedia.org/wiki/Literate_programming
>> Otherwise, what Subbu said makes a lot of sense for me.
> Thank you for your supportive words.
> LP was a great idea for creating books or articles describing code in languages like Pascal or C, but it doesn't fit our needs. Times have changed. Squeak code graph is huge, live and 3D [1]. A static linear rendering will be woefully inadequate.

+1000.  One of the flaws of Literate Programming is that it presents a post-hoc rationalization of the code, not how it actually came to be.  Another is that it is designed to present a program rather than a library.  Documenting an evolving library, that includes executable examples and tests, is a different thing.

Something Alan Kay and I nearly started discussing on Quora is how to write unit tests as both specification and documentation of an API.  This could be literate programming done right.  It doesn’t fit every use case; only certain kinds of API (say sequence manipulation APIs such as includesSubstring:, copyReplace:from:to:with:startingAt:, and arithmetic).  But if the tests are written to be read as a guide one may be able to combine language/api specification with verification and documentation in the same single piece of executable code.

> [1] Craig Latta's Nexus demo https://youtu.be/xCwidGFkn4Q
> I expect a modern guide to be like the guided tours in science expos or film studios - live, direct, concrete and interactive. It should be built with the same materials and operated by the same tools (staff) as the rest of the system.

+1000. Somewhat related, see Tudor Girba’s examples extension of unit tests.

> As Timothy and Tim have pointed out, we already have most of the low level support (doclets, hypertext, help topics) in place. We need a high level perspective and design to get them to work together to create a seamless experience.

And you, Subbu, have they vision.  I especially liked your characterization of principles, etc, three or do messaged earlier in this thread.  Please push this.

> Regards .. Subbu

More information about the Squeak-dev mailing list