List routines by category:
Atmospheric Sciences |
Benchmarking |
Color |
Date/Time |
Doc |
File & I/O |
BPCH Format |
Scientific Data Formats |
GAMAP Examples |
GAMAP Internals |
GAMAP Utilities |
GAMAP Data Manipulation |
GAMAP Models &
Grids |
GAMAP Plotting |
General |
Graphics |
Math & Units |
Plotting |
Regridding |
Strings |
Structures |
Time Series
List routines by alphabetical order:
A |
B |
C |
D |
E |
F |
G |
H |
I |
J |
K |
L |
M |
N |
O |
P |
Q |
R |
S |
T |
U |
V |
W |
X |
Y |
Z
NAME:
ADD_TEMPLATE
PURPOSE:
Add a near standard IDL template to a given IDL routine file.
CATEGORY:
Documentation
CALLING SEQUENCE:
ADD_TEMPLATE, FILE
INPUTS:
FILE -> Input IDL routine file name.
KEYWORD PARAMETERS:
None
OUTPUTS:
None
COMMON BLOCKS:
None
NOTES:
(1) Existing front end, up to the pro or function
statement, are replaced by the new template.
(2) Also see routine IDL2HTML, which converts the IDL
doc header text to HTML format.
MODIFICATION HISTORY:
written by:
R. Sterner, about Sep 1989 at Sac Peak. The exact date was
probably lost by this routine itself.
modified:
R. Sterner, 13 Dec, 1993 --- dropped spawn to copy files.
R. Sterner, 11 Mar, 1993 --- handled no help text case.
M. Schultz, 01 Aug, 1997 --- simplified version without
analyzing help text
Also, original file is left intact
(i.e. modification date etc.)
and renamed file.backup if operation successfully.
OF COURSE the copyright note is changed as well
mgs, 09 Oct 1998 : - added Id tag for RCS
bmy, 19 Jul 1999 : - changed name & email from mgs to bmy
for convenience! :-)
bmy, 27 Jul 1999 : - put RCS tag as the first line of
the standard header
bmy, 06 Jul 2000 : - extended separator lines a bit
bmy, 11 Oct 2006 : TOOLS VERSION 2.05
- Cosmetic chanes
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
- Now include 2 email addresses
- Updated comments, cosmetic changes.
- Same conditions apply
bmy, 22 Apr 2008: GAMAP VERSION 2.12
- Updated email addresses
(See /n/home09/ryantosca/IDL/gamap2/doc/add_template.pro)
NAME:
FIX_MANUAL_HTML
PURPOSE:
Removes text from the GAMAP manual pages that is
automatically inserted by IDL's MK_HTML_HELP routine,
and replaces them with better HTML code.
CATEGORY:
Documentation
CALLING SEQUENCE:
FIX_MANUAL_HTML
INPUTS:
None
KEYWORD PARAMETERS:
None
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
======================================================
EXTRACT_FILENAME (function) EXTRACT_PATH (function)
MFINDFILE (function) OPEN_FILE
REPLACE_TOKEN (function)
REQUIREMENTS:
Requires routines from the GAMAP package
NOTES:
Also see routines GAMAP2_HTML and IDL2HTML.
EXAMPLE:
GAMAP2_HTML, /ALL, OUTDIR='manual/html/all'
GAMAP2_HTML, /BY_CATEGORY, OUTDIR='manual/html/by_category'
GAMAP2_HTML, /BY_ALPHABET, OUTDIR='manual/html/by_alphabet'
FIX_MANUAL_HTML
; Creates GAMAP manual pages (HTML format) and then
; removes unwanted text that is automatically added
; by IDL's MK_HTML_HELP routine.
MODIFICATION HISTORY:
bmy, 23 Apr 2008: GAMAP VERSION 2.12
bmy, 06 Aug 2010: GAMAP VERSION 2.14
- Stop w/ error if "gamap_manual_replace.html"
file cannot be found
(See /n/home09/ryantosca/IDL/gamap2/doc/fix_manual_html.pro)
NAME:
GAMAP2_HTML
PURPOSE:
Wrapper routine for IDL2HTML. Is used to call IDL2HTML
repeatedly in order to create HTML documentation for each
of the source code files in the GAMAP installation. The
user may sort routines by alphabetical order or by category.
CATEGORY:
Documentation
CALLING SEQUENCE:
GAMAP2_HTML [, Keywords ]
INPUTS:
None
KEYWORD PARAMETERS:
OUTDIR -> Specifies the directory in which HTML documenation
will be created. Passes this to IDL2HTML.
/ALL_ROUTINES -> Select this option to create an HTML file
with documentation information about all routines
in the GAMAP directory. The output file name will be
"gamap2_html.pro".
/BY_ALPHABET -> Select this option to create HTML documentation
files for GAMAP routines by alphabetical order. A file
will be created for each letter of the alphabet.
/BY_CATEGORY -> Select this option to create HTML documentation
files for GAMAP routines according to category (as
specified by the "CATEGORY" tag of the IDL doc header).
A files will be created for each individual category.
NOTE: GAMAP routines may be cross-linked across more
than one category.
OUTPUTS:
SUBROUTINES:
External Routines Required:
============================
IDL2HTML
PROGRAM_DIR (function)
REQUIREMENTS:
None
NOTES:
(1) See also the documentation to IDL2HTML and the IDL manual
for routine MK_HTML_HELP.
(2) One of /ALL_ROUTINES, /BY_ALPHABET, or /BY_CATEGORY must
be selected.
EXAMPLES:
(1)
GAMAP2_HTML, /ALL_ROUTINES, OUTDIR='manual/html'
; Creates HTML documentation from the std headers to
; each of the IDL source code programs in the GAMAP
; installation. Writes output to the manual/html
; directory. The output file name is "gamap2.html",
; which directory.
(2)
GAMAP2_HTML, /BY_ALPHABET, OUTDIR="manual/html"
; Creates HTML documentation from the std headers to
; each of the IDL source code programs in the GAMAP
; installation. Will search through the IDL doc
; headers and create a new HTML file for each
; letter of the alphabet.
(3)
GAMAP2_HTML, /BY_CATEGORY, OUTDIR='manual/html'
; Creates HTML documentation from the std headers to
; each of the IDL source code programs in the GAMAP
; installation. Will search through the IDL doc
; headers and create a new HTML file for each
; category.
MODIFICATION HISTORY:
bmy & phs, 23 Jul 2007: GAMAP VERSION 2.10
bmy, 20 Nov 2007: GAMAP VERSION 2.11
- Added new category for timeseries routines
bmy, 06 Aug 2010: GAMAP VERSION 2.14
- Now check to see if OUTDIR exists
(See /n/home09/ryantosca/IDL/gamap2/doc/gamap2_html.pro)
NAME:
GAMAP2_MANUAL_CREATE
PURPOSE:
This routine creates the HTML documentation pages for each of
the GAMAP routines. This is a convenience wrapper routine
which calls both GAMAP2_HTML and FIX_MANUAL_HTML.
CATEGORY:
Documentation
CALLING SEQUENCE:
GAMAP2_MANUAL_CREATE
INPUTS:
None
KEYWORD PARAMETERS:
None
OUTPUTS:
None
SUBROUTINES:
External Routines Required:
============================
GAMAP2_HTML
FIX_MANUAL_HTML
REQUIREMENTS:
None
NOTES:
Will save output to the ../manual/html/* directories.
EXAMPLES:
GAMAP2_MANUAL_CREATE
; Creates HTML documentation from the std headers to
; each of the IDL source code programs in the GAMAP
; installation. Writes output to the manual/html
; directory.
MODIFICATION HISTORY:
bmy, 01 Jul 2008: GAMAP VERSION 2.12
(See /n/home09/ryantosca/IDL/gamap2/doc/gamap2_manual_create.pro)
NAME:
GAMAP2_REVISIONS
PURPOSE:
Wrapper routine for REVISIONS, used to create a "REVISIONS"
file for each code directory in the GAMAP installation.
CATEGORY:
Documentation
CALLING SEQUENCE:
GAMAP2_REVISIONS
INPUTS:
None
KEYWORD PARAMETERS:
None
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
===============================
PROGRAM_DIR (function)
REVISIONS
REQUIREMENTS:
None
NOTES:
The REVISIONS routine requires the tag "MODIFICATION HISTORY"
to be present. Files without this tag (e.g. data files or
input files) will not be included in the REVISIONS output.
EXAMPLE:
GAMAP2_REVISIONS
; Search through all of the directories in the GAMAP
; installation and create a REVISIONS file containing
; the modification histories of each *.pro file.
MODIFICATION HISTORY:
bmy, 17 Jul 2007: VERSION 1.00
(See /n/home09/ryantosca/IDL/gamap2/doc/gamap2_revisions.pro)
NAME:
IDL2HTML
PURPOSE:
Wrapper for MK_HTML_HELP. Can be used to create HTML files
which contain the comments from the standard doc headers
that are included with each IDL routine.
CATEGORY:
Documentation
CALLING SEQUENCE:
IDL2HTML, PATH, [ , Keywords ]
INPUTS:
PATH -> A file path (can be a directory, single file name,
or file mask) for the IDL routines whose doc headers
you wish to convert to HTML format.
KEYWORD PARAMETERS:
/ALPHABETICAL -> Set this switch to create a separate HTML
documentation file for files beginning with each letter
of the alphabet. This is useful if you have a lot of
files to process.
/CATEGORY -> If specified, IDL2HTML will create a HTML file
for all *.pro files corresponding to a given category
(as specified by the CATEGORY tag in the standard
IDL documentation headers).
HTMLFILE -> Name of the HTML file that will be created.
A default file name will be used if HTMLFILE is omitted.
OUTDIR -> Name of the directory into which the HTML
documentation files will be written.
_EXTRA=e -> Passes extra keywords to MK_HTML_HELP.
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
=======================================================
ADD_SEPARATOR (function) EXTRACT_FILENAME (function)
IS_DIR (function) STRWHERE (function)
REQUIREMENTS:
None
NOTES:
None
EXAMPLE:
IDL2HTML, '~/IDL/tools/', OUTDIR='~/doc/html/', /ALPHABETICAL
; Will create HTML files with documentation from the
; IDL routines in the ~/IDL/tools directory. Will
; place the output in the ~/doc/html directory.
MODIFICATION HISTORY:
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/doc/idl2html.pro)
NAME:
REVISIONS
PURPOSE:
Extract information about file modifications and create
REVISIONS file for all files w/in a directory.
CATEGORY:
Documentation
CALLING SEQUENCE:
REVISIONS, DIRNAME
INPUTS:
DIRNAME -> directory name to be searched for *.pro files
KEYWORD PARAMETERS:
None
OUTPUTS:
None
SUBROUTINES:
External Subroutines Required:
=================================================
ADD_SEPARATOR (function) MFINDFILE
STRDATE (function) STRRIGHT (function)
REQUIREMENTS:
The program files must have a standard header with tag
"MODIFICATION HISTORY" as last item. This must be followed
with a ;- line (!! NOT ;----- !!).
The REVISIONS file will be written in the directory DIRNAME,
thus the user must have write permission.
NOTES:
(1) All *.pro file in the given directory will be analyzed.
(2) Also see IDL routine ADD_TEMPLATE
EXAMPLE:
REVISIONS, '~/IDL/gamap2/doc/'
; Will produce a REVISIONS file for all of the
; *.pro files w/in the '~/IDL/gamap2/doc' directory
MODIFICATION HISTORY:
mgs, 16 Jun 1998: VERSION 1.00
mgs, 25 May 1999: - added caution for tag detection in this
routine itself.
bmy, 24 Oct 2003: TOOLS VERSION 1.53
- Bug fix: EXPAND_PATH strips the directory
separator string from the end of DIRNAME
in IDL 6.0+. Add this back manually.
- use MFINDFILE instead of FINDFILE to fix
file listing bug in IDL 5.2-
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/doc/revisions.pro)
NAME:
UPDATE_LIBRARY
PURPOSE:
automatic update of IDL WWW library
CATEGORY:
Documentation
CALLING SEQUENCE:
UPDATE_LIBRARY,TARGETDIR,TARNAME [,keywords]
INPUTS:
TARGETDIR --> directory where WWW library resides
Usually a local directory, the contents of which is then
ftp'd to the www site (default: '~/IDL/lib-tools/').
TARNAME --> after copying all the required files, the library
is tar'd and compressed. TARNAME is the name of the uncompressed
file (default 'idl_lib.tar').
KEYWORD PARAMETERS:
DIRS --> directories to search for files with SEARCHPATTERN.
This will only come to effect if no LISTFILE is given
(default ['~/IDL/tools/','~/IDL/tools3d']).
SEARCHPATTERN --> string array of filemasks which may contain
wildcards and determine the files to be included in the
library (default ['*.pro', '*.doc']). This
parameter is also used to obtain a list of files that are
already in the library and to determine the files to delete
if the PACKAGE option is set.
LISTFILE --> Name of a file that contains the names of all the
files to be included in the library (E.g. output from the
DISTRIBUTE routine, although this cannot be used directly).
In this case, no search for matching files is performed.
PACKAGE --> Normally, the individual files of the library will
remain in TARGETDIR together with the compressed tar file.
If the PACKAGE option is set, all individual files will be
deleted after creation of a new tar file. In order to retain
information about files once included in the library, the
file 'dirlist.old' is created before deleting the files.
Normally this file is created at the beginning of program
execution.
NO_ACTION --> DO not copy any files, create a tar file or compress
this. This will only produce a list of all the files that
would be included in the library together with their status
label ('NEW' or 'UPDATE', 'OLD' is represented byu blanks)
OUTPUTS:
Unless the NO_ACTION keyword is set, the TARGETDIR will contain
a compressed tar file and unless the PACKAGE option is set, it
will also contain a copy of all individual files that make up the
library.
SUBROUTINES:
REQUIREMENTS:
Requires function STRRIGHT.
NOTES:
This routine uses SPAWN extensively. The spawned commands are
UNIX specific.
The file status 'UPDATED' is obtained by comparing the filedate
of all files that are not 'NEW' with the date of the compressed
tar file using the Unix find command.
EXAMPLE:
UPDATE_LIBRARY
will collect all '*.pro', and '*.doc' files in the directories
'~/IDL/tools', and '~/IDL/tools3d' , copy them into the
default target directory '~/IDL/lib-tools', tar them and compress
the tar file 'idl-lib.tar'.
In order to create a library with all '*.pro' and '*.sav' files
of all subdirectories of '~/IDL/' in the target directory 'lib-all'
type:
DIRS = STR_SEP(EXPAND_PATH('+~/IDL'),':')
SEARCH = ['*.pro','*.sav']
UPDATE_LIBRARY,'~/lib-all/','all_idl.tar',dirs=DIRS, $
searchpattern=SEARCH
In order to pack together all the files needed to run program
TEST.PRO, proceed as follows:
(if you are in IDL, exit and come back in)
JOURNAL,'test.files'
DISTRIBUTE,'test'
JOURNAL
(now edit your journal file 'test.files', keeping only the
names of the files that belong to the test.pro package, and
maybe add documentation and/or example files that you would
like to include in the library and create directory ~/lib-test)
UPDATE_LIBRARY,'~/lib-test','test.tar',listfile='test.files', $
SEARCHPATTERN=['*.pro','*.doc','*.data'],/PACKAGE
Note, that the filemasks in SEARCHPATTERN will be used to
obtain the file status, and to find the files to be deleted after
updating the library. They are not necessary to include these
files in the library. This is completely controlled by the entries
of listfile.
If you want to collect all '*.data' files from a list of directories
in a library without keeping a copy of the individual files try:
dirlist=['~/data/','~/data/aircraft/','~/data/surface/']
UPDATE_LIBRARY,dirlist,'all_data.tar',/package, $
searchpattern='*.data'
MODIFICATION HISTORY:
mgs, 19 Nov 1997: VERSION 1.00
mgs, 22 Feb 1999: replaced findfile with mfindfile for SGI
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/doc/update_library.pro)
NAME:
USAGE
PURPOSE:
Display help information on any routine in the IDL path
that has a (more or less) standard header.
CATEGORY:
Documentation
CALLING SEQUENCE:
USAGE, ROUTINENAME
INPUTS:
ROUTINENAME -> (string) name of the routine for which help
information shall be provided. Tip: to get help for the
current routine use function ROUTINE_NAME().
KEYWORD PARAMETERS:
/PRINTALL -> prints complete header information. Normally, only
"user relevant" information is displayed.
OUTPUTS:
Prints usage information on the screen.
SUBROUTINES:
External Subroutines Referenced:
================================
DATATYPE (function)
FILE_EXIST (function)
REQUIREMENTS:
None
NOTES:
This routine is meant to replace /HELP constructs etc.
EXAMPLES:
(1)
IF ( N_PARAMS() NE 2 ) THEN BEGIN
PRINT,'Invalid number of arguments!'
USAGE, routine_name()
ENDIF
; Put this error check IF block at the top of
; an IDL routine to display the doc header
; info if the wrong # of arguments are passed
(2)
USAGE, 'MY_ROUTINE', /PRINTALL
; Print complete doc header information from
; the IDL routine "my_routine.pro".
MODIFICATION HISTORY:
mgs, 27 Mar 1998: VERSION 1.00
mgs, 16 Jun 1998: - replaced close by free_lun
bmy, 09 May 2002: TOOLS VERSION 1.50
- test RNAME to see if it's a string
- updated comments
bmy & phs, 13 Jul 2007: GAMAP VERSION 2.10
(See /n/home09/ryantosca/IDL/gamap2/doc/usage.pro)