[Yhc] Yhc/Javascript project/status documentation clarification

[Dimitry Golubovsky]

Hi,

As I see some increasing interest to the Javascript backend I am
developing, first of all I would like to thank everybody who contacted
me on this matter. I would like to give a clarification on the
project's current status, and usability of the documentation that is
available on Haskell Wiki.

1. History and status of the project.

The project was "officially" started about 1.5 years ago. In November
2006, the first public announcement was made, with so called "Echo
Demo Program" presented. Since then, a work was done on improvement of
Javascript generation from Core, and also on low-level support of DOM
which was achieved by automatic conversion of slightly patched IDL
specifications available from the Web Consortium. Currently DOM Level2
is supported; Level1 was imported earlier, but all higher level
functionality is added with respect to Level 2; usage of Level 1 is
discouraged.

After low-level interfaces with Javascript and DOM were settled, some
experiments were carried out to test various programming paradigms for
the high level interfaces with understanding that direct DOM
manipulation differs little from usage of Javascript itself. Finally,
from several concepts existing for Haskell GUI, some programming
paradigm was distilled out, which is currently being worked on under
the name of "Haskell Web Toolkit".

At the moment, this is considered that the paradigm choice has been
finalized, and the project is in the stage of proper documenting and
polishing of the existing code, and creation of the widget library for
practical use. Some examples could be seen in the recently published
demo program at
http://darcs.haskell.org/yhc/web/jsdemos/HsWTKDemo.html .

2. Available documentation

Over the course of development, some draft documentation was published
on the Haskell Wiki. As the coding approaches changed, parts of this
documentation might have become partially or completely incorrect. I
am now working on putting this in order, and for the time being I'd
like to give some clarifications re garding existing documentation's
usability.

Brief Overview
http://www.haskell.org/haskellwiki/Yhc/Javascript/Brief_overview

This is a very general description, and its statements still hold.

Users Guide
http://www.haskell.org/haskellwiki/Yhc/Javascript/Users_guide

The "Downloading" and "Build prerequisites" sections are correct. Same
about "Building on Unix/Windows".

"What is installed": now much more is installed, but general directory
structure remains the same.

"Compiling Haskell to Core", "Converting Core into Javascript", and
"Building a XHTML Page" still valid in general, but see
http://www.golubovsky.org/repos/wsptest/Makefile for better example of
tools usage.

"All togeher: a simple Makefile" is not correct: use a Makefile mentioned above.

Programmers Guide
http://www.haskell.org/haskellwiki/Yhc/Javascript/Programmers_guide

"Up from the ground"
Refers to the first historical Echo Demo Program. Although commented
in  great detail, no longer usable. This is kept for historical
purposes only.

The rest of the document is generally usable with the current state of
the backend, but it does not cover the HsWTK programming paradigm at
all. All examples referring to DOM.Level1 should be treated as if they
referred to DOM.Level2, but at this level there are no major
differences between DOM levels.

"Threads and events"
This section was added recently, after successful experiments with CPS
and cooperative threads (or rather coroutines), Usable, except for the
Message Boxes section: the Control.Concurrent.JSThreads module offers
a better imolementation of message boxes.

"Inner workings"
http://www.haskell.org/haskellwiki/Yhc/Javascript/Inner_workings

This was an attempt to describe the internals of the "spineful tagless
machine" implemented in Javascript as the central part of the backend
runtime. It is about 75% correct as structure of HsFun and HsDly
objects varied slightly over time, but the general principles are
still there.

3. Conclusion

I am hoping that this message answers many questions of people
potentially interested in using of this technology. Please feel free
to contact me (golubovsky at gmail.com) with any suggestions and
constructive critics.

I am going to work on improving the project documentation for some
time, but if anybody believes that some funcitonality might be now
added to the supporting libraries, I am open for discussions.

Thanks again.

-- 
Dimitry Golubovsky

Anywhere on the Web