;+
;
; @file_comments
; Display an IDL procedure header using widgets and the widget manager.
;
; @categories
; Widget
;
; @param FILENAME {in}{required}
; A scalar string that contains the filename of the file to display.
; If FILENAME does not include a complete path specification, xhelp will
; search for the file in the current working directory and then each of the
; directories listed in !PATH environment variable.  The
; ".pro" file suffix will be appended if it is not supplied.
;
; @keyword _EXTRA
; Used to pass keywords
;
; @restrictions
; Triggers the XMANAGER 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 mofification par Sebastien Masson : utilisation de
;  xdisplayfile, de findfile et de _extra.
;  6/7/1999: compatibility mac and windows
;
; @version
; $Id$
;
;-
;
PRO xhelp, filename, _extra=ex
;
  compile_opt idl2, strictarrsubs
;

; Are we sure filename is a string?
   cquoidonc = size(filename, /type)
   if cquoidonc NE 7 then begin
      ras = report('Input parameter must be a string and not a '+size(filename, /tname))
      return
   endif
; We have to find the full name
   pfile=FILENAME
   if strpos(pfile,".pro") lt 0 then pfile=pfile+".pro"
   thisOS = strupcase(strmid(!version.os_family, 0, 3))
   CASE thisOS of
      'MAC':BEGIN & sep = ':' & pathsep = ',' & end
      'WIN':BEGIN & sep = '\' & pathsep = ';' & end
      ELSE: BEGIN & sep = '/' & pathsep = ':' & end
   ENDCASE
   cd, current = current
   if strpos(pfile,sep) lt 0 then BEGIN
      if rstrpos(current,sep) NE strlen(current)-1 then current = current+sep
      multipath = str_sep(!path,pathsep)
      if rstrpos(multipath[0],sep) NE strlen(multipath[0])-1 then multipath = multipath +sep
      pfile = [current, multipath]+ pfile
   ENDIF
; We test each possible name to find where the file is.
   nfile=n_elements(pfile)
   n = 0
   repeat begin
      res = findfile(pfile[n])
      n = n+1
   endrep until res[0] NE '' OR n EQ n_elements(pfile)
   if res[0] NE '' then BEGIN
      openr, unit,pfile[n-1], /get_lun ; opening of the file
; we select the heading piece
      a = strarr(1000)          ;Maximum # of lines
      xsize=0
      i = 0
      c = ''
      readon=0
      while not eof(unit) do begin
         readf,unit,c
         if strpos(c,';-') eq 0 then readon=0
         if readon then BEGIN
            dum=where(byte(c) eq 9b,ntab) ; count tab characters
            xsize=xsize > (strlen(c)+8*ntab)
            a[i] = strmid(c,1,200)
            i = i + 1
         endif
         if strpos(c,';+') eq 0 then readon=1
      endwhile
      if i EQ 0 then $
         ras = report('file is badly written, no header ... Use xfile') ELSE BEGIN
         a = a[0:i-1]
; we wrote the a's content in a widget
         xdisplayfile,'toto',text = a,title=pfile[n-1], _extra = ex
      ENDELSE
      FREE_LUN, unit         ;free the file unit.
   ENDIF ELSE ras = report(filename + ' does not exist ...')

   return
end