summaryrefslogtreecommitdiff
path: root/web/clip/ms_dos/read_me.txt
blob: 634de1834906da42501aa14e19e366ca0c1cb087 (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

                           READ_ME for CLIP/MS_DOS
                           ***********************



1  Directory CLIP/MS_DOS

The directory contains the files
    a.  READ_ME.PS, READ_ME.TXT (this file).
    b.  CLIP_1.EXE, CLIP_2.EXE, CLIPHELP.HLP, CLIP_MSG.DAT (CLiP system).
    c.  CL.BAT, CLP.BAT, CLIP.BAT, CLP_ENV.BAT (user support).
    d.  EX01_A.PS, EX01_A.ASC, EX01_A.INI, EX01_A.PAS,
        EX01_B.PS, EX01_B.ASC, EX01_B.INI, EX01_B.PAS (example).
    e.  ADA.INI, C.INI, FORTRAN.INI, LISP.INI, MODULA.INI, PASCAL.INI
        (template INI-files for some languages).
    f.  MANUAL.PS, MANUAL.TXT (manual).
File extensions:
    PS-files are postscript files and represent the type-set versions of the
    corresponding ASC- or TXT-files.
    ASC-files are derived by ASCII-export from the original word-processor
    files (in our case Lotus Manuscript).
    TXT-files are ASCII versions of the corresponding PS-files. They are
    slightly modified to improve the lay-out. TXT-files are a service for
    people who have no easy access to a postscript printer.

2  Installing CLiP

    a.  Use FTP to copy the CLiP system to your local site. Note that
        CLIP_1.EXE, CLIP_2.EXE and CLIPHELP.HLP should be FTP-ed in binary
        mode.
    b.  Create a directory for the CLiP-system. This directory will be
        referred as the CLIP_DIR. Let us assume this directory is
            C:\CLIP
    c.  Copy the files
            CLIPHELP.HLP, CLIP_1.EXE, CLIP_2.EXE and CLIP_MSG.DAT
        to the CLIP_DIR.
    d.  Copy the files
            CL.BAT, CLP.BAT, CLIP.BAT, CLP_ENV.BAT
        to the directory that contains your batch files (this directory is
        assumed to be in the PATH definition of the AUTOEXEC.BAT).
    e.  If the name of your CLIP_DIR differs from the name "C:\CLIP" as
        suggested in point 2.a, the batch files
            CL.BAT, CLP.BAT and CLIP.BAT
        have to be adjusted. That is the string "C:\CLIP" has to be replaced
        by a string representing the correct name of your CLIP_DIR.

3  A quick installation test

To have a partial test (it does not check CLIP_1) to see if your CLiP system
has been properly installed, perform the following steps:
    a.  Choose a test directory and make it current. Let us assume "C:\TEST".
    b.  Copy the files EX01_A.ASC, EX01_B.ASC, EX01_A.INI, EX02_B.INI,
        EX01_A.PAS and EX01_B.PAS to this test directory.
    c.  Type the command
            >CL EX01_A.INI
        to produce the file PALINDRO.PAS. Note that EX01_A.INI specifies the
        current directory for the source files as well as for the target
        modules.


    d.  Compare the file PALINDRO.PAS with EX01_A.PAS by means of the command
            >COMP PALINDRO.PAS EX01_A.PAS
        There should be no differences.
    e.  Now type the command
            >CL EX01_B.INI
        to produce a new file PALINDRO.PAS.
    f.  Compare the new PALINDRO.PAS with EX01_B.PAS
            >COMP PALINDRO.PAS EX01_B.PAS
        Again there should be no differences.

4  What you should know

The complete system executes in two passes.
    The second pass, CLIP_2.EXE, performs the actual module extraction. It is
guided by a file, CLIP.INI, which tells it literally everything it has to know
in order to perform a run. Thus CLIP.INI specifies to CLIP_2.EXE:
    -   the files it has to read (i.e. the source files),
    -   the modules it should extract (i.e. target modules),
    -   the report file,
    -   the syntax of the CLiP-lines (i.e. the lines which trigger the module
        extraction process).
CLIP.INI is a straight forward ASCII-file. Its fairly simple structure is
explained in section 6 of the manual.
    The responsibility of the first pass of the CLiP-system, CLIP_1.EXE, is
purely to construct an appropriate INI-file for the task you want CLIP_2 to
perform. More often than not the first pass can be short-cut and several batch
files are supplied for this reason (see section 5).

5  Using CLiP ...

The batch procedures below are designed to make your working directories
independent of the CLIP_DIR. Remark that the original batch files assume that
your CLIP_DIR is the directory "C:\CLIP".

5.1  ... via CLIP.BAT

CLIP.BAT performs the complete cycle to define and execute a run of CLiP. Thus
both passes of CLiP are executed by this command. The procedure gives the user
complete control over the extraction process and supplies context sensitive
HELP when asked. The procedure works most comfortable when a mouse is
available.

PROJECT menu allows your to LOAD an already existing INI-file or to SAVE the
        one you have defined so far. In addition you can start the extraction
        process from here.

SETTINGS/SOURCEFILES allows you to define the sources files that CLiP has to
        include in the extraction process. The source files may reside in
        different directories.

SETTINGS/TARGETMODULES lets you specify which modules you want to be extracted.
        The names of modules you put in the list are used either to identify
        the modules that have to be extracted (in which case you set the
        radiobutton EXTRACTED) or the modules that have to be omitted during
        the extraction process (in which case you set of course the radiobutton
        OMITTED). The default is OMITTED which of course implies that if no
        modules are listed, CLiP will extract every module it finds.


SETTINGS/PARAMETERS refers partly to non implemented features. Therefore don't
        touch the CLIP_MOD radiobuttons and forget about the INTERACTIVE FAULT
        CORRECTION. If you want error messages to be filed, you have to specify
        the report file in this menu.

SETTINGS/SYNTAX allows you to change the appearance of the lines that trigger
        the CLiPping process. By LOADing an appropriate INI-file (like
        PASCAL.INI, C.INI, MODULA.INI or FORTRAN.INI) you have an adequate
        suggestion for that particular language. The choice SHOW SYNTAX
        displays the way CLiP lines will look.

5.2  ... via CLP.BAT and CLP_ENV.BAT

This procedure can be used in a situation where on wants to extract all the
modules from up to nine source files. The source files are passed as
parameters. CLP.BAT creates a CLIP.INI file and starts the CLIP_2 program
afterwards.
    All setting are assumed by the batch procedure. Originally it is tailored
to Pascal programs of the sort displayed in the example EX01 (i.e. the files
EX01_?.*) on the directory CLIP. To adjust CLP.BAT one should sufficiently
understand the syntax of CLiP [Ammers 1993]. Only modify the lines of CLP.BAT
as follows

    line 16: Replace "(*"       with the COMM-START of your choice.
    line 17: Replace "*)"       with the COMM-END of your choice.
    line 18: Replace "*"        with the CLIP-CHAR of your choice.
    line 19: Replace "ENDOF"    with the END-STRING of your choice.
    line 20: Replace "#"        with the OPTION-MARKER of your choice.
    line 23: Replace "CLIP.RPT" with the report file name of your choice.

Note that the characters "a"-"z", "A"-"Z", "0"-"9" and "." do not qualify as
characters for COMM-START, COMM-END, CLIP-CHAR or OPTION-MARKER while the
END-STRING should be chosen from letters only.
    If you are not sure of your modifications, you should compare the INI-file
produced by CLP.BAT with the one that CLIP.BAT produces from the same set of
preferences.
    CLP.BAT must know the directory of the source files and the directory of
the target modules. This information is taken from the environment variables
CLIP_SRC and CLIP_TRG that can be set using CLP_ENV.BAT. Note that the
directories must be specified excluding the trailing backslash. For example
        >CLP_ENV  D:  C:\PROJECT\PASCAL
defines the home directory of drive D: as source file directory while the
subdirectory PASCAL of directory PROJECT on drive C: will receive the extracted
modules.

5.3  ... via CL.BAT

CL.BAT is the fastest way to run CLiP and will probably be invoked most often.
It can be used whenever an INI-file already is available. It copies the
information of the specified INI-file to CLIP.INI and runs the CLIP_2 program.
    The INI-file to be used is passed as an optional parameter. If no INI-file
is specified, CL.BAT simply assumes CLIP.INI. For example
        >CL EX01_A.INI
will copy the file EX01_A.INI to CLIP.INI and run CLIP_2. However the command
        >CL
immediately runs CLIP_2 on the basis of an already existing CLIP.INI file.


6  Specimen INI-files

The files ADA.INI, C.INI, FORTRAN.INI, LISP.INI, MODULA.INI and PASCAL.INI
suggest a suitable CLiP syntax for a start. To customize such an INI-file run
the CLiP system through CLIP.BAT. Then load the proper INI-file and modify the
syntax by means of the SETTINGS/SYNTAX menu (see sect. 5.1).

7  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.