;+ ; NAME: ; www_help ; PURPOSE: ; Extract headers from source code files. Locations of source code can ; be specified as regular files or directories, or (vms only) as text libraries. ; An html-based help system is created from the headers. ; CATEGORY: ; www_help ; CALLING SEQUENCE: PRO www_help, files, header, $ paths = paths , $ destination = destination , $ style = style , $ swap_style = swap_style , $ list = list , $ email = email , $ cgi_bin = cgi_bin , $ update_master = update_master , $ tempdir = tempdir , $ copyright = copyright , $ _extra = _extra ; INPUTS: ; files array; type: string ; list of files. These may include directory specification ; and a wildcard in the file name. On VMS text libraries ; are permitted. ; paths=paths array; type: string ; list of directories to be searched ; ; destination = destination ; scalar; type: string ; The name of the directory for the html files ; ; The 'files' and 'paths' arguments are passed unmodified to FindAllFiles. ; Several other arguments are permitted to modify file selection. ; These are explained in href=FindAllFiles=: ; ; /recursive ; /symlink ; excl_files=excl_files ; excl_paths=excl_paths ; excl_recursive=excl_recursive ; ; OPTIONAL INPUT PARAMETERS: ; style=style array[1]; type: structure ; One of the structures returned from the procedure ; href=www_help_style=. The structure content is described ; there. Defaults are available for several types of source ; code (e.g. IDL and Fortran) with several options for ; changing defaults. ; ; list=list scalar; type: string ; name of file containing list of valid section headings. ; Usually valid section headings are set using information ; in the 'style' keyword (see href=www_help_section=). This ; keyword overrides that selection.; ; cgi_bin=cgi_bin ; scalar; string; default: none ; directory where web server looks for cgi files. ; Typically has the form: ; server.domain.edu/cgi-bin/ ; This is the directory where the python script ; www_help.cgi should be installed. If this keyword is ; specified the file name in the html files will be ; hyperlinks to the cgi script. If not specified these ; links are not created. ; ; email=email array; type: string ; list of email addresses. If any of these addresses is ; found it is converted to an html link ; ; swap_style=swap_style ; array[n]; type: structure ; same layout as keyword style ; adds a linkto enable swapping to the help system for ; another group of source files. ; ; /add_corpses if set then files containing no headers are added with a ; dummy header (this only makes sense if the cgi-script ; www_help.cgi is working to provide access to the source code). ; ; /automatic EXPERIMENTAL: can only be used for IDL code. ; If set then first an attempt is mode to get a list of referenced ; procedures and function by a call to href=www_help_get_info=. ; If this fails then the information in the CALLS section is used. ; ; tempdir=tempdir directory to be used for storing scratch files. Only needed ; if keyword /automatic is set. ; (alternatively, set environment variable 'www_help') ; ; Two keywords are passed unmodified to href=www_help_crosslinks=. ; These control how information from other www_help collections in the ; same destination directory are used to create hyperlinks. ; ; incl_sets=incl_sets ; array; type: string ; excl_sets=excl_sets ; array; type: string ; ; OUTPUTS: ; (number of html files) ; INCLUDE: @compile_opt.pro ; On error, return to caller ; CALLS: ; CheckDir, www_help_files, www_help_style, www_help_section, www_help_make ; www_help_crosslinks, www_help_master, InitVar, IsType ; RESTRICTIONS: ; Has not been tested on VMS ; On VMS text libraries are processed by extracting modules into SYS$TEMP. ; After processing these files are deleted. ; PROCEDURE: ; > For each header the fully-qualified file name of the corresponding file is ; put in the html file. If the keyword cgi-bin is used then the file name ; becomes a link to the cgi-script $SSW_SMEI/gen/python/www_help.cgi, which ; will try to pull up the actual source code. The script is assumed to accessible ; at the server specified in cgi-bin. ; ; > The www_help package depends on the a couple of procedures not included ; with the package itself: ; CheckDir, FindAllFiles, FindAllSubDirs, GetFileSpec, IsSymLink, os_separator ; SetFileSpec, strposn, SyncDims, where_common ; ; > For more information check the file sections_ssw.txt (should be located in the ; same directory as this file). ; MODIFICATION HISTORY: ; JAN-2001, Paul Hick (UCSD/CASS) ; JUN-2001, Paul Hick (UCSD/CASS); added /anycase keyword. ; See href=www_help_get_header= for more information. ; JAN-2002, Paul Hick (UCSD/CASS) ; Added cgi-bin keyword ; Added /automatic mode for IDL code. Now at V2.1 ; Added /automatic mode for Fortran code. Now at V2.2. ; Note that this requires the program ftnchek. The current ; setup only works for Fortran code in the SSW_SMEI tree. ; FEB-2002, Paul Hick (UCSD/CASS) ; Added keyword 'mask' to www_help_make. This allows correct processing of a ; whole software tree while creating separate catalogues for each branch ; below the top level directory and cross-referencing of procedures ; across the whole tree (i.e. also between branches). See www_help_tree. ; Now at V2.3. ; JUN-2003, Paul Hick (UCSD/CASS) ; Couple of bug fixes in www_help_files. Streamlined www_help_tree. ; Now at V2.5 ; SEP-2007, Paul Hick (UCSD/CASS; pphick@ucsd.edu) ; Added code to write function/prodedure name, file name, ; and CALLS, INCLUDE, SEE ALSO and EXTERNAL section into ; a plain text file. Required modifications to www_help_make ; and www_help_names. ;- InitVar, update_master, /key IF IsType(tempdir,/defined) THEN setenv, 'www_help='+tempdir[0] IF (IsType(files, /undef) OR IsType(paths, /undef)) OR $ IsType(destination, /undef) then message, 'Usage: www_help, files, destination' IF CheckDir(destination) THEN BEGIN ; Pick up a default style and a list of valid section headings. InitVar, style, www_help_style(/idlcode) section = www_help_section(style, list=list) ; Get a list of routines available in other catalogues. www_help_crosslinks, destination, style, crosslinks, _extra=_extra ; Get the headers, write the html files IF www_help_files(style, section, files, header, paths=paths, _extra=_extra) GT 0 THEN BEGIN www_help_make, destination, header, section, style, swap_style=swap_style, $ email=email, cgi_bin=cgi_bin, crosslinks=crosslinks, copyright=copyright ptr_free, header.lines ENDIF ENDIF ; Recreate the master IF update_master THEN www_help_master, destination, style, copyright=copyright RETURN & END