Active Essays on the Web

Active Essays is a concept of an essay mixed with computer program coined by Alan Kay. The goal is to explain mathematical or scientific ideas to kids with some interesting program like a computer simulation.

It is similar as a math book which includes a couple of paragraphs and formulas in a page, so that a reader would follow the author's idea by not only reading a text but also "do it" formulas. In case of Active Essays, computer programs are embedded in a page instead of formulas. The largest advantage of Active Essays to math book is that a program is often more dynamic than a formula. It is really fun to see a small lines of code generating a little surprise on screen. The second advantage would be that you don't have to calculate numbers by yourself, a computer must to do better job than you to fiddle variables.

Because Active Essay is not a definitive genre in computer media, so I'm not sure how many active essays have ever been written so far. But HyperCard might be the first media which affords contents mixed with text and program. And you would find many projects with this style in eToys on the web.

What I want to make in next a couple of months is an authoring tool for Active Essays taking advantage of Internet technology. And final goal is to describe entire system as a Active Essay itself.

Internet had a huge impact on our literacy. A lot of amateurs write texts, take photos, and publish to the web them every day. Even it is common that there are families whose every members have each blog. Besides social aspect, a new medium makes a new style of writing. Because actual appearance of writing is depended on reader's web browser or RSS reader, you don't have a full control of final looking of your text. And it is encouraged to take care about logical stricture instead of physical looking. I'm sure the those phenomena affects way of writing.

However, there is a something what have not been changed yet. Internet contents still tend to mimic traditional media. Even though it is highly depend on computer technology, it lacks the most interesting aspect, programming language as a communication media.

Programming language is the primary tool to talk between man and machine, and often even better way to exchange ideas among humans. If there were enough support tools, it would be natural that we write a blog post in programming language, chat with source code, and even write a novel running as a program. Especially when the topic is science or mathematics, programming language would be the most accurate way to tell an idea. It is irony that you can't play a LOGO program when you read LOGO's article on Wikipedia.

However, e.g. while the article on Logo has some good information and examples, none on them can be run, dynamically changed and tried, etc. To me this is outrageous given that the browser was done some years after Hypercard, longer after the Apple ][, and long long after the prior art of the 60s and 70s. -- Alan Kay

What kind of tool is useful to support the idea? Abundant introductory material for science written in eToys would be a good start to examine. And history of Literate Programming shows another interesting aspect of the topic. We would make a progress from these instances in terms of functionality and style.

As functionality, Don Knuth's original idea could evolve more in late binding language like JavaScript than Pascal or C, because WEB's some clumsy convention like macro is needed only for language's inflexibility. And as style, we can avoid limitation coming from physical paper. We don't have to care about pages nor font size, but let's concentrate its logical structure. Hyper link helps to support navigating in random access instead of page numbers.

This is an outline of current thought. I don't think special fancy feature is needed for first prototype (actually, I have made a lot of prototypes already, and this is not exactly the first). The simplest solution might be best. And when we need more, I would make everything from scratch in "Ian's System" later.

• Active Essays: http://www.squeakland.org/whatis/a_essays.html
• About LogoWiki: http://www.redhat.com/archives/olpc-software/2006-April/msg00035.html

My next three months goals.

The main point of my previous three months goals was making a text editor on Ian's stuff http://tinlizzie.org/svn/trunk/bottle/. I admit that it has not been finished in terms of building a really useful text widget. Making a text editor looks simple requirement. But even just a substitute widget for Squeak's ParagraphEditor from scratch is quite complicated because it has to deal with a large number of issues like text layout, scroll, font rendering, etc. To make the goal clearer and smaller, I propose one concrete prototype and one real implementation.

An authoring tool for Active Essays on web browser.

It will be direct successor of TileScript http://tinlizzie.org/jstile/ and YUI-based tool for Active Essays http://tinlizzie.org/ometa-js/alan/essays.html. Those were difficult to use even sometimes for myself because they were too heavy and UI was complicated. The focus of this project is brushing up the UI. I will not add a new function, but it will have enough features to express some of examples in Appendix A of STEP paper and Ted's puzzle.

• Basic text emphasis (header, list, in-line image)
• Wiki based collaboration mechanism.
• "include" mechanism
• OMeta/JS can be used through "include"
• Supported platform: IE6 and Firefox3

A basic widget component for Active Essays on Ian's stuff.

This is a real stuff based on above prototype. Every necessary widget which needed for text editing including text emphasis and in-line image will be implemented. Wiki-based collaboration part won't be included.

This text widget can be used a part of Ted's DB Jr.

Next Goals of My Hobby

I need my next three month research goals by next Tuesday's meeting. But it is too hard for me to write a documentation before writing source code. Because I'm a 100% pure programmer, I program therefore I am.

But I have to write something anyway. It might be better to write something fun idea before serious documentation. So my brain will switch to "writing mode" smoothly. So I made up my next three month hobby goals. This is it.

Simple Electronics Device

When I was first interested in electronics was around ten years old. I have tried a couple of electronics projects. However, I had never understood how to decide parameters of component. Sure, resistors and ohm's law are pretty easy, but capacitor, transistor, coil, such components are quite difficult. I hate numbers and I am too lazy to handle complicated equation.

Those knowledge is completely unnecessary as a programmer. But same time, I couldn't tolerate the fact that I was ignorance about electronics. So I got started to learn it again a couple of month ago. First goal is to make a simple device to communicate between a computer and real world. This is one of early attempts.

FPGA Block RAM and Demonstration

I happen to get a source code of tiny CPU in Verilog. This is quite beautiful so I bought a Spartan-3A FPGA board for $200 to test this code. FPGA is very interesting gadget. But it requires different ways of thinking against programmer's view. So I still do nothing for it. One of the problems is I don't understand how to use Block RAM. And I don't have nice idea to demonstrate it. Just running a CPU is too boring. I wish I can run the verilog CPU with fun demo perfectly.

A Compiler in Javascript

It still doesn't go beyond a joke. I have played a tiny source code in x86 assembler with GNU as. It was when I was teen that I played Z80 CPU, and I was surprised the some essence of Z80 machine code is still alive in modern CPUs (I had imagined as if modern CPU might have hundreds and thousands of generic registers, but still we call EAX register as an accumulator!). I can't say as it is good though, it is very appealing to me.

So I think that it would be fun if I will make a compiler, assembler and linker in Javascript on a web browser. It might support only one CPU and one platform like x86 linux, still it should be a good exercises.

I could write those ideas more. But this is it today.

Documentation and Programming Language

A number of major programming languages have its own documentation system. Those variations themselves interest me very much. I picked up some of them and examined.

There are some interesting points to characterize those systems.

• Text base VS Memory base: A text based documentation system is implemented as just a text formatter. But some are integrated in the language itself, so you can access the documentation in run time. Emacs Lisp is a significant example of Memory based documentation. I think Memory based documentation is more useful though, sometimes Text base is handy because it doesn't need to load a program only for the documentation.
• Description part and Reference part: A documentation might include a description part, which describes overall goals and functions of a part like a class or a module. In contrast with description part, a reference part describes detail of a particular entity like a function or a variable. A reference part is connected with its source code of definition.

Perl

Perl's documentation is described by POD (Plain Old Documentation). POD is a text based system. It has only description part.

POD is a very simple markup language and it has only enough mechanism to represent traditional UNIX manual style which includes certain sections like NAME, SYNOPSIS, DESCRIPTION, etc.

A POD document is embedded in a Perl program as a comment and the Perl's parser just ignores it. A POD parser just ignores program. POD doesn't use any information from the program source code.

http://search.cpan.org/perldoc?perlpod

Java

JavaDoc is the standard documentation tool for Java. It is a text based and it has both description part and reference part.

JavaDoc parser uses not only comments but also program codes to extract type information and class hierarchy. Even it works if you don't write a comment. Very structured HTML documentation is generated by the tool.

http://java.sun.com/j2se/javadoc/

Emacs Lisp

Emacs Lisp has memory based documentation. And it has only reference part.

Emacs Lisp's documentation is highly integrated with Emacs editor. You can access help document for every functions and variables without external tool.

A documentation is described as a first comment in a function or a variable definition. This comment is parsed by Emacs lisp parser, and shown by help command e.g. M-x describe-function. Help system of Emacs Lisp doesn't have description part, but info manual of Emacs lisp complements overall information.

http://www.gnu.org/software/emacs/emacs-lisp-intro/html_node/defun.html

Python

Python has memory based and text based documentation. And it has description part and reference part.

Basically Python's documentation is same as Lisp's. A documentation is described as a first comment of an entity (module, class, variable, etc...), and parsed by Python parser. You can access the documentation through __doc__ property in run time.

I don't know much about Python. But Python is unique because there seems to be a way to extract documentation by text processing like Java and Perl. I'll learn about it later.

http://www.python.org/dev/peps/pep-0257/

Squeak Smalltalk

Squeak Smalltalk doesn't have documentation system. It is not necessary because the IDE is strong enough. But you can see IDE itself as a memory based documentation system. Class comment is used as a description part, and method comment is used as a reference part. Class browser has mode to hide source code but comment.

What does documentation lose?

I realized that Knuth emphasized narrative way to express a program documentation instead of formal way in "Literate Programming" paper. The reason why WEB needed macro mechanism which Pascal didn't have was that it was needed to make the program flexible enough so that an author can keep order of original thinking flow on the text. Using WEB, whatever each symbol dependents on others, you can write down in any order which you like.

a program is, likewise, ready to comprehend it by learning its various parts in approximately the order in which it was written. -- LITERATE PROGRAMMING

Such consideration have been lost in current documentatin mechanisms like JavaDoc. Major goal of documentation generator for programming language is to make a comprehensive reference, certainly, literary value would be out of scope in those systems. I expect thet My Active Essays project would be a missing link following the lost feature.

However, before diving too deep, I need to know current art and science of program documentation... to be countinued.

Things in my mind recently

A couple of people asked me about this blog, so I add a new post finally. Because I don't spent my major time for Squeak recently, I changed the title of it with more general flavor than "Squeak Everyday". But "Workspace" is still a keyword from Smalltalk. What I am doing everyday is still dynamic hacking with / without computer.

I'm quite interested in relationship among programming and documentation. It was 80' when Knuth wrote about literate programming http://www.literateprogramming.com/knuthweb.pdf. In this article, he seems to be too excited about his idea that a program is a literature. How far we have elaborated the idea since then. Yes, from Emacs's documentation to JavaDoc, there are a lot of great works. But I'm not sure those are really literature, in other words, those are fun to read. In fact, although I am really fun of API documentation as a hacker, it could be more entertainment. That's what I am thinking these day.

When I was working on my old work http://metatoys.org/propella/js/workspace.cgi/Home (2007), such idea was in my mind, too. And I'm going to visit it again.