source: trunk/SRC/Utilities/xhelp.pro

;+
;
; @file_comments
; Display an IDL procedure header using widgets and the widget manager.
;
; @categories
; Utilities Widget
;
; @param filename {in}{required} {type=scalar string}
; It is the name of the procedure or of the function
; we want to display (with or without .pro at the end).
; FILENAME should be located in !path.
; ".pro" suffix will be appended if needed.
;
; @keyword _EXTRA
; Used to pass keywords to <proidl>XDISPLAYFILE</proidl>
;
; @restrictions
; Triggers the <proidl>XMANAGER</proidl> if it is not already in use.
;
; @examples
;
;   IDL> xhelp,'plt'
;
; @history
; Written By Steve Richards, December 1990
;       Graceful error recovery, DMS, Feb, 1992.
;       Modified to extract .pro documentation headers, PJR/ESRG mar94
;       Paul Ricchiazzi                            jun93
;       Institute for Computational Earth System Science
;       University of California, Santa Barbara
;  - 7/1/99 : legeres modification par Sebastien Masson : utilisation de
;    <proidl>XDISPLAYFILE</proidl>, de <proidl>FINDFILE</proidl> et de _extra.
;  - 6/7/1999: compatibility mac and windows
;
; @version
; $Id$
;
;-
PRO xhelp, filename, _EXTRA=ex
;
  compile_opt idl2, strictarrsubs
;
  usage="xhelp, filename, _EXTRA=ex"
;
; check parameters
  check_param = N_PARAMS()
  if (check_param EQ 0) then begin
     dummy = report(['No input parameter', $
                     'Usage : ' + usage])
     return
  endif
;
; check arguments
  if arg_present(filename) then begin
     dummy = report(['No input parameter filename', $
                     'Usage : ' + usage])
     return
  endif
;
; Are we sure filename is a string?
   intype = size(filename, /type)
   if intype NE 7 then begin
      dummy = report(['Input parameter filename type : ' + size(filename,/TNAME) , $
                      'Input parameter filename must be a string'])
      return
   endif
;
; find the file and display it!
   pfile = find(filename, /firstfound)
; read it
   IF (pfile NE 'NOT FOUND') THEN BEGIN
     fulltext = getfile(pfile)
; find the ";+"and ";-"
     start = where(stregex(fulltext,'^ *;\+ *$', /boolean) EQ 1, cnt1)
     ending = where(stregex(fulltext,'^ *;- *$', /boolean) EQ 1, cnt2)
     IF ((cnt1 EQ 0) OR (cnt1 NE cnt2)) THEN BEGIN
       dummy = report('file '+pfile+' is badly written, no proper header found... Use xfile')
       return
     ENDIF
; do we have hidden parts?
     hide = where(stregex(fulltext, '^ *; *@hidden *$', /boolean) EQ 1)
; build the text to display
     header = ''
     sepbloc = ['', string(replicate(byte('='), 60)), '']
     FOR i = 0, cnt1-1 DO BEGIN
; is this part hidden ?
       st = start[i]
       ed = ending[i]
       IF st NE ed +1 THEN BEGIN ; non-empty bloc
         dummy = where(hide GT st AND hide LT ed, cnt)
       IF cnt EQ 0 THEN header = [header, '', sepbloc, fulltext[st+1:ed-1]]
       ENDIF
     ENDFOR
; remove the first useless lines
     IF n_elements(header) GT 1 THEN header = header[4:*] ELSE BEGIN
       dummy = report('file '+pfile+' has empty header... Use xfile')
       return
     ENDELSE
;
     xdisplayfile, 'dummy', text = header[1:*], title = pfile, _extra = ex
;
   endif else begin
     dummy = report(['Input parameter filename : ' + filename, $
                     filename + ' does not exist ...'])
   endelse
;
   return
end