.require	"doc_rno:stdreport.rno"
.require	"STANDARDS.ttl"

.header	level 1	Introduction

	The purpose of this report is to give an overview of the standards
that have been followed in the organization what is to be referred to as a
'Toolkit'.
	The notion of a Toolkit is to encompass a collection of files, below a
common directory, that help in performing some function.
This could be for Document Development, Software Tools Development, or
the management of Toolkits.

.header	level 1	Standard Toolkit Files

	The files that are described here, are applicable to any directory
within the Toolkit structure.

.header	level 2	AAAREADME.TXT

	Each directory will have a descriptor file in it, unless it is a CMS
library, that is machine readable via any editor (EDT for example) or
printable.  This will detail the purpose of the directory, and list the
important files that are of note within the directory.

	Information about subdirectories will be kept to a mimimum, as they will
have their own AAAREADME.TXT files in them.

	In many cases there will be AAAREADME.RNO files, that allow the easier
maintenance of the AAAREADME.TXT file.  This could take advantage of the
Document Development Toolkit utilites that are suited to this (BLDREADME,
AAAREADME, or RNOTODOC).

.header	level 2	SETLOGS.COM

	If any references are to be made to anything that resides in a
directory, there should be a SETLOGS.COM file that will define logical names
for the directory.

	This file is written to use the current default device and directory,
by the use of lexical functions, and MUST BE RUN IN DIRECTORY IT RESIDES IN.
It will have embedded absolute directory names in it, only relative directory
names that refer to directories below itself.
This is done to
ensure that there will be no future problems associated with the pathnames of
the directory changing.

	An example of this could be a SETLOGS.COM file in the Toolkit
found in the directory
SYS_$USER1:[AMBY.EXAMPLE].

.literal

	$ SET DEFAULT	SYS$USER:[AMBY.EXAMPLE]
	$ @SETLOGS
.end	literal

.header	level 2	SETSYMBS.COM

	If any global symbols are to be defined, as part of a Toolkit,
they are done with the SETSYMBS.COM procedure.  This will make use of any
logical names that are defined as part of the SETLOGS.COM file, so it assumes
that all of the logical names are defined.

	At a minimum there will be a SETSYMBS.COM file in the root directory
of a Toolkit, but there can be SETSYMBS.COM files in subdirectories to the
Toolkit's main (root) directory.
If there are SETSYMBS.COM files in Toolkit subdirectories, they will be
also run from within the root SETSYMBS.COM file (by using defined logical
names).

	An example of this could be a SETSYMS.COM file in the Toolkit
found in the directory
SYS_$USER1:[AMBY.EXAMPLE], that is known to define the logical name
AMBY__EXAMPLE in the SETLOGS.COM file

.literal

	$ @AMBY_EXAMPLE:SETSYMBS
.end	literal

.header	level 1	Toolkit Root Directory Files

	The next group of files, are those that should only be found in the
root (top-level) directory of a particular Toolkit.

.header	level 2	BUILDKIT.COM

	This will be a command procedure, that can be run from the Toolkit
root directory, that will rebuild the HELP.HLB and SETUP.SET files.
This will allow an easy method to be sure that the help library and the
setup file is correct, with respect to the file system where it resides.

	This file will typically make use of some of the Toolkit Management
Tools (BLDSYMHLP, BLDSETUP, and BLDHELP), and therefore you will need to have
them defined before running it.
This will also make use of the logical names that are defined in the SETLOGS.COM
procedure, so will need to have run this as well.

	An example of this copuld be a Toolkit in the directory
SYS_$USER1:[AMBY.EXAMPLE], where the BUILDKIT.COM procedure is to be run.

.literal

	$ SET DEFAULT	SYS$USER:[AMBY.EXAMPLE]
	$ @BUILDKIT
.end	literal

.header	level 2	SETUP.SET

	This file is constructed with the BLDSETUP utility, that is part of
the Toolkit Managment Toolkit, and will be the only file in the Toolkit that
is to have an embedded directory pathname in it.

	This is then run as a DCL command procedure, from any default directory,
and will run the SETLOGS.COM and SETSYMBS.COM procedures that are in the
Toolkit root.  This is shown in the following example, for a toolkit that is
assumed to be found in the directory SYS_$USER1:[AMBY.EXAMPLE].

.literal

	$ @SYS$USER1:[AMBY.EXAMPLE]SETUP.SET
.end	literal

.header	level 1	Logical Name Conventions

	While there is a lot of freedom in the decidinn on logical names that
are to be used within a Toolkit, some guidelines will make it easier to
manage them.

.list

.list	element	;No Dollar (_$) Characters.

	To ensure that there will never be any problems, in a VAXcluster
environment under VMS 4.0, you should avoid embedded dollars.

.list	element	;Toolkit-Wide Prefix.

	Within a Toolkit it is recommended that you have some prefix for
all logical names that apply to that Toolkit, and that they are unique.
An example of this is the Toolkit that has been set up for Document Development,
where the prefix is to be DOC.

.literal

	DOC_TOOLS	- Toolkit root directory.
	DOC_RNO		- Toolkit Runoff template files directory.
	DOC_UTILS	- Toolkit utilities directory.
.end	literal

	This allows the easy checking of whether the logical names for the
Toolkit are defined, using the SHOW LOGICAL command.  The following would
display all of the above logicals.

.literal

	$ SHOW LOGICAL	DOC_*
.end	literal

.end	list