BOOK.TXT: Documentation on SCCS Booking Utility
=========

The "Booking" utility consists of a single korn shell script.
It provides a fairly basic set of shell commands to enable files
to be booked in and out of SCCS repository.

One of the advantages of the booking system is that all of the
environment ($PROJECTDIR etc.) is held within one file.
Therefore the booking system can be used by any user who has 
the book.ksh script in their PATH.

Another advantage of using the booking system is that it is
fairly forgiving. For example, if a file does not already exist
in SCCS, you would normally have to run an "sccs create" instead
of "sccs delget". The booking script shields you from this.
It also deletes old "," files, and re-sets the umask on files,
so that they could be executed, if required.

INSTALLING BOOKING SYSTEM
=========================
In order for the booking system to be used, you need to 
put the file book.ksh in some common directory which 
is in the PATH of all your users.

I suggest that /usr/local or /usr/local/bin is suitable.
Make sure it is in your PATH before installing.

Secondly, you need to decide which directory would equate
to "$PROJECTDIR" - the directory to hold the SCCS files.
Unlike other systems, this is defined inside book.ksh itself.
So you do not need to insist on it being in a users 
.profile before it will run.

See the section of code below...

#
# root filesystem for SCCS sub-directory
# change this to your machine-wide value...
PROJECTDIR=/usr/projects
export PROJECTDIR
#
# command to run SCCS binary
# your own system may have a different location...
SCCSCMD=/usr/ccs/bin/sccs
export SCCSCMD
#

Once you have changed these lines, you need to "install"
the utility. Assuming that book.ksh is now in your PATH, 
"cd" to the directory where book.ksh is held (see above), 
and enter the following...

	book.ksh install

This will set up symbolic links in the default directory.

Then you are on your way !

I suggest that as a precaution, your first command should be...

	bookin book.ksh

Then you at least have a file in SCCS which you can view.
Have a look at the $PROJECTDIR/SCCS directory to verify this.

BASIC COMMANDS
==============
The following commands are symbolic links to book.ksh.

BOOKDIFF	bookdiff <filename>

		Does a 'diff' listing between the current file
		and the version held in sccs.
		This can be helpful for working out what you
		have done with the file since booking it out.

BOOKHELP	bookhelp

		displays syntax info.

BOOKIN		bookin <filename>

		Allows users to "book in" a file to SCCS
		If the first time, create an initial entry, 
		otherwise do a normal SCCS delget.
		
BOOKOUT		bookout <filename>

		"bookout" a file for editing.
		This ensures that the file is booked out of
		SCCS, and the edit mask set.
		
BOOKREAD	bookread <filename> [<version>]

		Get out a read-only copy of a file.
		The version number is optional -
		if it is not included, the default is the 
		latest version of the file.
		(Note: you do NOT need to use a "-r" flag)

		bookread can be a very useful function,
		since you can extract a read-only version of 
		any file into a "/tmp" directory, 
		to view it.

BOOKUNDO	bookundo <filename>

		Undoes the existing editing feature.
		This is the panic "getout" clause.
		It destroys the current file, 
		and replaces it with the latest copy retrieved
		from SCCS.

BOOKINFO	bookinfo <filename>

		Display detailed file information
		This is equivalent to "sccs info",
		but slightly cleaned up.
		
BOOKLIST	booklist

		Lists all file(s) in SCCS
		Try running...

			booklist | grep edit
	
		This either returns a list of current files
		being edited, or the response "nothing being edited".

		In fact, it would be tempting to create
		the symbolic command "bookborrowers",
		to do this for you.
		
		But I will leave that for you to implement.

Dennis Adams
November 1999
=============