summaryrefslogtreecommitdiff
path: root/web/clip/ms_dos/manual.txt
blob: b7e319fd8f38bac6681fc222573ddbd87dd49920 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
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.