[ Basic Info | References | User Guide ]
Basic Information on doc
Task: doc
Purpose: MIRIAD documentation program
Categories: tools
doc extracts on-line documentation and presents the output in a
variety of formats. Non-programmers need only use doc to display
formatted on-line documentation of MIRIAD tasks (eg, "doc fits"). The
remainder of this documentation is intended only for MIRIAD
programmers.
Usage:
doc [-f] [-c#] [-ditruUpP] [-m module] [-x texformat] [-s type]
[-o dir] [-a] [-w#] [-e] [-l listfile] [files]
Options:
(none) show list of options
-f show the format for input files
-c# show recognized categories (# = 1, 2 or 3)
-d type formatted document(s) (default option)
-i make an alphabetized list of routines in input file
-t make a list of routines by functional category
-r extract codename of programmer responsible for routines
-U make a single TeX/LaTeX output of all input files
-u make TeX/LaTeX files, one for each routine in inputs
-P make a single on-line-format output of routines in inputs
-p make on-line-format files, one for each routine in inputs
-m search for documentation of 'module' in list of input files
-x select TeX or LaTeX (default); choice case insensitive
-s select to make a LaTeX section/subsection for each task
-o put 'dir' as directory of source code in the output
-a ask user what to do if an output file already exists
-w stop printing after # lines and ask if user wants to go on
-e do not check for filename extensions of input files
-l process all files listed on file 'listfile'
files input file(s) to be processed
Without the -e option, doc will work only on input files with
extensions .for, .f, .f2c and .c (source code) and with extensions .doc,
.sdoc, .tdoc, .cdoc and .kdoc (on-line documentation).
Input files can be read from a file (option -l) or listed. These
options can be combined. If no filename extensions are given for
[files], they are searched for in $MIRPDOC and $MIRSDOC.
Option -u writes output in the user's current working directory, with
filename extension .tex. Option -p writes output in the user's current
working directory with the appropriate .doc, .sdoc, .tdoc, .kdoc or
.cdoc filename extension.
Options -i and -t are used to construct alphabetic and systematic
indices.
Below a short description of in-code format, where output files have
extensions .doc, .sdoc, .tdoc or .cdoc:
c= [routine name] [one-line description] (for main programs/scripts)
c* [routine name] [one-line description] (for subroutines)
c& programmer responsible for the routine
c: comma-separated list of categories pertaining to the routine
c+
c multi-line program description block
[subroutine call and variable declarations]
c@ keyword
c multi-line keyword description
c< standard-keyword
c multi-line description of non-standard features
c-- end of multi-line documentation block
The flag character 'c' may also be 'C' or '/*' (the latter for .c
files). In the case where option -e was used, directives should start
with # or $! (for unix scripts and VMS command files, respectively).
The c< directive may be used for some keywords which have a standard
description (in, out, vis, select, line, region, server, device).
The keyword directives c@ and c< may be used more than once, unlike
the other directives. For tasks and scripts (i.e. not for subroutines)
the first character on the first non-empty line of the documentation
blocks determines an "alignment column". When converting to (La)TeX
format, lines that have a space in this column are typeset
``verbatim''. No line should start before the alignment column. The
documentation block between c+ and c-- may contain any character,
except that the tilde (~) cannot be used inside a verbatim block.
Backslashes should be doubled.
The recognized categories are listed below. doc can also print this
list if the -c1, -c2 or -c3 options are used, respectively.
Recognized task categories (: directive):
General Utility Data Transfer Visual Display
Calibration uv Analysis Map Making Deconvolution
Plotting Map Manipulation Map Combination Map Analysis
Profile Analysis Model Fitting Tools Other
Recognized subroutine categories (: directive):
Baselines Calibration Convolution Coordinates
Display Error-Handling Files Fits
Fourier-Transform Gridding Header-I/O History
Image-Analysis Image-I/O Interpolation Least-Squares
Log-File Low-Level-I/O Mathematics Model
PGPLOT Plotting Polynomials Region-of-Interest
SCILIB Sorting Strings Terminal-I/O
Text-I/O Transpose TV User-Input
User-Interaction Utilities uv-Data uv-I/O
Zeeman Other
Recognized script/command file categories (: directive):
System Operation Programmer Tool User Utility Other
Examples of use:
doc fits - Print on-line doc on the screen
doc -p $MIRPROG/* /fits.for - Generate on-line doc
doc -u $MIRPROG/* /fits.for - Generate tex file
doc -e mir.bug.csh - Print on-line doc of a script
doc -m xysetpl $MIRSUBS/* - Search for doc of xysetpl in MIRSUBS
doc -m xysetpl $MIRSDOC/* - Search for doc of xysetpl in MIRSDOC