Source Code 1994 March/Source_Code_CD-ROM_Walnut_Creek_March_1994.iso/compsrcs/unix/volume26/funnlweb/part14

Text File | 1993-04-10 | 121.3 KB | 3,062 lines

Newsgroups: comp.sources.unix
From: [e-mail] (Ross Williams)
Subject: v26i134: funnelweb - a tool for literate programming in C, Part14/20
Sender: [e-mail]
Approved: [e-mail]

Submitted-By: [e-mail] (Ross Williams)
Posting-Number: Volume 26, Issue 134
Archive-Name: funnelweb/part14

#! /bin/sh
# This is a shell archive.  Remove anything before this line, then unpack
# it by saving it into a file and typing "sh file".  To overwrite existing
# files, type "sh file -c".  You can also feed this as standard input via
# unshar, or by typing "sh <file", e.g..  If this archive is complete, you
# will see the following message at the end:
#        "End of archive 14 (of 20)."
# Contents:  answers/sc10.lis hackman/h_ch1.tex userman/u_manual.idx
# Wrapped by [e-mail] on Sun Apr 11 11:00:30 1993
PATH=/bin:/usr/bin:/usr/ucb ; export PATH
if test -f 'answers/sc10.lis' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'answers/sc10.lis'\"
else
echo shar: Extracting \"'answers/sc10.lis'\" \(44801 characters\)
sed "s/^X//" >'answers/sc10.lis' <<'END_OF_FILE'
XFUNNELWEB LISTING FILE
X======================
X
Dump of mapped file "<<Suppressed>>".
X
MEMORY DUMP OF MAPPED FILE
X==========================
X
X+-------------------------------------------------+------------------+
X| 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F | 0123456789ABCDEF |
X+-------------------------------------------------+------------------+
X| 53 63 61 6E 6E 65 72 20 54 65 73 74 3A 20 53 70 | Scanner Test: Sp |
X| 65 63 69 61 6C 20 53 65 71 75 65 6E 63 65 20 52 | ecial Sequence R |
X| 65 63 6F 67 6E 69 74 69 6F 6E 0A 3D 3D 3D 3D 3D | ecognition.===== |
X| 3D 3D 3D 3D 3D 3D 3D 3D 3D 3D 3D 3D 3D 3D 3D 3D | ================ |
X| 3D 3D 3D 3D 3D 3D 3D 3D 3D 3D 3D 3D 3D 3D 3D 3D | ================ |
X| 3D 3D 3D 3D 3D 0A 54 68 69 73 20 74 65 73 74 20 | =====.This test  |
X| 74 65 73 74 73 20 74 6F 20 73 65 65 20 74 68 61 | tests to see tha |
X| 74 20 46 75 6E 6E 65 6C 57 65 62 20 69 73 20 72 | t FunnelWeb is r |
X| 65 63 6F 67 6E 69 73 69 6E 67 20 74 68 65 20 66 | ecognising the f |
X| 75 6C 6C 20 73 65 74 20 6F 66 20 73 70 65 63 69 | ull set of speci |
X| 61 6C 0A 73 65 71 75 65 6E 63 65 73 2E 0A 0A 54 | al.sequences...T |
X| 75 72 6E 20 4F 66 66 20 74 68 65 20 50 61 72 73 | urn Off the Pars |
X| 65 72 0A 2D 2D 2D 2D 2D 2D 2D 2D 2D 2D 2D 2D 2D | er.------------- |
X| 2D 2D 2D 2D 2D 2D 0A 46 69 72 73 74 20 77 65 20 | ------.First we  |
X| 63 61 75 73 65 20 61 20 64 65 6C 69 62 65 72 61 | cause a delibera |
X| 74 65 20 73 63 61 6E 6E 65 72 20 65 72 72 6F 72 | te scanner error |
X| 20 73 6F 20 61 73 20 74 6F 20 70 72 65 76 65 6E |  so as to preven |
X| 74 20 74 68 65 20 70 61 72 73 65 72 20 66 72 6F | t the parser fro |
X| 6D 0A 67 65 6E 65 72 61 74 69 6E 67 20 6C 6F 74 | m.generating lot |
X| 73 20 6F 66 20 65 72 72 6F 72 73 20 6F 76 65 72 | s of errors over |
X| 20 74 68 65 20 73 79 6E 74 61 63 74 69 63 20 72 |  the syntactic r |
X| 75 62 62 69 73 68 20 70 72 65 73 65 6E 74 65 64 | ubbish presented |
X| 20 68 65 72 65 2E 0A 0A 20 20 20 40 20 0A 0A 4C |  here...   @ ..L |
X| 69 73 74 20 6F 66 20 41 6C 6C 20 50 6F 73 73 69 | ist of All Possi |
X| 62 6C 65 20 53 70 65 63 69 61 6C 20 53 65 71 75 | ble Special Sequ |
X| 65 6E 63 65 73 0A 2D 2D 2D 2D 2D 2D 2D 2D 2D 2D | ences.---------- |
X| 2D 2D 2D 2D 2D 2D 2D 2D 2D 2D 2D 2D 2D 2D 2D 2D | ---------------- |
X| 2D 2D 2D 2D 2D 2D 2D 2D 2D 2D 2D 2D 0A 54 68 65 | ------------.The |
X| 20 66 6F 6C 6C 6F 77 69 6E 67 20 69 73 20 61 20 |  following is a  |
X| 6C 69 73 74 20 6F 66 20 74 68 65 20 64 65 66 61 | list of the defa |
X| 75 6C 74 20 73 70 65 63 69 61 6C 20 63 68 61 72 | ult special char |
X| 61 63 74 65 72 20 66 6F 6C 6C 6F 77 65 64 20 62 | acter followed b |
X| 79 20 65 61 63 68 20 6F 66 0A 74 68 65 20 41 53 | y each of.the AS |
X| 43 49 49 20 70 72 69 6E 74 61 62 6C 65 73 2E 0A | CII printables.. |
X| 30 30 30 20 74 6F 20 30 33 31 20 61 72 65 20 75 | 000 to 031 are u |
X| 6E 70 72 69 6E 74 61 62 6C 65 20 63 6F 6E 74 72 | nprintable contr |
X| 6F 6C 20 63 68 61 72 61 63 74 65 72 73 2E 0A 0A | ol characters... |
X| 30 33 32 20 20 40 20 20 20 20 2D 20 49 4C 4C 45 | 032  @    - ILLE |
X| 47 41 4C 2E 20 20 28 4E 6F 74 65 3A 20 48 79 70 | GAL.  (Note: Hyp |
X| 68 65 6E 20 69 73 20 6E 65 65 64 65 64 20 74 6F | hen is needed to |
X| 20 61 76 6F 69 64 20 74 72 61 69 6C 69 6E 67 20 |  avoid trailing  |
X| 62 6C 61 6E 6B 73 20 65 72 72 6F 72 2E 29 0A 30 | blanks error.).0 |
X| 33 33 20 20 40 21 20 20 20 2D 20 43 6F 6D 6D 65 | 33  @!   - Comme |
X| 6E 74 2E 0A 30 33 34 20 20 40 22 20 20 20 2D 20 | nt..034  @"   -  |
X| 50 61 72 61 6D 65 74 65 72 20 64 65 6C 69 6D 65 | Parameter delime |
X| 74 65 72 2E 0A 30 33 35 20 20 40 23 58 20 20 2D | ter..035  @#X  - |
X| 20 53 68 6F 72 74 20 6E 61 6D 65 20 73 65 71 75 |  Short name sequ |
X| 65 6E 63 65 2E 0A 40 24 20 20 20 30 33 36 20 20 | ence..@$   036   |
X| 2D 20 44 65 66 69 6E 65 20 6D 61 63 72 6F 2E 20 | - Define macro.  |
X| 48 61 73 20 74 6F 20 62 65 20 61 74 20 73 74 61 | Has to be at sta |
X| 72 74 20 6F 66 20 6C 69 6E 65 2E 0A 30 33 37 20 | rt of line..037  |
X| 20 40 25 20 20 20 2D 20 49 4C 4C 45 47 41 4C 2E |  @%   - ILLEGAL. |
X| 0A 30 33 38 20 20 40 26 20 20 20 2D 20 49 4C 4C | .038  @&   - ILL |
X| 45 47 41 4C 2E 0A 30 33 39 20 20 40 27 20 20 20 | EGAL..039  @'    |
X| 2D 20 49 4C 4C 45 47 41 4C 2E 0A 30 34 30 20 20 | - ILLEGAL..040   |
X| 40 28 20 20 20 2D 20 4F 70 65 6E 20 70 61 72 61 | @(   - Open para |
X| 6D 65 74 65 72 20 6C 69 73 74 2E 0A 30 34 31 20 | meter list..041  |
X| 20 40 29 20 20 20 2D 20 43 6C 6F 73 65 20 70 61 |  @)   - Close pa |
X| 72 61 6D 65 74 65 72 20 6C 69 73 74 2E 0A 30 34 | rameter list..04 |
X| 32 0A 40 2A 20 20 20 20 20 20 20 20 2D 20 4F 6C | 2.@*        - Ol |
X| 64 20 66 61 73 68 69 6F 6E 65 64 20 73 65 63 74 | d fashioned sect |
X| 69 6F 6E 20 6D 61 72 6B 65 72 20 28 68 61 73 20 | ion marker (has  |
X| 74 6F 20 62 65 20 61 74 20 73 74 61 72 74 20 6F | to be at start o |
X| 66 20 61 20 6C 69 6E 65 2E 29 2E 0A 30 34 33 20 | f a line.)..043  |
X| 20 40 2B 20 20 20 2D 20 49 6E 73 65 72 74 20 6E |  @+   - Insert n |
X| 65 77 6C 69 6E 65 2E 0A 30 34 34 20 20 40 2C 20 | ewline..044  @,  |
X| 20 20 2D 20 50 61 72 61 6D 65 74 65 72 20 73 65 |   - Parameter se |
X| 70 61 72 61 74 6F 72 2E 0A 30 34 35 20 20 40 2D | parator..045  @- |
X| 0A 20 20 20 20 20 20 20 20 20 20 2D 20 49 67 6E | .          - Ign |
X| 6F 72 65 20 65 6E 64 20 6F 66 20 6C 69 6E 65 20 | ore end of line  |
X| 6D 61 72 6B 65 72 20 28 68 61 73 20 74 6F 20 62 | marker (has to b |
X| 65 20 61 74 20 65 6E 64 20 6F 66 20 6C 69 6E 65 | e at end of line |
X| 29 2E 0A 30 34 36 20 20 40 2E 20 20 20 2D 20 49 | )..046  @.   - I |
X| 4C 4C 45 47 41 4C 2E 0A 30 34 37 20 20 40 2F 20 | LLEGAL..047  @/  |
X| 20 20 2D 20 45 6D 70 68 61 73 69 73 65 64 20 74 |   - Emphasised t |
X| 65 78 74 2E 0A 30 34 38 20 20 40 30 20 20 20 2D | ext..048  @0   - |
X| 20 49 4C 4C 45 47 41 4C 2E 0A 30 34 39 20 20 40 |  ILLEGAL..049  @ |
X| 31 20 20 20 2D 20 46 6F 72 6D 61 6C 20 70 61 72 | 1   - Formal par |
X| 61 6D 65 74 65 72 20 31 2E 0A 30 35 30 20 20 40 | ameter 1..050  @ |
X| 32 20 20 20 2D 20 46 6F 72 6D 61 6C 20 70 61 72 | 2   - Formal par |
X| 61 6D 65 74 65 72 20 32 2E 0A 30 35 31 20 20 40 | ameter 2..051  @ |
X| 33 20 20 20 2D 20 46 6F 72 6D 61 6C 20 70 61 72 | 3   - Formal par |
X| 61 6D 65 74 65 72 20 33 2E 0A 30 35 32 20 20 40 | ameter 3..052  @ |
X| 34 20 20 20 2D 20 46 6F 72 6D 61 6C 20 70 61 72 | 4   - Formal par |
X| 61 6D 65 74 65 72 20 34 2E 0A 30 35 33 20 20 40 | ameter 4..053  @ |
X| 35 20 20 20 2D 20 46 6F 72 6D 61 6C 20 70 61 72 | 5   - Formal par |
X| 61 6D 65 74 65 72 20 35 2E 0A 30 35 34 20 20 40 | ameter 5..054  @ |
X| 36 20 20 20 2D 20 46 6F 72 6D 61 6C 20 70 61 72 | 6   - Formal par |
X| 61 6D 65 74 65 72 20 36 2E 0A 30 35 35 20 20 40 | ameter 6..055  @ |
X| 37 20 20 20 2D 20 46 6F 72 6D 61 6C 20 70 61 72 | 7   - Formal par |
X| 61 6D 65 74 65 72 20 37 2E 0A 30 35 36 20 20 40 | ameter 7..056  @ |
X| 38 20 20 20 2D 20 46 6F 72 6D 61 6C 20 70 61 72 | 8   - Formal par |
X| 61 6D 65 74 65 72 20 38 2E 0A 30 35 37 20 20 40 | ameter 8..057  @ |
X| 39 20 20 20 2D 20 46 6F 72 6D 61 6C 20 70 61 72 | 9   - Formal par |
X| 61 6D 65 74 65 72 20 39 2E 0A 30 35 38 20 20 40 | ameter 9..058  @ |
X| 3A 20 20 20 2D 20 49 4C 4C 45 47 41 4C 2E 0A 30 | :   - ILLEGAL..0 |
X| 35 39 20 20 40 3B 20 20 20 2D 20 49 4C 4C 45 47 | 59  @;   - ILLEG |
X| 41 4C 2E 0A 30 36 30 20 20 40 3C 20 20 20 2D 20 | AL..060  @<   -  |
X| 4F 70 65 6E 20 6D 61 63 72 6F 20 6E 61 6D 65 2E | Open macro name. |
X| 0A 30 36 31 20 20 40 3D 40 20 20 2D 20 53 65 74 | .061  @=@  - Set |
X| 20 73 70 65 63 69 61 6C 20 63 68 61 72 61 63 74 |  special charact |
X| 65 72 2E 0A 30 36 32 20 20 40 3E 20 20 20 2D 20 | er..062  @>   -  |
X| 43 6C 6F 73 65 20 6D 61 63 72 6F 20 6E 61 6D 65 | Close macro name |
X| 2E 0A 30 36 33 20 20 40 3F 20 20 20 2D 20 49 4C | ..063  @?   - IL |
X| 4C 45 47 41 4C 2E 0A 30 36 34 20 20 40 40 20 20 | LEGAL..064  @@   |
X| 20 2D 20 49 6E 73 65 72 74 20 73 70 65 63 69 61 |  - Insert specia |
X| 6C 20 63 68 61 72 61 63 74 65 72 20 69 6E 74 6F | l character into |
X| 20 74 65 78 74 2E 0A 40 41 20 20 30 36 35 20 20 |  text..@A  065   |
X| 20 2D 20 4E 65 77 20 73 65 63 74 69 6F 6E 20 28 |  - New section ( |
X| 6C 65 76 65 6C 20 31 29 2E 20 4D 75 73 74 20 62 | level 1). Must b |
X| 65 20 61 74 20 73 74 61 72 74 20 6F 66 20 61 20 | e at start of a  |
X| 6C 69 6E 65 2E 0A 40 42 20 20 30 36 36 20 20 20 | line..@B  066    |
X| 2D 20 4E 65 77 20 73 65 63 74 69 6F 6E 20 28 6C | - New section (l |
X| 65 76 65 6C 20 32 29 2E 20 4D 75 73 74 20 62 65 | evel 2). Must be |
X| 20 61 74 20 73 74 61 72 74 20 6F 66 20 61 20 6C |  at start of a l |
X| 69 6E 65 2E 0A 40 43 20 20 30 36 37 20 20 20 2D | ine..@C  067   - |
X| 20 4E 65 77 20 73 65 63 74 69 6F 6E 20 28 6C 65 |  New section (le |
X| 76 65 6C 20 33 29 2E 20 4D 75 73 74 20 62 65 20 | vel 3). Must be  |
X| 61 74 20 73 74 61 72 74 20 6F 66 20 61 20 6C 69 | at start of a li |
X| 6E 65 2E 0A 40 44 20 20 30 36 38 20 20 20 2D 20 | ne..@D  068   -  |
X| 4E 65 77 20 73 65 63 74 69 6F 6E 20 28 6C 65 76 | New section (lev |
X| 65 6C 20 34 29 2E 20 4D 75 73 74 20 62 65 20 61 | el 4). Must be a |
X| 74 20 73 74 61 72 74 20 6F 66 20 61 20 6C 69 6E | t start of a lin |
X| 65 2E 0A 40 45 20 20 30 36 39 20 20 20 2D 20 4E | e..@E  069   - N |
X| 65 77 20 73 65 63 74 69 6F 6E 20 28 6C 65 76 65 | ew section (leve |
X| 6C 20 35 29 2E 20 4D 75 73 74 20 62 65 20 61 74 | l 5). Must be at |
X| 20 73 74 61 72 74 20 6F 66 20 61 20 6C 69 6E 65 |  start of a line |
X| 2E 0A 30 37 30 20 20 40 46 20 20 20 2D 20 49 4C | ..070  @F   - IL |
X| 4C 45 47 41 4C 2E 0A 30 37 31 20 20 40 47 20 20 | LEGAL..071  @G   |
X| 20 2D 20 49 4C 4C 45 47 41 4C 2E 0A 30 37 32 20 |  - ILLEGAL..072  |
X| 20 40 48 20 20 20 2D 20 49 4C 4C 45 47 41 4C 2E |  @H   - ILLEGAL. |
X| 0A 30 37 33 20 20 40 49 20 20 20 2D 20 49 6E 63 | .073  @I   - Inc |
X| 6C 75 64 65 20 66 69 6C 65 2E 20 57 69 6C 6C 20 | lude file. Will  |
X| 70 72 6F 76 6F 6B 65 20 61 6E 20 65 72 72 6F 72 | provoke an error |
X| 20 68 65 72 65 20 74 68 6F 75 67 68 2E 0A 30 37 |  here though..07 |
X| 34 20 20 40 4A 20 20 20 2D 20 49 4C 4C 45 47 41 | 4  @J   - ILLEGA |
X| 4C 2E 0A 30 37 35 20 20 40 4B 20 20 20 2D 20 49 | L..075  @K   - I |
X| 4C 4C 45 47 41 4C 2E 0A 30 37 36 20 20 40 4C 20 | LLEGAL..076  @L  |
X| 20 20 2D 20 49 4C 4C 45 47 41 4C 2E 0A 30 37 37 |   - ILLEGAL..077 |
X| 20 20 40 4D 20 20 20 2D 20 54 61 67 73 20 6D 61 |   @M   - Tags ma |
X| 63 72 6F 20 61 73 20 62 65 69 6E 67 20 61 6C 6C | cro as being all |
X| 6F 77 65 64 20 74 6F 20 62 65 20 63 61 6C 6C 65 | owed to be calle |
X| 64 20 6D 61 6E 79 20 74 69 6D 65 73 2E 0A 30 37 | d many times..07 |
X| 38 20 20 40 4E 20 20 20 2D 20 49 4C 4C 45 47 41 | 8  @N   - ILLEGA |
X| 4C 2E 0A 40 4F 20 20 20 30 37 39 20 20 2D 20 4E | L..@O   079  - N |
X| 65 77 20 6D 61 63 72 6F 20 61 74 74 61 63 68 65 | ew macro attache |
X| 64 20 74 6F 20 6F 75 74 70 75 74 20 66 69 6C 65 | d to output file |
X| 2E 20 48 61 73 20 74 6F 20 62 65 20 61 74 20 73 | . Has to be at s |
X| 74 61 72 74 20 6F 66 20 6C 69 6E 65 2E 0A 30 38 | tart of line..08 |
X| 30 20 20 40 50 20 20 20 2D 20 50 72 61 67 6D 61 | 0  @P   - Pragma |
X| 2E 20 57 69 6C 6C 20 63 61 75 73 65 20 65 72 72 | . Will cause err |
X| 6F 72 20 68 65 72 65 20 74 68 6F 75 67 68 2E 0A | or here though.. |
X| 30 38 31 20 20 40 51 20 20 20 2D 20 49 4C 4C 45 | 081  @Q   - ILLE |
X| 47 41 4C 2E 0A 30 38 32 20 20 40 52 20 20 20 2D | GAL..082  @R   - |
X| 20 49 4C 4C 45 47 41 4C 2E 0A 30 38 33 20 20 40 |  ILLEGAL..083  @ |
X| 53 20 20 20 2D 20 49 4C 4C 45 47 41 4C 2E 0A 30 | S   - ILLEGAL..0 |
X| 38 34 20 20 40 54 20 20 20 2D 20 54 79 70 65 73 | 84  @T   - Types |
X| 65 74 74 65 72 20 64 69 72 65 63 74 69 76 65 2E | etter directive. |
X| 20 57 69 6C 6C 20 63 61 75 73 65 20 61 6E 20 65 |  Will cause an e |
X| 72 72 6F 72 20 68 65 72 65 20 74 68 6F 75 67 68 | rror here though |
X| 2E 0A 30 38 35 20 20 40 55 20 20 20 2D 20 49 4C | ..085  @U   - IL |
X| 4C 45 47 41 4C 2E 0A 30 38 36 20 20 40 56 20 20 | LEGAL..086  @V   |
X| 20 2D 20 49 4C 4C 45 47 41 4C 2E 0A 30 38 37 20 |  - ILLEGAL..087  |
X| 20 40 57 20 20 20 2D 20 49 4C 4C 45 47 41 4C 2E |  @W   - ILLEGAL. |
X| 0A 30 38 38 20 20 40 58 20 20 20 2D 20 49 4C 4C | .088  @X   - ILL |
X| 45 47 41 4C 2E 0A 30 38 39 20 20 40 59 20 20 20 | EGAL..089  @Y    |
X| 2D 20 49 4C 4C 45 47 41 4C 2E 0A 30 39 30 20 20 | - ILLEGAL..090   |
X| 40 5A 20 20 20 2D 20 54 61 67 73 20 6D 61 63 72 | @Z   - Tags macr |
X| 6F 20 61 73 20 62 65 69 6E 67 20 61 6C 6C 6F 77 | o as being allow |
X| 65 64 20 74 6F 20 62 65 20 63 61 6C 6C 65 64 20 | ed to be called  |
X| 7A 65 72 6F 20 74 69 6D 65 73 2E 0A 30 39 31 20 | zero times..091  |
X| 20 40 5B 20 20 20 2D 20 49 4C 4C 45 47 41 4C 2E |  @[   - ILLEGAL. |
X| 0A 30 39 32 20 20 40 5C 20 20 20 2D 20 49 4C 4C | .092  @\   - ILL |
X| 45 47 41 4C 2E 0A 30 39 33 20 20 40 5D 20 20 20 | EGAL..093  @]    |
X| 2D 20 49 4C 4C 45 47 41 4C 2E 0A 30 39 34 20 20 | - ILLEGAL..094   |
X| 40 5E 44 28 30 36 35 29 20 2D 20 49 6E 73 65 72 | @^D(065) - Inser |
X| 74 20 63 6F 6E 74 72 6F 6C 20 63 68 61 72 61 63 | t control charac |
X| 74 65 72 20 69 6E 74 6F 20 74 65 78 74 0A 30 39 | ter into text.09 |
X| 35 20 20 40 5F 20 20 20 2D 20 49 4C 4C 45 47 41 | 5  @_   - ILLEGA |
X| 4C 2E 0A 30 39 36 20 20 40 60 20 20 20 2D 20 49 | L..096  @`   - I |
X| 4C 4C 45 47 41 4C 2E 0A 40 61 20 20 20 30 39 37 | LLEGAL..@a   097 |
X| 20 20 2D 20 4E 65 77 20 73 65 63 74 69 6F 6E 20 |   - New section  |
X| 28 6C 65 76 65 6C 20 31 29 2E 20 4D 75 73 74 20 | (level 1). Must  |
X| 62 65 20 61 74 20 73 74 61 72 74 20 6F 66 20 61 | be at start of a |
X| 20 6C 69 6E 65 2E 0A 40 62 20 20 20 30 39 38 20 |  line..@b   098  |
X| 20 2D 20 4E 65 77 20 73 65 63 74 69 6F 6E 20 28 |  - New section ( |
X| 6C 65 76 65 6C 20 31 29 2E 20 4D 75 73 74 20 62 | level 1). Must b |
X| 65 20 61 74 20 73 74 61 72 74 20 6F 66 20 61 20 | e at start of a  |
X| 6C 69 6E 65 2E 0A 40 63 20 20 20 30 39 39 20 20 | line..@c   099   |
X| 2D 20 4E 65 77 20 73 65 63 74 69 6F 6E 20 28 6C | - New section (l |
X| 65 76 65 6C 20 31 29 2E 20 4D 75 73 74 20 62 65 | evel 1). Must be |
X| 20 61 74 20 73 74 61 72 74 20 6F 66 20 61 20 6C |  at start of a l |
X| 69 6E 65 2E 0A 40 64 20 20 20 31 30 30 20 20 2D | ine..@d   100  - |
X| 20 4E 65 77 20 73 65 63 74 69 6F 6E 20 28 6C 65 |  New section (le |
X| 76 65 6C 20 31 29 2E 20 4D 75 73 74 20 62 65 20 | vel 1). Must be  |
X| 61 74 20 73 74 61 72 74 20 6F 66 20 61 20 6C 69 | at start of a li |
X| 6E 65 2E 0A 40 65 20 20 20 31 30 31 20 20 2D 20 | ne..@e   101  -  |
X| 4E 65 77 20 73 65 63 74 69 6F 6E 20 28 6C 65 76 | New section (lev |
X| 65 6C 20 31 29 2E 20 4D 75 73 74 20 62 65 20 61 | el 1). Must be a |
X| 74 20 73 74 61 72 74 20 6F 66 20 61 20 6C 69 6E | t start of a lin |
X| 65 2E 0A 31 30 32 20 20 40 66 20 20 20 2D 20 49 | e..102  @f   - I |
X| 4C 4C 45 47 41 4C 2E 0A 31 30 33 20 20 40 67 20 | LLEGAL..103  @g  |
X| 20 20 2D 20 49 4C 4C 45 47 41 4C 2E 0A 31 30 34 |   - ILLEGAL..104 |
X| 20 20 40 68 20 20 20 2D 20 49 4C 4C 45 47 41 4C |   @h   - ILLEGAL |
X| 2E 0A 31 30 35 20 20 40 69 20 20 20 2D 20 49 6E | ..105  @i   - In |
X| 63 6C 75 64 65 20 66 69 6C 65 2E 20 57 69 6C 6C | clude file. Will |
X| 20 70 72 6F 76 6F 6B 65 20 61 6E 20 65 72 72 6F |  provoke an erro |
X| 72 20 68 65 72 65 20 74 68 6F 75 67 68 2E 0A 31 | r here though..1 |
X| 30 36 20 20 40 6A 20 20 20 2D 20 49 4C 4C 45 47 | 06  @j   - ILLEG |
X| 41 4C 2E 0A 31 30 37 20 20 40 6B 20 20 20 2D 20 | AL..107  @k   -  |
X| 49 4C 4C 45 47 41 4C 2E 0A 31 30 38 20 20 40 6C | ILLEGAL..108  @l |
X| 20 20 20 2D 20 49 4C 4C 45 47 41 4C 2E 0A 31 30 |    - ILLEGAL..10 |
X| 39 20 20 40 6D 20 20 20 2D 20 54 61 67 73 20 6D | 9  @m   - Tags m |
X| 61 63 72 6F 20 61 73 20 62 65 69 6E 67 20 61 6C | acro as being al |
X| 6C 6F 77 65 64 20 74 6F 20 62 65 20 63 61 6C 6C | lowed to be call |
X| 65 64 20 6D 61 6E 79 20 74 69 6D 65 73 2E 0A 31 | ed many times..1 |
X| 31 30 20 20 40 6E 20 20 20 2D 20 49 4C 4C 45 47 | 10  @n   - ILLEG |
X| 41 4C 2E 0A 40 4F 20 20 20 31 31 31 20 20 2D 20 | AL..@O   111  -  |
X| 4E 65 77 20 6D 61 63 72 6F 20 61 74 74 61 63 68 | New macro attach |
X| 65 64 20 74 6F 20 6F 75 74 70 75 74 20 66 69 6C | ed to output fil |
X| 65 2E 20 48 61 73 20 74 6F 20 62 65 20 61 74 20 | e. Has to be at  |
X| 73 74 61 72 74 20 6F 66 20 6C 69 6E 65 2E 0A 31 | start of line..1 |
X| 31 32 20 20 40 70 20 20 20 2D 20 50 72 61 67 6D | 12  @p   - Pragm |
X| 61 2E 20 57 69 6C 6C 20 63 61 75 73 65 20 65 72 | a. Will cause er |
X| 72 6F 72 20 68 65 72 65 20 74 68 6F 75 67 68 2E | ror here though. |
X| 0A 31 31 33 20 20 40 71 20 20 20 2D 20 49 4C 4C | .113  @q   - ILL |
X| 45 47 41 4C 2E 0A 31 31 34 20 20 40 72 20 20 20 | EGAL..114  @r    |
X| 2D 20 49 4C 4C 45 47 41 4C 2E 0A 31 31 35 20 20 | - ILLEGAL..115   |
X| 40 73 20 20 20 2D 20 49 4C 4C 45 47 41 4C 2E 0A | @s   - ILLEGAL.. |
X| 31 31 36 20 20 40 74 20 20 20 2D 20 54 79 70 65 | 116  @t   - Type |
X| 73 65 74 74 65 72 20 64 69 72 65 63 74 69 76 65 | setter directive |
X| 2E 20 57 69 6C 6C 20 63 61 75 73 65 20 61 6E 20 | . Will cause an  |
X| 65 72 72 6F 72 20 68 65 72 65 20 74 68 6F 75 67 | error here thoug |
X| 68 2E 0A 31 31 37 20 20 40 75 20 20 20 2D 20 49 | h..117  @u   - I |
X| 4C 4C 45 47 41 4C 2E 0A 31 31 38 20 20 40 76 20 | LLEGAL..118  @v  |
X| 20 20 2D 20 49 4C 4C 45 47 41 4C 2E 0A 31 31 39 |   - ILLEGAL..119 |
X| 20 20 40 77 20 20 20 2D 20 49 4C 4C 45 47 41 4C |   @w   - ILLEGAL |
X| 2E 0A 31 32 30 20 20 40 78 20 20 20 2D 20 49 4C | ..120  @x   - IL |
X| 4C 45 47 41 4C 2E 0A 31 32 31 20 20 40 79 20 20 | LEGAL..121  @y   |
X| 20 2D 20 49 4C 4C 45 47 41 4C 2E 0A 31 32 32 20 |  - ILLEGAL..122  |
X| 20 40 7A 20 20 20 2D 20 54 61 67 73 20 6D 61 63 |  @z   - Tags mac |
X| 72 6F 20 61 73 20 62 65 69 6E 67 20 61 6C 6C 6F | ro as being allo |
X| 77 65 64 20 74 6F 20 62 65 20 63 61 6C 6C 65 64 | wed to be called |
X| 20 7A 65 72 6F 20 74 69 6D 65 73 2E 0A 31 32 33 |  zero times..123 |
X| 20 20 40 7B 20 20 20 2D 20 4F 70 65 6E 20 6D 61 |   @{   - Open ma |
X| 63 72 6F 20 62 6F 64 79 2E 0A 31 32 34 20 20 40 | cro body..124  @ |
X| 7C 20 20 20 2D 20 49 4C 4C 45 47 41 4C 2E 0A 31 | |   - ILLEGAL..1 |
X| 32 35 20 20 40 7D 20 20 20 2D 20 43 6C 6F 73 65 | 25  @}   - Close |
X| 20 6D 61 63 72 6F 20 62 6F 64 79 2E 0A 31 32 36 |  macro body..126 |
X| 20 20 40 7E 20 20 20 2D 20 49 4C 4C 45 47 41 4C |   @~   - ILLEGAL |
X| 2E 0A 31 32 37 20 74 6F 20 32 35 35 20 61 72 65 | ..127 to 255 are |
X| 20 6E 6F 74 20 73 74 61 6E 64 61 72 64 20 70 72 |  not standard pr |
X| 69 6E 74 61 62 6C 65 20 41 53 43 49 49 20 63 68 | intable ASCII ch |
X| 61 72 61 63 74 65 72 73 2E 0A                   | aracters..       |
X+-------------------------------------------------+------------------+
X
X
X=========================== Start of LINE LIST DUMP ============================
X
Globl Local| Text
X-----------+--------------------------------------------------------------------
X00001 00001| Scanner Test: Special Sequence Recognition<010>
X00002 00002| ==========================================<010>
X00003 00003| This test tests to see that FunnelWeb is recognising the full set of special<010>
X00004 00004| sequences.<010>
X00005 00005| <010>
X00006 00006| Turn Off the Parser<010>
X00007 00007| -------------------<010>
X00008 00008| First we cause a deliberate scanner error so as to prevent the parser from<010>
X00009 00009| generating lots of errors over the syntactic rubbish presented here.<010>
X00010 00010| <010>
X00011 00011|    @ <010>
X00012 00012| <010>
X00013 00013| List of All Possible Special Sequences<010>
X00014 00014| --------------------------------------<010>
X00015 00015| The following is a list of the default special character followed by each of<010>
X00016 00016| the ASCII printables.<010>
X00017 00017| 000 to 031 are unprintable control characters.<010>
X00018 00018| <010>
X00019 00019| 032  @    - ILLEGAL.  (Note: Hyphen is needed to avoid trailing blanks error.)<010>
X00020 00020| 033  @!   - Comment.<010>
X00021 00021| 034  @"   - Parameter delimeter.<010>
X00022 00022| 035  @#X  - Short name sequence.<010>
X00023 00023| @$   036  - Define macro. Has to be at start of line.<010>
X00024 00024| 037  @%   - ILLEGAL.<010>
X00025 00025| 038  @&   - ILLEGAL.<010>
X00026 00026| 039  @'   - ILLEGAL.<010>
X00027 00027| 040  @(   - Open parameter list.<010>
X00028 00028| 041  @)   - Close parameter list.<010>
X00029 00029| 042<010>
X00030 00030| @*        - Old fashioned section marker (has to be at start of a line.).<010>
X00031 00031| 043  @+   - Insert newline.<010>
X00032 00032| 044  @,   - Parameter separator.<010>
X00033 00033| 045  @-<010>
X00034 00034|           - Ignore end of line marker (has to be at end of line).<010>
X00035 00035| 046  @.   - ILLEGAL.<010>
X00036 00036| 047  @/   - Emphasised text.<010>
X00037 00037| 048  @0   - ILLEGAL.<010>
X00038 00038| 049  @1   - Formal parameter 1.<010>
X00039 00039| 050  @2   - Formal parameter 2.<010>
X00040 00040| 051  @3   - Formal parameter 3.<010>
X00041 00041| 052  @4   - Formal parameter 4.<010>
X00042 00042| 053  @5   - Formal parameter 5.<010>
X00043 00043| 054  @6   - Formal parameter 6.<010>
X00044 00044| 055  @7   - Formal parameter 7.<010>
X00045 00045| 056  @8   - Formal parameter 8.<010>
X00046 00046| 057  @9   - Formal parameter 9.<010>
X00047 00047| 058  @:   - ILLEGAL.<010>
X00048 00048| 059  @;   - ILLEGAL.<010>
X00049 00049| 060  @<   - Open macro name.<010>
X00050 00050| 061  @=@  - Set special character.<010>
X00051 00051| 062  @>   - Close macro name.<010>
X00052 00052| 063  @?   - ILLEGAL.<010>
X00053 00053| 064  @@   - Insert special character into text.<010>
X00054 00054| @A  065   - New section (level 1). Must be at start of a line.<010>
X00055 00055| @B  066   - New section (level 2). Must be at start of a line.<010>
X00056 00056| @C  067   - New section (level 3). Must be at start of a line.<010>
X00057 00057| @D  068   - New section (level 4). Must be at start of a line.<010>
X00058 00058| @E  069   - New section (level 5). Must be at start of a line.<010>
X00059 00059| 070  @F   - ILLEGAL.<010>
X00060 00060| 071  @G   - ILLEGAL.<010>
X00061 00061| 072  @H   - ILLEGAL.<010>
X00062 00062| 073  @I   - Include file. Will provoke an error here though.<010>
X00063 00063| 074  @J   - ILLEGAL.<010>
X00064 00064| 075  @K   - ILLEGAL.<010>
X00065 00065| 076  @L   - ILLEGAL.<010>
X00066 00066| 077  @M   - Tags macro as being allowed to be called many times.<010>
X00067 00067| 078  @N   - ILLEGAL.<010>
X00068 00068| @O   079  - New macro attached to output file. Has to be at start of line.<010>
X00069 00069| 080  @P   - Pragma. Will cause error here though.<010>
X00070 00070| 081  @Q   - ILLEGAL.<010>
X00071 00071| 082  @R   - ILLEGAL.<010>
X00072 00072| 083  @S   - ILLEGAL.<010>
X00073 00073| 084  @T   - Typesetter directive. Will cause an error here though.<010>
X00074 00074| 085  @U   - ILLEGAL.<010>
X00075 00075| 086  @V   - ILLEGAL.<010>
X00076 00076| 087  @W   - ILLEGAL.<010>
X00077 00077| 088  @X   - ILLEGAL.<010>
X00078 00078| 089  @Y   - ILLEGAL.<010>
X00079 00079| 090  @Z   - Tags macro as being allowed to be called zero times.<010>
X00080 00080| 091  @[   - ILLEGAL.<010>
X00081 00081| 092  @\   - ILLEGAL.<010>
X00082 00082| 093  @]   - ILLEGAL.<010>
X00083 00083| 094  @^D(065) - Insert control character into text<010>
X00084 00084| 095  @_   - ILLEGAL.<010>
X00085 00085| 096  @`   - ILLEGAL.<010>
X00086 00086| @a   097  - New section (level 1). Must be at start of a line.<010>
X00087 00087| @b   098  - New section (level 1). Must be at start of a line.<010>
X00088 00088| @c   099  - New section (level 1). Must be at start of a line.<010>
X00089 00089| @d   100  - New section (level 1). Must be at start of a line.<010>
X00090 00090| @e   101  - New section (level 1). Must be at start of a line.<010>
X00091 00091| 102  @f   - ILLEGAL.<010>
X00092 00092| 103  @g   - ILLEGAL.<010>
X00093 00093| 104  @h   - ILLEGAL.<010>
X00094 00094| 105  @i   - Include file. Will provoke an error here though.<010>
X00095 00095| 106  @j   - ILLEGAL.<010>
X00096 00096| 107  @k   - ILLEGAL.<010>
X00097 00097| 108  @l   - ILLEGAL.<010>
X00098 00098| 109  @m   - Tags macro as being allowed to be called many times.<010>
X00099 00099| 110  @n   - ILLEGAL.<010>
X00100 00100| @O   111  - New macro attached to output file. Has to be at start of line.<010>
X00101 00101| 112  @p   - Pragma. Will cause error here though.<010>
X00102 00102| 113  @q   - ILLEGAL.<010>
X00103 00103| 114  @r   - ILLEGAL.<010>
X00104 00104| 115  @s   - ILLEGAL.<010>
X00105 00105| 116  @t   - Typesetter directive. Will cause an error here though.<010>
X00106 00106| 117  @u   - ILLEGAL.<010>
X00107 00107| 118  @v   - ILLEGAL.<010>
X00108 00108| 119  @w   - ILLEGAL.<010>
X00109 00109| 120  @x   - ILLEGAL.<010>
X00110 00110| 121  @y   - ILLEGAL.<010>
X00111 00111| 122  @z   - Tags macro as being allowed to be called zero times.<010>
X00112 00112| 123  @{   - Open macro body.<010>
X00113 00113| 124  @|   - ILLEGAL.<010>
X00114 00114| 125  @}   - Close macro body.<010>
X00115 00115| 126  @~   - ILLEGAL.<010>
X00116 00116| 127 to 255 are not standard printable ASCII characters.<010>
X00117 00117| <End-Of-File><010>
X-----------+--------------------------------------------------------------------
Globl Local| Text
X
X============================ End of LINE LIST DUMP =============================
X
X
X=========================== Start of TOKEN LIST DUMP ===========================
X
Summary: There are 137 tokens in the token list.
X
Line[Column]: Token Description
X-------------------------------
X
X0001[01]: Text. Text scrap[Grey]="Scanner Test: Special Sequence Recognition<010>
X==========================================<010>
This test tests to see that FunnelWeb is recognising the full set of special<010>
sequences.<010>
X<010>
Turn Off the Parser<010>
X-------------------<010>
XFirst we cause a deliberate scanner error so as to prevent the parser from<010>
generating lots of errors over the syntactic rubbish presented here.<010>
X<010>
X   "
X0011[06]: Text. Text scrap[Grey]="<010>
X<010>
List of All Possible Special Sequences<010>
X--------------------------------------<010>
The following is a list of the default special character followed by each of<010>
the ASCII printables.<010>
X000 to 031 are unprintable control characters.<010>
X<010>
X032  "
X0019[08]: Text. Text scrap[Grey]="   - ILLEGAL.  (Note: Hyphen is needed to avoid trailing blanks error.)<010>
X033  "
X0021[01]: Text. Text scrap[Grey]="034  "
X0021[06]: @" Quote.
X0021[08]: Text. Text scrap[Grey]="   - Parameter delimeter.<010>
X035  "
X0022[06]: @# Name. Character='X'.
X0022[09]: Text. Text scrap[Grey]="  - Short name sequence.<010>
X"
X0023[01]: @$ Macro defn.
X0023[03]: Text. Text scrap[Grey]="   036  - Define macro. Has to be at start of line.<010>
X037  "
X0024[08]: Text. Text scrap[Grey]="   - ILLEGAL.<010>
X038  "
X0025[08]: Text. Text scrap[Grey]="   - ILLEGAL.<010>
X039  "
X0026[08]: Text. Text scrap[Grey]="   - ILLEGAL.<010>
X040  "
X0027[06]: @( Open param.
X0027[08]: Text. Text scrap[Grey]="   - Open parameter list.<010>
X041  "
X0028[06]: @} Close param.
X0028[08]: Text. Text scrap[Grey]="   - Close parameter list.<010>
X042<010>
X"
X0030[03]: Text. Text scrap[Grey]="        - Old fashioned section marker (has to be at start of a line.).<010>
X043  "
X0031[06]: Text. Text scrap[White]="<010>
X"
X0031[08]: Text. Text scrap[Grey]="   - Insert newline.<010>
X044  "
X0032[06]: @, Comma.
X0032[08]: Text. Text scrap[Grey]="   - Parameter separator.<010>
X045  "
X0034[01]: Text. Text scrap[Grey]="          - Ignore end of line marker (has to be at end of line).<010>
X046  "
X0035[08]: Text. Text scrap[Grey]="   - ILLEGAL.<010>
X047  "
X0036[06]: @/ Emphasise.
X0036[08]: Text. Text scrap[Grey]="   - Emphasised text.<010>
X048  "
X0037[08]: Text. Text scrap[Grey]="   - ILLEGAL.<010>
X049  "
X0038[06]: @n Parameter. Parameterno=1.
X0038[08]: Text. Text scrap[Grey]="   - Formal parameter 1.<010>
X050  "
X0039[06]: @n Parameter. Parameterno=2.
X0039[08]: Text. Text scrap[Grey]="   - Formal parameter 2.<010>
X051  "
X0040[06]: @n Parameter. Parameterno=3.
X0040[08]: Text. Text scrap[Grey]="   - Formal parameter 3.<010>
X052  "
X0041[06]: @n Parameter. Parameterno=4.
X0041[08]: Text. Text scrap[Grey]="   - Formal parameter 4.<010>
X053  "
X0042[06]: @n Parameter. Parameterno=5.
X0042[08]: Text. Text scrap[Grey]="   - Formal parameter 5.<010>
X054  "
X0043[06]: @n Parameter. Parameterno=6.
X0043[08]: Text. Text scrap[Grey]="   - Formal parameter 6.<010>
X055  "
X0044[06]: @n Parameter. Parameterno=7.
X0044[08]: Text. Text scrap[Grey]="   - Formal parameter 7.<010>
X056  "
X0045[06]: @n Parameter. Parameterno=8.
X0045[08]: Text. Text scrap[Grey]="   - Formal parameter 8.<010>
X057  "
X0046[06]: @n Parameter. Parameterno=9.
X0046[08]: Text. Text scrap[Grey]="   - Formal parameter 9.<010>
X058  "
X0047[08]: Text. Text scrap[Grey]="   - ILLEGAL.<010>
X059  "
X0048[08]: Text. Text scrap[Grey]="   - ILLEGAL.<010>
X060  "
X0049[06]: @< Open name.
X0049[08]: Text. Text scrap[Grey]="   - Open macro name.<010>
X061  "
X0050[09]: Text. Text scrap[Grey]="  - Set special character.<010>
X062  "
X0051[06]: @> Close name.
X0051[08]: Text. Text scrap[Grey]="   - Close macro name.<010>
X063  "
X0052[08]: Text. Text scrap[Grey]="   - ILLEGAL.<010>
X064  "
X0053[06]: Text. Text scrap[Grey]="@"
X0053[08]: Text. Text scrap[Grey]="   - Insert special character into text.<010>
X"
X0054[01]: @A New section (Level 1).
X0054[03]: Text. Text scrap[Grey]="  065   - New section (level 1). Must be at start of a line.<010>
X"
X0055[01]: @B New section (Level 2).
X0055[03]: Text. Text scrap[Grey]="  066   - New section (level 2). Must be at start of a line.<010>
X"
X0056[01]: @C New section (Level 3).
X0056[03]: Text. Text scrap[Grey]="  067   - New section (level 3). Must be at start of a line.<010>
X"
X0057[01]: @D New section (Level 4).
X0057[03]: Text. Text scrap[Grey]="  068   - New section (level 4). Must be at start of a line.<010>
X"
X0058[01]: @E New section (Level 5).
X0058[03]: Text. Text scrap[Grey]="  069   - New section (level 5). Must be at start of a line.<010>
X070  "
X0059[08]: Text. Text scrap[Grey]="   - ILLEGAL.<010>
X071  "
X0060[08]: Text. Text scrap[Grey]="   - ILLEGAL.<010>
X072  "
X0061[08]: Text. Text scrap[Grey]="   - ILLEGAL.<010>
X073  "
X0063[01]: Text. Text scrap[Grey]="074  "
X0063[08]: Text. Text scrap[Grey]="   - ILLEGAL.<010>
X075  "
X0064[08]: Text. Text scrap[Grey]="   - ILLEGAL.<010>
X076  "
X0065[08]: Text. Text scrap[Grey]="   - ILLEGAL.<010>
X077  "
X0066[06]: @M Many calls.
X0066[08]: Text. Text scrap[Grey]="   - Tags macro as being allowed to be called many times.<010>
X078  "
X0067[08]: Text. Text scrap[Grey]="   - ILLEGAL.<010>
X"
X0068[01]: @F File defn.
X0068[03]: Text. Text scrap[Grey]="   079  - New macro attached to output file. Has to be at start of line.<010>
X080  "
X0070[01]: Text. Text scrap[Grey]="081  "
X0070[08]: Text. Text scrap[Grey]="   - ILLEGAL.<010>
X082  "
X0071[08]: Text. Text scrap[Grey]="   - ILLEGAL.<010>
X083  "
X0072[08]: Text. Text scrap[Grey]="   - ILLEGAL.<010>
X084  "
X0074[01]: Text. Text scrap[Grey]="085  "
X0074[08]: Text. Text scrap[Grey]="   - ILLEGAL.<010>
X086  "
X0075[08]: Text. Text scrap[Grey]="   - ILLEGAL.<010>
X087  "
X0076[08]: Text. Text scrap[Grey]="   - ILLEGAL.<010>
X088  "
X0077[08]: Text. Text scrap[Grey]="   - ILLEGAL.<010>
X089  "
X0078[08]: Text. Text scrap[Grey]="   - ILLEGAL.<010>
X090  "
X0079[06]: @Z Zero calls.
X0079[08]: Text. Text scrap[Grey]="   - Tags macro as being allowed to be called zero times.<010>
X091  "
X0080[08]: Text. Text scrap[Grey]="   - ILLEGAL.<010>
X092  "
X0081[08]: Text. Text scrap[Grey]="   - ILLEGAL.<010>
X093  "
X0082[08]: Text. Text scrap[Grey]="   - ILLEGAL.<010>
X094  "
X0083[06]: Text. Text scrap[Grey]="A"
X0083[14]: Text. Text scrap[Grey]=" - Insert control character into text<010>
X095  "
X0084[08]: Text. Text scrap[Grey]="   - ILLEGAL.<010>
X096  "
X0085[08]: Text. Text scrap[Grey]="   - ILLEGAL.<010>
X"
X0086[01]: @A New section (Level 1).
X0086[03]: Text. Text scrap[Grey]="   097  - New section (level 1). Must be at start of a line.<010>
X"
X0087[01]: @B New section (Level 2).
X0087[03]: Text. Text scrap[Grey]="   098  - New section (level 1). Must be at start of a line.<010>
X"
X0088[01]: @C New section (Level 3).
X0088[03]: Text. Text scrap[Grey]="   099  - New section (level 1). Must be at start of a line.<010>
X"
X0089[01]: @D New section (Level 4).
X0089[03]: Text. Text scrap[Grey]="   100  - New section (level 1). Must be at start of a line.<010>
X"
X0090[01]: @E New section (Level 5).
X0090[03]: Text. Text scrap[Grey]="   101  - New section (level 1). Must be at start of a line.<010>
X102  "
X0091[08]: Text. Text scrap[Grey]="   - ILLEGAL.<010>
X103  "
X0092[08]: Text. Text scrap[Grey]="   - ILLEGAL.<010>
X104  "
X0093[08]: Text. Text scrap[Grey]="   - ILLEGAL.<010>
X105  "
X0095[01]: Text. Text scrap[Grey]="106  "
X0095[08]: Text. Text scrap[Grey]="   - ILLEGAL.<010>
X107  "
X0096[08]: Text. Text scrap[Grey]="   - ILLEGAL.<010>
X108  "
X0097[08]: Text. Text scrap[Grey]="   - ILLEGAL.<010>
X109  "
X0098[06]: @M Many calls.
X0098[08]: Text. Text scrap[Grey]="   - Tags macro as being allowed to be called many times.<010>
X110  "
X0099[08]: Text. Text scrap[Grey]="   - ILLEGAL.<010>
X"
X0100[01]: @F File defn.
X0100[03]: Text. Text scrap[Grey]="   111  - New macro attached to output file. Has to be at start of line.<010>
X112  "
X0102[01]: Text. Text scrap[Grey]="113  "
X0102[08]: Text. Text scrap[Grey]="   - ILLEGAL.<010>
X114  "
X0103[08]: Text. Text scrap[Grey]="   - ILLEGAL.<010>
X115  "
X0104[08]: Text. Text scrap[Grey]="   - ILLEGAL.<010>
X116  "
X0106[01]: Text. Text scrap[Grey]="117  "
X0106[08]: Text. Text scrap[Grey]="   - ILLEGAL.<010>
X118  "
X0107[08]: Text. Text scrap[Grey]="   - ILLEGAL.<010>
X119  "
X0108[08]: Text. Text scrap[Grey]="   - ILLEGAL.<010>
X120  "
X0109[08]: Text. Text scrap[Grey]="   - ILLEGAL.<010>
X121  "
X0110[08]: Text. Text scrap[Grey]="   - ILLEGAL.<010>
X122  "
X0111[06]: @Z Zero calls.
X0111[08]: Text. Text scrap[Grey]="   - Tags macro as being allowed to be called zero times.<010>
X123  "
X0112[06]: @{ Open defn.
X0112[08]: Text. Text scrap[Grey]="   - Open macro body.<010>
X124  "
X0113[08]: Text. Text scrap[Grey]="   - ILLEGAL.<010>
X125  "
X0114[06]: @} Close defn.
X0114[08]: Text. Text scrap[Grey]="   - Close macro body.<010>
X126  "
X0115[08]: Text. Text scrap[Grey]="   - ILLEGAL.<010>
X127 to 255 are not standard printable ASCII characters.<010>
X"
X0117[01]: End Of File.
X============================ End of TOKEN LIST DUMP ============================
X
Macro table dump skipped (Parser was not invoked).
Document list dump skipped (Parser was not invoked).
X
Global Local| Input File
X------------+-------------------------------------------------------------------
X     1     1| Scanner Test: Special Sequence Recognition
X     2     2| ==========================================
X     3     3| This test tests to see that FunnelWeb is recognising the full set of special
X     4     4| sequences.
X     5     5|
X     6     6| Turn Off the Parser
X     7     7| -------------------
X     8     8| First we cause a deliberate scanner error so as to prevent the parser from
X     9     9| generating lots of errors over the syntactic rubbish presented here.
X    10    10|
X    11    11|    @
X       Error|....^<special><space> is not a legal special sequence.
X     Warning|.....^Line has trailing spaces up to and including this space.
X    12    12|
X    13    13| List of All Possible Special Sequences
X    14    14| --------------------------------------
X    15    15| The following is a list of the default special character followed by each of
X    16    16| the ASCII printables.
X    17    17| 000 to 031 are unprintable control characters.
X    18    18|
X    19    19| 032  @    - ILLEGAL.  (Note: Hyphen is needed to avoid trailing blanks error.)
X       Error|......^<special><space> is not a legal special sequence.
X    20    20| 033  @!   - Comment.
X    21    21| 034  @"   - Parameter delimeter.
X    22    22| 035  @#X  - Short name sequence.
X    23    23| @$   036  - Define macro. Has to be at start of line.
X    24    24| 037  @%   - ILLEGAL.
X       Error|......^Unknown special sequence.
X    25    25| 038  @&   - ILLEGAL.
X       Error|......^Unknown special sequence.
X    26    26| 039  @'   - ILLEGAL.
X       Error|......^Unknown special sequence.
X    27    27| 040  @(   - Open parameter list.
X    28    28| 041  @)   - Close parameter list.
X    29    29| 042
X    30    30| @*        - Old fashioned section marker (has to be at start of a line.).
X       Error|.^Unknown special sequence.
X    31    31| 043  @+   - Insert newline.
X    32    32| 044  @,   - Parameter separator.
X    33    33| 045  @-
X    34    34|           - Ignore end of line marker (has to be at end of line).
X    35    35| 046  @.   - ILLEGAL.
X       Error|......^Unknown special sequence.
X    36    36| 047  @/   - Emphasised text.
X    37    37| 048  @0   - ILLEGAL.
X       Error|......^Unknown special sequence.
X    38    38| 049  @1   - Formal parameter 1.
X    39    39| 050  @2   - Formal parameter 2.
X    40    40| 051  @3   - Formal parameter 3.
X    41    41| 052  @4   - Formal parameter 4.
X    42    42| 053  @5   - Formal parameter 5.
X    43    43| 054  @6   - Formal parameter 6.
X    44    44| 055  @7   - Formal parameter 7.
X    45    45| 056  @8   - Formal parameter 8.
X    46    46| 057  @9   - Formal parameter 9.
X    47    47| 058  @:   - ILLEGAL.
X       Error|......^Unknown special sequence.
X    48    48| 059  @;   - ILLEGAL.
X       Error|......^Unknown special sequence.
X    49    49| 060  @<   - Open macro name.
X    50    50| 061  @=@  - Set special character.
X    51    51| 062  @>   - Close macro name.
X    52    52| 063  @?   - ILLEGAL.
X       Error|......^Unknown special sequence.
X    53    53| 064  @@   - Insert special character into text.
X    54    54| @A  065   - New section (level 1). Must be at start of a line.
X    55    55| @B  066   - New section (level 2). Must be at start of a line.
X    56    56| @C  067   - New section (level 3). Must be at start of a line.
X    57    57| @D  068   - New section (level 4). Must be at start of a line.
X    58    58| @E  069   - New section (level 5). Must be at start of a line.
X    59    59| 070  @F   - ILLEGAL.
X       Error|......^Unknown special sequence.
X    60    60| 071  @G   - ILLEGAL.
X       Error|......^Unknown special sequence.
X    61    61| 072  @H   - ILLEGAL.
X       Error|......^Unknown special sequence.
X    62    62| 073  @I   - Include file. Will provoke an error here though.
X       Error|......^Include sequence must be at the beginning of a line.
X            |......^Include ignored.
X    63    63| 074  @J   - ILLEGAL.
X       Error|......^Unknown special sequence.
X    64    64| 075  @K   - ILLEGAL.
X       Error|......^Unknown special sequence.
X    65    65| 076  @L   - ILLEGAL.
X       Error|......^Unknown special sequence.
X    66    66| 077  @M   - Tags macro as being allowed to be called many times.
X    67    67| 078  @N   - ILLEGAL.
X       Error|......^Unknown special sequence.
X    68    68| @O   079  - New macro attached to output file. Has to be at start of line.
X    69    69| 080  @P   - Pragma. Will cause error here though.
X       Error|......^Pragma sequence @p must be at the start of a line.
X            |......^The rest of this line will be ignored.
X       Error|......^Unrecognised pragma. Possible legal pragmas are:
X            |......^   @p indentation = none | blank
X            |......^   @p maximum_input_line_length  = <num>|infinity
X            |......^   @p maximum_output_line_length = <num>|infinity
X            |......^   @p typesetter = none | tex
X            |......^The blanks between arguments are important.
X            |......^Pragma ignored.
X    70    70| 081  @Q   - ILLEGAL.
X       Error|......^Unknown special sequence.
X    71    71| 082  @R   - ILLEGAL.
X       Error|......^Unknown special sequence.
X    72    72| 083  @S   - ILLEGAL.
X       Error|......^Unknown special sequence.
X    73    73| 084  @T   - Typesetter directive. Will cause an error here though.
X       Error|......^Typesetter directive @t must be at the start of a line.
X            |......^The rest of this line will be ignored.
X       Error|......^Unrecognised typesetter directive. Legal ones are:
X            |......^   @t new_page
X            |......^   @t table_of_contents
X            |......^   @t title <font> <align> <string>
X            |......^   @t vskip <num> mm
X            |......^The blanks between arguments are important.
X            |......^Typesetter directive ignored.
X    74    74| 085  @U   - ILLEGAL.
X       Error|......^Unknown special sequence.
X    75    75| 086  @V   - ILLEGAL.
X       Error|......^Unknown special sequence.
X    76    76| 087  @W   - ILLEGAL.
X       Error|......^Unknown special sequence.
X    77    77| 088  @X   - ILLEGAL.
X       Error|......^Unknown special sequence.
X    78    78| 089  @Y   - ILLEGAL.
X       Error|......^Unknown special sequence.
X    79    79| 090  @Z   - Tags macro as being allowed to be called zero times.
X    80    80| 091  @[   - ILLEGAL.
X       Error|......^Unknown special sequence.
X    81    81| 092  @\   - ILLEGAL.
X       Error|......^Unknown special sequence.
X    82    82| 093  @]   - ILLEGAL.
X       Error|......^Unknown special sequence.
X    83    83| 094  @^D(065) - Insert control character into text
X    84    84| 095  @_   - ILLEGAL.
X       Error|......^Unknown special sequence.
X    85    85| 096  @`   - ILLEGAL.
X       Error|......^Unknown special sequence.
X    86    86| @a   097  - New section (level 1). Must be at start of a line.
X    87    87| @b   098  - New section (level 1). Must be at start of a line.
X    88    88| @c   099  - New section (level 1). Must be at start of a line.
X    89    89| @d   100  - New section (level 1). Must be at start of a line.
X    90    90| @e   101  - New section (level 1). Must be at start of a line.
X    91    91| 102  @f   - ILLEGAL.
X       Error|......^Unknown special sequence.
X    92    92| 103  @g   - ILLEGAL.
X       Error|......^Unknown special sequence.
X    93    93| 104  @h   - ILLEGAL.
X       Error|......^Unknown special sequence.
X    94    94| 105  @i   - Include file. Will provoke an error here though.
X       Error|......^Include sequence must be at the beginning of a line.
X            |......^Include ignored.
X    95    95| 106  @j   - ILLEGAL.
X       Error|......^Unknown special sequence.
X    96    96| 107  @k   - ILLEGAL.
X       Error|......^Unknown special sequence.
X    97    97| 108  @l   - ILLEGAL.
X       Error|......^Unknown special sequence.
X    98    98| 109  @m   - Tags macro as being allowed to be called many times.
X    99    99| 110  @n   - ILLEGAL.
X       Error|......^Unknown special sequence.
X   100   100| @O   111  - New macro attached to output file. Has to be at start of line.
X   101   101| 112  @p   - Pragma. Will cause error here though.
X       Error|......^Pragma sequence @p must be at the start of a line.
X            |......^The rest of this line will be ignored.
X       Error|......^Unrecognised pragma. Possible legal pragmas are:
X            |......^   @p indentation = none | blank
X            |......^   @p maximum_input_line_length  = <num>|infinity
X            |......^   @p maximum_output_line_length = <num>|infinity
X            |......^   @p typesetter = none | tex
X            |......^The blanks between arguments are important.
X            |......^Pragma ignored.
X   102   102| 113  @q   - ILLEGAL.
X       Error|......^Unknown special sequence.
X   103   103| 114  @r   - ILLEGAL.
X       Error|......^Unknown special sequence.
X   104   104| 115  @s   - ILLEGAL.
X       Error|......^Unknown special sequence.
X   105   105| 116  @t   - Typesetter directive. Will cause an error here though.
X       Error|......^Typesetter directive @t must be at the start of a line.
X            |......^The rest of this line will be ignored.
X       Error|......^Unrecognised typesetter directive. Legal ones are:
X            |......^   @t new_page
X            |......^   @t table_of_contents
X            |......^   @t title <font> <align> <string>
X            |......^   @t vskip <num> mm
X            |......^The blanks between arguments are important.
X            |......^Typesetter directive ignored.
X   106   106| 117  @u   - ILLEGAL.
X       Error|......^Unknown special sequence.
X   107   107| 118  @v   - ILLEGAL.
X       Error|......^Unknown special sequence.
X   108   108| 119  @w   - ILLEGAL.
X       Error|......^Unknown special sequence.
X   109   109| 120  @x   - ILLEGAL.
X       Error|......^Unknown special sequence.
X   110   110| 121  @y   - ILLEGAL.
X       Error|......^Unknown special sequence.
X   111   111| 122  @z   - Tags macro as being allowed to be called zero times.
X   112   112| 123  @{   - Open macro body.
X   113   113| 124  @|   - ILLEGAL.
X       Error|......^Unknown special sequence.
X   114   114| 125  @}   - Close macro body.
X   115   115| 126  @~   - ILLEGAL.
X       Error|......^Unknown special sequence.
X   116   116| 127 to 255 are not standard printable ASCII characters.
X            | <End-Of-File>
X------------+-------------------------------------------------------------------
X
There were 58 Errors and 1 Warning.
END_OF_FILE
if test 44801 -ne `wc -c <'answers/sc10.lis'`; then
    echo shar: \"'answers/sc10.lis'\" unpacked with wrong size!
fi
# end of 'answers/sc10.lis'
fi
if test -f 'hackman/h_ch1.tex' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'hackman/h_ch1.tex'\"
else
echo shar: Extracting \"'hackman/h_ch1.tex'\" \(40771 characters\)
sed "s/^X//" >'hackman/h_ch1.tex' <<'END_OF_FILE'
X%==============================================================================%
X%                              Start of Ch1.tex                                %
X%==============================================================================%
X%
X% Copyright
X% ---------
X% Copyright (C) 1992 Ross N. Williams.
X% This file contains a chapter of the FunnelWeb Hacker's Manual.
X% See the main TeX file for this manual for further information.
X%
X%==============================================================================%
X
X\chapter{FunnelWeb Design}
X\label{chapdesign}\xx{FunnelWeb}{design}
X
This chapter contains notes on the design of FunnelWeb. These notes were
not created \dq{from scratch}, as the original
version of FunnelWeb (\newterm{FunnelWeb V1}) was designed
and constructed in a hurry late in 1986, and no design notes were ever
recorded.
These notes are in fact the result of a complete review of the
XFunnelWeb design that took place in late 1991 as part
of the process of upgrading it for public release.
X
Throughout the design process I tried to stick to the principles of
simplicity and clarity. As a rule, it was considered more important
that a feature be simple and not allow the user to outsmart himself than it
was for the feature to be particularly crisp. For example, the FunnelWeb
macro calling syntax is not as crisp as the C syntax, but is
more visible.
X
To some extent the design review was influenced by the requirements of
backward compatibility.\xx{backwards}{compatibility}
During the review it was hard not to think about
all the source files in FunnelWeb~V1 format that I have written over the
years that would have to be
converted were I to significantly deviate from the old input language.
Luckily it turned out that there was little clash between these
interests, and the resulting design is both clean and does not require
much conversion of old source files.
The main revision is in the document structuring facility.
XFunnelWeb~V1 had just two levels of heading indicated by \p{@*@*}
X(for major headings) and
X\p{@*} (for minor headings). This scheme (which was copied from Knuth's
Web) has been replaced by a hierarchical scheme of five heading levels
levels (\p{@A}$\ldots$\p{@E}).
X
This chapter is rather unstructured, acting as it has, mainly as a
dumping ground for random ideas about FunnelWeb.
X
X\section{Motivation for FunnelWeb}
X\xx{FunnelWeb}{motivation}
X
During 1986, I was exposed to Donald Knuth's\xn{Donald}{Knuth}
X\p{WEB} literate
programming system in the
form of Jon Bentley's\xn{Jon}{Bentley}
X\i{Programming  Pearls}\x{programming pearls}
column in \i{Communications\x{Communications of the ACM} of
the ACM}\/\paper{Bentley86}.\footnote{As it happens, this was somewhat of a
lucky encounter. I had only just joined the ACM and
the May 1986 issue of CACM in which the column appeared was the first
issue I received.} This  prompted me to obtain  a copy of the
report on the Web system\paper{Knuth83}
and to try out the program which had been installed on the local Vaxen.
X
Web was  the best system that I had seen  for producing printed and
online, inline  documentation. To me
the most  extraordinary aspect of the  system was
its success despite the fact that it had been built into the horribly antiquated
file/batch processing systems that we all know  and love (and use). I had
imagined sophisticated documentation systems before this time, but had always
assumed that they would be parts of complex programming environments.
Knuth showed that, to some extent, it can be done using 1960s
software technology (excluding the 1980s typesetting technology).
This was exciting.
X
The Web  system was  enticing and promising  but to me suffered  from many
drawbacks, many of which Knuth had  promoted as advantages. The following highly
subjective list  of disadvantages formed  a springboard for the  construction of
XFunnelWeb.
X
X\begin{itemize}
X
X\item Web can only process Pascal\x{Pascal} programs.
X
X\item Web can produce only one output file. In many instances it is
desirable to generate  more than one output file. For  example, when programming
in Ada,  it is  desirable to write  a package specification  and a  package body
together in the same file.\xx{number}{output files}
X
X\item  Web  enforces  Knuth's  individual style  of  indentation.  Web  supplies
commands to over-ride  the automatic indentation but it is  an uphill battle and
the code becomes clogged up with format directives.\x{indentation}
X
X\item Web  does not cater for  non-standard Pascal programs. In  particular, all
identifiers are truncated to about eight characters.
X
X\item Web  formats the  program output file  into a form  that is  unreadable to
humans.
X
X\item  Web does  not  provide an include facility.
This  was considered a feature essential for supporting macro libraries.
X
X\item Web provides macros with at most one parameter. Knuth
describes a hack that can
extract a multiple parameter macro facility  from a single parameter one,
but it is hardly satisfactory.
X
X\item Web does not provide conditionals.
X
X\end{itemize}
X
Most  of these  objections boiled  down  to two points:
that Web  is far  too
specialized, and that Knuth's \dq{Occam's Razor}\x{Occam's razor}
had cut too far.
What I wanted was
a documentation system that employed  all the same principles as Web
but was far
more  general. The  result  was FunnelWeb~V1,  which can
process  programs in  any
language or any combination of languages at  the cost of typesetting the text in
X\p{tt font}.
X
Originally, it  was intended that  FunnelWeb would be typesetter  independent as
well as language independent. It was intended that a format file consisting of a
set of productions describing how the document file was to be formatted would be
handed to FunnelWeb along with the input file. In the end, time pressures forced
me to take the back door and hack up a \TeX{} document file generator. This
compromise has found its way into FunnelWeb~V3.0 which is still reliant
on \TeX{}, although V3.0 at least encourages input files to be typesetter
independent. It is hoped that future versions of FunnelWeb will include
more sophisticated typesetting facilities.
X
X\section{Indentation}
X\x{indentation}\xx{indentation}{no}%
X\xx{indentation}{blank}\xx{indentation}{text}
X
A macro call that does not appear at the left margin is called an
X\newterm{indented macro call} and seems to lead to three different
alternatives for its expansion: \newterm{no indentation}, \newterm{blank
indentation}, and \newterm{text indentation}. Here are examples of each kind
of indentation. First the example problem.
X
X\begin{verbatim}
X@$@<Sloth@>==@{@-
Aardvark
Walrus@}
X
X@O@<Output@>==@{@-
Zebra@<Sloth@>
Giraffe
X@}
X\end{verbatim}
X
There are three ways that the second line of the \p{Sloth} macro
can be indented.
X
X\thing{No indentation:}
X\begin{verbatim}
X     ZebraAardvark
X     Walrus
X     Giraffe
X\end{verbatim}
X
X\thing{Blank indentation:}
X\begin{verbatim}
X     ZebraAardvark
X          Walrus
X     Giraffe
X\end{verbatim}
X
X\thing{Text indentation:}
X\begin{verbatim}
X     ZebraAardvark
X     ZebraWalrus
X     Giraffe
X\end{verbatim}
X
No indentation is useful where the user wishes to deal with the output
stream as a pure output stream. Blank indentation is useful when the user
wishes to generate indented computer programs.
Text indentation is useful where the user wishes to prefix each line of an
entire macro invocation with a string. This can be useful for
commenting out code (\eg{}in Ada using \p{--}), and for prepending things
like a dollar sign at the start of each line an a VAX VMS DCL script
command file.\x{DCL}
X
XFunnelWeb~V1 provided a choice of no indentation or blank indentation.
The choice was made in the command line and could not be overridden.
X
The design questions are as follows:
X
X\begin{enumerate}
X\item Which of the three kinds of indentation should FunnelWeb support?
X\item What should be the granularity of swapping between indentation modes?
X\item Are particular indentation modes dangerous?
X\item Is the presence of particular combinations of indentation modes
X      confusing to the user?
X\item How and when should the choice of indentation be specified?
X\end{enumerate}
X
All sorts of schemes were considered, including a finely grained system in
which the user could specify at the point of call which indentation mode
should be used for the called macro expansion.
X
After a lot of thought, the dominant factor that should affect the design
was decided to be the \i{clarity} in the user's mind of the indentation facility
and the \i{danger} associated with misunderstanding it. Here are two
examples that show how easily a confusion or
misunderstanding of the indenting being used can cause danger.
The first example shows how blank or no indentation might be
misused.
X
X\begin{verbatim}
X--Misuse of blank (and no) indentation.
X--@<Sloth@>
X\end{verbatim}
X
Here the user has assumed that text indentation is in action and has
placed an Ada comment symbol \dqp{--} before the invocation of the macro
X\p{@<Sloth@>} in the hope that the entire text of the macro would be prefixed by
X\dqp{--}. The result could be passed by the compiler which would activate all
but the first statement in the expansion of macro \p{@<Sloth@>}.
X
The next example demonstrates how text indentation could be
misused.\xx{indentation}{dangers}
X
X\begin{verbatim}
X--Misuse of text indentation:
a++; @<Sloth@>
X\end{verbatim}
X
Here the user has placed the call to \p{@<Sloth@>} after the incrementing of
variable
X\p{a}. The result is that there is a good chance that the \dqp{a++;}
prepended to
each line of the expansion of \p{@<Sloth@>} will be passed by the compiler and
will cause \p{a} to be overincremented.
X
These examples are not to be laughed at. It is possible that FunnelWeb will
be used widely, and the problems above may cause problems in critical systems.
The examples above are particularly scary because they are reflexive. One cannot
simply pin the blame on one particular indentation form. A little thought
reveals that the greatest danger lies in \i{confusion} in the user's mind.
If the
user is confused between text or blank indenting, problems will arise.
X
There seem to be two ways to solve the problem. The first is to ban all
macro calls that are preceded by non-blank text. This is not a good option
because there are so many cases where it is desirable to expand more than one
single line macros on the same line. A second option is to eliminate one of
the two forms so as to reduce the potential for ambiguity in the user's
mind. I choose the latter option. Of the two forms, the clear choice for
elimination is text indenting for the following reasons:
X
X\begin{enumerate}
X\item It actually introduces extra text which gives it an a priori
X      potential for problems.
X\item It is harder to implement and would slow down Tangle.
X\item It would not be compatible with FunnelWeb~V1 which uses blank
X      indentation.
X\end{enumerate}
X
The only other decision is the level of granularity of choice between the
remaining options: no indentation and blank indentation. FunnelWeb~V1
allowed this choice to be made in the command line. In retrospect, this
was bad design because the user might unwittingly code certain macro calls
relying on one or the other mode. A better system is to allow the user
to specify which mode in the input file itself. This has been done in
XFunnelWeb~V3.
X
Again, to avoid confusion, it seems sensible to allow the user only
one indentation mode per FunnelWeb input file. In most cases, the user
will be happy with blank indentation (the default) and there will be
no need for change anyway.
X
X\thing{Decision:} Implement only \dq{no indentation} and \dq{blank indentation}.
Make the
choice of indentation a static attribute of a particular FunnelWeb run
that is specified in the input file. This solution is the same as FunnelWeb~V1
except that the choice has been moved from the command line to the
input file.
X
X\section{Review of FunnelWeb Syntax}
X\xx{FunnelWeb}{syntax}
X
One of the distressing aspects of FunnelWeb~V1 was its clumsy macro
definition and calling syntax.
Compared to (say) the C preprocessor, FunnelWeb's macro call syntax is
like a freight train in a china show.
During the FunnelWeb redesign, a complete review of this syntax took place to
try to neaten it up. Surprisingly, the V1 syntax survived unscathed
with the exception that \dqp{==}\x{==} in macro definitions was made optional.
The survival of this clumsy syntax was a product of the design goal of
making everything simple, explicit, and not subject to subtle errors.
X
X\subsection{Review of Macro Definition Syntax}
X\xx{macro definition}{syntax}
X
XFunnelWeb~V1 used a macro definition syntax that resulted in macro
definitions such as the following.
X
X\begin{verbatim}
X@$@<Put out the cat@>==@{@-
Open the door
Say out
Close the door@}
X\end{verbatim}
X
This is messy, but I couldn't think of anything better at the time.
The \p{@\$} is necessary to cue a definition. Without it, the definition
might somehow be mistaken for an invocation.
The \p{@<} and \p{@>} delimit the name.
The \p{@$\{$} and \p{@$\}$} delimit the text.
The \p{@-} is a product of the rule
X\dq{exactly the text between the \p{@$\{$} and \p{@$\}$}}.
X
The only real target is the \dqp{+=} and \dqp{==} which really break all
the rules
and should be changed. Unfortunately I couldn't
think of anything to change them
to. If there was no \p{+=} mechanism, we could use:
X
X\begin{verbatim}
X@$@<Put out the cat@>@{
Open the door
Say out
Close the door@}
X\end{verbatim}
X
In fact, eliminating \p{+=} is thinkable because it does not appear in
many of my existing FunnelWeb source files. This indicates at least that
it was not needed much by myself.
X
A minimalist construct could be
X
X\begin{verbatim}
X@<Put out the cat@>
Open the door
Say out
Close the door@}
X\end{verbatim}
X
but this is too dangerous for my tastes.
X
X\thing{Decision:} For compatibility reasons,
retain the old \p{+=} and \p{==} constructs, but make them optional.
The new syntax for defining macros is:
X
X\begin{verbatim}
X@$@<Put out the cat@>@{
Open the door
Say out
Close the door@}
X\end{verbatim}
X
Next we turn to parameterized macro
definitions.\xx{parameterized macro definitions}{syntax}
A conventional FunnelWeb parameterized macro definition looks like this:
X
X\begin{verbatim}
X@$@<Put out the cat@>@(@3@)==@{@-
Open the door
Say out
Close the door@}
X\end{verbatim}
X
which is a bit messy. The natural alternative is even worse:
X
X\begin{verbatim}
X@$@<Put out the cat@>@(@1@,@2@,@3@)==@{@-
Open the door
Say out
Close the door@}
X\end{verbatim}
X
Thus, just specifying the number of parameters seems sensible. However,
perhaps the syntax could be trimmed to
X
X\begin{verbatim}
X@$@<Put out the cat@>@3==@{@-
Open the door
Say out
Close the door@}
X\end{verbatim}
X
I decided to reject this in favour of the old syntax.
X
X\thing{Decision:} Retain the old syntax of $\ldots$\p{@(@3@)}$\ldots$
X
X\subsection{Review of Macro Call Syntax}
X\xx{macro call}{syntax}
X
Here are some ideas for alternatives to the FunnelWeb~V1 macro call syntax.
X
X\begin{verbatim}
Open the door
X@<Say Out@>         @! FunnelWeb~V1 style.
Close the door
X
Open the door
X@<Say out>@
Close the door
X
Open the door
X@"Say out@"
Close the door
X
Open the door
X@(Say out@)
Close the door
X
Open the door
X@<Say out>
Close the door
X\end{verbatim}
X
X\thing{Decision:} Continue with the old notation. It may not be neat, but at
least it is clear and consistent. The main temptation is the format
X\p{@<say out>@}
which looks rather good. However, it breaks the special sequence
rational and hence is too confusing.
X
X\subsection{Review of Parameterized Macro Call Syntax}
X\xx{parameterized macro call}{syntax}
X
XFunnelWeb~V1 provided a messy parameterized macro call syntax:
X
X\begin{verbatim}
X@<Say Out@>@(@"firstparam@" @, @"Secondparam@" @, @"thirdparam@" @)
X\end{verbatim}
X
This syntax can be cleaned up considerably by making the \p{@"} symbols
optional. This results in calls such as the following:
X
X\begin{verbatim}
X@<Say Out@>@(firstparam@,Secondparam@,thirdparam@)
X\end{verbatim}
X
As the first form allows the alignment of complicated parameters by
allowing white space to be inserted outside the \p{@"}, and the second
form is cleaner, both are retained simply by making the quotes optional.
X
X\thing{Decision:} Make the double quotes optional.
X
X\section{Document Structuring}
X\xx{document}{structure}\x{headings}\x{sections}
X
XExperience with FunnelWeb~V1, which provided only two levels of
headings (major and minor)
proved that there was a strong need for fully hierarchical
multiple-level headings.
The only question was how it should be done.
X
Here are some ideas that were considered.
X
X\begin{verbatim}
X@*@<Main Program@>
X@**@<Read the Message@>
X@***@<Encrypt the Buffer@>
X
X@*@<Main Program@>
X@*@*@<Read the Message@>
X@*@*@*@<Encrypt the Buffer@>
X
X@s@<Main Program@>
X@ss@<Read the Message@>
X@sss@<Encrypt the Buffer@>
X
X@s@<Main Program@>
X@s@s@<Read the Message@>
X@s@s@s@<Encrypt the Buffer@>
X
X@S@<Main Program@>
X@SS@<Read the Message@>
X@SSS@<Encrypt the Buffer@>
X
X@S@<Main Program@>
X@S@S@<Read the Message@>
X@S@S@S@<Encrypt the Buffer@>
X
X@A@<Main Program@>           -- The syntax finally chosen.
X@B@<Read the Message@>
X@C@<Encrypt the Buffer@>
X
X@A Main Program
X@B Read the Message
X@C Encrypt the Buffer
X
X@*A Main Program
X@*B Read the Message
X@*C Encrypt the Buffer
X
X@1@<Main Program@>
X@2@<Read the Message@>
X@3@<Encrypt the Buffer@>
X(using @A..@I@ as macro parameters or overload @1..@9)
X
X@*@1@<Main Program@>
X@*@2@<Read the Message@>
X@*@3@<Encrypt the Buffer@>
X(using @A..@I@ as macro parameters or overload @1..@9)
X\end{verbatim}
X
Choosing between these alternatives was not easy. The following thoughts
contributed to the decision.
X
X\begin{itemize}
X
X\item Syntaxes that require visual counting are probably not a good idea.
X
X\item Syntaxes that do not delimit the heading name somehow are likely
to cause problems where heading names are omitted. Users will be
tempted to start paragraphs after the start of heading symbol and the
result is that the first line of the paragraph will be sucked into the
heading.
X
X\item Overloading the \p{@1}, $\ldots$, \p{@9} sequences is undesirable.
X
X
X\end{itemize}
X
X\thing{Decision:} Use \p{@A}$\ldots$\p{@E} with optional following
macro name syntax for the section name.
Note: We stop at \p{@E} because five levels is probably sufficient, and we
may wish later to use \p{@F} for \b{F}ile (to augment or replace \p{@O}).
X
X
X\section{Discussion of Some Miscellaneous Issues}
X\xx{miscellaneous}{issues}
X
X\thing{Comment duplication:} If\xx{comment}{duplication}
the FunnelWeb user inserts
comments into the target code (in the \p{.fw} file) as well as into the
documentation (free text)
part of the \p{.fw} file, then it is possible for the
situation to get a bit silly. \b{Decision:} This is a problem for the
programmer, not for FunnelWeb.
X
X\thing{Out-of-date documentation:} Sometimes\xx{out of date}{documentation}
it is all too easy for the
programmer to modify the code without updating the surrounding documentation.
X\b{Decision:} This is a serious and major problem. In an automated environment,
it may be possible to create a system of dependencies between scraps of
code and scraps of documentation. However, it is hard to see how a tool
such as FunnelWeb could provide support for prevention of this sort of error.
X
X\thing{Meta-macro-level parameterization:} Sometimes, when using FunnelWeb,
the facility to use one macro to construct the name of another has been
needed. \b{Decision:} Allowing macro names
to be constructed would lose the simple
nature of the preprocessor and so this suggestion is rejected.
X
X\thing{Clumsy notation:} The \p{@} notation can be clumsy.
X\b{Decision:} This is necessary to maintain the simplicity of the translation.
X
X\section{Automated Regression Testing}
X\xx{regression}{testing}
X
Automated regression testing is extremely important for two reasons:
X
X\begin{enumerate}
X
X\item It provides confidence that changes made to the program have
not introduced bugs.
X
X\item It allows portability problems to be pinpointed when the program is
moved to a new machine.
X
X\end{enumerate}
X
The simplest way to set up automated regression testing is to construct
a suite of test cases (and their solutions) and then write a
script in the target machine's command language to run through the suite.
Unfortunately, there is no command language that is shared among the
machines to which FunnelWeb must be ported. These machines are at least:
Macintosh, IBM-PC, Sun, VMS Vax.
X
One option is simply to rewrite the script in each machine's particular
command language. This would be a feasible option were it not for the fact
that the Macintosh (the machine upon which FunnelWeb was developed) does
not have a command language!
X
After some thought, I decided that the best solution to the problem was
to create a command language \i{within FunnelWeb}. FunnelWeb could then
be invoked in two modes, one-shot command line or interactive/script. This
approach had the benefit of providing total control over the command
language and its complete portability.
X
The result is described in the \i{FunnelWeb User's Manual}.
X
X\section{Command Line Interface}
X\xx{command line}{interface}
X
XFunnelWeb~V1 was implemented in Ada\x{Ada} and runs on a VMS VAX.\xx{vms}{vax}
As such it
has a full VMS DCL command line interface. Here is the \dqp{.CLD}
file\xx{.cld}{file} for the
DCL command line interface.
X
X\beginsmall
X\begin{verbatim}
X! FUNNELWEB Command Definition
X! ============================
X! Ross Williams. 28 April 1987.
X
module command_table
X   define verb dummy_command
X   parameter p1           , label=input_file   ,value(required,type=$file)
X   qualifier include_files, label=include_files,value(type=$file) ,default
X   qualifier output_files , label=output_files ,value(type=$file) ,default
X   qualifier delete       , label=delete                          ,default
X   qualifier tex_file     , label=tex_file     ,value(type=$file) ,default
X   qualifier listing_file , label=listing_file ,value(type=$file) ,default
X   qualifier brief        , label=brief,value(type=$number,default=5),default
X   qualifier screen       , label=screen       ,value(type=$number,default=0)
X   qualifier trace        , label=trace
X   qualifier file_spec    , label=file_spec
X   qualifier compare
X\end{verbatim}
X\endsmall
X
As portability was a key goal of FunnelWeb~V3, it was obvious that the
command line interface would have to be redesigned. The design goals for the
new command line interface were:\xx{design goals}{command line interface}
X
X\begin{enumerate}
X
X\item The interface should not \i{depend} on case. However, it must allow
X      case-sensitive filenames to be transmitted on systems that have
X      case-sensitive filenames.
X
X\item Each option must have a symmetric positive and negative form. For
X      example, it is confusing for \p{-X} to turn on a feature and \p{-Q}
X      to turn it off.
X
X\item The interface must be extensible to allow inclusion of more features
X      at a later date.
X
X\item Options should be consistent and memorable.
X
X\end{enumerate}
X
The result is described in the \i{FunnelWeb User's Manual}.
X
X\section{File Name Management}
X\xx{file}{names}
X
XFile names present a host of problems for a program like FunnelWeb.
XFirst, FunnelWeb can generate so many different kinds of files that
conventions must be adopted to prevent them from becoming unmanageable.
Second, the constraints on file names, and even the structure of file
names themselves varies considerably from machine to machine. These two
problems have combined to result in the sophisticated and
rather complicated way in which FunnelWeb~V3 handles filenames.
X
To summarize, the three problems are:
X
X\begin{enumerate}
X\item What filename extensions should be chosen for various kinds of file?
X\item What filename inheritance should take place?
X\item How should FunnelWeb cope with the variations in filename structure
between machines?
X\end{enumerate}
X
The following three sections address these questions.
X
X\subsection{Filename Extensions}
X\xx{filename}{extensions}
X
XFunnelWeb is capable of reading and writing a variety of different kinds
of files. In particular, FunnelWeb must often operates in an environment where
the same information is stored in many forms (\eg{}prog.fw, prog.c, proc.exe).
XFile extensions are an essential tool in managing this situation.
The filename extensions chosen for FunnelWeb are:
X
X\begin{verbatim}
XFunnelWeb     : .fw
Product       : None.
Documentation : .tex
Listing       : .lis
Journal       : .jrn
X\end{verbatim}
X
Lowercase will be used in systems that are case sensitive.
X
Readers who are wondering how FunnelWeb copes in environments such as UNIX
where there are no file extensions should refer to
Section~\ref{portablefilenames}.
X
X\subsection{Filename Inheritance}
X\xx{filename}{inheritance}
X
Inheritance in filenames refers to how input and output files inherit parts
of their name from other filenames and their environment. For example if
the command
X
X\begin{verbatim}
X   fw sloth +J +L +T
X\end{verbatim}
X
was issued,
you would expect to see output files \p{sloth.jrn}, \p{sloth.lis}, and
X\p{sloth.tex}.
The output file names have inherited the \dqp{sloth}. The following table
gives the hierarchy devised for FunnelWeb.
X
X\begin{center}
X\begin{tabular}{|l|l|l|l|l|l|l|l|}                                             \hline
X  & Script     & Input     &  Include   &  Journal   &  List      &  Document  & Product \\ \hline
X1 &            &           & \p{@i}     &            &            &            & \p{@o}  \\
X2 & \p{+x}     & \p{+f}    & \p{+i}     & \p{+j}     & \p{+l}     & \p{+t}     & \p{+o}  \\
X3 & \dqp{.fws} & \dqp{.fw} & \dqp{.fwi} & \dqp{.jrn} & \dqp{.lis} & \dqp{.tex} &         \\
X4 &            &           & \p{+f}     & \p{+f}     & \p{+f}     & \p{+f}     &         \\
X5 & DefDir     & Defdir    & Defdir     & Defdir     & Defdir     & Defdir     & Defdir  \\ \hline
X\end{tabular}
X\end{center}
X
The following notes explain the table.
X
X\begin{enumerate}
X
X\item This scheme is similar to that used in FunnelWeb~V1.
X
X\item The journal, list, and documentation
files all fall in the same pattern and
can be considered as a single case.
X
X\item Level~1 has the highest priority because it is a direct specification
by the user in the input file.
X
X\item Level~2 comes next because this is also a direct specification
from the user on the command line.
X
X\item Level~3 provides the default file extensions.
Product files do not inherit an
extension as they could be of any type.
X
X\item Level~5 is built into most operating systems' file specification systems.
If I specify file \dqp{x.y}, it is taken to mean on the default disk in the
default directory.
X
X\item Level~4 looks straightforward, but secretly conceals a difficult design
decision. By the time we get down to this level of inheritance, we know for
sure that the filename has already picked up a file extension. So all that
is left to inherit is the path and the filename proper. Obviously we
have to inherit the filename proper (e.g. \p{sloth} in \p{sloth.tex}), but
should we inherit the input file path? If we do inherit the input file
path, files will be placed in the same directory as the input file. If we
don't inherit the input file path, files will be placed in the current
directory. The choice I have made is to send all the logging type files
into the same directory as the input file. This means, for example,
that \p{sloth.lis} and \p{sloth.tex} will generally land in the same directory
as \p{sloth.fw}. However, I have decided that output files should be sent to
the default directory (if not earlier specified) as this is where the
action is. In normal use, the main product of FunnelWeb will be product files
and so the user will expect them to appear in the current directory by
default.
X
X\end{enumerate}
X
X\subsection{Portable Structure of File Names}
X\label{portablefilenames}\xx{file}{names}\xx{portable}{filenames}
X
Another problem with file names is the variation of their structure
between environments. Here are examples of some of the formats that prevail:
X
X\begin{verbatim}
X   UNIX   /device/dir1/dir2/name
X   VMS    node::device:[dir1.dir2]name.ext;vn
X   MSDOS  device:\dir1\dir2\name.ext
X   MAC    device:dir1:dir2:name
X\end{verbatim}
X
Isn't it amazing that none of these popular systems use the same format?
X
The solution to dealing with these different formats is to classify them
as non-portable and hide the functions that manipulate them
in the machine-specific module of FunnelWeb.
Luckily there are not many such functions.
X
The main problem is coping with
file systems that do not
explicitly support file extensions.
With so many possible input and output files, FunnelWeb all but
needs such extensions. Machines that do not support them pose difficult
design decisions.
If the user specifies \dqp{sloth} as an input file on such
a non-extension-supporting system,
should FunnelWeb look for \p{sloth}
or \p{sloth.fw}? If the user specifies \p{walrus} as a listing file, should
it generate \p{walrus} or \p{walrus.lis}?
X
Some possible solutions are:
X
X\begin{enumerate}
X
X\item Regard the filename \p{sloth} as having an empty extension. It will then
default to \p{sloth.fw}.
X
X\item Regard the filename \p{sloth} as having a blank but full extension.
That is, it cannot be overwritten by inheritance, but it remains blank.
X
X\item Provide an extra syntactic mechanism to allow the user to specify one or
other of the two options above.
X
X\end{enumerate}
X
My solution was to choose the first option. Use of FunnelWeb
results in lots of files lying around (\eg{}\p{sloth.lis}) and it is hard
to see how
the user will cope with them all
without some kind of naming discipline. If a naming discipline
has to be used, it might as well be the FunnelWeb one.
X
Thus the names of all files read and written by FunnelWeb will have a file
extension of from zero to three letters separated from the rest of the filename
by a \dqp{.}.
X
The only exception is product files whose extension is left
undefined. Product files need not
contain a \dqp{.} and a file extension,
although they can inherit one if the user wishes.
X
X\section{Specifying Constraints on the Number of Instantiations}
X\xx{invocations}{number}
X
XExperience with FunnelWeb~V1 demonstrated
the need to be able to specify in
macro definitions how many times it was expected that the macro would
be used. FunnelWeb~V1 generates an error if a macro is not used, but
permits macros to be called more than once. This caused problems for macro
libraries, which would be included, but whose macros were often not called.
X
By default, FunnelWeb~V3 requires that each macro (except for the ones
attached to output files) be called exactly once.
However, it also provides
syntax that allows the user to specify that a macro be allowed
to be called zero times or many times.
This allows a macro to be specified with the following permissible ranges
of numbers of calls depending on the presence or absence of \dqp{@Z} and
X\dqp{@M}:
X
X\begin{verbatim}
X   0..1          @$@<Sloth@>@Z==...
X      1          @$@<Sloth@>==...
X      1..n       @$@<Sloth@>@M==...
X   0.....n       @$@<Sloth@>@Z@M==...
X\end{verbatim}
X
The only two problems with this scheme are:
X
X\begin{enumerate}
X
X\item It is incompatible with
XFunnelWeb~V1 files, as the default in FunnelWeb~V1 is $1 \ldots n$
whereas the default in new FunnelWeb is $1$. This is not a big problem because
most macros in the old files were used exactly once. Only a few macros will
have to be changed.
X
X\item What should the syntax be? (above is a sneak preview only!)
X
X\end{enumerate}
X
The initial proposal for syntax was to allow the user to insert zero, one,
or both of \p{@?} and \p{@M} just after the \p{@\$} of a macro definition.
However, this has the following drawbacks:
X
X\begin{enumerate}
X
X\item It uses two sequences that are desirable to reserve
X      (\p{@?} for conditionals and \p{@M} for macro).
X
X\item It stops the user from searching for the string \p{@\$@<name} to find
X      the definition of a macro.
X
X\end{enumerate}
X
These are significant problems.
Here are some alternative
ideas for where to position the modifiers in the macro definition:
X
X\begin{verbatim}
X@?@M@$@<Slothy dogs@>@(@5@)==@{@-
This is a short macro.
With only a line or two@}
X
X@$@<Slothy dogs@>@?@M@(@5@)==@{@-
This is a short macro.
With only a line or two@}
X
X@$@<Slothy dogs@>@(@5@)@?@M==@{@-
This is a short macro.
With only a line or two@
X\end{verbatim}
X
The first form puts me off because I think that it is a good visual rule
to start all the macros with \p{@\$}. The second form puts me off because it
detaches the macro name from the parameter list, thus making it look
less like a call, which is desirable syntactic resonance. The third form
is messy but probably workable. Because we are right next to the tested
constant string (either \p{==} or \p{+=}) we could augment it further. For
example, \p{01==} could allow a macro to be called from 0 to 1 times.
The main problem with this is that we are trying to phase out \p{==} anyway!
X
Nevertheless, all the logic points to after the parameter list as the best
place to locate this information.
X
After some thought, it was decided that the \dqp{@?} sequence be reserved
for a possible future conditional facility, and so \p{@Z} was used
instead.
X
X\thing{Decision:} The position is after the parameter list. The notation
is \p{@Z} for zero, and \p{@M} for many.\x{@Z}\x{@M}
X
XExample of final syntax:
X
X\begin{verbatim}
X@$@<Slothy dogs@>@(@5@)@Z@M+=@{@-
This is a short macro.
With only a line or two@}
X\end{verbatim}
X
X\section{The Relationship Between Document Structure and Macro Structure}
X\xx{document structure}{macro structure}%
X\xx{document}{structure}\xx{macro}{structure}\note{01-Dec-1991}%
X\xx{hierarchical}{structure}
X
Having already decided upon a fully hierarchical document
structure, I determined to refine the details.
The issues to be addressed were as follows:
X
X\begin{itemize}
X
X\item How should the hierarchical structure connect to the macro structure?
X\item How can backwards compatibility be achieved? Should it?
X\item Should the macros be cross referenced by section or by definition?
X\item Should nameless sections inherit macro names as headings?
X\item Should we simply use \TeX{} macros to structure the document?
X
X\end{itemize}
X
After some thought, I arrived at the following thoughts:
X
X\thing{Basically a \TeX{} file:} One option is simply
to treat each \p{.fw} file as a \TeX{}\x{TeX} file
laced with macros. That is, a \p{.fw} file could be
structured as a real \TeX{} file from which FunnelWeb could
extract macro definitions. This approach is feasible because
X\TeX{} could be programmed to
respond to the \p{@} sequences in the same way that
XFunnelWeb responds to them. Thus, there would be no need for Weave.
X
I rejected this approach, first because it is too typesetter-dependent,
and second because it complicates the inclusion of any sort of
complicated post-processing in the documentation file. This would have to
be implemented in \TeX{}.
X
A better approach is
to use an invented section notation (e.g. \p{@A @B @C}). This maintains
XFunnelWeb's typesetter independence and can easily be
converted into \TeX{} sectioning macros by Weave.
X
In the same spirit, it might be worth introducing a few \p{@} sequences for
certain general typesetting operations such as italics and program code.
X
X\thing{Confusion in FunnelWeb~V1 Heading Numbering:} FunnelWeb~V1
uses two levels of section headings, but numbers all
the headings sequentially. In this, it is a little confused. Clearly
with a fully hierarchical document structure, the headings cannot be
numbered sequentially --- the numbering must reflect the structure
X(\eg{}3.2.1).
X
X\thing{Hierarchical numbering is messy for macros:} Unfortunately,
hierarchical numbering\xx{section}{numbering} is messy
and confusing when applied to macro names.
In FunnelWeb~V1's typeset output, each macro
call has appended in square brackets the number of the section in which the
macro is defined. Use of hierarchical numbering would be somewhat messy.
XFor example, a macro call might look like.
X
X\begin{verbatim}
X   Write out the output[6.7.4.3]
X\end{verbatim}
X
Similarly, cross reference lists would be messy:
X
X\begin{verbatim}
X   This macro is used in 3.4.5, 1.2, 7.8.9, 7.4, 2.2.1.1.
X\end{verbatim}
X
X\thing{Separate numbering for macros and headings:} One
idea is to use hierarchical numbering for the sections, but to
number the macros sequentially. This could be a little confusing in
documents without much structure, but would be very much less messy than
cross referencing using hierarchical numbering.
Also, it will be easier to find macros
indexed by a sequential number than by section,
which has a less direct relationship
with page bulk and number. By macro numbering is meant the sequential
numbering of each macro body part through the whole document.
X
X\thing{Input format matters more than output format:} At this point we
realize that a distinction should be made between
the \i{input format} and the \i{typeset output}.
The critical issue here is not how the
program should be formatted for printing, but rather the format of its
X\p{.fw} file. The typeset output can always be changed simply by fiddling
with Weave. However, as soon as the document structuring features of FunnelWeb
are fixed, they will be used in dozens or hundreds of documents and it will
be very difficult indeed to change them. Therefore, the important thing is to
provide as sensible and expressive a \p{.fw} format as possible.
X
It is therefore a separate decision as to whether we should number macros
by section or by sequence number. The important thing is to address the
format and rules for the expression of structure.
X
X\thing{Naming sections:} The naming
of sections requires some thought. In many cases (especially
in the case of high-level sections) the writer will provide an explicit
name for a section. In other cases, provision of such a name will merely
duplicate the name of the macro contained within the section. It therefore
makes sense to allow the user to omit the name from a section, with Weave
naming the section after the first macro definition in the section. If a
macro is unnamed and there
is no macro in the section, an error can be generated.
X
All these thoughts lead to the following scheme:
X
X\begin{itemize}
X\item Documents will be hierarchically structured using \p{@A}, \p{@B} etc.
X\item Each section can be given a name delimited by \p{@<@>}.
X\item Sections that do not have names inherit the name of their first macro.
X\item If a section does not have a name or a macro, it is erroneous.
X\item Sections will be numbered hierarchically either by FunnelWeb or by \TeX{}.
X\item Macro body parts will be numbered sequentially by FunnelWeb and cross
X  referenced by these numbers.
X\end{itemize}
X
All this results in a system which:
X
X\begin{itemize}
X
X\item Provides a hierarchical document structuring capability.
X\item Is typesetter independent.
X\item Does not require duplication between heading and macro names.
X\item Separates the heading and macro systems so that Weave can be configured
X  at a later date to cross reference in different ways without requiring
X  input files to be reworked.
X\end{itemize}
X
X\section{Diagnostic Messages}
X\xx{diagnostic}{messages}
X
In FunnelWeb, all error messages commence with an indicator indicating
the severity of the error message. Here are some of the formats that
I investigated before settling on the final format:
X
X\begin{verbatim}
W--Error creating sloth.
XE--Error opening output file.
S--I'm a teapot.
XF--Can't open output file.
X
W-Error creating sloth.
XE-Error opening output file.
S-I'm a teapot.
XF-Can't open output file.
X
W:Error creating sloth.
XE:Error opening output file.
S:I'm a teapot.
XF:Can't open output file.
X
W: Error creating sloth.       -- Format chosen.
XE: Error opening output file.
S: I'm a teapot.
XF: Can't open output file.
X
War-Error creating sloth.
XErr-Error opening output file.
Sev-I'm a teapot.
XFat-Can't open output file.
X
W-Old fashioned feature.
X
W-Old fashioned feature.
X
W--Old fashioned feature.
X
W: Old fashioned feature.
X
W:Old fashioned feature.
X\end{verbatim}
X
X\section{Summary}
X
This rather unstructured chapter has addressed some of the key design
decisions of FunnelWeb. In many cases, the alternatives have been
unpleasant, but I am confident that in all cases, a fully workable solution
has been found.
X
X%==============================================================================%
X%                              Start of Ch1.tex                                %
X%==============================================================================%
END_OF_FILE
if test 40771 -ne `wc -c <'hackman/h_ch1.tex'`; then
    echo shar: \"'hackman/h_ch1.tex'\" unpacked with wrong size!
fi
# end of 'hackman/h_ch1.tex'
fi
if test -f 'userman/u_manual.idx' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'userman/u_manual.idx'\"
else
echo shar: Extracting \"'userman/u_manual.idx'\" \(33582 characters\)
sed "s/^X//" >'userman/u_manual.idx' <<'END_OF_FILE'
X\indexentry{Ross Williams}{1}
X\indexentry{Williams Ross}{1}
X\indexentry{copyright notice}{1}
X\indexentry{notice copyright}{1}
X\indexentry{preface}{9}
X\indexentry{Donald Knuth}{9}
X\indexentry{Knuth Donald}{9}
X\indexentry{Knuth83}{9}
X\indexentry{Web}{9}
X\indexentry{GNU license}{9}
X\indexentry{license GNU}{9}
X\indexentry{acknowledgements}{11}
X\indexentry{David Hulse}{11}
X\indexentry{Hulse David}{11}
X\indexentry{Ada}{11}
X\indexentry{Simon Hackett}{11}
X\indexentry{Hackett Simon}{11}
X\indexentry{Jeremy Begg}{11}
X\indexentry{Begg Jeremy}{11}
X\indexentry{Barry Dwyer}{11}
X\indexentry{Dwyer Barry}{11}
X\indexentry{Roger Brissenden}{11}
X\indexentry{Brissenden Roger}{11}
X\indexentry{Donald Knuth}{11}
X\indexentry{Knuth Donald}{11}
X\indexentry{presentation notes}{13}
X\indexentry{typesetting}{13}
X\indexentry{Andrew Trevorrow}{13}
X\indexentry{Trevorrow Andrew}{13}
X\indexentry{OzTeX}{13}
X\indexentry{Knuth84}{13}
X\indexentry{Lamport86}{13}
X\indexentry{TeX}{13}
X\indexentry{LaTeX}{13}
X\indexentry{Macintosh}{13}
X\indexentry{tutorial}{15}
X\indexentry{literate programming}{15}
X\indexentry{literate programming}{15}
X\indexentry{magic trick}{15}
X\indexentry{tools literate programming}{15}
X\indexentry{literate programming tools}{15}
X\indexentry{hypertext}{15}
X\indexentry{literate programming, facilities}{15}
X\indexentry{program ordering}{15}
X\indexentry{ordering program}{15}
X\indexentry{Pascal}{15}
X\indexentry{BSI82}{15}
X\indexentry{cross referencing}{17}
X\indexentry{literate programming, most significant benefit}{17}
X\indexentry{Rosovsky90}{17}
X\indexentry{universities}{17}
X\indexentry{explaining code}{17}
X\indexentry{code explaining}{17}
X\indexentry{development time}{17}
X\indexentry{time development}{17}
X\indexentry{Knuth83}{17}
X\indexentry{Knuth84}{17}
X\indexentry{Smith91}{17}
X\indexentry{FunnelWeb overview}{18}
X\indexentry{overview FunnelWeb}{18}
X\indexentry{input file}{18}
X\indexentry{product files}{18}
X\indexentry{documentation file}{18}
X\indexentry{output files}{18}
X\indexentry{simplicity}{18}
X\indexentry{reliability}{18}
X\indexentry{language independence}{18}
X\indexentry{independence language}{18}
X\indexentry{typesetter independence}{18}
X\indexentry{independence typesetter}{18}
X\indexentry{BSI82}{18}
X\indexentry{Knuth84}{18}
X\indexentry{TeX}{18}
X\indexentry{portability}{18}
X\indexentry{controllability}{18}
X\indexentry{GNU license}{18}
X\indexentry{license GNU}{18}
X\indexentry{production tool}{19}
X\indexentry{FunnelWeb name}{19}
X\indexentry{name FunnelWeb}{19}
X\indexentry{Funnel-web spider}{19}
X\indexentry{spider Funnel-web}{19}
X\indexentry{Sydney}{19}
X\indexentry{Atrax robustus}{19}
X\indexentry{ANZE}{19}
X\indexentry{tiger snake}{19}
X\indexentry{snake tiger}{19}
X\indexentry{white pointer shark}{19}
X\indexentry{shark white pointer}{19}
X\indexentry{Edna Everage}{19}
X\indexentry{Everage Edna}{19}
X\indexentry{Barry Humphries}{19}
X\indexentry{Humphries Barry}{19}
X\indexentry{Humphries91}{19}
X\indexentry{tutorial}{19}
X\indexentry{tutorial introduction}{19}
X\indexentry{introduction tutorial}{19}
X\indexentry{hello world document}{20}
X\indexentry{invoking FunnelWeb}{20}
X\indexentry{special character}{20}
X\indexentry{special sequence}{20}
X\indexentry{@<}{20}
X\indexentry{@>}{20}
X\indexentry{@O}{20}
X\indexentry{@braces}{20}
X\indexentry{@+}{20}
X\indexentry{simple rule}{20}
X\indexentry{rule simple}{20}
X\indexentry{C preprocessor}{20}
X\indexentry{preprocessor C}{20}
X\indexentry{@=}{20}
X\indexentry{Hello Northern Hemisphere Program}{21}
X\indexentry{FunnelWeb two main aspects}{21}
X\indexentry{two main aspects FunnelWeb}{21}
X\indexentry{Tangling}{21}
X\indexentry{Weaving}{21}
X\indexentry{WEB}{21}
X\indexentry{tutorial macro facilities}{22}
X\indexentry{macro facilities tutorial}{22}
X\indexentry{tutorial simple macros}{22}
X\indexentry{simple macros tutorial}{22}
X\indexentry{tutorial macros simple}{22}
X\indexentry{macros simple tutorial}{22}
X\indexentry{@O}{22}
X\indexentry{@dollar}{22}
X\indexentry{order program}{22}
X\indexentry{program order}{22}
X\indexentry{program layout}{22}
X\indexentry{layout program}{22}
X\indexentry{macro bindings}{22}
X\indexentry{bindings macro}{22}
X\indexentry{TeX}{22}
X\indexentry{number of times called}{23}
X\indexentry{calls number}{23}
X\indexentry{number calls}{23}
X\indexentry{invocation number}{23}
X\indexentry{number invocation}{23}
X\indexentry{EOL suppression}{23}
X\indexentry{suppression EOL}{23}
X\indexentry{@-}{23}
X\indexentry{@Z tutorial}{24}
X\indexentry{tutorial @Z}{24}
X\indexentry{@M tutorial}{24}
X\indexentry{tutorial @M}{24}
X\indexentry{indentation macro calls}{25}
X\indexentry{macro calls indentation}{25}
X\indexentry{pragma}{25}
X\indexentry{WEB}{25}
X\indexentry{Knuth83}{25}
X\indexentry{Pascal}{25}
X\indexentry{output WEB}{25}
X\indexentry{WEB output}{25}
X\indexentry{Knuth83}{25}
X\indexentry{object code}{26}
X\indexentry{additive macros}{26}
X\indexentry{macros additive}{26}
X\indexentry{additive macro}{26}
X\indexentry{tutorial ==}{26}
X\indexentry{== tutorial}{26}
X\indexentry{tutorial +=}{26}
X\indexentry{+= tutorial}{26}
X\indexentry{data abstraction}{26}
X\indexentry{abstraction data}{26}
X\indexentry{Pascal}{26}
X\indexentry{program layout}{28}
X\indexentry{layout program}{28}
X\indexentry{parameterized macros}{28}
X\indexentry{macros parameterized}{28}
X\indexentry{formal parameters}{28}
X\indexentry{parameters formal}{28}
X\indexentry{@1...}{28}
X\indexentry{formal parameters}{28}
X\indexentry{parameters formal}{28}
X\indexentry{actual parameters}{29}
X\indexentry{parameters actual}{29}
X\indexentry{@(}{29}
X\indexentry{@)}{29}
X\indexentry{@,}{29}
X\indexentry{@"}{29}
X\indexentry{parameter list, absent}{29}
X\indexentry{song}{29}
X\indexentry{twelve bugs of christmas}{29}
X\indexentry{rec.humor.funny}{29}
X\indexentry{Pat Scannel}{29}
X\indexentry{Scannel Pat}{29}
X\indexentry{macro expansion}{30}
X\indexentry{expansion macro}{30}
X\indexentry{memory use of}{30}
X\indexentry{use of memory}{30}
X\indexentry{include files}{30}
X\indexentry{files include}{30}
X\indexentry{@i}{30}
X\indexentry{poem camera}{30}
X\indexentry{camera poem}{30}
X\indexentry{animal poem}{30}
X\indexentry{poem animal}{30}
X\indexentry{shooting}{31}
X\indexentry{special character changing}{31}
X\indexentry{changing special character}{31}
X\indexentry{include files recursive}{31}
X\indexentry{recursive include files}{31}
X\indexentry{macro libraries}{31}
X\indexentry{libraries macro}{31}
X\indexentry{tutorial typesetting}{32}
X\indexentry{typesetting tutorial}{32}
X\indexentry{documentation vs code}{32}
X\indexentry{code vs documentation}{32}
X\indexentry{overview typesetting}{32}
X\indexentry{typesetting overview}{32}
X\indexentry{macro definitions}{32}
X\indexentry{directives}{32}
X\indexentry{free text}{32}
X\indexentry{typesetter independence}{34}
X\indexentry{independence typesetter}{34}
X\indexentry{typesetter independent}{34}
X\indexentry{hierarchical structure}{34}
X\indexentry{structure hierarchical}{34}
X\indexentry{section headings}{34}
X\indexentry{headings section}{34}
X\indexentry{@A...}{34}
X\indexentry{name section}{34}
X\indexentry{section name}{34}
X\indexentry{section name inheritance}{35}
X\indexentry{inheritance section name}{35}
X\indexentry{programmer's cheer}{35}
X\indexentry{cheer programmer's}{35}
X\indexentry{hacker's cheer}{35}
X\indexentry{cheer hacker's}{35}
X\indexentry{hacker's dictionary}{35}
X\indexentry{dictionary hacker's}{35}
X\indexentry{literal construct}{37}
X\indexentry{emphasis construct}{37}
X\indexentry{@slash}{37}
X\indexentry{@braces}{37}
X\indexentry{header page}{37}
X\indexentry{vskip directive}{37}
X\indexentry{directive vskip}{37}
X\indexentry{title directive}{37}
X\indexentry{directive title}{37}
X\indexentry{newpage directive}{37}
X\indexentry{directive newpage}{37}
X\indexentry{table of contents directive}{37}
X\indexentry{directive table of contents}{37}
X\indexentry{comments}{37}
X\indexentry{@!}{37}
X\indexentry{complete example}{38}
X\indexentry{example complete}{38}
X\indexentry{FunnelWeb Example}{38}
X\indexentry{Example FunnelWeb}{38}
X\indexentry{FunnelWeb hints}{41}
X\indexentry{hints FunnelWeb}{41}
X\indexentry{macro names}{41}
X\indexentry{names macro}{41}
X\indexentry{macro identifiers}{41}
X\indexentry{identifiers macro}{41}
X\indexentry{quick names}{42}
X\indexentry{names quick}{42}
X\indexentry{empty name}{42}
X\indexentry{name empty}{42}
X\indexentry{quick name}{42}
X\indexentry{FunnelWeb rules}{42}
X\indexentry{rules FunnelWeb}{42}
X\indexentry{FunnelWeb martinet}{42}
X\indexentry{martinet FunnelWeb}{42}
X\indexentry{trailing blanks}{42}
X\indexentry{blanks trailing}{42}
X\indexentry{input line length}{42}
X\indexentry{length input line}{42}
X\indexentry{output line length}{42}
X\indexentry{length output line}{42}
X\indexentry{Fortran compilers}{42}
X\indexentry{compilers Fortran}{42}
X\indexentry{control characters}{42}
X\indexentry{characters control}{42}
X\indexentry{text editors}{42}
X\indexentry{editors text}{42}
X\indexentry{tabs}{42}
X\indexentry{invocations number}{42}
X\indexentry{number invocations}{42}
X\indexentry{recursion macro}{43}
X\indexentry{macro recursion}{43}
X\indexentry{EOL fiddling with}{43}
X\indexentry{fiddling with EOL}{43}
X\indexentry{end-of-line fiddling with}{43}
X\indexentry{fiddling with end-of-line}{43}
X\indexentry{spacing}{43}
X\indexentry{fudging conditionals}{44}
X\indexentry{conditionals fudging}{44}
X\indexentry{Ada}{44}
X\indexentry{headings strength}{46}
X\indexentry{strength headings}{46}
X\indexentry{typesetting strength}{46}
X\indexentry{strength typesetting}{46}
X\indexentry{section strength}{46}
X\indexentry{strength section}{46}
X\indexentry{font size}{46}
X\indexentry{size font}{46}
X\indexentry{FunnelWeb efficiency}{47}
X\indexentry{efficiency FunnelWeb}{47}
X\indexentry{efficiency notes}{47}
X\indexentry{notes efficiency}{47}
X\indexentry{memory}{47}
X\indexentry{input files}{47}
X\indexentry{files input}{47}
X\indexentry{speed}{47}
X\indexentry{macro expansion}{47}
X\indexentry{expansion macro}{47}
X\indexentry{interactive mode}{47}
X\indexentry{keyboard mode}{47}
X\indexentry{regression testing}{47}
X\indexentry{testing regression}{47}
X\indexentry{command interpreter}{47}
X\indexentry{interpreter command}{47}
X\indexentry{useful commands}{47}
X\indexentry{commands useful}{47}
X\indexentry{FunnelWeb proper}{48}
X\indexentry{set command}{48}
X\indexentry{command set}{48}
X\indexentry{show command}{48}
X\indexentry{command show}{48}
X\indexentry{trace on command}{48}
X\indexentry{command trace on}{48}
X\indexentry{workstations}{48}
X\indexentry{options setting defaults}{49}
X\indexentry{setting defaults options}{49}
X\indexentry{default options}{49}
X\indexentry{options default}{49}
X\indexentry{alias}{49}
X\indexentry{fwinit.fws}{49}
X\indexentry{startup script}{49}
X\indexentry{script startup}{49}
X\indexentry{initialization script}{49}
X\indexentry{script initialization}{49}
X\indexentry{make utility}{49}
X\indexentry{file dependencies}{49}
X\indexentry{dependencies file}{49}
X\indexentry{Ada}{49}
X\indexentry{D option}{49}
X\indexentry{option D}{49}
X\indexentry{delete output files}{49}
X\indexentry{output files delete}{49}
X\indexentry{suppression file}{49}
X\indexentry{file suppression}{49}
X\indexentry{FunnelWeb dangers}{50}
X\indexentry{dangers FunnelWeb}{50}
X\indexentry{FunnelWeb pitfalls}{50}
X\indexentry{pitfalls FunnelWeb}{50}
X\indexentry{Donald Knuth}{50}
X\indexentry{Knuth Donald}{50}
X\indexentry{literate programming}{50}
X\indexentry{programming literate}{50}
X\indexentry{spaghetti organization}{50}
X\indexentry{organization spaghetti}{50}
X\indexentry{stream of consciousness}{50}
X\indexentry{boring organization}{50}
X\indexentry{organization boring}{50}
X\indexentry{random access}{50}
X\indexentry{access random}{50}
X\indexentry{novels}{50}
X\indexentry{maintenance programmer}{50}
X\indexentry{programmer maintenance}{50}
X\indexentry{documentation interdependent}{50}
X\indexentry{interdependent documentation}{50}
X\indexentry{pavlov documentation}{51}
X\indexentry{documentation pavlov}{51}
X\indexentry{MIL-STD-2167A}{51}
X\indexentry{2167A}{51}
X\indexentry{Strunk79}{51}
X\indexentry{duplicate documentation}{51}
X\indexentry{documentation duplicate}{51}
X\indexentry{Ada}{51}
X\indexentry{over documentation}{51}
X\indexentry{documentation over}{51}
X\indexentry{Gries81}{51}
X\indexentry{wholistic debugging}{53}
X\indexentry{debugging wholistic}{53}
X\indexentry{wholistic debugging}{53}
X\indexentry{debugger}{53}
X\indexentry{code gardening}{53}
X\indexentry{gardening code}{53}
X\indexentry{wholistic medicine}{53}
X\indexentry{medicine wholistic}{53}
X\indexentry{FunnelWeb example applications}{53}
X\indexentry{example applications FunnelWeb}{53}
X\indexentry{FunnelWeb applications}{53}
X\indexentry{applications FunnelWeb}{53}
X\indexentry{monster file postscript}{54}
X\indexentry{postscript monster file}{54}
X\indexentry{MacDraw}{54}
X\indexentry{TeX}{54}
X\indexentry{PhD thesis}{54}
X\indexentry{thesis PhD}{54}
X\indexentry{Macintosh}{54}
X\indexentry{PostScript}{54}
X\indexentry{postscript header file}{54}
X\indexentry{header file postscript}{54}
X\indexentry{cryptic text files}{55}
X\indexentry{text files cryptic}{55}
X\indexentry{Ada}{55}
X\indexentry{abstract data type}{55}
X\indexentry{ADT}{55}
X\indexentry{package}{55}
X\indexentry{DOD83}{55}
X\indexentry{multiple languages}{55}
X\indexentry{languages multiple}{55}
X\indexentry{open systems}{55}
X\indexentry{printing system}{55}
X\indexentry{system printing}{55}
X\indexentry{laser printer}{55}
X\indexentry{printer laser}{55}
X\indexentry{sharing information}{56}
X\indexentry{small functions}{56}
X\indexentry{functions small}{56}
X\indexentry{code abstraction}{56}
X\indexentry{abstraction code}{56}
X\indexentry{Pascal}{57}
X\indexentry{preprocessor C}{57}
X\indexentry{C preprocessor}{57}
X\indexentry{procedure call overhead}{57}
X\indexentry{overhead procedure call}{57}
X\indexentry{binding problems}{57}
X\indexentry{problems binding}{57}
X\indexentry{comments abuse}{57}
X\indexentry{abuse comments}{57}
X\indexentry{eliminating comments}{57}
X\indexentry{comments eliminating}{57}
X\indexentry{good old days}{57}
X\indexentry{BASIC}{57}
X\indexentry{REM statement}{57}
X\indexentry{statement REM}{57}
X\indexentry{header files}{57}
X\indexentry{files header}{57}
X\indexentry{C header}{57}
X\indexentry{header C}{57}
X\indexentry{postscript}{57}
X\indexentry{sharing text}{58}
X\indexentry{text sharing}{58}
X\indexentry{annual report}{58}
X\indexentry{report annual}{58}
X\indexentry{examples documentation}{58}
X\indexentry{documentation examples}{58}
X\indexentry{generics fudging}{59}
X\indexentry{fudging generics}{59}
X\indexentry{Pascal}{59}
X\indexentry{Barry Dwyer}{59}
X\indexentry{Dwyer Barry}{59}
X\indexentry{University Adelaide}{59}
X\indexentry{Adelaide University}{59}
X\indexentry{set abstraction}{59}
X\indexentry{abstraction set}{59}
X\indexentry{typesafe generics}{61}
X\indexentry{generics typesafe}{61}
X\indexentry{FunnelWeb definition}{63}
X\indexentry{definition FunnelWeb}{63}
X\indexentry{notation}{63}
X\indexentry{EBNF syntax}{63}
X\indexentry{syntax EBNF}{63}
X\indexentry{terminology}{63}
X\indexentry{semantic architecture}{64}
X\indexentry{architecture semantic}{64}
X\indexentry{FunnelWeb overview}{64}
X\indexentry{overview FunnelWeb}{64}
X\indexentry{execution phases}{64}
X\indexentry{phases execution}{64}
X\indexentry{input file}{64}
X\indexentry{FunnelWeb file}{64}
X\indexentry{phases}{64}
X\indexentry{output files}{64}
X\indexentry{journal file}{64}
X\indexentry{listing file}{64}
X\indexentry{documentation}{64}
X\indexentry{product files}{64}
X\indexentry{scanner}{64}
X\indexentry{parser}{64}
X\indexentry{document list}{64}
X\indexentry{list document}{64}
X\indexentry{macro table}{64}
X\indexentry{table macro}{64}
X\indexentry{analyser}{65}
X\indexentry{tangle}{65}
X\indexentry{weave}{65}
X\indexentry{FunnelWeb proper}{65}
X\indexentry{FunnelWeb program}{65}
X\indexentry{diagnostics}{65}
X\indexentry{diagnostics levels of}{65}
X\indexentry{levels of diagnostics}{65}
X\indexentry{severity}{65}
X\indexentry{warning severity}{65}
X\indexentry{severity warning}{65}
X\indexentry{error severity}{65}
X\indexentry{severity error}{65}
X\indexentry{severe severity}{65}
X\indexentry{severity severe}{65}
X\indexentry{fatal severity}{65}
X\indexentry{severity fatal}{65}
X\indexentry{assertion severity}{65}
X\indexentry{severity assertion}{65}
X\indexentry{return status}{65}
X\indexentry{status return}{65}
X\indexentry{typesetter independence}{65}
X\indexentry{independence typesetter}{65}
X\indexentry{Kernighan88}{65}
X\indexentry{typesetter directives}{66}
X\indexentry{command line interface}{66}
X\indexentry{interface command line}{66}
X\indexentry{FunnelWeb invoking}{66}
X\indexentry{invoking FunnelWeb}{66}
X\indexentry{FunnelWeb running}{66}
X\indexentry{running FunnelWeb}{66}
X\indexentry{command line processing}{66}
X\indexentry{processing command line}{66}
X\indexentry{command line parsing}{66}
X\indexentry{parsing command line}{66}
X\indexentry{fw command verb}{66}
X\indexentry{command verb fw}{66}
X\indexentry{command line argument}{67}
X\indexentry{argument command line}{67}
X\indexentry{syntax command line}{67}
X\indexentry{command line syntax}{67}
X\indexentry{arguments}{67}
X\indexentry{case dependence}{67}
X\indexentry{dependence case}{67}
X\indexentry{Unix}{67}
X\indexentry{sign}{67}
X\indexentry{letter}{67}
X\indexentry{string}{67}
X\indexentry{command line options syntax}{67}
X\indexentry{syntax command line options}{67}
X\indexentry{options syntax}{67}
X\indexentry{syntax options}{67}
X\indexentry{options}{67}
X\indexentry{options}{68}
X\indexentry{list options}{68}
X\indexentry{options list}{68}
X\indexentry{B option}{68}
X\indexentry{option B}{68}
X\indexentry{tracedump options}{68}
X\indexentry{options tracedump}{68}
X\indexentry{dump option}{68}
X\indexentry{option dump}{68}
X\indexentry{dump mapped file}{68}
X\indexentry{mapped file dump}{68}
X\indexentry{dump global line list}{68}
X\indexentry{global line list dump}{68}
X\indexentry{dump token list}{68}
X\indexentry{token list dump}{68}
X\indexentry{dump macro table}{68}
X\indexentry{macro table dump}{68}
X\indexentry{dump document list}{68}
X\indexentry{document list dump}{68}
X\indexentry{dump times}{68}
X\indexentry{times dump}{68}
X\indexentry{non-determinism}{68}
X\indexentry{C option}{68}
X\indexentry{option C}{68}
X\indexentry{listing file context}{68}
X\indexentry{context listing file}{68}
X\indexentry{infinite context}{68}
X\indexentry{context infinite}{68}
X\indexentry{D option}{68}
X\indexentry{option D}{68}
X\indexentry{delete output option}{68}
X\indexentry{option delete output}{68}
X\indexentry{F option}{68}
X\indexentry{option F}{68}
X\indexentry{input file option}{68}
X\indexentry{option input file}{68}
X\indexentry{H option}{68}
X\indexentry{option H}{68}
X\indexentry{help option}{68}
X\indexentry{option help}{68}
X\indexentry{I option}{69}
X\indexentry{option I}{69}
X\indexentry{include file option}{69}
X\indexentry{option include file}{69}
X\indexentry{include file}{69}
X\indexentry{file include}{69}
X\indexentry{J option}{69}
X\indexentry{option J}{69}
X\indexentry{journal file option}{69}
X\indexentry{option journal file}{69}
X\indexentry{journal file}{69}
X\indexentry{file journal}{69}
X\indexentry{K option}{69}
X\indexentry{option K}{69}
X\indexentry{keyboard option}{69}
X\indexentry{option keyboard}{69}
X\indexentry{interactive option}{69}
X\indexentry{option interactive}{69}
X\indexentry{L option}{69}
X\indexentry{option L}{69}
X\indexentry{listing file option}{69}
X\indexentry{option listing file}{69}
X\indexentry{listing file}{69}
X\indexentry{file listing}{69}
X\indexentry{Q option}{69}
X\indexentry{option Q}{69}
X\indexentry{quiet option}{69}
X\indexentry{option quiet}{69}
X\indexentry{suppress console output}{69}
X\indexentry{console output suppress}{69}
X\indexentry{S option}{69}
X\indexentry{option S}{69}
X\indexentry{screen option}{69}
X\indexentry{option screen}{69}
X\indexentry{context}{69}
X\indexentry{T option}{69}
X\indexentry{option T}{69}
X\indexentry{typeset option}{69}
X\indexentry{option typeset}{69}
X\indexentry{typeset file}{69}
X\indexentry{file typeset}{69}
X\indexentry{W option}{69}
X\indexentry{option W}{69}
X\indexentry{width option}{69}
X\indexentry{option width}{69}
X\indexentry{product file width}{69}
X\indexentry{width product file}{69}
X\indexentry{X option}{69}
X\indexentry{option X}{69}
X\indexentry{execute script option}{69}
X\indexentry{option execute script}{69}
X\indexentry{filename inheritance}{70}
X\indexentry{inheritance filename}{70}
X\indexentry{filename fields}{70}
X\indexentry{fields filename}{70}
X\indexentry{directory}{70}
X\indexentry{name}{70}
X\indexentry{extension}{70}
X\indexentry{filename inheritance example}{70}
X\indexentry{example filename inheritance}{70}
X\indexentry{FunnelWeb startup}{70}
X\indexentry{startup FunnelWeb}{70}
X\indexentry{FunnelWeb initialization}{70}
X\indexentry{initialization FunnelWeb}{70}
X\indexentry{Action options}{70}
X\indexentry{Ordinary options}{70}
X\indexentry{action execution order}{71}
X\indexentry{order action execution}{71}
X\indexentry{initialization script}{71}
X\indexentry{script initialization}{71}
X\indexentry{fwinit.fws}{71}
X\indexentry{scanner}{71}
X\indexentry{mapper}{71}
X\indexentry{file termination}{71}
X\indexentry{termination file}{71}
X\indexentry{line termination}{71}
X\indexentry{termination line}{71}
X\indexentry{unprintable characters}{71}
X\indexentry{characters unprintable}{71}
X\indexentry{line length}{71}
X\indexentry{length line}{71}
X\indexentry{special sequences}{72}
X\indexentry{sequences special}{72}
X\indexentry{special character}{72}
X\indexentry{special sequence}{72}
X\indexentry{default special character}{72}
X\indexentry{special character default}{72}
X\indexentry{simple sequence}{72}
X\indexentry{setting special character}{74}
X\indexentry{special character setting}{74}
X\indexentry{special character inserting into text}{74}
X\indexentry{inserting into text special character}{74}
X\indexentry{arbitrary characters inserting into text}{74}
X\indexentry{inserting into text arbitrary characters}{74}
X\indexentry{control characters inserting into text}{74}
X\indexentry{inserting into text control characters}{74}
X\indexentry{@circumflex}{74}
X\indexentry{Unix newline}{75}
X\indexentry{comments FunnelWeb}{75}
X\indexentry{FunnelWeb comments}{75}
X\indexentry{@!}{75}
X\indexentry{quick names}{76}
X\indexentry{names quick}{76}
X\indexentry{quick name}{76}
X\indexentry{@hash}{76}
X\indexentry{EOL markers inserting}{76}
X\indexentry{inserting EOL markers}{76}
X\indexentry{@+}{76}
X\indexentry{EOL markers suppressing}{77}
X\indexentry{suppressing EOL markers}{77}
X\indexentry{@-}{77}
X\indexentry{include files}{77}
X\indexentry{files include}{77}
X\indexentry{@i}{77}
X\indexentry{input file}{77}
X\indexentry{include files}{77}
X\indexentry{pragmas}{78}
X\indexentry{pragmas visible}{78}
X\indexentry{visible pragmas}{78}
X\indexentry{pragmas invisible}{78}
X\indexentry{invisible pragmas}{78}
X\indexentry{pragma}{78}
X\indexentry{indentation macro expansion}{78}
X\indexentry{macro expansion indentation}{78}
X\indexentry{no indentation}{78}
X\indexentry{indentation none}{78}
X\indexentry{none indentation}{78}
X\indexentry{blank indentation}{78}
X\indexentry{indentation blank}{78}
X\indexentry{blank indentation}{78}
X\indexentry{input line length}{79}
X\indexentry{line length input}{79}
X\indexentry{maximum input line length}{79}
X\indexentry{input line length maximum}{79}
X\indexentry{pragma input line length}{79}
X\indexentry{input line length pragma}{79}
X\indexentry{maximum product file line length}{79}
X\indexentry{product file line length maximum}{79}
X\indexentry{pragma maximum product file line length}{79}
X\indexentry{maximum product file line length pragma}{79}
X\indexentry{maximum output file line length}{79}
X\indexentry{output file line length maximum}{79}
X\indexentry{pragma maximum output file line length}{79}
X\indexentry{maximum output file line length pragma}{79}
X\indexentry{typesetter pragma}{80}
X\indexentry{pragma typesetter}{80}
X\indexentry{typesetter independence}{80}
X\indexentry{independence typesetter}{80}
X\indexentry{typesetter directives}{81}
X\indexentry{directives typesetter}{81}
X\indexentry{inline}{81}
X\indexentry{freestanding}{81}
X\indexentry{new page}{81}
X\indexentry{pragma new page}{81}
X\indexentry{new page pragma}{81}
X\indexentry{table of contents}{81}
X\indexentry{contents table of}{81}
X\indexentry{pragma table of contents}{81}
X\indexentry{table of contents pragma}{81}
X\indexentry{vertical skip}{81}
X\indexentry{skip vertical}{81}
X\indexentry{pragma vskip}{81}
X\indexentry{vskip pragma}{81}
X\indexentry{title}{82}
X\indexentry{pragma title}{82}
X\indexentry{title pragma}{82}
X\indexentry{parser}{82}
X\indexentry{text tokens}{82}
X\indexentry{special tokens}{82}
X\indexentry{typesetter directive tokens}{82}
X\indexentry{syntax high level}{82}
X\indexentry{high level syntax}{82}
X\indexentry{free text}{83}
X\indexentry{text free}{83}
X\indexentry{Free text}{83}
X\indexentry{directives}{83}
X\indexentry{freestanding typesetter directives}{83}
X\indexentry{inline typesetter directives}{83}
X\indexentry{section constructs}{83}
X\indexentry{constructs section}{83}
X\indexentry{tree structure}{83}
X\indexentry{structure tree}{83}
X\indexentry{LaTeX}{84}
X\indexentry{section name}{84}
X\indexentry{name section}{84}
X\indexentry{literal directive}{84}
X\indexentry{directive literal}{84}
X\indexentry{emphasis directive}{85}
X\indexentry{directive emphasis}{85}
X\indexentry{macro definition}{85}
X\indexentry{definition macro}{85}
X\indexentry{macro name}{85}
X\indexentry{macro body}{85}
X\indexentry{expression}{85}
X\indexentry{macro attributes}{85}
X\indexentry{attributes macro}{85}
X\indexentry{@Z}{85}
X\indexentry{@M}{85}
X\indexentry{==}{85}
X\indexentry{+=}{85}
X\indexentry{additively defined}{85}
X\indexentry{names}{86}
X\indexentry{macro names}{86}
X\indexentry{names macro}{86}
X\indexentry{section names}{86}
X\indexentry{names section}{86}
X\indexentry{parameter lists formal}{86}
X\indexentry{formal parameter lists}{86}
X\indexentry{@1...}{86}
X\indexentry{macro expressions}{86}
X\indexentry{expressions macro}{86}
X\indexentry{macro calls}{86}
X\indexentry{calls macro}{86}
X\indexentry{macro parameter delimiting}{87}
X\indexentry{delimiting macro parameter}{87}
X\indexentry{formal parameters}{87}
X\indexentry{parameters formal}{87}
X\indexentry{macro definition}{87}
X\indexentry{definition macro}{87}
X\indexentry{macro expansion}{87}
X\indexentry{expansion macro}{87}
X\indexentry{macros static}{87}
X\indexentry{static macros}{87}
X\indexentry{analyser}{88}
X\indexentry{checks macro}{88}
X\indexentry{macro checks}{88}
X\indexentry{static analysis}{88}
X\indexentry{analysis static}{88}
X\indexentry{macro recursion}{88}
X\indexentry{recursion macro}{88}
X\indexentry{tangle}{88}
X\indexentry{weave}{89}
X\indexentry{typesetting}{89}
X\indexentry{target typesetter}{89}
X\indexentry{typesetter target}{89}
X\indexentry{cross referencing}{89}
X\indexentry{referencing cross}{89}
X\indexentry{cross reference numbering}{89}
X\indexentry{numbering cross reference}{89}
X\indexentry{section numbering}{89}
X\indexentry{numbering section}{89}
X\indexentry{FunnelWeb command shell}{90}
X\indexentry{command shell FunnelWeb}{90}
X\indexentry{commands FunnelWeb}{90}
X\indexentry{FunnelWeb commands}{90}
X\indexentry{FunnelWeb shell}{90}
X\indexentry{shell FunnelWeb}{90}
X\indexentry{FunnelWeb command shell}{90}
X\indexentry{uses shell}{90}
X\indexentry{shell uses}{90}
X\indexentry{workstation}{90}
X\indexentry{errors shell}{90}
X\indexentry{shell errors}{90}
X\indexentry{status success}{90}
X\indexentry{success status}{90}
X\indexentry{status warning}{90}
X\indexentry{warning status}{90}
X\indexentry{status error}{90}
X\indexentry{error status}{90}
X\indexentry{status severe}{90}
X\indexentry{severe status}{90}
X\indexentry{status fatal}{90}
X\indexentry{fatal status}{90}
X\indexentry{status assertion}{90}
X\indexentry{assertion status}{90}
X\indexentry{command length}{91}
X\indexentry{length command}{91}
X\indexentry{string substitution}{91}
X\indexentry{substitution string}{91}
X\indexentry{define command}{91}
X\indexentry{command define}{91}
X\indexentry{command line processing}{92}
X\indexentry{processing command line}{92}
X\indexentry{command options}{92}
X\indexentry{options command}{92}
X\indexentry{default options}{92}
X\indexentry{options default}{92}
X\indexentry{shell commands list}{93}
X\indexentry{list shell commands}{93}
X\indexentry{commands shell}{93}
X\indexentry{shell commands}{93}
X\indexentry{command absent}{93}
X\indexentry{absent command}{93}
X\indexentry{command codify}{93}
X\indexentry{codify command}{93}
X\indexentry{command compare}{93}
X\indexentry{compare command}{93}
X\indexentry{command define}{94}
X\indexentry{define command}{94}
X\indexentry{string substitution}{94}
X\indexentry{substitution string}{94}
X\indexentry{command diff}{94}
X\indexentry{diff command}{94}
X\indexentry{file differences}{94}
X\indexentry{differences file}{94}
X\indexentry{command diffsummary}{95}
X\indexentry{diffsummary command}{95}
X\indexentry{command diffzero}{95}
X\indexentry{diffzero command}{95}
X\indexentry{command eneo}{95}
X\indexentry{eneo command}{95}
X\indexentry{command execute}{96}
X\indexentry{execute command}{96}
X\indexentry{command exists}{96}
X\indexentry{exists command}{96}
X\indexentry{command fixeols}{96}
X\indexentry{fixeols command}{96}
X\indexentry{non-printable characters}{96}
X\indexentry{characters non-printable}{96}
X\indexentry{command fw}{97}
X\indexentry{fw command}{97}
X\indexentry{command help}{97}
X\indexentry{help command}{97}
X\indexentry{command here}{98}
X\indexentry{here command}{98}
X\indexentry{command quit}{98}
X\indexentry{quit command}{98}
X\indexentry{command set}{98}
X\indexentry{set command}{98}
X\indexentry{command show}{98}
X\indexentry{show command}{98}
X\indexentry{command skipto}{98}
X\indexentry{skipto command}{98}
X\indexentry{command status}{99}
X\indexentry{status command}{99}
X\indexentry{command tolerate}{100}
X\indexentry{tolerate command}{100}
X\indexentry{command trace}{100}
X\indexentry{trace command}{100}
X\indexentry{command write}{100}
X\indexentry{write command}{100}
X\indexentry{command writeu}{100}
X\indexentry{writeu command}{100}
X\indexentry{FunnelWeb installation}{101}
X\indexentry{installation FunnelWeb}{101}
X\indexentry{FunnelWeb obtaining}{101}
X\indexentry{obtaining FunnelWeb}{101}
X\indexentry{ftp anonymous}{101}
X\indexentry{anonymous ftp}{101}
X\indexentry{directory tree}{102}
X\indexentry{tree directory}{102}
X\indexentry{admin directory}{102}
X\indexentry{directory admin}{102}
X\indexentry{answers directory}{102}
X\indexentry{directory answers}{102}
X\indexentry{correct answers}{102}
X\indexentry{answers correct}{102}
X\indexentry{hackman directory}{103}
X\indexentry{directory hackman}{103}
X\indexentry{results directory}{103}
X\indexentry{directory results}{103}
X\indexentry{scripts directory}{103}
X\indexentry{directory scripts}{103}
X\indexentry{regression testing}{103}
X\indexentry{testing regression}{103}
X\indexentry{sources directory}{103}
X\indexentry{directory sources}{103}
X\indexentry{tests directory}{104}
X\indexentry{directory tests}{104}
X\indexentry{userman directory}{105}
X\indexentry{directory userman}{105}
X\indexentry{compiling FunnelWeb}{105}
X\indexentry{FunnelWeb compiling}{105}
X\indexentry{testing FunnelWeb}{105}
X\indexentry{FunnelWeb testing}{105}
X\indexentry{installing FunnelWeb}{106}
X\indexentry{FunnelWeb installing}{106}
X\indexentry{FunnelWeb executable}{106}
X\indexentry{executable FunnelWeb}{106}
X\indexentry{printing manuals}{107}
X\indexentry{manuals printing}{107}
X\indexentry{problems installation}{107}
X\indexentry{installation problems}{107}
X\indexentry{FunnelWeb administration}{109}
X\indexentry{administration FunnelWeb}{109}
X\indexentry{commitment FunnelWeb}{109}
X\indexentry{FunnelWeb commitment}{109}
X\indexentry{ANSI}{109}
X\indexentry{FunnelWeb documentation}{110}
X\indexentry{documentation FunnelWeb}{110}
X\indexentry{FunnelWeb registration}{110}
X\indexentry{registration FunnelWeb}{110}
X\indexentry{FunnelWeb support}{110}
X\indexentry{support FunnelWeb}{110}
X\indexentry{copyright FunnelWeb}{112}
X\indexentry{FunnelWeb copyright}{112}
X\indexentry{FunnelWeb license}{112}
X\indexentry{license FunnelWeb}{112}
X\indexentry{GNU license}{112}
X\indexentry{license GNU}{112}
X\indexentry{warranty}{112}
X\indexentry{FunnelWeb Distribution}{113}
X\indexentry{Distribution FunnelWeb}{113}
X\indexentry{FunnelWeb versions}{114}
X\indexentry{versions FunnelWeb}{114}
X\indexentry{author contacting}{114}
X\indexentry{contacting author}{114}
X\indexentry{ftp archive}{114}
X\indexentry{archive ftp}{114}
X\indexentry{FunnelWeb archive}{114}
X\indexentry{archive FunnelWeb}{114}
X\indexentry{glossary}{115}
X\indexentry{Analyser}{115}
X\indexentry{Argument}{115}
X\indexentry{Directive}{115}
X\indexentry{Documentation}{115}
X\indexentry{Documentation file}{115}
X\indexentry{Free text}{115}
X\indexentry{FunnelWeb}{115}
X\indexentry{FunnelWeb file}{115}
X\indexentry{FunnelWeb language}{115}
X\indexentry{FunnelWeb proper}{115}
X\indexentry{FW}{115}
X\indexentry{Include file}{115}
X\indexentry{Input file}{115}
X\indexentry{Journal file}{115}
X\indexentry{Listing file}{115}
X\indexentry{Macro}{115}
X\indexentry{Macro definition}{116}
X\indexentry{Mapper}{116}
X\indexentry{Option}{116}
X\indexentry{Output file}{116}
X\indexentry{Parser}{116}
X\indexentry{Pragma}{116}
X\indexentry{Printed documentation}{116}
X\indexentry{Product file}{116}
X\indexentry{Scanner}{116}
X\indexentry{Script}{116}
X\indexentry{Shell}{116}
X\indexentry{Special character}{116}
X\indexentry{Special sequence}{116}
X\indexentry{Tangle}{116}
X\indexentry{Typesetting directive}{116}
X\indexentry{Weave}{116}
X\indexentry{references}{117}
X\indexentry{ANSI}{117}
X\indexentry{ANZE}{117}
X\indexentry{BSI82}{117}
X\indexentry{Gries81}{117}
X\indexentry{Humphries91}{117}
X\indexentry{Kernighan88}{117}
X\indexentry{Knuth83}{117}
X\indexentry{Knuth84}{117}
X\indexentry{Knuth84}{117}
X\indexentry{Lamport86}{117}
X\indexentry{Rosovsky90}{117}
X\indexentry{Smith91}{117}
X\indexentry{Strunk79}{117}
X\indexentry{USDOD83}{117}
END_OF_FILE
if test 33582 -ne `wc -c <'userman/u_manual.idx'`; then
    echo shar: \"'userman/u_manual.idx'\" unpacked with wrong size!
fi
# end of 'userman/u_manual.idx'
fi
echo shar: End of archive 14 \(of 20\).
cp /dev/null ark14isdone
MISSING=""
for I in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 ; do
    if test ! -f ark${I}isdone ; then
    MISSING="${MISSING} ${I}"
    fi
done
if test "${MISSING}" = "" ; then
    echo You have unpacked all 20 archives.
    rm -f ark[1-9]isdone ark[1-9][0-9]isdone
else
    echo You still need to unpack the following archives:
    echo "        " ${MISSING}
fi
##  End of shell archive.
exit 0