(Version 0.01)
Steve Gibson
copyright © 1999 by Steve Gibson free to copy and modify(GPL)
Introduction
The philosophy behind Hweb is that programmers who want to provide the best possible documentation for their programs need two things simultaneously: a text processing and formatting system, and a progamming language system. Neither type of system can provide the best documentation by itself. But when both are appropriately combined, we obtain a system that is much more useful than either system separately.
The structure of a software program may be thought of as a ``web'' that is made up of many interconnected pieces. To document such a program, we want to explain each individual part of the web and how it relates to its neighbors. The hypertext tools provided by hweb give us an opportunity to explain the local structure of each part by making that structure visible, and the programming tools provided by C make it possible for us to specify the algorithms formally and unambiguously. By combining the two, we can develop a style of programming that maximizes our ability to perceive the structure of a complex piece of software, and at the same time the documented programs can be mechanically translated into a working software system that matches the documentation.
The Hweb system consists of two parts; programs for working with text and html, and guidelines and methods for laying down programs. When writing a Hweb program the user keeps the code and the documentation in two files, labeled with the same name except for the extension . The something.html file is an output file and display file, which can correctly display typographic details like page layout and the use of indentation, italics, boldface, and mathematical symbols. You also have a modified C source code program that can be compiled and run as is, or you can run the command htangle -isomething.c to get a source file free of any html.
Besides providing a documentation tool, Hweb enhances
the C language by providing the ability to hide information and rearrange
pieces of the program text, so that a large system can be understood entirely
in terms of small sections and their local interrelationships.
The advantage of programming in Hweb is that the algorithms
can be expressed in ``untangled'' form, with each section explained separately.
A user of Hweb should be fairly familiar with the C programming
language. A minimal amount of acquaintance with html is also desirable,
but in fact it can be acquired as one uses Hweb, since WSYWG editors are
available which require virtually no knowledge of that language. To someone
familiar with both C and html the amount of effort necessary to learn the
commands of Hweb is small.
Overview
Three kinds of material go into hWeb files: raw text, html markup and C program text. A programmer writing in Hweb should be thinking both of the documentation and of the C program being created; i.e., the programmer should be instinctively aware of the different uses that C program and documentation will be put to. The program should end up being readable as a document, and give pleasure and information for years to come
A Hweb file is built up from units called sections that are more or less self-contained. Each section has three parts:
A test part, containing explanatory material about what is going on in the section.
Implementation
The C source code is edited with a simpl text editor.
The html documentation file is edited with a html editor
or a text editor.
The doc file should describe how the propram works, the
algorithem and design concepts.
the C source file has html markup embedded in it:
The first line in the file has /* C comment marker, then
<html>
<body>
*/
are used at the beginning of the source file to qualify
the file as readable by a html browser
Then <pre> markup is used to tell the browser to not
reformat the following text.
Following is normal C program text, until a link point
is needed.
For example, you may wish to mark the location of the
main() function.
The a comment /* marker is used, followed by
</pre>
<a name="main">main</a>
<pre>
*/
In the html doc file the following contruct is used to
link to it:
<a href="filename.c#main">main</a>
The same method can be used with .h header files.
The C source file ends with
/*
</pre>
</body>
</html>
*/
The C source can be run through the compiler as is. The html markup tags will not be seen by the compiler and the program should compile as intended.
However, a utility is provided to remove all html tags
from the C source, if desired. Run the utility htangle if you need to have
C source code with no html tags.
Credits
This document describes a version a system of program writing that
gets its inspiration from
Don Knuth's WEB system, and as adapted by Silvio Levy for CWEB. Since its creation in 1987, CWEB has been revised and enhanced in various ways, by both Knuth and Levy. Ramsey has made literate programming accessible to users of yet other
languages by means of his SPIDER system [see Communications of the ACM
32 (1989), 1051-1055].
|