summaryrefslogtreecommitdiff
path: root/web/clip/unix/read_me.txt
diff options
context:
space:
mode:
Diffstat (limited to 'web/clip/unix/read_me.txt')
-rw-r--r--web/clip/unix/read_me.txt148
1 files changed, 148 insertions, 0 deletions
diff --git a/web/clip/unix/read_me.txt b/web/clip/unix/read_me.txt
new file mode 100644
index 0000000000..868cd91647
--- /dev/null
+++ b/web/clip/unix/read_me.txt
@@ -0,0 +1,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.