Literate Programming: The WEB System of Structured Documentation

Languages and Tools Session LT005 Thursday, 10:30 AM, Palisades DECUS Symposium, Fall 1987, Anaheim

E. W. (Wayne) Sewell E-Systems, Garland Division Dallas, Texas

slide # 1

Topics :

•

Introduction—What is WEB and why is it needed

• Features of WEB

• Implementation of WEB

• Drawbacks of WEB

• Sample Program

• Variations of WEB

• Acquiring WEB

slide # 2

What is WEB ?

• Unique programming methodology

• “Literate Programming”—programs as literature

• Higher level of source than program language like Pascal or documentation language like TEX

• Combination of the two, plus built-in macro preprocessor

• One source file produces executable code and document to describe it What is WEB ? (Cont’d)

• WEB program consists of independent scraps of text called code sections

• Each scrap has three parts:

– Description written in TEX document language – Macro definitions

– Program fragment written in Pascal

• any or all of the three parts may be present in a given section

slide # 4

Readability Concerns

• Traditional programs hard to read

• Inconsistent styles (comments, indentation, etc.) from one programmer to another • Legibility problems—even with laser printers

slide # 5

Listings Published in Computer Magazines Have Their Own Problems

• Legibility problems compounded by reproduction process

• Errors during transcription to typeset form

• Introduction of syntax errors

• Spacing problems Topics :

• Introduction—What is WEB and why is it needed •

Features of WEB

• Implementation of WEB

• Drawbacks of WEB

• Sample Program

• Variations of WEB

• Acquiring WEB

slide # 7

Code Reorganization

• Each code fragment is self-contained and independent of all other fragments

• Fragments can be presented in any order

• Top-down or bottom-up at the same time—whichever makes the most sense

• “Stream of consciousness”

• Types and variables can be declared near where they are used

• Initialization code can be placed near declaration of variable

slide # 8

Structured Programming

• Breaks up a program into smaller pieces

• The less code visible at once, the easier it is to understand

• WEB provides structured programming without subroutine overhead

• Structure exists only in mind of programmer—compiler sees monolithic block • Subroutines used only if really needed (to pass parameters, for recursion) — not

used just to support structure

• WEB can be used as a program design language (PDL)

Superior Listings

• Typeset quality (uses TEX document compiler)

• Programs look like those in computer science textbooks

• Bold font for reserved words, italics for identifiers

• Substitution of true mathematical symbols (such as ‘≠’ for ‘<>’ and ‘¬’ for ‘not’)

slide # 10

Superior Listings (Continued)

• Standard pretty printer functions (reformatting, indentation)

• Upward and downward references added to each section

• cross-references, table of contents, and list of section names added automatically • Description can contain tables, boxes, formulas, etc.

slide # 11

Macros

• Similar to C Preprocessor

• Three types of macros – Numeric — similar to Pascal constants, except that expressions are allowed – string — simple string substitution

– Parametric — can specify one parameter, designated by (#) following macro

name

slide # 12

Example define inc(#) ≡ # ← # + 1 From that point on, ‘inc(junk)’ is equivalent to ‘junk ← junk + 1’.

slide # 13

Differences Between Code Sections and Macros

• Macros are for symbols or expressions; code sections are larger

• Macros can have a parameter; code sections cannot

• Macros must be defined before they are used; forward references OK for code sections

• Macro names must be standard symbols (alphanumeric plus underscore); code section names can be any horizontal-mode TEX code

slide # 14

Portability

• WEB is portable at the source level

• Main WEB file is generic and is never changed

• Different change file for each implementation

• Macros can be used for implementation-dependent code

slide # 15

case Statement

• the case statement is good example of portability problems

• otherwise clause not standard Pascal

• some compilers use otherwise, others use else

• every implementation different

slide # 16

case Statement (Cont’d) The following definitions are placed near the beginning of the program: define othercases ≡ others: define endcases ≡ end format othercases ≡ else format endcases ≡ end

slide # 17

case Statement (Cont’d)

Throughout the remainder of the program, case statements take the following form:

case x of 1: ⟨ code for x = 1 ⟩; 3: ⟨ code for x = 3 ⟩; othercases ⟨ code for x ≠ 1 and x ≠ 3 ⟩ endcases

slide # 18

case Statement (Cont’d)

To port to a compiler which uses otherwise instead of others:, we replace the first define statement with:

define othercases ≡ otherwise

slide # 19

Conditional Compilation

• True conditional compilation not supported

• Can be simulated by using “meta-comments” (text between ‘@{’ and ‘@}’)

• Meta-comment delimiters passed through to Pascal source; regular comments ignored

• Optional code placed between two macro symbols

• Code turned “on” or “off” by making macros equal to either meta-comments or nothing Conditional Compilation (Cont’d) Given the following in the WEB file: define debug ≡ @{ define gubed ≡ @} format debug ≡ begin format gubed ≡ end ⋮ debug if interaction < batch mode then debug help; gubed the following output will result:

{IF INTERACTION<BATCHMODE THEN DEBUGHELP;}

slide # 21

Conditional Compilation (Cont’d) If everything is the same except: define debug ≡ define gubed ≡ then the following output will result:

IF INTERACTION<BATCHMODE THEN DEBUGHELP;

slide # 22

Extensions to Pascal • Add new capabilities to more primitive versions of Pascal • Hex and octal constants

• Constant expressions

• Symbolic labels (used as goto targets)

• Underscores in identifiers

• All of these are resolved within the WEB system

slide # 23

String Handling

• Single-quoted strings handled like Pascal

• Double-quoted strings converted to numeric constants – Single characters converted to numeric equivalent (as in ORD)

– Multi-char strings replaced by index into “String Pool”

slide # 24

Topics :

• Introduction—What is WEB and why is it needed

• Features of WEB •

Implementation of WEB

• Drawbacks of WEB

• Sample Program

• Variations of WEB

• Acquiring WEB

slide # 25

WEB Language Definition

• WEB source file consists of header followed by unspecified number of code sections • Each section contains Pascal code, TEX code, and WEB commands

• WEB commands are two-letter combinations, first of which is always ‘@’

• ‘@ ’ or ‘@*’ marks the start of the description part of a new section

• First ‘@d’ or ‘@f’ (define or format) starts the definition part

• Beginning of the section name (‘@<’) indicates the start of the Pascal code Structure of a WEB file

limbo text

code section 1

code section 2

⋮

code section n description of what section does (TEX)

                             @ ...

macro definitions

                             @d ...

program code (Pascal)

                             @<...@>=

[figure] [figure]

slide # 27

WEB Processors

• TANGLE – Creates Pascal source file from WEB source file

– Removes underscores and forces program text to uppercase

– Reorders code sections based on how they are referenced

– Pascal code created is deliberately made unreadable—meant for compilers,

not people

• WEAVE – Creates TEX source file from same WEB source file

– Adds formatting commands Basic WEB Data Flow

WEB Source File TEX Source File

Pascal Source File Program Document

Object File

            WEAVE

[figure]

            TANGLE

[figure]

TEX

[figure]

Pascal

[figure]

[figure] [figure]

slide # 29

Change Files

• Separate source files containing system-dependent code

• Dynamic override of key statements in main WEB file

• Each implementation has its own change file

• Base WEB file is generic and is never changed; same WEB file for PC’s, VAXen, and mainframes TANGLE Data Flow Using Change Files for Different Implementations

WEB Source File Change File For Microsoft Pascal

Change File For VAX Pascal Microsoft Pascal Source File Devel. Pascal Source File VAX Pascal Source File MS-DOS Object File Devel. System Object File VMS Object File

[figure]

TANGLE

[figure]

TANGLE

[figure]

TANGLE

[figure]

MS Pascal

[figure]

Devel. Pascal

[figure]

VAX Pascal

[figure] [figure]

slide # 31

WEAVE Data Flow Using Change Files for Different Implementations.

WEB Source File Change File For Microsoft Pascal

Change File For VAX Pascal Microsoft Specific TEX File Generic TEX File VAX Specific TEX File Microsoft Specific Program Document Generic Program Document VAX Specific Program Document

[figure]

 WEAVE

[figure]

 WEAVE

[figure]

 WEAVE

[figure]

TEX

[figure]

TEX

[figure]

TEX

[figure] [figure]

slide # 32

Topics :

• Introduction—What is WEB and why is it needed

• Features of WEB

• Implementation of WEB •

Drawbacks of WEB

• Sample Program

• Variations of WEB

• Acquiring WEB

slide # 33

Drawbacks of WEB

• Source level debugging is difficult with TANGLE-generated source

• Extra steps in development cycle—edit-TANGLE-compile-link-WEAVE-TEX-print

• Programmer must be proficient in three languages (WEB, Pascal, & TEX) and can make errors in all three simultaneously

• Requires TEX and bit mapped printer

• Monolithic structure—no provision for modules or separate compilation

slide # 34

Topics :

• Introduction—What is WEB and why is it needed

• Features of WEB

• Implementation of WEB

• Drawbacks of WEB •

Sample Program

• Variations of WEB

• Acquiring WEB Sample Listing

See section 13 of listing following these slides in session notes

slide # 36

WEB Source of a Section (Description Part)

@ Each of the 8 possible moves is attempted.
If the move can be made, it is recorded and a
move from the new position is attempted.
If |successful| is ever |true|,
it can only mean that a complete solution has
been found and the search is terminated.
If |successful| is false, the remaining
candidate moves are tried.

slide # 37

WEB Source (Definition Part)

@d no_more_candidates== @|
(candidate_move = number_of_legal_knight_moves)

slide # 38

WEB Source (Program Part)

@<Try the moves...@>=
candidate_move := 0 ;
repeat
  incr(candidate_move) ;
  successful := false ;
  @<Set the coordinates of the next move as defined
         by the rules of chess@>;
  @<Record the move if acceptable and try to make
       further moves; set |successful| if
       solution found@>;
until successful or no_more_candidates ;

TEX File Created by WEAVE

⋮

\1\&{repeat} \37$\\{incr}(\\{candidate\_move})$;\5
$\\{successful}\K\\{false}$;\5
\X16:Set the coordinates of the next move as defined
by the rules of chess\X;\6
\X14:Record the move if acceptable and try to make
further moves; set %
\\{successful} if solution found\X;\6

⋮

slide # 40

Pascal Source Generated by TANGLE

⋮

{:10}{11:}CANDIDATEMOV:0..8;{:11}BEGIN{13:}CANDIDATEMOV:=0;
REPEAT CANDIDATEMOV:=CANDIDATEMOV+1;SUCCESSFUL:=FALSE;{16:}
TARGROW:=ROW+ROWDELTAS[CANDIDATEMOV];
TARGCOL:=COL+COLDELTAS[CANDIDATEMOV];{:16};{14:}

⋮

slide # 41

Topics :

• Introduction—What is WEB and why is it needed

• Features of WEB

• Implementation of WEB

• Drawbacks of WEB

• Sample Program

•

Variations of WEB

• Acquiring WEB Variations of WEB

• WEB not locked into TEX and Pascal—can be adapted to other languages • Other programming languages

– Modula-2 language (MWEB)

– C language (CWEB)

• Other documentation languages – NROFF/TROFF

slide # 43

Topics :

• Introduction—What is WEB and why is it needed

• Features of WEB

• Implementation of WEB

• Drawbacks of WEB

• Sample Program

• Variations of WEB • Acquiring WEB

slide # 44

Acquiring WEB

• WEB is in the public domain

• TEX User’s Group (TUG)

• DECUS library (bundled with TEX itself)

• Commercial versions for PC’s