summaryrefslogtreecommitdiff
path: root/web/clip/unix/read_me.txt
blob: 868cd916478c28f8b694db9407c870393558b643 (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

                            READ_ME for CLIP/UNIX
                            *********************


1  Directory CLIP/UNIX

The directory contains the files
    a.  read_me.ps, read_me.txt (this file).
    b.  clip.pas, clip, CLIP_MSG (CLiP system).
    c.  cl.csh, clp.csh, clp_env.csh, (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).
About 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 is
        our own executable version of clip.pas, and it 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 named
                          ~/clip
    c.  Copy clip.pas to your CLIP_DIR and compile. Since it is written in
        ISO-Pascal there should be no problem. We use the Sun Pascal 2.0
        compiler under operating system SunOS 4.2 running on Sun4c (Sun1,
        Sun1+, Sun2) hardware. If you have problems you may want to try the
        binary version of clip.pas, clip, instead.
    d.  Copy the files CLIP_MSG, cl.csh, clp.csh and clp_env.csh to your
        CLIP_DIR. Make sure the file name CLIP_MSG is in uppercase.
    e.  Make the script files executable through the command
            % chmod  +x  *.csh

3  A quick installation test

To test if your CLiP system has been properly installed, perform the following
steps:
    a.  Choose a test directory. Let us assume ~/test.
    b.  Copy the files ex01_a.asc, ex01_b.asc, ex01_a.ini, ex01_b.ini,
        ex01_a.pas and ex01_b.pas to your test directory.
    c.  Type the command
            % cl ex01_a.ini
        to produce the file palindrome.pas. Note that ex01_a.ini locates the
        source files as well as the target modules in the current directory.
    d.  Compare the file palindrome.pas with ex01_a.pas by means of the
        command
            % diff palindrome.pas ex01_a.pas
        There should be no differences.


    e.  Now type the command
            % cl ex01_b.ini
        to produce a new file palindrome.pas.
    f.  Compare the new palindrome.pas with ex01_b.pas by means of the command
            % diff palindrome.pas ex01_b.pas
        Again there should be no differences.

4  What you should know

clip performs the actual module extraction on the basis of a special file,
CLIP.INI, which tells it literally everything it has to know in order to
perform a run. Thus CLIP.INI specifies to clip:
    -   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. It has a simple structure which is
explained in section 6 of the manual. In extreme situations you may want to
edit a CLIP.INI manually but in general it will be more convenient to use the
procedures cl.csh, clp.csh and clp_env.csh. These routines construct a CLIP.INI
for you and run clip immediately afterwards. They are adequate most of the
time.
    Whenever you decide to create an INI-file to accommodate your special
wishes, make sure you start from an INI-file you already know to be correct.
Also if you want to change the syntax CLiP recognizes, please study section 2
of the manual.
    A more extensive description of the CLiP system can be found in [1].

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 user/clip.

5.1  ... via clp.csh and clp_env.csh

These procedures if one wants to extract all modules from up to 8 source files
which are passed as parameters. First use clp_env.csh to define explicitly the
source file directory and the target module directory, for example
    % clp_env.csh  /user/test  /user/test
defines the subdirectory test from the directory user as directory for the
source files as well as for the target modules. With this setting the command
    % clp.csh  file1.asc  file2.asc  file3.asc
will process the files /user/test/file1.asc etc. and extract all modules it
encounters towards the directory /user/test.
    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.csh to another syntax one should
be familiar with section 2 of the manual. Only modify the following lines
clp.csh for this purpose:

    line 15: Replace (*        with the COMM-START of your choice.
    line 16: Replace *)        with the COMM-END of your choice.
    line 17: Replace *         with the CLIP-CHAR of your choice.
    line 18: Replace ENDOF     with the END-STRING of your choice.
    line 19: Replace #         with the OPTION-MARKER of your choice.
    line 22: 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.

5.2  ... via cl.csh

cl.csh 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 program.
    The INI-file to be used is passed as an optional parameter. If no INI-file
is specified, cl.csh simply assumes CLIP.INI. For example
        % cl ex01_a.ini
will copy the file ex01_a.ini to CLIP.INI and run clip. However the command
        % cl
immediately runs clip with the assumption that a CLIP.INI already exists.

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 clp.csh for such a
syntax, refer to the previous section and to section 6 of the manual.

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.