#!/usr/local/bin/tcsh
#+
# help -- print documentation for a DEIMOS script, or list all scripts
#
# Purpose:
#	With no arguments, print an alphabetically-sorted list of the
#	brief descriptions for all DEIMOS scripts.  With one argument,
#	determine whether the given argument represents an alias, a
#	script, or a Unix command, and print out any available
#	documentation. 
#
# Usage:
#	help [-s] [cmd]
# 
# Arguments:
#	-s = source; print full source code for script instead of just the help block
#	cmd = name of command or script to describe
# 
# Output:
#	Documentation is printed to stdout
# 
# Exit values:
#	 0 = normal completion
#	 1 = wrong number of arguments
#
# Example:
#	1) list all available scripts:
#		help
#
#	2) get help on the "goi" script:
#		help goi
#
#	3) get help on the Unix "find" command:
#		help find
#
#	3) view the full source code for the "wfi" command:
#		help -s wfi
#-
# Note:
#	In order to ensure that the path and all aliases are properly
#	defined, this script uses "tcsh" instead of "csh" and also
#	does NOT use "-f" to avoid reading the .cshrc file
#
# Modification history:
#	2000-Jan-01	GDW	Original version
#	2003-Aug-27	GDW	Added "-s" option
#-----------------------------------------------------------------------

# set defaults...
set source = 0

# no arg ==> list brief description of all commands...
if ( $#argv == 0 ) then

  echo "Listing all available DEIMOS scripts:"
  
  # get list of all scripts which are executable plain files
  # NOT ending in "~", cat the contents, extract description lines,
  # and sort the output...
    gawk '/^#.* -- .*/{i=gsub("^#","");printf "%-12s", $1;$1="";print;nextfile}'  `/usr/bin/find $DEIMOS_PROC_DIR -perm -700 -type f \! -name '*~'` \
    | sort | more

  exit
endif

# parse flags...
while ( $#argv > 0 )

  # check for source flag...
  if ( "$1" =~ \-s* ) then
    set source = 1
    shift
    continue
  endif

  # exit flag check if no flags remain...
  break

end

if ( $#argv > 1 ) then
  echo "Usage: help [-s] [cmd]"
  exit 1
endif

# 1 arg ==> get help for that command...
set cmd = $1
set buf = `which $cmd`

# test whether output indicates alias, error, or script...
set error = 0
set alias = `echo "$buf" | fgrep "aliased to" >& /dev/null ; echo $status`
if ( $alias ) set error = `echo "$buf" | fgrep "not found" >& /dev/null ; echo $status`
if ( $error ) set script = `find $buf -ls | fgrep /procs >& /dev/null ; echo $status`

# give appropriate feedback to customer...
if ( $alias == 0 ) then
  echo "$buf"
  exit 0
else if ( $error == 0 ) then
  echo command \"$cmd\" not found
  exit 2
else if ( $script == 0 ) then

    # NOTE: use find -ls to resolve symlinks...
    set file = `find $buf -ls | gawk '{print $NF}'`

    # check for source code option...
    if ( $source ) then
	printf "---------- Source for %s ----------\n" $file
	more $file
    else
	gawk 'NR==1{buf= " Help for " FILENAME ": ";l=length(buf);n=(80-l-2)/2;d="";if(n>0){for(i=1;i<=n;i++){d=d "-"}};printf "%s %s %s\n\n", d, buf, d}\
/^\#\+/{ok=1;next}/^\#\-/{exit}ok==1{i=gsub("^#","");print}' $file | more
    endif
else
  man $cmd
endif