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 (******************* **********************) 2 (**************** End of ******************) 3 (** **) 4 (***************************************************************) 5 6 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 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 . 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 * *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.