#!/usr/bin/perl
#
# nu - new user help library
#
# This is a script that implements a new user help library.  By setting various
# invalid commands as softlinks to this script, when a new user tyeps an
# invalid command (say a VMS user who is new to using UNIX), the script will
# output portions of a help file to assist the user in their becoming familiar
# with the system.  To use, change the $help_files variable to the directory
# containing nu and the help files.  Also, change the $pager variable to meet
# your needs.  Then, create softlinks from a directory in your PATH to nu, 
# using each of the names of the help files:
#
# 	mkdir /usr/local/share/nu
# 	cp -p * /usr/local/share/nu
# 	ln -s /usr/local/share/nu /usr/local/bin/nu
# 	ln -s /usr/local/share/nu /usr/local/bin/create
# 	ln -s /usr/local/share/nu /usr/local/bin/directory
# 	...
#
# NOTE: This handles commands fine, but misses commands with arguments.  For
# example, it will treat "create" and "create /dir" the same, even though you
# may want to handle them differently.  This could be accomplished, but I never
# bothered to code for these eventualities.
#
# This and other hacks can be found at: http://oddgeek.info/
#
# Copyright (c) 2005 Jason A. Dour & University of Louisville
#
# This software is provided 'as-is', without any express or implied warranty.
# In no event will the authors be held liable for any damages arising from the
# use of this software.
# 
# Permission is granted to anyone to use this software for any purpose,
# including commercial applications, and to alter it and redistribute it
# freely, subject to the following restrictions:
#
#     1. The origin of this software must not be misrepresented; you must not
#     claim that you wrote the original software. If you use this software in a
#     product, an acknowledgment in the product documentation would be
#     appreciated but is not required.
#
#     2. Altered source versions must be plainly marked as such, and must not
#     be misrepresented as being the original software.
#
#     3. This notice may not be removed or altered from any source
#     distribution.
#

#
# Version Information
#
# 1.0	2005.05.27
#
# 	Added comments and reformatted code.  Noted limitation of only catching
# 	'command' and not 'command arg'.
#
# 0.9b	1995.04.25
#
# 	First release.  Wrote this during my tenure as an Assistant Systems 
# 	Administrator at the University of Louisville.  Was written to address
# 	the new users coming onto the university's main UNIX server from a
# 	VMS cluster which was being decommissioned.  We used nu as well as a
# 	menuing system to ease their transition to UNIX.
#

#
# ORIGINAL TEXT FROM A DECADE AGO...
#
# NU -- New User -- version 0.9b -- April 25th, 1995
# Script written by Jason A. Dour.  (jadour01@homer.louisville.edu)
#      You are free to distribute this file to users on OSF/1 
#      (homer.louisville.edu) as long as it is in its original
#      distribution form.  Any modifications made are to be 
#      reported to the author at the address stated above.  
#      Remember...a good utility is only as good as everyone 
#      makes it.  The more you help, the better it will be.
#

#
# GLOBAL VARIABLES

# Version string.
$version = "\n   nu - New User - verison 0.9b -- 4/25/95 -- (c)1995  Jason A. Dour & UofL   \n\n";

# Directory containing the help files.
$help_files = "/usr/local/share/nu";

# Text pager.
$pager = "/usr/bin/less -CenrwP' NewUser - press space for next page - h for help - q to quit?e - END OF HELP! '";

#
# MAIN

# Remove path gunk from command name...
$name = $0;
$name =~ s#^.*/##;

#
# Load the help file...
if ( $name eq "nu" ) { 
    # Open the help file requested on the command line...
    open(HELP,"$help_files/$ARGV[0].nu") ||
        die "\nNU: ERROR! : Cannot open help file for '$ARGV[0]!'\n\n";
    
    # Read all of the contents into memory...
    read(HELP,$help_buff,(-s "$help_files/$ARGV[0].nu")) ||
        die "\nNU: ERROR! : Cannot read help file for '$ARGV[0]!'\n\n";
   
    # Close the help file.
    close(HELP);

    # Parse the buffer containing the help information.
    ( $equiv, $help ) = split(/\n#\n/,$help_buff);

    # Open the pager and give it the buffer.
    open(LESS,"| $pager")
        || die "\nNU: ERROR! : Cannot open pager for output!\n\n";
    print LESS $version,$help;
    close(LESS);
   
    # Exit as we've given the user what they wanted.
    exit(0);
} else {
    # Open the help file related to the soft-linked invalid command name.
    open(HELP,"$help_files/$name.nu")
        || die "\nNU: ERROR! : Cannot open help file for '$name!'\n\n";
    
    # Read all of the contents into memory.
    read(HELP,$help_buff,(-s "$help_files/$name.nu"))
        || die "\nNU: ERROR! : Cannot read help file for '$name!'\n\n";
   
    # Close the help file.
    close(HELP);

    # Parse the buffer containing the command equivalent.
    ($equiv, $junk) = split(/\n#\n/,$help_buff);
}

# Show new user information...
printf "\n   You have just tried to run       : %-41.41s\n",$name;
printf "   The probable UNIX equivalent is  : %-41.41s\n\n",$equiv;
printf "   For more help on equivalents,\n";
printf "   or if no exact equivalent exists : nu %-41.41s\n\n",$name;
print  "   WARNING! : UNIX wildcards are much more powerful than those of\n";
print  "              other operating systems.  Use extreme caution before\n";
print  "              attempting wildcard command operations!\n";
print $version;

# YAY!  We're outta here!
exit(0);