⟦7a128ee97⟧

TextFile

~setup(doublesided)

~string_macro(reg="~superscript(~char(313))")
~string_macro(tm="~superscript(~char(312))")
~string_macro(copyright="~superscript(~char(314))")
~macro(cmd="~bold(~typewriter(~argument(text)))")
~macro(key_font="~null(~environment(font_family=helvetica-narrow)~argument(text))")
~macro(key="~key_font([~argument(text)])")

~macro(revision_date="~string_macro(revision_date_value=[~argument(text)])")
~revision_date(~value(date,month_day_year))

~left_footing(~value(page)~>~>~null(~environment(point_size=9)~revision_date_value)~ ~ ~ ~null(~environment(font_family=avantgarde-book,point_size=20)RATIONAL))
~right_footing(~null(~environment(font_family=avantgarde-book,point_size=20)RATIONAL)~ ~ ~ 
~null(~environment(point_size=9)~revision_date_value)~>~>~value(page))

~setup(itemized_paragraph_format=~~char(183)~|~~char(32)~|~~char(32)~|~~char(32)~|~~char(32))
~environment(font_family=Palatino-Roman,justify_mode=justified,point_size=11)
~setup(indented_pp_indent=14points)

~environment(point_size=20)

~center(~bold(The Rational Software Catalog: Design and Toolset))

~environment(point_size=12)

~blankspace(2)
                              
~majorheading(Overview)

The Rational Software Catalog is a mechanism for delivering software to
end-users outside the context of standard Environment releases.
                             
The user receives a tape and a release notice. The release notice tells
the user how to install the catalog, and how to operate the catalog
~italic(browser).
                      
The browsing program is menu-driven, and it allows the user to preview
the contents of the catalog, to get a description of a particular item
in the catalog, or to extract a particular item from the catalog and put
it in some library (without having to construct a complicated
~cmd(Archive.Restore) command~footnote(The catalog is delivered in
archived form as a Data and Index file, from which items can be restored
via ~cmd(Archive.Restore) commands. These commands can be fairly complex
without the assistance of the browser.)). The user-interface to the browser
is designed to be as close to the standard Environment user-interface as
possible.

The browsing program has a parameter which allows the user to specify
the location of the catalog's Data and Index files to be browsed (a
default location is used if none is specified).

~majorheading(Items)

Items in the catalog come from a variety of sources:
~startip
~ip
Rational tech-reps, technical consultants, and developers
~ip
Customers
~ip
Public Domain
~ip
other sources
~endip

Depending upon its origin and the significance placed upon it by the
author(s), an item may be released with no restrictions, or may have
various restrictions placed upon its use and distribution. Similarly,
the support offered for a particular item may range from non-existent to
fairly well-supported. The level and kind of support available, as well
as any restrictions, are documented for each item.

Items in the catalog exist in one of four forms:
~startnp
~np
~italic(Visible units) items consist of a subsystem which contains at least
one load view containing Ada source. The item may or may not contain spec
views.
~np
~italic(Code only) items consists of a subsystem which contains no load
views containing Ada source. The item may or may not contain spec views.
~np
~italic(Free form) items consist of some arbitrary library structure (subject
to the limitation that the outermost scope must be a library of major class
~italic(World).)
~np
~italic(Environment) items are not actually part of the tape, because they
are already a part of the standard Environment. This kind of item is used
to acquaint users with tools and interfaces in the Environment which they
may not otherwise be familiar with.
~endnp

Items may import other items in the catalog, and may also import subsystems
outside the context of the catalog.

~majorheading(Sections)

Sections exists in one of two forms:
~startnp
~np
~italic(Textual) sections consist only of text, and have no actual physical
realization in the library structure.
~np
Sections of kind ~italic(item) contain 1 to N items. Such sections
serve as a grouping mechanism for clustering similar items together
under one major heading.
~endnp

~majorheading(General Library Structure)

Software Catalogs are arranged on the host machine (the machine where the
catalogs are maintained prior to being released) as follows:

~begin(verbatim)
~begin(null)
~environment(point_size=9)
!Software_Catalogs
    .Catalogs
       <CATALOG 1>
          .Sections
             <SECTION 1>
                <ITEM 1>
                <ITEM 2>
                 ...
                <ITEM N>
             <SECTION 2>
                <ITEM 1>
                <ITEM 2>
                 ...
                <ITEM N>
              ...
             <SECTION N>
          .Versions
             <VERSION 1>
             <VERSION 2>
              ...
             <VERSION N>
       <CATALOG 2>
          .Sections
             <SECTION 1>
                <ITEM 1>
                <ITEM 2>
                 ...
                <ITEM N>
             <SECTION 2>
                <ITEM 1>
                <ITEM 2>
                 ...
                <ITEM N>
              ...
             <SECTION N>
          .Versions
             <VERSION 1>
             <VERSION 2>
              ...
             <VERSION N>
        ...
       <CATALOG N>
          etc
    .Defaults
    .Templates
~end(null)
~end(verbatim)

As indicated above, multiple catalogs, as well as multiple versions of a
particular catalog, can co-exist on a single machine.

~majorheading(Tools Structure)

The Software Catalog toolset depends on several invariants being satisfied
with respect to the location of libraries on the machine. The general
structure is as follows (this must be adhered to or the tools will not
work properly):

~begin(verbatim)
~begin(null)
~environment(point_size=9)
!Software_Catalogs
    .Catalogs
       .Customer
          .Sections
             .Software_Catalog_Tools
                .Software_Catalog_Tools
                   <VIEWS>
                   .Templates
             <OTHER SECTIONS>
                <OTHER ITEMS>
          .Versions
             <VERSION 1>
             <VERSION 2>
              ...
             <VERSION N>
       <OTHER CATALOGS>
    .Defaults
    .Templates
~end(null)
~end(verbatim)                        
              
Within any given view in the ~cmd(Software_Catalog_Tools) subsystem, the
subdirectory structure is as follows;

~begin(verbatim)
~begin(null)
~environment(point_size=9)
.Software_Catalog_Tools
   <VIEW> 
      .Exports
      .Imports
      .State
      .Units
         .Browser
         .Commands
         .Structure
         .Utilities    
~end(null)
~end(verbatim)
                          
~majorheading(Getting Started)
                                       
The Software Catalog tools import three other items in the Catalog:
~startip
~ip                
~cmd(Objects) (located in the ~cmd(Directory_Tools) section)
~ip
~cmd(Miscellaneous_Components) (located in the ~cmd(Reusable_Components)
section)
~ip
~cmd(Window_IO_Utilities) (located in the ~cmd(Input_Output) section)
~endip

These three items should be extracted and compiled first before installing
the Software Catalog tools themselves. Once all four items have been 
successfully installed, generate a code view for each item and edit your
default activity to have entries for the spec views and code views for
all four items.

Once the default activity has been edited, add to ~cmd(!LOCAL) a link to
the package ~cmd(Catalog), which is located in the ~cmd(Commands)
subdirectory within the ~cmd(Units) directory of the spec view for the
Software Catalog tools. Edit your searchlist so that it has an entry for
~cmd(!LOCAL`).

Create two worlds ~cmd(Defaults) and ~cmd(Templates) in
~cmd(!Software_Catalogs). (These two directories are shared by all
catalogs on the machine.) Copy the contents of the ~cmd(Templates) directory
in the ~cmd(Software_Catalog_Tools) subsystem to the ~cmd(Templates) world
you just created; once the templates have been successfully copied, destroy
the ~cmd(Templates) directory in the subsystem.

~majorheading(The Command Set)

You are now ready to execute commands. All commands are prefixed with the
package name ~cmd(Catalog). You should print out the spec for this catalog
and familiarize yourself with the comments.

If you are creating a brand new catalog, run the command
~cmd(Catalog.Build_Catalog). If you are creating a new version of an
existing catalog, run the command ~cmd(Catalog.Build_Version).

Almost all commands accept either an explicit catalog name and/or version,
or one or more default values. Defaults are established on a user-by-user
basis by running the command ~cmd(Catalog.Set_Defaults). The defaults are
stored in files in the ~cmd(Defaults) library you created earlier (although
there is no reason you should ever have to edit the files directly).

~majorheading(The Data File)

The single point of maintenance for the Software Catalog is a text file
called the ~italic(data file). The data file has a special syntax for
describing the structure of the various items in the catalog, what kind of
items they are, their imports, a description of each item, what spec and
load views should be used for a particular item, what models and links
are allowable for a particular catalog, and more.

The data file syntax is described in detail in the package ~cmd(Syntax),
which is located in the ~cmd(Structure) subdirectory in the ~cmd(Units)
directory of the load view of the ~cmd(Software_Catalog_Tools) subsystem.
Basically, the data file consists of ordinary text interspersed with
special lines of text called ~italic(annotations). In addition, Rational
document formatter markup language can be embedded in the data file.

Data files are stored on a version-by-version basis: each version library
contains its own data file.

~majorheading(The Structure Package)

The ~cmd(Structure) package is located in the ~cmd(Structure)
subdirectory in the ~cmd(Units) directory of the load view of the
~cmd(Software_Catalog_Tools) subsystem. The ~cmd(Structure) package is
responsible for parsing the data file and for constructing from it an
in-memory data structure which can be more readily manipulated by other
programs in the Software Catalog toolset. Changes to the syntax of the
data file are thereby concealed from clients of the ~cmd(Structure)
package.

Clients of the ~cmd(Structure) package include ~cmd(Catalog.Check_Consistency),
~cmd(Catalog.Build_Release), ~cmd(Catalog.Generate_Booklet), and the browser.

~majorheading(Usage Scenario)

For an individual maintaining a Software Catalog, the most typical
usage scenario is:
~startip
~ip   
Starting from some baseline, the default catalog and version for the user
are established.
~ip
As new items or sections are added to the catalog (or old ones are updated),
the user edits the data file for the user's default version to reflect the
changes.
~ip
As the time for a release approaches, the user runs
~cmd(Catalog.Check_Consistency) to verify that the catalog as specified
in the data file is consistent with respect to all of the various invariants
which must be satisfied to produce a good tape. Any inconsistencies are
fixed, and the consistency check is performed again. The process is repeated
until there are no more inconsistencies.
~ip
When the release is due, the user runs ~cmd(Catalog.Build_Release) to create
a release tape for the Software Catalog. In addition, the user runs
~cmd(Catalog.Print_Booklet) to generate a laser-quality printout of the
contents of the tape, and runs ~cmd(Catalog.Print_Release_Notice) to generate
a laser-quality printout of the release notice for the catalog.
~ip
After the release deliverables (i.e. tape, booklet, and release notice) have
been handed off to the group(s) responsible for producing copies, the user
runs the command ~cmd(Catalog.Build_Version) to create a new version of the
catalog from the old version (freezing the old version in the process).
~ip
The cycle is repeated for the next release, using the new version as the
baseline.
~endip

~majorheading(Other Important Files)

There are three other files besides the data file which require explanation:
~startnp
~np
~italic(Document_Setup_File:) This file should contain any and all
macros, ~cmd(~~setup) commands, and ~cmd(~~environment) commands which you
would like used when formatting the booklet and/or release notice with
the document formatter. (This file is interpreted first, before any other
markup language is processed.)
~np                         
~italic(Printer_Options_File:) This file must contain, on the first line of
the file only, the string which you would like passed to the ~cmd(Options)
parameter of the ~cmd(Queue.Print) command when printing the booklet and/or
release notice (i.e. ~cmd(Class=!!Logo!Mlaser,p=(REVERSED=FALSE))). 
~np                          
~italic(Browser_View_Name_File:) This file must contain, on the first line
of the file only, the simple name of the load view which should be used
when generating the loaded main browser when building a release of a
Catalog (i.e. ~cmd(Rev1_0_1)). (This information cannot be extracted from
the default activity, since the default activity contains code views
instead of load views.)
~endnp

Like the data file, these three files are maintained on a 
version-by-version basis.

~majorheading(Tool Limitations)

There are two limitations to the current toolset:
~startnp
~np
~italic(Concurrency:) The current toolset is not robust in the face of
simultaneous use by several individuals with the same default catalog
and version. Several kinds of collisions may occur under these
circumstances (although with very low frequency). This was a deliberate
design decision, and it has worked well so far (since typically very few
people are responsible for maintaining a particular catalog).
~np
~italic(Job Page Limit:) When building releases of very large catalogs,
the job page limit may be exceeded. If this happens, the job page limit
must be increased, and the release must be rebuilt. (It should be pointed
out that this is not particularly likely to occur: the Software Catalog
released by Rational does not exceed the job page limit, and it is
very big.)
~endnp

Maintenance of the Software Catalog tools is currently handled by the
Technical Consulting group within Rational. Please direct any and all
questions to that group. Feedback, suggested improvements, questions
about setup or usage, and bug reports are all welcome.
DataMuseum.dk

Rational R1000/400 Tapes

⟦7a128ee97⟧ TextFile

Derivation

TextFile
