This page was created by the IDL library routine
make_html_help. For more information on
this routine, refer to the IDL Online Help Navigator
or type:
? make_html_help
at the IDL command line prompt.
Last modified: Mon Apr 6 16:41:45 1998.
NAME:
BUILD_DAVIS_HTML
PURPOSE:
Construct a tree of HTML pages describing idl code.
CATEGORY:
CALLING SEQUENCE:
build_davis_html
INPUTS:
None, but see Notes below.
KEYWORD PARAMETERS:
/LINK_FILES - If set to a non-zero value, a file link will be
created from the code description web page to
the actual code. Note that these links will be
valid only for people who have the disks where
the code lives NFS mounted (i.e. no one outside
Berkeley will have access).
OUTPUTS:
None
COMMON BLOCKS:
_BUILD_DAVIS_HTML_COMMON_
SIDE EFFECTS:
Creates a tree of web pages.
NOTES:
Suppose you have the following set of directories:
top_IDL_dir
/ | \
/ \ \
sub1 sub2 DESCRIPTION (see note below)
_________/ | /|\
/ | / | \
DESCRIPTION (.pro files) / | \_
/ | \
sub2a sub2b DESCRIPTION
________/ | | \_____________
/ | | \
DESCRIPTION (.pro files) (.pro files) DESCRIPTION
In the above picture, each directory contains either
subdirectories or IDL code, but not both. In addition, each
directory contains a file called DESCRIPITON describing what
the directory contains. The contents of the DESCRIPTION file
are described below.
This routine creates HTML documentation for this tree of IDL
code by creating a tree of web pages and directories that
mirror the structure of the code tree:
top_HTML_dir
/ | \
/ | \
sub1 sub2 HTML page (to sub1, sub2)
/ /|\
/ / | \
HTML page / | \_
/ | \
sub2a sub2b HTML page (to sub2a, sub2b)
/ \
/ \
HTML page HTML page
The HTML page in top_HTML_dir contains a list of the
subdirectories sub1 and sub2, a short description of each
(obtained from sub1/DESCRIPTION and sub2/DESCRIPTION) and
links to the HTML pages in sub1 and sub2. The HTML page in
sub1 contains actual documentation of IDL code, since sub1 in
the code tree contained only IDL code. The HTML page in sub2
is similar to the page in top_HTML_dir, describing and
providing links to the information in sub2a and sub2b.
Finally the HTML pages in each of those directories contains
documentation of the IDL code in those directories in the code
tree.
The DESCRIPTION files in the code tree need not exist at the
time this procedure is run. The user will be prompted for the
contents of any missing DESCRIPTION files, and the files will
be created based on that input. The DESCRIPTION file may
contain HTML tags if desired. The file should have the
following format:
Line 1: Brief (few word) description of directory
Lines 2+: Lengthier description of contents of
directory, including HTML tags if you want.
This routine requires that three environmental variables be
set:
IDL_GROUP_CODE -- FULL pathname of the top level directory
containing IDL code--top_IDL_dir in the
picture above.
IDL_HTML_HOME -- FULL pathname of the top level HTML
directory in which the documentation is
to be placed--top_HTML_dir in the
picture above.
IDL_GROUP_URL -- URL pointing to IDL_HTML_HOME. This is
used only for creating navigation links
between the pages. If it is not set,
these links are simply not created.
The entire tree of code is traversed each time the code is
run, though only pages which have actually changed are
rebuilt. This is a deliberate design decision. The hope is
that if one person puts code into the idl tree and forgets to
run this routine, some one else will run it, at which time ALL
changes will be updated.
When does this code rebuild a web page?
+ When a new directory has been added to the code tree.
+ When a DESCRIPTION file has changed.
+ When a procedure has changed or when a new procedure has
been added to the code tree.
+ When the keyword FORCE_REBUILD is set all pages are
rebuilt.
What if my idl code has no document header? Then the routine
which generates the pages for the code itself will ignore it.
Placing an empty document header at the top of the file will
at least get the code listed on the page, though the name has
to be filled in for that to be really useful.
IMPORTANT NOTE ABOUT FILE PERMISSIONS: All of the files and
directories this code creates have group write permission.
This is to allow any member of the davis group to rebuild the
html tree, which may involving removing unneeded files or
overwriting existing files. This behaviour cannot be turned
off (unless someone wants that feature). It is neither
necessary nor advisable to make all files and directories in
the IDL code tree group writable.
WARNING: DO NOT MODIFY the web pages produced by this code.
They are automatically generated and any changes you make to
the web page may very well be lost the next time someone runs
the code.
EXAMPLE:
Proper settings for the environmental variables for use in the
Davis group is (put this in your .idlenv or .cshrc):
setenv IDL_GROUP_CODE /deep0/marc/idlshare
setenv IDL_HTML_HOME /deep0/marc/html/idlshare
setenv IDL_GROUP_URL "http://astro.berkeley.edu/~marc/idlshare"
IDL> build_davis_html, /LINK_FILES
creates a tree of web pages located at IDL_GROUP_URL with
links to the actual code.
LIBRARY FUNCTIONS CALLED:
make_html_help
MODIFICATION HISTORY:
$Id: build_davis_html.pro,v 1.1 1998/04/06 21:59:26 mcraig Exp mcraig $
$Log: build_davis_html.pro,v $
Revision 1.1 1998/04/06 21:59:26 mcraig
Initial revision
RELEASE:
$Name: $
(See /deep0/marc/idlshare/general/html/build_davis_html.pro)
NAME:
MAKE_HTML_HELP
PURPOSE:
Given a list of IDL procedure files (.PRO), VMS text library
files (.TLB), or directories that contain such files, this procedure
generates a file in the HTML format that contains the documentation
for those routines that contain a DOC_LIBRARY style documentation
template. The output file is compatible with World Wide Web browsers.
CATEGORY:
Help, documentation.
CALLING SEQUENCE:
MAKE_HTML_HELP, Sources, Outfile
INPUTS:
Sources: A string or string array containing the name(s) of the
.pro or .tlb files (or the names of directories containing
such files) for which help is desired. If a source file is
a VMS text library, it must include the .TLB file extension.
If a source file is an IDL procedure, it must include the .PRO
file extension. All other source files are assumed to be
directories.
Outfile: The name of the output file which will be generated.
KEYWORDS:
TITLE: If present, a string which supplies the name that
should appear as the Document Title for the help.
VERBOSE: Normally, MAKE_HTML_HELP does its work silently.
Setting this keyword to a non-zero value causes the procedure
to issue informational messages that indicate what it
is currently doing. !QUIET must be 0 for these messages
to appear.
STRICT: If this keyword is set to a non-zero value, MAKE_HTML_HELP will
adhere strictly to the HTML format by scanning the
the document headers for characters that are reserved in
HTML (<,>,&,"). These are then converted to the appropriate
HTML syntax in the output file. By default, this keyword
is set to zero (to allow for faster processing).
LINKFILES: If this keyword is set to a non-zero value,
MAKE_HTML_HELP will generate "file" links to the idl
procedures documented on the web page created by this
code.
COMMON BLOCKS:
None.
SIDE EFFECTS:
A help file with the name given by the Outfile argument is
created.
RESTRICTIONS:
The following rules must be followed in formatting the .pro
files that are to be searched.
(a) The first line of the documentation block contains
only the characters ";+", starting in column 1.
(b) There must be a line which contains the string "NAME:",
which is immediately followed by a line containing the
name of the procedure or function being described in
that documentation block. If this NAME field is not
present, the name of the source file will be used.
(c) The last line of the documentation block contains
only the characters ";-", starting in column 1.
(d) Every other line in the documentation block contains
a ";" in column 1.
Note that a single .pro file can contain multiple procedures and/or
functions, each with their own documentation blocks. If it is desired
to have "invisible" routines in a file, i.e. routines which are only
for internal use and should not appear in the help file, simply leave
out the ";+" and ";-" lines in the documentation block for those
routines.
No reformatting of the documentation is done.
MODIFICATION HISTORY:
July 5, 1995, DD, RSI. Original version.
July 13, 1995, Mark Rivers, University of Chicago. Added support for
multiple source directories and multiple documentation
headers per .pro file.
July 17, 1995, DD, RSI. Added code to alphabetize the subjects;
At the end of each description block in the HTML file,
added a reference to the source .pro file.
July 18, 1995, DD, RSI. Added STRICT keyword to handle angle brackets.
July 19, 1995, DD, RSI. Updated STRICT to handle & and ".
Changed calling sequence to accept .pro filenames, .tlb
text librarie names, and/or directory names.
Added code to set default subject to name of file if NAME
field is not present in the doc header.
February 10, 1998, MWC, UC Berkeley. Added purpose to the line
which is output for each routine in the tableof
contents. This used to just contain the name.
April 1, 1998, MWC, UC Berkeley. Added option to create file
link to the location of the procedure being documented.
(See /deep0/marc/idlshare/general/html/make_html_help.pro)