HWEB

0. Introduction to HWEB.

HWEB is a language for literate programming. It combines a formatting language with a programming language to allow the construction of literate programs. Here is an example of such a program, based upon a blog entry by Neil Mitchell. Here is the code submitted to the compiler. Which is easier to understand?

Both files were generated by applying HWEB to the source file mitchell0.hweb. HWEB allows us to program in such a way that we can automatically obtain compiler-ready code while preserving the structure vital to understanding our programs.

1. First steps. A HWEB program is divided into sections. Each section begins with @* which marks the start of the section commentary. Immediately following @* can come an optional section title, which is terminated by a ".". The control code @h marks the end of the commentary and the beginning of the code, written in Haskell.

2. Let's look at an easy example:

@*A very easy program.
This program is no doubt easy to write because it does nothing.
@h
main = return()

Type the above into a file called easy.hweb and then after installing HWEB type

hweb0 easy0.hweb

This will produce a literate file called easy0.shtml which you view with your browser and an illiterate file easy0.hs which is Haskell code you can compile and run.

3. @h is not the only control code for introducing code. @< introduces code that is an expansion of a specific top-level description, a description that appears between the @< and a @>. For example:

@*Another easy program.
This program writes a string to the console.

@<Print a greeting@>=do{putStrLn "Hello, HWEB"}

@*. Here is the main program.
@h
main = @<Print greeting@>

Save the above in a file easy1.hweb and use HWEB to see the results.

4. Installing HWEB.