README March 1, 1996 SYSDOC SYStem DOCumentation Program SYSDOC - Version 1.0 1996/03/01 sysdoc1.0.DGUX.tar.gz - Distribution prepared on a Data General AViiON under DG/UX 5.4 sysdoc1.0.source.tar.gz - Distribution that includes the source code but no compiled software TABLE OF CONTENTS A. DESCRIPTION B. DOCUMENTATION C. EXTRACTING FILES D COMPILING E. INSTALLING F. RUNNING THE PROGRAM G. TESTING H. CONTACTS A. DESCRIPTION The System Documentation program (SYSDOC) is used to produce detailed documentation for Fortran 77 software that conforms to a style described in the documentation. SYSDOC produces text files that summarize programs, subroutines, functions, and common blocks and documents all links between them. B. DOCUMENTATION Flynn, K.M., Kittle, J.L., Jr., and Lumb, A.M., 1994, A Fortran coding convention for use in the U.S. Geological Survey, Water Resources Division: U.S. Geological Survey Open-File Report 94-501, 64 p. C. EXTRACTING FILES Compressed tar files are used to distribute pre-compiled versions of the software and the source code. All of the files needed to install sysdoc1.0 are contained in the files sysdoc1.0.______.tar.gz (where ______ is a string indicating the file contains either the source code or a pre-compiled version of the program for the indicated operating system). The source version of the tar file contains the source code and all other files needed to compile and install the software on a UNIX-based computer. For either type of distribution, the directory sysdoc1.0 will be created (or overwritten) when the files are extracted from the tar tape. If the sysdoc1.0 directory already exists, you may want to delete or rename it before extracting the files. The following are the steps to extract the files from a distribution tar file. Steps in extracting files explanation --------------------------------------- ----------------------------------- mv sysdoc1.0.____.tar.gz /usr/opt/wrdapp If the tar file is not already in the directory where you want the distribution installed, move it there. cd /usr/opt/wrdapp If you are not in the directory where the tar file is located, go there. gunzip sysdoc1.0.____.tar.gz Uncompress the distribution file. tar xf sysdoc1.0.____.tar Extract the distribution files from the tar file. This creates the following directory structure (the contents of each directory are shown to the right): sysdoc1.0 copy of this README file `-----bin compiled executable `-----bin_data information file required during execution `-----doc documentation files (see file Contents) `-----src Makefile (and, with source tar, the source code) `-----test scripts to run verification tests `-----data standard data sets used in verification tests Notes: a) The bin subdirectory is not included in the distribution of sysdoc1.0.source.tar.gz, it is created during compilation. b) Source code is included only with the sysdoc1.0.source.tar.gz distribution. c) It is recommended that no user files be kept in the sysdoc1.0 directory structure. If you plan to put files in the sysdoc1.0 directory structure, do so only by creating subdirectories under sysdoc1.0. d) The software is configured for installation under the directory /usr/opt/wrdapp. The wrdapp directory may be a separate file system mounted at /usr/opt/wrdapp. If you choose to install the software elsewhere, you will need to retrieve the source version of the tar file and compile the software. e) To compile a new version of the software, you will also need: (1) libraries and other data files from the lib3.0 library (lib3.0.______.tar.gz), and (2) ANSI-compliant Fortran 77 compiler. D. COMPILING If you have retrieved a pre-compiled distribution of the software, skip to the Installing section below. If a compiled version of the software is not available for your computer, or if you want to build the executable yourself, follow the instructions in this section. The source code is provided in the sysdoc1.0.source.tar.gz distribution so that users can generate the executable themselves. Little or no support can be provided for users generating their own versions of the software. In general, the requirements are ANSI-compliant Fortran 77 and a minimum level of knowledge of the compiler and the UNIX operating system. Libraries and data files from the lib3.0 distribution are also required. As provided, the make file and source code are set up for use on Data General AViiON workstations running the DG/UX operating system. To generate the executable and message file, do the following: 1. The values for the indicated variables in the following sysdoc1.0 files may need to be modified (see the file sysdoc1.0/doc/versions.doc for more details): may need to be modified ----------------------- version compiler file name variables flags name --------------------- --------- ------------ src/Makefile WrdA FFLAGS F77 fsysdc.inc INTFIL psort.inc LENARY bin_data/sysdoc.int intrinsics test/test.sh WrdA 2. Run the Makefile program in the src directory to compile the source and build the message file. In the directory sysdoc1.0/src, run the make: cd sysdoc1.0/src make The sysdoc1.0/src/Makefile will: a. Create the directories sysdoc1.0/bin if it does not already exist. b. Compile the source code and place the sysdoc executable in the directory sysdoc1.0/bin. E. INSTALLING To make the sysdoc program easy to use, it should be installed in a directory included in the user's search path. The Makefile in sysdoc1.0/src contains instructions to optionally place a link in a specified directory to the executable contained in sysdoc1.0/bin. Use the following commands to do this: cd sysdoc1.0/src make install [BINDIR=bin_path] where bin_path is the name of a directory in the user's search path. If BINDIR is specified, a link to the executable (sysdoc1.0/bin/sysdoc) is placed in the specified directory. If BINDIR is not specified, no link is set and the full pathname of the executable is required to run the program. For example, if the search path is /usr/bin:/usr/opt/bin:/usr/local/bin, you can use the following command to install the program: make install BINDIR=/usr/local/bin Notes: a) Brackets "[xxx]" are used to indicate optional arguments to commands. b) To create and delete links to the sysdoc executable, the installer must have sufficient rights to the BINDIR directory. F. RUNNING THE PROGRAM After the sysdoc executable is properly installed (see Installing, above) in a directory that is included in the user's PATH, the program can be executed with the command "sysdoc". G. TESTING Test data sets are provided to verify that the program is correctly installed and running on the system. The tests may also be looked at as examples of how to use the program. The directory sysdoc1.0/test contains the scripts to run the tests. The directory sysdoc1.0/data contains the input data and the expected results for each test. Tests are usually run in the sysdoc1.0/test directory, but they can be run in any user directory. Type the following command to test the program installation: [path]/test.sh [start [stop]] where: path = path to the script use "." if running the tests in the sysdoc1.0/test directory use full pathname if not running the test in sysdoc1.0/test start = the number of the first test to perform default = 1 stop = the number of the last test to perform default = 2 For example: command what happens ------------------------------------- -------------------------------- ./test.sh runs all of the tests ./test.sh 1 1 runs the first test ./test.sh 2 2 runs test 2 /usr/opt/wrdapp/sysdoc1.0/test/test.sh runs all of the tests After the tests are completed, the results are compared to the expected results (found in sysdoc1.0/data). See the file check.out; if all goes well, there should be no differences. To clean up after the tests, type the command: ./clean.sh The tests are described in the table below, where 'test' is the test number, 'program' is the program used to run the test, and the 'usage' column indicates how a file is used, with i for input and o for output. test program description of test and files file name & usage ---- ------- --------------------------------- ----------------- 1 sysdoc Generates sysdoc reports for two code groups. Reports not page numbered and there is no index. Intermediate files are saved for test 2. list of source code to include test1.inp i code group, character utilities utilcc.f i code group, numeric utilities utilcn.f i cross reference for utilcc utilcc.XRF o cross reference for utilcn utilcn.XRF o intermediate file SDcall.t o intermediate file SDnam.t o intermediate file SDarg.t o intermediate file SDcuse.t o intermediate file SDcuse.t o intermediate file SDadef.t o intermediate file SDfrag.t o report for all processed routines test1.out o usage of intrinsics test1.int o usage of common blocks test1.com o usage of unknown routines test1.unk o 2 sysdoc Generate sysdoc reports for two code groups. Reports are page numbered and there is an index. Intermediate files saved from test 1 are used. list of source code to include test2.inp i intermediate file SDcall.t i intermediate file SDnam.t i intermediate file SDarg.t i intermediate file SDcuse.t i intermediate file SDcuse.t i intermediate file SDadef.t i intermediate file SDfrag.t i report for all processed routines test2.out o usage of intrinsics test2.int o usage of common blocks test2.com o usage of unknown routines test2.unk o alphabetical index test2.ina o sorted index test2.ins o H. CONTACTS Inquiries about this software distribution should be directed to: U.S. Geological Survey Hydrologic Analysis Software Support Team Kathleen M. Flynn e-mail: h2osoft@usgs.gov 437 National Center phone: 703-648-5313 Reston, VA 22092 fax: 703-648-5722