summaryrefslogtreecommitdiff
path: root/web/clip/unix/manual.txt
diff options
context:
space:
mode:
Diffstat (limited to 'web/clip/unix/manual.txt')
-rw-r--r--web/clip/unix/manual.txt854
1 files changed, 854 insertions, 0 deletions
diff --git a/web/clip/unix/manual.txt b/web/clip/unix/manual.txt
new file mode 100644
index 0000000000..b7e319fd8f
--- /dev/null
+++ b/web/clip/unix/manual.txt
@@ -0,0 +1,854 @@
+
+
+
+ CLiP - C ode from Li terate P rograms
+ *************************************
+
+ Provisional User Manual
+
+
+
+Disclaimer:
+ This document is meant for programmers who are already familiar with the
+literate programming paradigm. It pretends in no way to be a complete user
+manual in the real meaning of the word. But the document should supply
+sufficient hints to experiment successfully with the CLiP system.
+ You are assumed to be familiar with the ideas and design goals of the CLiP
+system as explained in [Ammers and Kramer 1993]. Also you should have read *
+READ_ME.TXT* or *READ_ME.PS* which come with the executables and understand the
+meaning of the INI-file which guides the extraction process.
+ The DOS and VMS versions of CLiP consist of two independent programs,
+CLIP_1 and CLIP_2. CLIP_1 is purely to create an INI-file for CLIP_2, which
+performs the actual work. The Unix version consists of only one program, CLIP
+(which is identical to CLIP_2), and an INI-file should be made using the
+supplied scripts or an editor. This manual only deals with the second program.
+
+
+
+ Table of Contents
+
+1 Introduction 1
+
+2 Syntax (programming style) 2
+ 2.1 Stub blocks and documentation blocks 3
+ 2.2 Segments 3
+ 2.3 Options 3
+3 Examples 4
+ 3.1 Example 1: Defining a module 4
+ 3.2 Example 2: Multiple slots 5
+ 3.3 Example 3: Quick stubs and abstract data types 6
+ 3.4 Example 4: An ordinary refinement step 7
+ 3.5 Example 5: A subroutine module 9
+4 Semantics of options 11
+
+5 Using CLiP 12
+
+6 The structure of an INI-file 13
+
+7 Bugs, work-arounds and undocumented features 15
+ 7.1 "SP_EXTR_STR: system failure .... call maintenance" 15
+ 7.2 Options in general 15
+ 7.3 Multiple option 15
+ 7.4 Report file option NONE 15
+ 7.5 Generating target modules 15
+ 7.5.1 Specification 15
+ 7.5.2 Omitted modules 16
+ 7.5.3 Empty run 16
+ 7.6 Lost lines 16
+ 7.7 DOS version only 17
+8 References 17
+
+
+1 Introduction
+
+In short the idea behind CLiP is to define a style of programming sufficiently
+formal to be recognized by a literate programming automaton. This syntax (which
+we will refer to as the CLiP-syntax) should not obstruct a natural way of
+programming. Ideally the system should be smart enough to "see" stubs, slots
+and the like by "inspecting" the documentation and simply "understanding" the
+refinements the programmer has made. Alas, this is far beyond the current
+potential of artificial intelligence and we will have to reach the automaton a
+helping hand by defining a special syntax.
+ So we want the "look and feel" of a documentation to be as "natural" as
+possible, but with CLiP features that can be recognized by an automaton. On the
+other hand should the reader be burdened as little as possible with the fact
+that additional processing is needed to extract the modules. In systems like
+VAMP [Ammers 1984] and WEB [Knuth 1984] - which use batch formatters - this is
+achieved by adding explicit commands in the source-files that are suppressed in
+the formatted documentation. But this technique does not work if the
+documentation environment is an interactive word-processor (Word Perfect, Lotus
+Manuscript, MS-Word, Ami Pro, etc.). So CLiP uses either the ASCII-export from
+a word-processors or the ASCII input of a formatter and extracts modules from
+there. In these files CLiP recognizes the important sections by a particular
+programming-style rather than by explicit commands.
+ The first section describes the syntax that CLiP "sees". The next section
+gives a couple of useful examples. In section 4 we describe the options that
+may be used to customize the process of module generation. In section 5 we give
+some hints on how to organize your working with CLiP efficiently. Stubs and
+slots my remaining sections illustrate the style of documentation and programs
+that would result. CLiP is in development and we compile the known bugs in
+section 6.
+
+2 Syntax (programming style)
+
+CLiP-lines [-] that is lines which have a special meaning to CLiP [-] start
+with a CLIP-left-parenthesis (CLIP-lpar) and end with a CLIP-right-parenthesis
+(CLIP-rpar). Both tokens are constructed as extensions of the tokens
+encapsulating comments which we will refer to as *COMM-START* and *COMM-END*.
+If we program in Pascal then everything between "*(**" and "**)*" is seen as
+comment, thus we have the convention:
+
+ *COMM-START* = "*(**"
+ *COMM-END* = "**)*"
+
+Extension of the comment token is by a character with a special meaning to
+clip, the *CLIP-CHAR*. In our case we assume
+
+ *CLIP-CHAR* = "***"
+
+Thus CLiP-lines are enclosed by
+
+ CLIP-lpar of the form "*(***"
+
+and
+
+ CLIP-rpar of the form "***)*"
+
+The parameters *COMM-START*, *COMM-END* and *CLIP-CHAR* are set by the INI-file
+and it is evident that the convention can be adjusted.
+
+
+ CLiP distinguishes six source line categories:
+
+ 1 (******************* <arbitrary string> **********************)
+ 2 (**************** End of <arbitrary string> ******************)
+ 3 (** <arbitrary string> **)
+ 4 (***************************************************************)
+ 5 <the empty string>
+ 6 <any string not falling in one of the above categories>
+
+We will refer to a line from the second category as an "L2" and so on and
+investigate the meaning is of the various categories for CLiP.
+ The string "*End of*" of an L2 has a special meaning that distinguishes an
+L2 from an L1. Again this special string is defined by a parameter in the
+INI-file
+
+ *END-STRING* = "*ENDOF*"
+
+Observe that CLiP does not distinguish between upper and lower case and forgets
+about spaces. In fact CLiP reduces the <arbitrary string> internally to a
+sequence of the characters "*A*"-"*Z*", "*0*"-"*9*" and "*.*"
+ Note that for an L3 the character immediately following the *CLIP-CHAR* on
+the left side and the character preceding the *CLIP-CHAR* on the right side may
+be anything apart from the *CLIP-CHAR* itself.
+
+2.1 Stub blocks and documentation blocks
+
+From CLiP's point of view the source-files are divided in documentation blocks
+and stub-blocks. A stub-block starts with an L1 and usually ends with an L2. A
+special kind of stub, a so called quick stub (see sect. 3.3 and 4), is ended by
+an L5 or an <EOF>. Everything outside a stub-block is a documentation block and
+ignored by CLiP. For this reason we say that CLiP is in active mode during the
+processing of a stub-block and in passive mode otherwise. The only way to
+change CLiP from passive to active mode is by an L1 and the usual way from
+active to passive is through an L2. An L2 in passive mode is presumably an
+error and will be ignored.
+
+2.2 Segments
+
+A stub-block contains one and only one stub-segment, which starts the
+stub-block. The stub-segment may be followed by any number of slot-segments
+and/or code-segments.
+ An L1 always starts a new stub- or slot-segment and the segment continues
+with any number of lines of type L3 or L4. A segment is a slot-segment if and
+only if it is not the first one of a stub-block. A code-segment consists of any
+number of contiguous lines of type L5. Stub- and slot-segments have an
+identification or name which is constructed somehow from the *<arbitrary string>
+*s inside the segment.
+ L3 and L4 are continuations of stub- and slot-segments, but with a slightly
+different status. An L3 that cannot be pasted to a segment is flagged as an
+error. But an L4 under the same conditions is interpreted as belonging to the
+current code-segment.
+
+2.3 Options
+
+The module extraction process can be tuned by means of options. Stub-segments
+as well as slot-segments may have options. An option starts with a keyword
+signalled by a special *OPTION-MARKER*. The option keyword may be abbreviated
+to a unique headerstring for that option. We will assume "*#*" for *
+OPTION-MARKER*, but of course this again is a parameter set by the INI-file.
+
+
+The argument(s) following an option continue till the next option-keyword or
+till the end of the segment. Therefore the name of a segment must precede the
+options.
+ In general options operate on the inside of the stub only, since that is
+the part of the program that the programmer of this particular refinement has
+in his or her mind. In addition options can be inherited. The meaning of the
+various options is explained in section 4. Some frequently used options show up
+in the examples of section 3.
+
+
+3 Examples
+
+In the examples we will illustrate the most important features of CLiP by
+making remarks on excerpts drawn from the documentation of CLiPs predecessor,
+VAMP.
+
+3.1 Example 1: Defining a module
+
+ The module VAMP:
+ Starting from nowhere, the empty program will do.
+
+
+ 1 (**** #File "VAMP.PAS". #Indent on. ****)
+ 2
+ 3 (***************************************************************)
+ 4 (* Routine: VAMP - Main module of the VAMP system. *)
+ 5 (* Purpose: Main module and unique entry point to the *)
+ 6 (* VAMP-system. *)
+ 7 (* Interface: TTY - All communication with the user *)
+ 8 (* proceeds via the terminal. *)
+ 9 (* Author/Date: VAMP project management, Sept. 12, 1983. *)
+ 10 (***************************************************************)
+ 11
+ 12 (********************** VAMP (body) **************************)
+ 13
+ 14 (*********************** End of VAMP *************************)
+ 15
+ 16
+ 18 (********* VAMP (body) #def ***********)
+ 19 PROGRAM VAMP (INPUT, OUTPUT);
+ 20 BEGIN
+ 21 WRITELN ('!!! VAMP was here !!!');
+ 22 END (*VAMP*).
+ 23 (********** End of VAMP (body) *********)
+
+Remarks:
+ There are two stubs in this section. Line 1-14 and line 18-23. Both
+stub-blocks have a stub-segment of one line only (lines 1 and 18 respectively).
+ The first stub-segment has no identification. It specifies the start of a
+new output module by the FILE option and thus is not meant to be referenced
+(see also example 5).
+ Line 2 (an L5) separates line 3 (an L4) from the stub-segment and makes it
+belong to the code-segment which expands over lines 2-11.
+ There resides only one slot inside the first stub (line 12) and this slot
+is identified as "*VAMPBODY*". The second stub has no slots at all.
+ Line 13 is a trivial code-segment and line 14 marks the end of the first
+stub-block. The string following the "End of" is optional and does not have to
+match the stub name in any way.
+
+
+3.2 Example 2: Multiple slots
+
+ Environment module:
+ In the past there have been made several changes in the VAMP
+ program. These changes have been made in the extracted modules rather
+ then in the VAMP source. To make source files consistent with the
+ modules, the source files have been updated in march 1990 by Jeroen
+ Reef.
+
+ Furthermore, the updated source files contain two additional
+ modules, VAMP.MSG and DECLAR_MOD. The module VAMP.MSG contains the error
+ messages of VAMP and the module DECLAR_MOD contains the types and
+ constants used by several modules of VAMP. This module uses the
+ ENVIRONMENT, which directs the compiler to generate an environment file
+ DECLAR.PEN. Other modules can reference the identifiers declared in
+ DECLAR_MOD by inheriting the environment with the INHERIT attribute.
+
+
+
+ 1 (****** #File "DECLAR_MOD.PAS". #Indent ON. ******)
+ 2
+ 3 (***************************************************************)
+ 4 (* Module to contain all parameters and global declarations *)
+ 5 (* of the VAMP system. *)
+ 6 (***************************************************************)
+ 7 [ENVIRONMENT ('DECLAR.PEN')] MODULE DECLARS;
+ 8
+ 9 (********** Parameters of the VAMP-system (#mul) *************)
+ 10
+ 11 TYPE
+ 12 ABSTRACT = (DEFINED, UNDEFINED);
+ 13 (********* Simple types of the VAMP-system (#mul) ********)
+ 14 (******** Structured types of the VAMP-system (#mul) ******)
+ 15 END.
+ 16 (***************** End of DECLARE_MOD.PAS ********************)
+
+Remarks:
+ The stub-block extends over 16 lines. Line 1 is the stub-segment and line
+16 closes the stub-block. Lines 2-8 constitute the first code-segment of the
+stub, lines 10-12 the middle one and line 15 the last one.
+ There are three slots (or slot-segments), lines 9, 13 and 14. All slots
+consist of one line only and carry the multiple option. For instance the first
+slot can swallow any number of parameter definition that might turn up in the
+future.
+ The names (identifications) of the slots are respectively
+
+ "*PARAMETERSOFTHEVAMPSYSTEM*"
+ "*SIMPLETYPESOFTHEVAMPSYSTEM*"
+ "*STRUCTUREDTYPESOFTHEVAMPSYSTEM*"
+
+
+3.3 Example 3: Quick stubs and abstract data types
+
+ First level data structures:
+ This level introduces the data-structure TTY_INFO, containing the
+ initial communication between the terminal and the program. The
+ definition requires in addition four system parameters and some
+ constants and types which are related to file specifications. The
+ structure of CODE_INFO is left open for the time being.
+
+
+ 1 (********** Parameters of the VAMP-system (#quick) ***********)
+ 2 (* -------- Parameters of TTY_INFO --------- *)
+ 3 MAX_FILE_SPEC_L = 255; (* Maximum length file-specific. *)
+ 4 MAX_FILE_NAME_L = 39; (* Maximum length file-name. *)
+ 5 MAX_FILE_EXT_L = 39; (* Maximum length file-extension. *)
+ 6 MAX_IN_FILES = 8; (* Maximum number of in-files for *)
+ 7 (* a single run. *)
+ 8 UPB_IN_FILES = 9; (* = MAX_IN_FILES + 1. *)
+ 9 MAX_MODULES = 10; (* Maximum number of modules *)
+ 10 (* specified for a run. *)
+ 11 UPB_MODULES = 11; (* = MAX_MODULES + 1. *)
+ 12 EMPTY = '';
+ 13
+ 14 (********* Simple types of the VAMP-system (#quick) **********)
+ 15 (* -------- Simple types of TTY_INFO --------- *)
+ 16 FILE_SPEC = VARYING [MAX_FILE_SPEC_L] OF CHAR;
+ 17 FILE_NAME = VARYING [MAX_FILE_NAME_L] OF CHAR;
+ 18 FILE_EXT = VARYING [MAX_FILE_EXT_L] OF CHAR;
+ 19
+ 20 (******** Structured types of the VAMP-system ****************)
+ 21 (* -------- Structured types of TTY_INFO --------- *)
+ 22 TTY_INFO = RECORD
+ 23 IN_FILES: ARRAY [1..UPB_IN_FILES] OF FILE_SPEC;
+ 24 MODULES: ARRAY [1..UPB_MODULES] OF FILE_NAME;
+ 25 DFLT_EXT: FILE_EXT;
+ 26 INV_MODE,
+ 27 GO: BOOLEAN;
+ 29 END (*RECORD*);
+ 30 (**************** Declaration of CODE_INFO *******************)
+ 31 (******** End of Structured types of the VAMP-system *********)
+ 32
+ 33
+ 34 (************* Declaration of CODE_INFO (#def) ***************)
+ 35 CODE_INFO = ABSTRACT;
+ 36 (******************** End of declaration *********************)
+
+Remarks:
+ This section contains five stubs altogether, i.e. lines 1-12, 14-18, 20-31
+and 34-36. The first two blocks one have no internal slots. The quick option
+promotes them to quick stubs, which means that they are completed by the first
+line that is not an L6.
+ The third stub (20-31) illustrates how an abstract data type can be
+implemented. The stub is an ordinary one with one slot - identified as "*
+DECLARATIONOFCODEINFO*" - at line 30. The slot is by default satisfied with the
+stub at lines 34-36. But this declaration will be replaced by a new one at some
+time in the future.
+
+
+3.4 Example 4: An ordinary refinement step
+
+ Body of VAMP:
+ The input-files will be processed sequentially in the same order as
+ given by the user. The intermediate file "VAMP.TMP" is guarded by a
+ sentinel to simplify backspacing later on and it needs an additional
+ global declaration.
+
+
+ 1 (*********** Simple types of the VAMP-system ************)
+ 2 FTYPE = FILE OF CHAR;
+ 3 (****************** End of declaration ******************)
+
+
+ Now the body of VAMP expands to
+
+ 4 (********************** VAMP (body) **************************)
+ 5 [INHERIT ('SYS$LIBRARY:STARLET.PEN', 'DECLAR.PEN')]
+ 6 PROGRAM VAMP (INPUT, OUTPUT);
+ 7
+ 8 (***************** Constants of VAMP (#mult) *****************)
+ 9 (***************** Types of VAMP (#mult) *********************)
+ 10 VAR
+ 11 FILE_CNT: 1..UPB_IN_FILES;
+ 12 CURR_IN_FILE: TEXT; (* Currently read file. *)
+ 13 CODE_LINES: FTYPE; (* From input extracted code. *)
+ 14 TTY_DATA: TTY_INFO;
+ 15 CODE_STRUCT: CODE_INFO;
+ 16 (************ Variables of VAMP (#mult) ******************)
+ 17
+ 18 [EXTERNAL] PROCEDURE ASKTTY (VAR TTY_DATA: TTY_INFO); EXTERN;
+ 19 (*************** Functions of VAMP (#mult) *******************)
+ 20
+ 21 BEGIN
+ 22 (* Take the data, that are needed for this VAMP run from *)
+ 23 (* the terminal. *)
+ 24 ASKTTY (TTY_DATA);
+ 25 WITH TTY_DATA DO
+ 26 IF GO THEN
+ 27 BEGIN
+ 28 (********************* VAMP (C) **********************)
+ 29 (** Initialize CODE_STRUCT. **)
+ 30 (*******************************************************)
+ 31
+ 32 OPEN (CODE_LINES, FILE_NAME :='VAMP.TMP',
+ 33 ORGANIZATION := RELATIVE, ACCESS_METHOD := DIRECT,
+ 34 DISPOSITION := DELETE);
+ 35 REWRITE (CODE_LINES);
+ 36 FILE_CNT := 1;
+ 37 WHILE (IN_FILES [FILE_CNT] <> EMPTY) DO
+ 38 BEGIN
+ 39 WRITELN ('Proceeding on file ',IN_FILES [FILE_CNT]);
+ 40 OPEN (CURR_IN_FILE, FILE_NAME := IN_FILES [FILE_CNT],
+ 41 HISTORY := READONLY);
+ 42 RESET (CURR_IN_FILE);
+ 43 PUT (CODE_LINES); (* Start file with a sentinel. *)
+ 44
+
+
+ 45 (****************** VAMP (A) *********************)
+ 46 (** Build CODE_STRUCT and fill CODE_LINES by a **)
+ 47 (** scan of CURR_IN_FILE, using the information **)
+ 48 (** of MODULES, DFLT_EXT and INV_MODE. **)
+ 49 (***************************************************)
+ 50
+ 51 CLOSE (CURR_IN_FILE);
+ 52 FILE_CNT := FILE_CNT + 1;
+ 53 END (*WHILE*);
+ 54
+ 55 (******************** VAMP (B) ***********************)
+ 56 (** Generate the files as specified by CODE_STRUCT **)
+ 57 (** from the data contained by CODE_LINES. **)
+ 58 (*******************************************************)
+ 59
+ 60 (* Close and Delete scratch-file CODE_LINES. *)
+ 61 CLOSE (CODE_LINES, DELETE);
+ 62 END
+ 63 ELSE
+ 64 WRITELN ('!!! You specified an empty run - try again !!!');
+ 65 END (*VAMP*).
+ 66 (******************* End of VAMP (body) **********************)
+ 67
+ 68
+ 69 (************ Constants of VAMP (#leader, #quick) ************)
+ 70 CONST
+ 71 (************ Types of VAMP (#leader, #quick) ****************)
+ 72 TYPE
+
+Remarks:
+ This refinement contains four stubs (lines 1-3, 4-66, 69-70 and 71-72). The
+second stub has seven slots (lines 8, 9, 16, 19, 28-30, 45-49 and 55-58). Lines
+22, 23 and 60 are simple code-lines from CLiPs point of view.
+ The leader option of the last two stubs defines the code that will be
+inserted in front of a stub that matches the slot.
+
+
+3.5 Example 5: A subroutine module
+
+ 1 (****** #File "ASKTTY.PAS" ******)
+ 2 [INHERIT ('DECLAR.PEN')] MODULE ASKTTY (INPUT, OUTPUT);
+ 3
+ 4 (*********** External procedures of ASKTTY (#mult) ************)
+ 5
+ 6 (***************************************************************)
+ 7 (* Routine: ASKTTY - ASK information from TTY. *)
+ 8 (* Purpose: To obtain from the TTY the information which *)
+ 9 (* is needed to perform a VAMP run. *)
+ 10 (* Interface: TTY_DATA - Data from TTY to VAMP. *)
+ 11 (* TTY - Source of all knowledge. *)
+ 12 (* Author/Date: VAMP project management, September 29, 1983. *)
+ 13 (***************************************************************)
+ 14 [GLOBAL] PROCEDURE ASKTTY (VAR TTY_DATA: TTY_INFO);
+ 15
+ 16 (************* Constants of ASKTTY (#multiple) ***************)
+ 17 (************* Types of ASKTTY (#multiple) *******************)
+ 18 (************* Variables of ASKTTY (#multiple) ***************)
+ 19 (************* Procedures of ASKTTY (#multiple) **************)
+ 20
+ 21 BEGIN
+ 22 WITH TTY_DATA DO
+ 23 BEGIN
+ 24 (******************** ASKTTY (1) *********************)
+ 25 (** Get IN_FILES from TTY. **)
+ 26 (*******************************************************)
+ 27
+ 28 GO := NOT (IN_FILES[1] = EMPTY);
+ 29 IF GO THEN
+ 30 BEGIN
+ 31 (**************** ASKTTY (2) *********************)
+ 32 (** Ask which modules must be generated by VAMP. **)
+ 33 (** Set INV_MODE, MODULES and GO accordingly. **)
+ 34 (***************************************************)
+ 35 END (*IF*);
+ 36 IF GO THEN
+ 37 BEGIN
+ 38 (**************** ASKTTY (3) *********************)
+ 39 (** Ask DFLT_EXT from the terminal. **)
+ 40 (***************************************************)
+ 41 END (*IF*);
+ 42 END (*WITH*);
+ 43 END (*ASKTTY*);
+ 44
+ 45 END (*MODULE*).
+ 46 (********************** End of MODULE ************************)
+ 47
+ 48
+ 49 (********** Constants of ASKTTY (#leader, #quick) ************)
+ 50 CONST
+
+
+ 51 (********** Types of ASKTTY (#leader, #quick) ****************)
+ 52 TYPE
+ 53 (********** Variables of ASKTTY (#leader, #quick) ************)
+ 54 VAR
+
+Remarks:
+ A clear cut example of a subroutine definition in VAX/VMS Pascal that is to
+be compiled independently. The refinement contains stubs at lines 1-46, 49-50,
+51-52 and 53-54. The last three stubs are all quick stubs.
+ The first stub is a main stub. It carries no identification and only
+specifies the name of the file that will finally hold the module. Had the
+file-option be omitted, this would have meant an error.
+ Lines 4, 16, 17, 18 and 19 are single-line slot for future declarations.
+The leader stubs at the end secure syntactic details. Lines 24-26, 31-34 and
+38-40 are ordinary slots again.
+
+
+4 Semantics of options
+
+#Comment (stub, slot)
+ The comment option transforms the special CLIP-characters to a predefined
+ format which suits a particular programming language. The option has an
+ obligatory argument, e.g. PASCAL, FORTRAN, C, ADA etc. or ON/OFF. The
+ ON/OFF argument specifies wether or not the slot- or stub-segment is to be
+ included upon substitution. Comment options can be nested and the most
+ local version controls the operation.
+
+#Default (stub)
+ A default stub is prefixed to exclusively substituted if no other stub is
+ found for that particular slot.
+
+#Indent (stub, slot)
+ The indent option controls the indentation of the generated listing. Indent
+ options can be nested and the most local option overrules the more global
+ ones. Indent has as one optional argument, ON or OFF.
+
+#File (stub)
+ The file option identifies the stub as a main stub (viz. the root of a new
+ module). The option carries a string in quotes as argument. This string
+ specifies the name of the file to be generated.
+
+#Leader (stub)
+ The leader stub is usually combined with multiple slots. It modifies the
+ environment of the stubs that will be substituted by inserting the leader
+ stub in front of the first encountered normal stub.
+
+#Multiple (slot)
+ A multiple slot accepts the substitution of any number of stubs.
+
+#Optional (slot)
+ An optional slot accepts the substitution of 0 or 1 stubs only.
+
+#Overrule (stub)
+ The overrule stub replaces the stub already substituted in a particular
+ position. It is mainly meant for testing purposes.
+
+#Quick (stub)
+ A quick stub is a stub without internal structure (viz. slots). Following
+ the stub segment only L6-type lines are allowed. Any other type of line
+ will end the stub.
+
+#Separator (stub)
+ A separator stub is to be inserted between two consecutive stubs of the
+ same slot.
+
+#Trailer (stub)
+ The trailer stub is the counterpart of the default stub. It modifies the
+ environment by adding the trailer stub after the last encountered normal
+ stub.
+
+
+5 Using CLiP
+
+The complete CLiP system for DOS and VMS consists of two independent programs,
+CLIP_1.EXE and CLIP_2.EXE. The Unix version has only one program, CLIP, which
+is functionally identical to CLIP_2. CLIP_1 prepares a file, CLIP.INI, telling
+CLIP_2 (the actual module extractor) literally everything it has to know in
+order to perform a run (a detailed description of the structure of an INI-file
+is in the next section). Thus CLIP.INI specifies to CLIP_2 (CLIP):
+ - the files it has to read (i.e. the source files),
+ - the modules it should extract (i.e. target modules),
+ - the name of the report file,
+ - the syntax of the CLiP-lines (i.e. the style of the lines that trigger
+ the module extraction process).
+CLIP_1 allows a very detailed specification of the extraction process, much
+more detailed than you will need in general. For this reason the CLiP system
+comes with a couple of routines to shortcut CLIP_1 and for Unix users these
+routines are the primary tool to construct their INI-file. For a description of
+these routines we refer to section "Using CLiP" of the READ_ME file of this
+release.
+ When using CLiP it is recommended to introduce at least the following
+directories:
+ - A directory for the source files CLiP will use. This directory also
+ holds the various INI-file you maintain to conduct the extraction
+ process.
+ - A directory to contain the extracted modules.
+ - A directory to contain the results of the compilation and linking of
+ the modules.
+ - In case CLiP is used in combination with a word-processor, it is wise
+ to keep the word-processor files again in a separate directory. In this
+ case the source file directory should be fed with ASCII exports from
+ word-processor files.
+
+
+6 The structure of an INI-file
+
+This section explains the structure of an INI-file by means of an example file.
+You should understand this structure thoroughly before your try to edit
+INI-files yourself directly through an editor [Ammers 1993].
+ The example is an INI-file for MS-DOS. The only difference with other
+platforms is the specification of directories. The numbers at the beginning of
+every line are added for convenience of reference. They are not part of the
+file itself.
+
+ <================= Example of an INI-file ====================>
+ 1 This file contains data that is needed to run CLiP
+ 2 And is generated by CLiP_MENU
+ 3 Modifying this file at own risk.
+ 4 Using CLiP_MENU is definitely recommended.
+ 5
+ 6 INTERACTIVE_MODE Mode (INTERACTIVE/DEBUG/HELPFUL/AUTO)
+ 7 NO Interactive fault correction (YES/NO)
+ 8 BOTH Error message destination (TERMINAL/......)
+ 9 (* Left comment string
+ 10 *) Right comment string
+ 11 * Command character
+ 12 ENDOF END string
+ 13 # Option marker
+ 14 EXTRACTED The specified modules are (OMITTED/EXTRACTED)
+ 15 ------------ REPORT FILE -----------
+ 16 CLIP.RPT
+ 17 ------------ INPUT FILES -----------
+ 18 f:\LPT\MAN\EX01_A.ASC
+ 19 f:\LPT\MAN\EX01_B.ASC
+ 20 ------------ MODULES ---------------
+ 21 F:\TEST\
+ 22 PALINDRO.PAS
+ 23 F:\TEST\
+ 24 TESTDATA.IN
+ 25 ------------ MODULE DIRECTORY ------
+ 26 f:\LPT\
+ 27 ------------ END OF INI FILE -------
+ <================= End of Example INI-file ===================>
+
+Lines 1-5: Descriptive lines that are flushed upon reading.
+
+Lines 6-14: Information behind position 24 is not interpreted.
+
+Lines 6-7: These lines refer to unimplemented options. They should not be
+ changed.
+
+Lines 8: Identifies the output device for messages and reports. The first
+ word of the line must be on of the following keywords TERMINAL,
+ REPORTFILE (or FILE), BOTH or NONE and we assume the meaning self
+ evident.
+
+Lines 9-13: These lines together define the syntax of the lines CLiP will
+ recognize. For an explanation of the CLiP syntax, refer to [Ammers
+ 1993].
+
+
+Lines 9: At most 6 characters to specify the "left comment string" i.e. the
+ opening sequence of a comment string of the programming language
+ you want to use. The characters cannot be letters (A-Z, a-z),
+ digits (0-9) or a dot (.).
+
+Lines 10: At most 6 characters to specify the "right comment string" i.e.
+ the closing sequence of a comment string of the programming
+ language you want to use. The characters cannot be letters (A-Z,
+ a-z), digits (0-9) or a dot (.).
+
+Lines 11: The character that is postfixed to a left comment string and
+ prefixed to a right comment string in order to identify it as a
+ special comment that CLiP has to process, a so called CLiP-line.
+ The character cannot be a letter (A-Z, a-z), a digits (0-9) or a
+ dot (.).
+
+Lines 12: The leading characters that identify a particular CLiP-line as the
+ end of a stub, i.e. a particular section that can be substituted
+ elsewhere.
+
+Lines 13: The character that identifies the options.
+
+Line 14: Relates to the modules in the module section below. The specified
+ modules must either be extracted or omitted and the first word of
+ this line can only be OMITTED or EXTRACTED.
+
+Line 15: Starts the section defining the file that mirrors the extraction
+ process. This line should be copied literally.
+
+Line 16: Path and file specification of the report file.
+
+Line 17: Starts the section defining the input files for the extraction
+ process, the so called source files. This line should be copied
+ literally.
+
+Line 18-19: Every line specifies a path and source file. There may be up to 64
+ lines in this section.
+
+Line 20: Starts the section defining the modules that are considered during
+ the extraction process. Whether the modules are extracted or
+ omitted depends on line 14. This line should be copied literally.
+
+Line 21-24: Every line pair specifies a path and a module file. There may be
+ up to 64 pairs (128 lines) in this section.
+
+Line 25: Starts the section to identify the default directory for modules,
+ i.e. the directory where modules go to that have no explicit
+ directory specified by the MODULES section. This line should be
+ copied literally.
+
+Line 26: Default directory for extracted modules.
+
+Line 27: Identifies the end of the INI-file. This line should be copied
+ literally.
+
+
+7 Bugs, work-arounds and undocumented features
+
+7.1 "SP_EXTR_STR: system failure .... call maintenance"
+
+This failure may happen if the stubs have not been correctly closed with the
+END-STRING that has been specified as the syntax. The default value of this
+string is "ENDOF". Also the line containing the END-STRING should be properly
+closed. For example in a Pascal situation
+
+ (********* End of module (2.1) ***)
+
+should be all right, but
+
+ (****** End of module (2.1) **)
+
+may give trouble since the string "**)" is incorrect here.
+
+7.2 Options in general
+
+Several options have been introduces with very advanced applications in mind.
+They have hardly been tested will probably not work. You won't need them
+either. For this reason don't use the options OVERRULE, SEPARATOR and TRAILER.
+
+7.3 Multiple option
+
+A slot with the "MULTIPLE" option raises an error if no stubs are found
+matching the slot. To prevent this error message one should specify the option
+"OPTIONAL" also for the slot.
+
+7.4 Report file option NONE
+
+This option to suppress the printing of reports to the terminal has not been
+implemented. It will be eliminated in some later version.
+
+7.5 Generating target modules
+
+7.5.1 Specification
+
+If CLIP.INI specifies a target module that matches no file-option argument
+anywhere in the list of specified source files, CLiP does not complain. The
+matching is case sensitive and for instance a file-option argument
+
+ (********** #file "EXAMPLE.PAS" ***********************)
+
+does not fit a module specification in CLIP.INI of the form
+
+ Example.PAS
+
+This may lead to unpleasant surprises.
+ On MS-DOS and VAX/VMS platforms the specification of files is not context
+sensitive. For this reason the CLIP_1 program (which is available for the
+MS-DOS and VAX/VMS versions of CLiP) converts those names to upper case in the
+INI-file it creates. Thus the file-option arguments in the source files should
+definitely be specified in upper case too.
+ In a Unix environment a file name is case sensitive indeed. Currently no
+CLIP_1 exists for Unix and an INI-file has to be created by means of the
+short-cut routine CLP (or directly by means of an editor, cf. section 6). No
+conversion is performed in this case and one has to make sure the file-option
+argument is identical to the corresponding name in the INI-file.
+
+
+7.5.2 Omitted modules
+
+If modules are specified for being OMITTED at extraction time, it will be
+omitted independent of the path that may have been specified. The module will
+never be generated.
+
+7.5.3 Empty run
+
+CLiP does not always recognize a corrupted INI-file. Thus if you run CLiP and
+it produces a report of the form
+
+ ============================ CLiP version 2.1 ==========================
+
+ ============================ Busy scanning =============================
+ Scanning file: ..................
+ .................................
+
+ ============================ End scanning ==============================
+
+ ============================ Busy analysing ============================
+
+ ============================ End analysing =============================
+
+ ============================ Busy generating ===========================
+
+ ============================ End generating ============================
+ Used (CPU) time :5.88 Sec.
+ See you next time !
+
+then you start checking the specifications of the target modules, since this is
+the most likely source of trouble. Keep in mind however, that the problem may
+be also arise due to a corrupted INI-file.
+
+7.6 Lost lines
+
+If you have stubs of the form
+
+ (****************** GEN_POOL global routines ********************)
+ (******************************************************************)
+ (* routine: write_string .... *)
+ (* ................... *)
+ (******************************************************************)
+
+you will see that the second line of the stub (the "starred" line) is not
+generated in the target modules. For this reason it is better to put an
+additional empty line in between. For example the following stub will be
+extracted correctly.
+
+ (****************** GEN_POOL global routines ********************)
+
+ (******************************************************************)
+ (* routine: write_string .... *)
+ (* ................... *)
+ (******************************************************************)
+
+
+7.7 DOS version only
+
+If you activate the PROJECT/Load INI-file or PROJECT/Save INI-file menu of the
+CLIP_1 program and you specify an illegal drive in the Current Directory
+option, you may hang the system. For instance a drive specification preceeded
+by a space will produce this bug.
+
+
+8 References
+
+Ammers E.W. van, M.R. Kramer (1993), The CLiP Style of Literate Programming
+ (submitted for publication). Anonymously ftp-able as CLIP_STYLE.PS,
+ CLIP_STYLE_A.PS and CLIP_STYLE_B.PS from directory CLIP on
+ sun01.info.wau.nl.
+
+Ammers E.W. van, Kramer M.R. (1992), VAMP: A Tool for Literate Programming
+ Independent of Programming Language and Formatter. CompEuro '92
+ Proceedings, May 4-8 1992, the Hague, pg. 371-376.
+
+Knuth D.E. (1984). Literate Programming. The Computer Journal 27, 2, 97-111.