DOC_LIBRARY Procedure (UNIX/OpenVMS)

Standard Library procedure that extracts header documentation for user-written procedures and functions.

DOC_LIBRARY [, name]

name A string containing the name of the user-written module for which documentation is desired. The search for the file follows the current path in the system variable !Path.

Directory (UNIX only) The name of the directory to search. If this keyword is omitted, the current directory and !Path are used.

File (OpenVMS only) If present and nonzero, sends the output to the file userlib.doc in the current directory.

Multi (UNIX only) A flag that allows for the printing of more than one file. To do this, Multi must be nonzero and the named file must exist in more than one directory in the path.

Path (OpenVMS only) The directory/library search path. It has the same format and semantics as the system variable !Path. If this keyword is omitted, !Path is used.

Print A flag to direct the output:

• A value of 1 specifies the output from the procedure is to be sent to the default printer.

• A string value specifies a command to redirect the standard output.

• If the Print keyword is not used, documentation is sent to the standard output.

The first line of the header documentation must begin with the characters ; + and the last line of the header documentation must begin with the characters ; -. DOC_LIBRARY extracts all the information between the + and - characters. (Each line of the header must begin with the semicolon character to denote a comment line.)

DOC_LIBRARY is a useful tool for finding out what is available in the undocumented Users' Library. This procedure can be used to search each routine in the Users' Library and extract all the text that is bracketed by the + and the - characters. This includes the routine's name, purpose, category, calling sequence, inputs, outputs, and modification history.

DOC_LIBRARY checks to see what operating system you are using, and then calls the appropriate version DOC_LIB_UNIX or DOC_LIB_VMS.

Keywords allow you to have the output sent to a printer or displayed on the screen. If the procedure is called without keywords, you are prompted for specific information about the search.

When creating your own PV-WAVE routines, it is helpful to include a ; + as the second line in the file and a ; - as the last informational line so that DOC_LIBRARY can then be used to create documentation for the routine. An example of a file set up to use DOC_LIBRARY in this way is shown below. (All the information shown in bold will be extracted by DOC_LIBRARY.)

FUNCTION COSINES, x, m
;+
; NAME:
; COSINES
; PURPOSE:
; 	Example of a function to be used by SVDFIT. ;
; 	Returns COS(i*COS(x(j)).
; CATEGORY:
; 	Curve fitting.
; CALLING SEQUENCE:
; 	r = COSINES(x, m)
; INPUTS:
; 	x = vector of data values. n elements.
; 	m = order, or number of terms.
; OUTPUTS:
; 	Function result = (n,m) array,
; 	where n is the number of points in x,
; 	and m is the order. r(i,j) = COS(j * x(i))
; MODIFICATION HISTORY:
; 	DMS, Nov, 1987.
;-
ON_ERROR, 2 
;Return to caller if an error occurs.
RETURN, COS(x # FINDGEN(m)) 
;Couldn't be much simpler.
END

DOC_LIBRARY, 'gamma'

; On the screen, display the header for the gamma.pro procedure

; using the default search path.                        

DOC_LIBRARY, 'gamma', Print='cat  gamma_header'

; Print the header for gamma.pro to the file gamma_header.

DOC_LIBRARY, '*',directory=  $
    '$VNI_DIR/wave/lib/std',  $
    Print='cat  user_lib_headers'

; Print the headers for all the files located in the Users' Library.

DOC_LIBRARY, 'gamma'

; On the screen, display the header for the gamma.pro procedure

; using the default search path.

DOC_LIBRARY, 'gamma', /File

; Print the header for gamma.pro to the file userlib.doc.

INFO

System Variables: !Path