Next: About this document ...
Up: APPENDIX E: Manipulating the
Previous: Documentation
Subsections
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.
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 ++++.
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 which is this text, was prepared from the latex file
$CCSL/doc/texes/appene.tex using LATEXfollowed by
LaTeX2HTML
(see below).
Note that LATEX2HTML 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 CCSL mk4 users' manual has been written in LATEX, using some special
LaTeX2HTML LATEX2HTML will also need to find the
style file html.sty, which is part of the LATEX2HTML 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
Next: About this document ...
Up: APPENDIX E: Manipulating the
Previous: Documentation
P.J. Brown - Institut Laue Langevin, Grenoble, FRANCE. e-mail: brown@ill.fr