Installing the CCSL documentation

The Installdoc script must be edited so that its first line indicates where Perl is installed on your system.
eg ``#! /usr/sbin/perl" may need to be changed to say ``#! /bin/perl"

Executing the command ``Install" will then install these files in a directory structure rooted at the directory given as argument to the script, or at the current working directory if no argument is given. This should normally be $CCSL/doc. After intallation the doc directory should have subdirectories html, icons, and texes vis:
./doc:

0README	Installdoc	Makefile
html	icons	texes
./doc/html:
Contains html files needed to build the CCSL home page
./doc/icons:
Contains the set of gif images
./doc/texes:
CCSLapa.cls	Makeman	chap3.tex	chap7.tex
CCSLman.cls	appene.tex	chap4.tex	manual.tex
CCSLstyles.css	chap1.tex	chap5.tex
Makeappene	chap2.tex	chap6.tex
CCSLapa.cls	Makefile	appenx	mk4man
CCSLman.cls	appene.tex	icons

This directory will finally also contain postscript files of the manual and appendices. There will eventually be additional subdirectories:
./doc/appenx: Containing the HTML files for the appendices to the manual.
./doc/mk4man: Containing the HTML files for the the manual istelf.

The files CCSLman.perl, CCSLapa.perl and latex2html-init are copied to the HOME directory where they can be found by latex2html. latex2html-init may need to be edited to suit local conditions.

Auto-documentation of subroutines and programs

Each subroutine and program on the library contains its own internal documentation in the form of flagged comment lines included between the subroutine or program declaration and the begining of the other FORTRAN declarations and executable code. These lines start CX where X is one of the letters H, A, P, D, I, O, N and in addition, for main programs, R. The meaning of these tags is given in the second section of the master file: that flagged ++++.

Manual Appendices A, C and D

cp The perl script orfeus makes use of the above tags to construct appendices A and D to the mk4 manual. Orfeus also determines which modules calls which others, and which modules use which COMMON blocks. This information is assembled in appendices A, C and D. The appendices may be made as either or both of html and LaTeX files. The html version is fully cross-referenced which allows the usage of one module by another to be traced easily.
The appendices A, C and D in both LaTeX and html versions are made by the command
$CCSL_PERL orfeus mistre.ss both lib mai com
A LaTeX version of just appendix A could be made with the command:
$CCSL_PERL orfeus mistre.ss tex lib
but it would not include the called by references to main programs.
After running orfeus, and before running latex, the perl script mkindex should be executed to make the contents pages and indices for the appendices.
$CCSL_DOC/Makefile is a makefile to carry out the above steps. Issueing the command ``make all" from the $CCSL/doc directory will create appendices A, C D and E, it will also remake the MK4 manual if it is out of date with respect to the master file. Beware! this is a rather lengthy process.

Appendix E

Appendix E which is this text, was prepared from the latex file $CCSL/doc/texes/appene.tex using L^ATEXfollowed by LaTeX2HTML (see below). Note that L^ATEX2HTML uses the style file CCSLapa.perl to make appendix E. The make file for appendix E is $CCSL/doc/texes/Makeappene and the make command is ``make -f Makeappene all".

The MK4 manual

The CCSL mk4 users' manual has been written in L^ATEX, using some special LaTeX2HTML L^ATEX2HTML will also need to find the style file html.sty, which is part of the L^ATEX2HTML distribution, to allow LaTeX2HTML to build an html version. A printable postscript file can be obtained by running latex twice on manual.tex and then dvips on manual.dvi. The preparation of the html version is more complicated because of cross-references between chapters. The makefile Makeman included in $CCSL/doc will ensure that all the required files are up-to-date, and the html manual will be created in $CCSL/doc/mk4man with the base URL $CCSL/doc/mk4man/html/ccsldoc.html. Since the Appendices contain references to the manual, and the manual uses the lists of subroutines and programs prepared by orfeus it is recommended to run orfeus once, then make the manual, and finally to run orfeus again. This should be taken care of by using the makefiles. The whole process may be initiated from the directory $CCSL/doc by the command ``make all". Once all the documentation has been successfully compiled, unnecessary work files can be removed by executing ``make clean". The complete set of files created by make all can be removed by executing ``make clear".

In case of problems the documentation can be read from http://www.ill.fr/dif/ccsl/ccsldoc.html