jimbi@copper.TEK.COM (Jim Bigelow) (02/12/88)
This is the ms source for my paper Hypertext and CASE presented at
CASE'87 in Boston last May and it will be printed in IEEE Software,
in March.
: This is a shar archive.
: Remove everything above this line.
: Run the file through sh, not csh.
: type `sh article.prt1'
: If you do not see the message
: `article.prt1 completed!'
: then the file was incomplete.
echo extracting - man.ms
sed 's/^X//' > man.ms << 'SHAR_EOF'
X.RP
X.AD 0
X.ND December 17, 1987
X.so title.ms
X.HY 0
X.so lead.ms
X.so discus.ms
X.so conclusion.ms
X.[
X$LIST$
X.]
SHAR_EOF
echo extracting - title.ms
sed 's/^X//' > title.ms << 'SHAR_EOF'
X.TL
XHypertext and CASE
X.AU
XJames Bigelow
X.AI
XComputer Aided Software Engineering Division
XDesign Automation Group
XTektronix, Inc.
XP.O. Box 4600
XBeaverton, Oregon 97075
X.AB
XCASE systems require a method to tie various documents, memos, source code,
Xetc. together to provide coherent system documentation.
XThese systems also require
Xcomplete version
Xhistories of everything in a project.
XHypertext
Xmeets these requirements and
Xprovides an excellent data model for CASE systems.
XThis paper describes
Xhypertext and the Hypertext Abstract Machine, built at Tektronix,
Xand shows how hypertext is useful for CASE applications.
X.AE
SHAR_EOF
echo extracting - lead.ms
sed 's/^X//' > lead.ms << 'SHAR_EOF'
X.PP
XThe heart of any CASE system is its database
X.[ \*{
XPenedo Stukle 1985
X.] ,
X.[
Xsoftware engineering environments H\*:unke 1981
X.] ,
X.[
XDelisle Schwartz 1986
X.] \*}
Xwhich must provide at least three capabilities:
X.IP \fB\(bu\fR 10 5
XThe ability to logically associate documentation and source code.
X.IP \fB\(bu\fR 10 5
XThe ability to make annotations for recording explanations and assumptions.
X.IP \fB\(bu\fR 10 5
XThe ability to provide good version management.
X.PP
XA CASE environment places other demands on a database, due to
Xthe nature of large scale projects and project teams.
XThe database must support simultaneous access by team members and
Xsupport editing and authorship in a computer network.
XTeam members also must be able to work independently without
Xinterference from
Xother team members and then be able to merge their work back into the
Xmain project; a taxing demand on a configuration management system.
X.PP
XThe database must allow specific configurations or version trees
Xto be built, along with the ability to subsequently merge version branches
Xback into the primary version.
XMeeting this requirement provides the fundamentals for good version management
Xas well as the functionality for a configuration manager.
X.PP
XIn search of a system that meets the above requirements, researchers at
XTektronix built Neptune,
Xwhich demonstrates that hypertext
Xprovides an appropriate data model for CASE systems.
XHypertext is a medium grained, entity-relationship-like data model that
Xallows an arbitrary structuring of information and keeps
Xa complete version history of both information and structure.
SHAR_EOF
echo extracting - discus.ms
sed 's/^X//' > discus.ms << 'SHAR_EOF'
X.SH
XHypertext and Neptune Revealed
X.PP
XHypertext
Xwas first conceived as early as 1945
Xas a means of storing all sources of information, both
Xfor ready access and cross referencing.
X.[ \*{
XNelson 1981
X.] ,
X.[
XBush 1945
X.] \*}
XThere are now a number of commercial and academic packages promoting
Xhypertext capabilities.
X.[ \*{
X%A D. Goodman
X%T The Complete HyperCard Handbook
X%D Sept. 1987
X.] \*}
XHowever,
Xthe key to the future success of hypertext is
Xan efficient, application independent data storage method,
Xsuch as was introduced in
X1986, with the development of
XNeptune, at Tektronix.
XNeptune achieves application independency by using a layered system
Xarchitecture; at the bottom is a transaction-based server,
Xthe Hypertext Abstract Machine (HAM),
Xwith applications
Xand a user interface layered above.
XThe HAM provides distributed access over a computer network, and is
Xsynchronized
Xfor multi-user access with transaction based recovery.
XThe HAM also presents a generic hypertext model
Xby defining operations for creating, modifying, and accessing
Xhypertext components .
XA complete information and version history is maintained and rapid access to
Xany version is provided.
X.PP
X\fBHypertext Concepts and Terminology.\fR
XThe basic ingredients of a hypertext system are \fBnodes\fR and \fBlinks\fR.
XNodes provide a means to store data, and links provide the relationship
Xbetween the data in different nodes.
XThe HAM identifies nodes and links by
Xassociating an
X\fBattribute/value pair\fR with a node or link.
XFor example, a node's name attribute is given a value such as
X\*(``module 1\*('' to identify the contents as the source code in module 1.
XInformation is grouped into configurations
Xby using \fBcontexts\fR, collections
Xof nodes and links.
XSince nodes and links may be thought of as directed graphs,
Xa collection of nodes, links, and contexts is called a \fBgraph\fR.
X.KS
X.PP
X\fB An Example CASE Environment.\fR
XAn example C\-based
XCASE environment, DynamicDesign developed at Tektronix, has all of its
Xproject components in the HAM:
X.DS I
X\(bu requirements and specifications
X\(bu design notes and documents
X\(bu implementation notes
X\(bu source and object code
X\(bu user documentation
X.DE
X.KE
X.PP
XNodes are used to contain the project components,
Xand links depict the relationships
Xbetween the components.
XAttributes are used to label the types of nodes and links.
XTable 1 shows
Xthe possible values of two node and link attributes.
X.KF
X.. \" ***** Insert Table 1 Here *****
X.so attTbl.asci
X.KE
X.PP
XIn DynamicDesign,
Xnodes have an attribute, \fIprojectComponent\fR, which identifies the type
Xof project component they contain.
XLinks have an attribute, \fIrelatesTo\fR,
Xwhich shows the type of relation
Xthe link provides.
XFor example, sequential information may be associated by connecting
Xtwo nodes with a link whose attribute, \fIrelatesTo\fR, has a value of
X\fIleadsTo\fR.
XIn Figure 1, module 1 precedes module 2 so they are both stored in nodes
Xand connected by a link having the attribute value \fIleadsTo\fR.
X.PP
XThe relationship between a specification and the code which implements it
Xcan be shown with links.
XThe node containing the portion of the specification (\fIprojectComponent =
Xspec\fR) and a node containing the code (\fIprojectComponent =
Xsource\fR)
Xare related with a link which has \fIrelatesTo = implements\fR.
XAs another example,
Xa link can used to show what module contains the definition of a variable
Xby relating the two modules with a link of type \fIrefersTo\fR.
X.PP
X\fBNodes.\fR
XNodes are similar to the nodes in directed graphs
Xand are used to hold any object in the CASE system: text, graphics,
Xobject code, etc..
XHypertext does not place any constraint on node format, making it
Xparticularly useful for holding, in one database,
Xthe wide variety of information found in the
XCASE environment.
X.PP
XNodes are atomic data units, so the issue of node contents is important.
XIf a piece of data is referenced in more than one place (e.g. a section of
Xtext is in both the requirements and the comments for
Xa section of code) the data should be in
Xa node by itself.
XHowever, the application that uses hypertext,
Xby determining the unit of incrementality used when processing the
Xinformation,
Xis the final arbitrator of how much should be placed
Xin one node.
XFor example, in
Xthe case of a compiler, which can recompile a changed procedure individually
Xwithout recompiling the entire module that contains the procedure,
X.[ \*{
XSchwartz Delisle Begwani 1984
X.],
X.[
Xmedina-mora feiler 1981
X.] \*}
Xthe unit of incrementality is a procedure.
XOther compilers may enforce a larger increment, such as a module.
X.PP
XVersion history, in the HAM, is kept at the node and link level (see the next
XSection for an explanation of link history) .
XWhile lookup time is proportional to the age of the version, all versions
Xof a node's content may be archived and retrieved on demand. When combined
Xwith contexts (see below)
Xthis creates the fundamentals of
Xa configuration manager.
X.KF
X. \"***** Insert Figure 1 here *****
X.so code_cmnt.asci
X.KE
X.PP
X\fBLinks.\fR
XLinks are thought of as the arcs in directed graphs
Xand exist to associate two nodes.
XLinks, along with nodes, form the essence of hypertext; information storage and
Xlinking to allow nonlinear organization of information.
XIn Figure 1, the link connecting the two nodes, paragraph 1 and module 1,
Xprovides the logical association that paragraph 1 comments on module 1.
XIn addition to association, the HAM provides the ability to traverse a
Xlink in either direction.
XThus, while reading paragraph 2, in Figure 1, one can traverse the link to
Xmodule 2, read the module, traverse the link to paragraph 3, and
Xread that paragraph.
X.PP
XIn the HAM, a link is not restricted to merely pointing to the entire node.
XA link is attached, at each end, to any object or place in a node.
XExamples of objects
Xthat a link can attach to are:
Xa character in text, an extent of text (e.g. a sentence or paragraph),
Xan x,y coordinate in graphic information, or a graphics object, such as
Xa process bubble in a data flow diagram.
X.PP
XThe history of a link is the history of its attribute/value pairs and its
Xattachment object within a node.
XBy looking at a link's history you can tell if its name or
Xlocation of attachement point ever changed and what the changes were.
X.PP
X\fBAttribute/Value Pairs.\fR
XAttribute/value pairs extend the power of hypertext, by allowing the
Xorganization of nodes and links into sub-graphs within a single context
X(see below for an explanation of grouping by contexts).
XThe primary objective of attribute/value pairs
Xis to make it easy to access all the information
Xneeded and to restrict the access to only what is needed.
XWith the preceding goal in mind, attributes
Xare used to identify or categorize nodes, links and contexts.
XThe HAM provides an unlimited number of attribute/value pairs
Xso numerous attributes are used to multiply categorize
Xnodes, links and contexts.
XTable 1 is an example of using attribute values to identify the contents
Xof nodes and the meaning of links.
XAnother example is identifying contexts in DynamicDesign.
XContexts are given an attribute, \fIprojectCategory\fR, which has the
Xfollowing values:
X\fIspecifications, design documentation, program documentation,
Xuser documentation, implementation notes, source code,
Xobject code, symbol tables, \fRand \fIproduct\fR (refer to
XFigure 3 for the uses of these attributes).
XThe context attribute is used in the query operations, discussed in the
Xnext section, as a method to locate or filter information.
XAlso, a thorough example of attribute usage in
XCASE environments is presented in PMDB.
X.[ \*{
XPenedo Stukle 1985
X.] \*}
X.PP
X\fBAttributes and Query Operations.\fR
XThe HAM provides a sophisticated set of query operations to both traverse
Xand retrieve a collection of nodes, links and contexts.
XThe query operations use predicates based on attribute/value pairs to
Xdetermine which nodes, links and contexts satisfy the queries.
XFor example, in DynamicDesign, nodes containing source code are placed in the
Xcontext, \fIprojectCategory = source code\fR and have an attribute
X\fIsystem\fR attached to them.
XThe attribute, \fIsystem\fR, can assume any of the following values:
X\fIall, amiga, bsd, eunice, osk, sysv,\fR and \fIvms\fR.
XA node predicate \*(``\fIsystem = all\fR\*('' used in a retrieval query
Xshows only those nodes containing source code applicable to all systems.
XConversely, a node predicate of \*(``\fIsystem = vms\fR\*('' allows
Xaccess to nodes with source code applicable only to VAX/VMS\(dg.
X.FS \(dg
XVAX/VMS is a trade mark of Digital Equipment Corporation
X.FE
XA traversal query using a predicate such as \*(``\fIsystem = all OR system
X= vms\fR\*('' returns the version of the product source code
Xtailored for the VAX/VMS environment.
X.PP
X\fBThe Code and Comments Problem.\fR
XThe documentation
Xof a computer program is usually either
Xsqueezed into the margins of the program where it is generally too terse to
Xbe useful,
Xor its text is interspersed through out the text of the program,
Xbreaking up the
Xflow of both the program and the documentation.
XDynamicDesign allows the program documentation and program source code
Xto
Xexist in
Xseparate nodes with links between them.
X.PP
XFigure 1 illustrates two node types; program code and program documentation.
XThe nodes labeled module 1, module 2 and module 3
Xcontain program source code while the
Xnodes labeled paragraph 1, paragraph 2, paragraph 3, and paragraph 4
Xcontain the documentation.
XFigure 1 also shows two uses of links: the sequential link, \fIleadsTo\fR
Xand the annotative link , \fIcomments\fR.
XBy using this arrangement, either documentation or source code may be
Xviewed
Xby following links typed \fIleadsTo\fR,
Xwithout interruption.
XHowever, if source code requires an explanation, it is seen by following
Xthe \fIcomments\fR link back to its source in the program documentation.
XAlso, while reading the program documentation, source code is
Xviewed at any time by traversing the \fIcomment\fR link.
XThis method provides the program documentation with a freedom from space
Xrestrictions not usually found in conventional, in-code documentation
Xmethods.
X.SH
XContexts
X.PP
XThe concept of a context, i.e. collecting or partitioning
Xnodes and links into a set, was missing
Xfrom hypertext until 1987.
X.[ \*{
Xdelisle schwartz 1987
X.] \*}
XContexts provide a way to group common nodes and links.
XBut they are more powerful than that because
Xcontexts indirectly support cooperative multi-person design and
Xdocumentation of large-scale software systems by directly supporting
Xpartitioning, version trees, and configuration management.
XThe HAM provides operations for creating and populating contexts with
Xnodes, links and sub-contexts.
XA merging operation is provided to allow a subset of nodes and links
Xin one context to be copied into another context.
XThe merge operation has several interesting uses and ramifications that are
Xdiscussed in the next two sections.
X.SH
XContexts and Configuration Management
X.PP
XA context allows
Xthe designation of a configuration of nodes and links.
XWhen a group of source nodes have reached a baseline configuration,
Xthey are moved, with the merge operation,
Xinto another context holding released products.
XFigure 2 depicts the state transitions of two contexts, \fIproject\fR and
X\fIrelease\fR.
XThe states are labeled V0, V1, V2, etc. and are used to show differences
Xin the nodes and links that comprise the content of both contexts.
XFigure 2 illustrates the merging of the content of
Xcontext \fIproject\fR, at state V0,
Xinto context \fIrelease\fR, at state V0.
XDevelopment continues in \fIproject\fR and is shown
Xby the intermediate states V1, V2, and V3.
XAt state V3, in \fIproject\fR, the content of \fIproject\fR
Xis again merged into \fIrelease\fR; yielding
Xstate V1 in \fIrelease\fR.
XOne of the properties of the merge operation is that node and link histories
Xare not moved from one context to another.
XTherefore, while complete node and link histories are preserved in
X\fIproject\fR, the version
Xhistory in \fIrelease\fR is that of the versions of
Xthe nodes and links in \fIproject\fR when they were merged into
X\fIrelease\fR.
XThis means that the nodes and links in \fIrelease\fR do not have a record of
Xthe states V1 and V2 in \fIproject\fR, only states V0 and V3.
X.KF
X. \" ***** Insert Figure 2 Here ****
X.so context.asci
X.KE
X.PP
X\fBContexts and Local Workspaces.\fR
XContexts can also be used to define a workspace and to partition a project
Xinto a project workspace and local workspaces.
X.[ \*{
XErickson Pellegrin 1984
X.] \*}
XA local workspace allows a developer to abstract a subset of nodes and
Xlinks from the project workspace and place them in another workspace.
XThis workspace becomes the local workspace
Xin which developers may make local modifications and test them against the
Xrest of the project.
XWhen satisfied, the developer attempts to merge
Xthe changes back into the system.
X.PP
XIdeally the partitioning of workspaces between developers is disjoint,
Xhowever, this may not be possible due to project and/or requirement
Xconstraints.
XSo, two or more developers may be working on the same nodes concurrently.
XThe chance of concurrent development
Xmeans that when merging a local workspace back into the project
Xworkspace some method of detecting and resolving concurrent updates must be
Xavailable.
XDetection of changes is mandatory to avoid overwriting
Xwork by one or more developers.
XTherefore, the HAM provides operations for detecting differences between both
Xnodes and contexts.
XThese two operations facilitate merging changed nodes
Xback into the project workspace by detecting the differences that may have been
Xmade in the project workspace after the developer created the local workspace.
X.SH
XProject Category Interconnections
X.EH
X.PP
XA project component is any piece of information or data associated with a
Xproject.
XThere are some broad categories that the data can be placed in:
X.DS I
X\(bu management reports
X\(bu specification and requirements
X\(bu design, program, and user documentation
X\(bu implementation notes
X\(bu source code
X\(bu object code
X\(bu products
X.DE
XWithin each of these categories are the actual documents, memos, papers,
Xbinaries, etc. that make up the project.
XBy placing all the components of a project in hypertext, they are archived,
Xrecoverable, and available for use within other parts of the project.
X.KF
X. \"**** Insert Figure 3 here *****
X.so ex2.asci
X.KE
X.PP
XInterconnections between project components exist
Xeven in a project which uses paper documents.
XHowever, there is also much duplication of both effort and documentation.
XAdditionally, many opportunities to point out the relationships
Xbetween components are missed because the effort involved is too great
Xfor the time permitted.
X.PP
XDynamicDesign, the example CASE environment, has all the information
Xconcerning a
Xproject in its hypertext database.
XContexts are used to group the data into the categories mentioned above,
Xshown in Figure 3 and enumerated in the section describing
Xattribute/value pairs.
XThe lines, in Figure 3 which connect the ellipses, representing contexts,
Xshow the direct interconnection and interrelationships between the data in
Xthe contexts.
XDue to the ability to use
Xlinks, one piece of data can be
Xpresent in several contexts.
XTherefore a paragraph about a design may do triple duty, as
Xa comment in the program documentation and a paragraph in both the user
Xand design documentation.
X.PP
XLinks are used to provide traceability of functional requirements.
XA link from a
Xrequirement in \fIspecifications\fR,
Xleads to a data flow diagram in \fIdesign documentation\fR.
XFrom the data flow diagram, a link leads to a structure chart or other
Xdesign document and then back to the requirement.
XThis provides a check on the one-to-one relationship between requirements and
Xdesigns.
X.PP
XLinks also exist from nodes in \fIdesign documents\fR to nodes in
X\fIprogram documents\fR
Xand then nodes in \fIsource code\fR.
X\fIImplementation notes\fR provides a repository for
Xdocumenting assumptions
Xand decisions based on the actual implementation of the design.
XThere are links between the nodes in
X\fIimplementation notes\fR and those in \fIdesign documentation\fR and
X\fIsource code\fR
Xto record the associates between them.
X.PP
XOne real gain from this system is the ease of demonstrating that all
Xthe requirements have been fulfilled.
XStarting at \fIspecifications\fR, links radiate out through the
Xproject; through \fIdesign documentation, implementation notes,
Xsource code, user
Xdocumentation\fR, and back to
X\fIspecifications\fR, forming a graph cycle.
XEvery path from \fIspecifications\fR
Xthat is not a cycle, indicates an unfulfilled
Xrequirement.
X.PP
XDynamicDesign also aides in program maintenance.
XMaintenance personnel are able to read the designer's design documents,
Xassumptions, implementation notes and have them linked directly to the
Xrelevant sections of the code.
XSo the job of gauging the effect of a program modification is aided by
Xeasy access to documentation linked to specific portions of the code.
X.PP
XNote in Figure 3 that the object code and symbol tables, while part of the
Xproject,
Xare only related directly to the source code.
XA compiler integrated with hypertext makes good use of its storage
Xabilities.
XModule symbol tables need not be reconstructed for every compile, but merely
Xupdated.
XA symbolic debugger can make excellent use of the module symbol tables left
Xin hypertext and, since they are in hypertext and not in the object code, the
Xsymbol table and debugging information can be quite extensive.
XWhen a compiler is used with a facility similar to the
X.UX
Xmake facility
Xto generate recompilation commands,
XDynamicDesign becomes a programming environment.
SHAR_EOF
echo article.prt1 completed!
: That's all folks!