diff options
Diffstat (limited to 'web/clip/unix/read_me.txt')
-rw-r--r-- | web/clip/unix/read_me.txt | 148 |
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. |