CatalogDoc.tioga
Rick Beach, May 30, 1985 2:34:48 pm PDT
Bertrand Serlet July 8, 1986 3:52:55 pm PDT
Michael Plass, December 3, 1987 3:07:34 pm PST
CATALOG
CEDAR 7.0 —
Catalog of
Cedar Software Packages
Richard J. Beach
© Copyright 1985, 1986, 1987 Xerox Corporation. All rights reserved.
Abstract: The Catalog command creates a catalog document of all the software packages contained in a software directory. The catalog describes each package and provides both a command index and a keyword index to the packages. Typically, a catalog is created from a Cedar released-software directory or the CedarChest software directory. However, a catalog can be created from any directory that conforms to the software naming conventions used in Cedar releases.
Created by: Richard J. Beach
Keywords: catalog, documentation, software release
XEROX   Xerox Corporation
    Palo Alto Research Center
    3333 Coyote Hill Road
    Palo Alto, California 94304

1. Contents of a Cedar Catalog
A catalog of Cedar software contains brief descriptions of all the components or packages in that software. Each package has a name and the catalog entry is created from information known about that package. The catalog also contains two indices of commands and keywords for the set of packages.
Package Descriptions
DF File
The DF file refers to the description file for the package software and documentation. By convention, the DF file for Package in software release SoftwareRelease is in a software release directory [Server]<SoftwareRelease>Top>Package.DF. Conventional SoftwareRelease names are <Cedar®> for Cedar releases, <PostCedar®> for revisions to released packages in the corresponding Cedar release, <CedarChest®> for hacks available for a particular Cedar release, where, in all of the above, ® refers to the release number, such as 5.2, 6.0 or 6.1.
Documentation Files
This is a list of documentation files available to describe the package in some detail. By convention, documentation files for the package are named PackageDoc.Tioga and live in the directory [Server]<SoftwareRelease>Documentation>.
Author
The author of the package is provided. In some cases, this may be of historical interest only.
Maintainer
The maintainer is the person or distribution list to whom enquiries should be directed.
Keywords
The list of keywords indicates the topics addressed by this package. The catalog contains an index of these keywords.
Commands
The collection of commands defined in this package are listed. Only those commands that have load files in the package DF file are included in this list. The catalog contains an index of commands.
Abstract or Documentation
The brief abstract or documentation for this package is included in the catalog. If there is no documentation file listed, then this may be the entire documentation available for the package (as in the case of some hacks).
2. The Catalog Command
name Catalog
syntax
Catalog [-quietly] [-releaseMessage] [-documentationWarnings] CatalogName
description
Creates a catalog document for the software packages included in the df file CatalogName.
The -quietly options suppresses the running commentary on the packages being included in the catalog.
The -releaseMessage affects the content of the catalog.
The -documentationWarnings option suppresses warnings regarding documentation files stored in unusual locations. Default is to have warnings.
examples
Catalog -documentationWarnings /DATools/DATools6.1/Top/DAWorldMap.df
Catalog -quietly -releaseMessage /Cedar/Cedar6.1/Top/Cedar.df
Catalog -releaseMessage /Cedar/CedarChest6.1/Top/CedarChest.df
warnings
Catalog will bring all the DF files and documentation files into your local file cache. This may result in a large number of files being flushed from your cache to make room.
stop/undo
Click STOP! in the CommandTool.
implementation
CatalogImpl.Mesa in Catalog.DF
contact
Beach.pa
3. Heuristics for Creating a Catalog Document
DF Files
The argument DF file is enumerated for all its included DF files. Each DF file is assumed to be a package; that is, Package.DF is assumed to refer to the software component Package.
Command Files
The commands are found by enumerating all the exported ".Load" files in Package.DF. The file Command.Load is assumed to refer to the command Command. Commands registered by software without load files are assumed to be private commands and are not included in the catalog. Besides, there is no convenient way to enumerate these commands and discover their existence.
Documentation Files
Documentation files are found by enumerating all the ".Tioga" files in Package.DF. Any file that matches the pattern "*Doc.Tioga" is assumed to be a documentation file and is included in the list of files. The distinguished documentation file, PackageDoc.Tioga is examined to extract the author, keywords, and abstract for the package.
Author
The author is found by searching for a Tioga node with format "authors" in the documentation file PackageDoc.Tioga. Multiple author nodes are concatenated together separated by a semi-colon. Only the title page of the documentation is searched, where the title page is defined to be those nodes preceeding the Xerox PARC address which has format "boilerplate", appropriately enough.
Abstract
The documentation abstract is found by copying nodes with format `abstract' from the documentation file PackageDoc.Tioga. The abstract is defined to begin with the phrase `Abstract' or to be the first node following the copyright notice. The abstract is defined to end just prior to the first node without format `abstract' or an abstract node that begins with one of the phrases `Keyword', `Created by', or `Maintained by'.
Creator
Maintainer
Keywords
The list of keywords is copied from the documentation file. The keyword list is found by searching for a Tioga node with format "abstract" that begins with the phrase "Keyword". The list of keywords is parsed to create a keyword index. Each keyword phrase is assumed to be separated by a comma and the first phrase, assumed to be "Keywords: ", is ignored.