The System Manager, An Admin Tool For UNIX
==============================================================================
Introduction For Developers
==============================================================================

== Introduction ==============================================================

	The System Manager is a collection of 'modules', individual programs
	which provide support for specific tasks.
	
	This file is an overview to the System Manager, and this should be of
	interest to developers.
	
	(Stuart's note : This documentation sucks.  If there's anything
	you're not sure about, look at the supplied modules, or mail me.  My
	main priority before this becomes BETA is to write some decent
	documentation.)
	
== Directory Structure =======================================================

	The System Manager has a standard directory layout :
	
	* /var/adm/sysman/bin
		This directory contains any utilities required by your module.
	
	* /var/adm/sysman/install
		This directory should only contain the sub-directory MANIFEST.
		
		(Stuart's note : This directory is used by distributions to
		hold files which will be installed into the /usr/ hierarchy
		by the INSTALL script.)
		
	* /var/adm/sysman/install/MANIFEST
		This directory contains MANIFEST files which are built
		automatically by the System Manager.  These files are used
		for REMOVEing installed modules; you can also distribute them
		with the INSTALL script to simplify installing your module.
		
	* /var/adm/sysman/modules
		This directory contains all the modules, one sub-directory
		for each module.
	
	* /var/adm/sysman/src
		This directory can be used to provide the user with the
		source code to any supporting utilities (needless to say,
		this is optional).
		
== Contents Of A Module ======================================================

	The directory /var/adm/sysman/modules contains all installed modules.
	
	Each module is a separate sub-directory, which contains a file called
	'README.module', any programs which are to be linked into the
	module's menu, and any data files these programs require.
	
	IT IS A REQUIREMENT THAT EVERY EXECUTABLE FILE INSIDE A MODULE'S
	DIRECTORY CORRECTLY HONOUR THE FOLLOWING PARAMETERS :
	
	--SysmanAuthor
		The program should echo to the screen some 'blurb' about who
		wrote the program and what it does.  The 'INFO' option on
		every menu uses this parameter to find out about the contents
		of the module, by calling each program with the
		--SysmanAuthor parameter.
		
	--SysmanInstall
		The program should echo a valid menu string (explained below)
		which is used by the UPDATE software to rebuild the System
		Manager's menus.
		
	As a consequence of this, any program required by your module, but
	which itself won't be directly available from the menus, should be
	placed in /var/adm/sysman/bin.
	
	-- NOTE : --
	
		Any parameters starting with the string '--Sysman' are
		reserved for future use by The System Manager.
		
	----
	
== README.module =============================================================
		
	This is a /bin/bash shell script which has three purposes :
		
	* To supply the menu entry for the module
		When called with '--SysmanInstall', the script should echo a
		set of valid menu information, and then exit.
		
        * To supply information to the user
		When called with '--SysmanAuthor', the script should use the
		functions 'title', 'author' and 'comment' to provide a blurb
		about itself, and then call 'endinfo'.

		(As you will see later, when called with '--SysmanAuthor', a
		README.module file calls /var/adm/sysman/bin/ParseMod, which
		defines the INSTALL functions (see INSTALL.functions) so that
		most of them don't do anything.  The script will then drop
		through into the same code as used for the last requirement.)

	* To provide a MANIFEST for use by INSTALL
		When called with no parameters, the script should use the
		INSTALL functions (see INSTALL.functions) to install the
		module.  

		The script should check for any required support utilities,
		and install any files which ARE NOT contained in the same
		directory as the script itself.  The code required to install
		files which are contained in the same directory as the script
		is automatically generated by the MANIFEST option.

	Please read the file 'INSTALL.functions' for information about the
	functions provided for use inside a MANIFEST.
	
== Menu Strings ==============================================================

	A menu string has the following syntax :
	
		Root : Users : Name : Description :$0
	
	where
	
	* Root
		This field is a 'Y' or a 'y' if the string defines an entry
		in the menus used by the user 'root', or 'N' or 'n' otherwise.
		
	* Users
		This field is a 'Y' or a 'y' if the string defines an entry
		in the menus used by non-root users, or 'N' or 'n' otherwise.
		
	* Name
		This field contains a UNIQUE, one word identifier which is used 
		to distinguish this menu entry from all other entries on the
		same menu.  The identifiers 'INFO', 'BACK' and 'DONE' are
		reserved for use by the System Manager.
		
	* Description
		This field contains a short description which is shown on the
		menu to explain what the entry is for.
		
	* $0
		This will be substituted for the name of the program echoing
		the menu entry.  (Stuart's note : This currently is unused,
		but please include it for future compatibility)
		
        Normally, the only program inside a module which echos two menu
	strings will be the README.module script, which may want to provide
	different NAME and DESCRIPTION for each type of user (root or
	non-root).  However, any program can echo two menu strings.
	
	-- EXAMPLE --
	
		#! /bin/bash
		#
		# Example menu string handler
		
		if [ -n "$1" ]; then
		  case "$1" in
		    --SysmanInstall)
		      echo "Y : N : EDIT : Edit A User's Details :$0"
		      echo "N : Y : EDIT : Edit Your Details :$0"
		      exit
		      ;;
		   ...
		  esac
		fi
		
		# done
		
	----
	
	In the example above, when called with the parameter
	'--SysmanInstall', two menu strings are echoed, one for root, and one
	for non-root users.

== Functions Available =======================================================

	Although the programs which make up a module are not required to be
	shell scripts, there are functions available to those programs which
	*are* shell scripts.
	
	(Stuart's note : please read the 'sysman' script to see what
	variables and functions are available, and what they do.)

== Distributing Modules ======================================================

	Once you have written your module, and you've run the MANIFEST option
	of the SYSMAN module, you simply need to do the following to create a
	distribution :
	
	tar zcf mymodule.tar.gz modules/MyModule INSTALL \
	  install/MANIFEST/MyModule + any other files your module requires.
	  
	When a user extracts the tar file, they will be able to run the
	INSTALL script to install your module correctly.
	
	(Stuart's note : Perhaps I should provide a module to create a
	distribution for any given module?)
	
==============================================================================
Stuart Herbert - S.Herbert@Sheffield.ac.uk
