The Hweb System of Structured Documentation


(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.

A markup part, containing links to the program.
A code, containing program code that C can understand
This C code should ideally be about a dozen lines long, so that it is easily comprehensible as a unit and so that its structure is readily perceived.
The three parts of each section must appear in this order; i.e., the / commentary must come first, then the middle part, and finally the / code. Any of the parts may be empty.
 

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].