=Paper=
{{Paper
|id=None
|storemode=property
|title=Edition of Structured Documents in a Hypertext Environment
|pdfUrl=https://ceur-ws.org/Vol-961/paper26.pdf
|volume=Vol-961
|dblpUrl=https://dblp.org/rec/conf/caise/BuorsV89
}}
==Edition of Structured Documents in a Hypertext Environment==
https://ceur-ws.org/Vol-961/paper26.pdf
EDITION OF STRUCTURED
DOCUMENTS IN A HYPER-
TEXT ENVIRONMENT
Christine Buors
Jean-Louis Vignaud
(
Cap Gemini Sogeti Group
Cap Sesa Research Center
(
Chemin du vieux chene
ZmST 38240 MEYLAN
FRANCE
Abstract
This paper presents the TWlST (Technical Writer's Integrated Support
Tool) project. The system developed within TWlST can be viewed as a
high level hypertext system intelface, as well as an environment for the
edition of structured documents. This paper explains in which way the
two points of view are addressed. In particular, it describes TWIST ob-
jectives and the means carried out to reach them. This presentation will
led us to introduce the hypertext and stmctured edition concepts
Key words
Documentation! document! role! stl1lctured edition! hypertext
- to provide some help in writing and ns-
1. Introduction ing the documentation during the whole
project life cycle.
Documentation is one of the key compo- To meet these objectives an environment
nents in any project, and particularly in is under specification. This paper pre-
the software production domain. Indeed sents the main functionalities which will
documents are often the most suitable be supported and the underlying con-
and the most reliable communication me- cepts. The choice of the functionalities to
dia. Even if some people agree with the be provided has been based on an inves-
idea that we generally write too much, tigation of users' needs and on our own
we cannot avoid the production of a mini- unf0l1unate experiences.
mum set of documents. The current sys-
tems carried out in most companies,
leave the user feeling uncomfortable: ev- 2. The documentation
erybody has experienced, at least one
time in his life, the agony of the poor
problem (
lonesome writer. We can easily imagine
that a good documentation sUpp0l1, or en- Management of documents is a well-
vironment, is really a need in any activity known problem in any domain. There are
domain (and therefore in the computer generally many kinds of worries:
based activities).
In the context of ESF (Eureka Software - the problem of writing: a lot of people
Factory) this problem has been ad- still dream of a fancy editor allowing the
dressed. ESF is an Eureka project use of bold characters without using bar-
whose major interest is the management barous signs such as \\f-, $(, and so on,
of large projects (that means, projects in- not to mention the luxurious versions al-
volving a lot of people). In this context, lowing the "What You See Is What You
problems such as activity management Get" !
and control, integration, and man-ma-
chine interface design are addressed. The - the problem of homogeneity: how is it
aim of the project is to provide companies possible to avoid, in the same project,
with a way to design their own software the use of anarchical document formats,
environment, according to their specific other than doing a visual control?
needs and resources.
ESF is a very large project divided into - the problem of consistency: when docu-
sub-projects according to different ments share information (for example a
themes. TWIST - Technical Writer Inte- schema), how is it possible to control the
grated Support Tool - is one of these evolutions of this information in all the
sub-projects. As indicated by its name, documents?
TWIST deals with documentation man-
agement problems. Its two main objec- - the problem of organization: when docu-
tives are: ments are finally written (phew!), the
- to improve the quality and the produc- last problem is to localize each document
tivity of documents within a software among others. This work is really impor-
project; tant: particularly in that it introduces a
reading order.
The documcntation of a project is the
- and the last problem (but not the least set of all the documents produced dming
1), how to manage a document all along the project life cycle. To be easily man-
its life cycle (versions, archiving, etc.) ? aged these documents must be classi-
fied. This classification generally de-
In the domain of computer science the pends on the organization of the compa-
problem is particularly important since ny, and on the method used to develop
any activity is sanctioned by a document. the project. The method, also indicates
The set of the documents produced with- which role is responsible for the creation
in the whole life cycle of a project there- and the update of a set of documents (or
fore constitutes a mountain! In the con- a specific document) and indicates which
text of large projects, all the problems roles may consult or modify this set.
previously mentioned are increased.
(
Before going further, let us introduce a
few vocabulary that will be used in this 3.. TWIST functionalities
paper.
The aim of TWIST is to prove that the
A rolc corresponds to the representation
current technology in computer science
of people functions in the organization of
allows the design of an efficient solution
the production process. For example, in
to all the problems described above.
the software production, we may identify
We think that the improvement of docu-
the following roles: secretary, support
ments quality and productivity goes with
manager, project manager, programmer,
methodological support for organization
analyst, sales manager, system engi-
of documentation, standardization and re-
neer, etc. With roles are related activi-
use of documents, automatic generation
ties, responsibilities and ability to per-
of documents, archiving capacities and
form actions to access (more or less
maintenance help.
"confidential") information. The different
roles in a company are identified by the
For doing so, TWIST will provide some
method used for the production. Obvious-
functionalities that could be classified in
ly, roles are played by physical persons
\ three large classes:
named actors.
- those dealing with the organization of
the documentation
A documcnt is an organized set of text,
- those dealing with the management of
graphics, formulae, etc. For TWIST, doc-
the documentation of a specific project
uments are structured and constituted of
- those dealing with the manipulation of
three types of information: the structure,
content of documents
the presentation and the content of the
document. The content is updated by the
Each of these functionalities corresponds
user while editing the document. The
to the need of a particular role within a
structure and the presentation corre-
company or a project. Each of the specific
spond to a standardization of the docu-
roles allows the definition o( an environ-
ment.
ment in which concerned functionalities
.3
will be implemented by tools. project documentation.
Unlike documentation models, project
documentations have a content: the docu-
3.1 Management of documenta- ments realized during the project life cy-
tion OI'ganization cle. Documents belonging to a library
may be included in a project documenta-
Design of the organization of a documen- tion. On the opposite, documents belong-
tation consists in combining documents ing to a project documentation may be
in sets, describing all the relationships stored in a library.
between these sets, defining standards When created (see section 3.1.3), docu-
of presentation and structure for the doc- ments may be archived or moved from a
uments contained in these sets, and as- set of docnments to another one. These
sociating a list of roles with their rights manipulations me also available for sets
on each set. of documents.
TWIST provides the possibility to de- Otherwise, TWIST allows automatic
scribe several structures of documenta- generation of a document providing that
tion. These suuctures will be used as its content has been desclibed.
models for documentation of projects: All the manipulations described in this
each time a project starts, the best section me generally performed by the re-
adapted structLU'e of documentation is sponsible of documentation within a
chosen, and then duplicated. A project project, and grouped in an environment
documelltatioll can therefore be consid- named document manager environment.
ered as an instance of a model documell-
tatioll
Documentation models manipulations 3.3 Management of documents'
and creation of instances for projects are content and versions
attributed to the same role (for example,
the method engineer) and grouped in an As soon as a project documentation has
environment named administrator envi- been defined, one can create documents.
ronment. Creation, destmction, and consultation of
documents are obviously realized using
an editor. Nevertheless, TWIST provides
3.2 Management of a specific new functionalities concerning co-author-
project documentation ing, information sharing and inter-docu-
ment references. These capacities are al-
A project documentation is therefore an so supported by the editor. Additional
instance of a model of documentation. functionalities concern versions of docu-
This instance may be particularized to fit ments (listing versions, purging ver-
special constraints bound to the project . sions), and impression of documents
For example, a set of documents defined (printing facilities).
in the model may be obsolete for a specif- These manipulations are grouped in an
ic project, or a set of documents may environment named writer/reader envi-
need a particular presentation for a typi- ronment or editing environment.
cal project. TWIST allows this kind of ad-
aptation. In this case, the modifications
performed are local to the concerned
tion. Another way to increase the produc-
tivity is in reusing documents existing in
4. How these functional- other documentations. Generally in a
company some reference documents
Hies meet TWIST objec- could always be used to make new docu-
tives ments (for example, contract, quality
plan, etc.). This con'esponds to the cul-
ture (or experience) of the company.
Since we mentioned TWIST objectives in
These kinds of documents should be in
the introduction of chapter 3, we must
free access libraries: one can then import
now examine in which way the functional-
( any document desired in his own docu-
ities proposed will ensure them.
mentation, eventually attributing some
4.1 Methodological support specific properties to it (for example, new
roles and access rights).
( The organization of the documentation
and the association of role/rights upon 4.4 Automatic generation of docu-
each set of documents depend on the ments
method used to develop the project.
Providing a way to descxibe documenta- Generally in a company, many software
tion models, TWIST therefore ensure a environments are used assisting people
methodological support for the develop- in their work. Each of these environ-
ment of any project. ments manages its own data. For exam-
If the scheduling of document production ple, an environment supporting project
is not a goal for TWIST, any component management has the data needed to pro-
able to perform this capacity can be inte- duce monthly reports. Generally this en-
grated to TWIST (in the context of soft- vironment is able to produce these kinds
ware factory). of documents. The problem is that the
documents produced are not managed by
4.2 Standardization of documents the documentation support environment,
l and therefore they are not consulted,
We have seen that structure, presenta- printed or archived like the other docu-
tion and content of documents can be con- ments of the project.
trolled independently. Using TWIST envi- In the context of software factories,
ronment, the work of a the author of a where environments or tools are able to
document is reduced to writing its con- communicate easily, all the documents
tent. That is good way to increase the may reside in the documentation environ-
productivity. Moreover the use of the ment. In particular, TWIST is able to gen-
same structure and the same presenta- erate documents providing that their
tion for all documents of a same set war- structures and presentations are de-
rant at least an equal quality of presenta- scribed, and pJincipally their content is
tion. specified. Describing the content of a doc-
ument consists in providing the paths to
4.3 Reuse of parts of documents find some data in another environment. A
TWIST allows information shaJing special mechanism is then able to inter-
among documents of a same documenta- pret them, generating the specified docu-
ment. find a quality plan concerning real-time
applications in the nuclear domain").
4.5 Editing support These kinds of request may be assumed
by TWIST providing that documents are
TWIST provides capabilities of:
annotated with comments or specific in-
- managing the co-authoring, in indicat-
formation.
ing the part of documents reserved by au-
thors
TWIST manages infOlmation sharing and
- sharing parts of documents. in main-
references between documents. It allows
t.aining the consistency between the dif-
archiving and versions control.
ferent documents sharing an information
- inter-document referencing. in manag-
ing links between parts of documents.
These functionalities are not managed by
5. Concepts used to im-
the editor: this allows the possibility to plement TWIST
integrate to TWIST any editor (providing
that it manages structure and presenta-
The two main underlying concepts of the
tion standards).
TWIST implementation are structured
edition and hypertext stmctures and ma-
4.6 Archiving capacities
nipulations
Documents have to be archived in the life
cycle of the project. Archiving a document
means that this document is considered
finished and no more modifiable. 5.1 Structured document edition
TWIST allows the definition of an ar-
There are two kinds of documents manip-
chiving property which will be attached to
ulation system based on two document
documents. The management of relations
models. A possible model consists in de-
between archived documents and non-ar-
scribing documents as characters flows
chived ones is ensured.
containing special control characters (line
4.7 Maintenance help jump. page jump, spaces...). Another kind
of model consists in taking into account
Documentation maintenance help re- the logical stmctures of documents: in-
quires at least two capacities: stead of only desclibing their physical
- brownsing of the documentation presentations. it describes their organi-
- maintaining consistency within the doc- zation in telm of chapters. sections, sub-
umentation. sections, titles. etc. The physical repre-
sentation is described separately.
Using the documentation structure, a us-
er may be able to find (more or less easi- We have chosen to use this second ap-
ly) a specific infOimation. This action is proach. A document is defined by two ge-
more difficult to realize since the expres- neric descriptions: its logical structure,
sion of the request is not very precise but its default presentation. These descrip-
corresponds to a semantic information tions allow the classification of docu-
(for example, request as "I would like to ments in classes.
The logical structures are essentially
tree structures: nodes are components of
the logical structure (chapter, section,
etc.), and links represent inclusion rela-
tions among nodes (e.g., section I ->
sub-section I.1). The structure is de- 5.2.1 Graph
scribed using rules. The brows of the doc- A graph is a set of nodes, including links
ument is equivalent to a path in the tree. and reference links. For example, G, set
The physical presentation is attached to of nodes NI, N2, N3, reference link RLI
the logical structure. The presentation is and including link ILl, is a graph
defined by a set of 11Iles. It allows the
( definition of multiple views of a same
document (e.g., the document is viewed
as a whole or as its table of contents).
The content of the document is dis-
( patched among its nodes.
G
5.2. Hypertext concepts
An Hypertext abstract machine (or
o: graph " : including link
HAM) allows the manipulation of five
D : node \.... : reference link
types of objects: the type-graph, the
type-context, the type-node, the type-in-
cluding-link and the type-reference-link.
Objects of these types are, respectively, Property:
graph, context, node, including link, and All the graphs are disjoint (i.e., two dif-
reference link. ferent graph - which have different
An object is identified by a name. Each names - cannot include the same node,
tinle an object is modified a new version or the same link).
of it is created.
Each class of object may own at- Use ill TWIST:
tributes/values pairs. The amibutes and A project documentation 1Il TWIST is a
the values are either imposed or speci- graph.
fied by the user (i.e., the user can create
all the attributes/values pairs he needs).
The manipulations provided by the HAM
5.2.2 Context
are creation, destruction, modification of
all these objects. A context is a part of a graph. It is a set
of nodes, including links and reference
We can now described more precisely links. For example C = {Nl, N3, ILl}
the different objects introduced below, means that C is a context of the graph G
and explained in which way they can be
used within TWIST.
the first node in the associated pair of
nodes. (I.e., if NI belongs to C and ILl
relies NI to N2 then ILl and N2 belong
to C)
G If a link (reference or including) is associ-
.. c ated to two nodes belonging to the same
. - - - - /.... context, then the link belongs also to the
context (i.e., if NI and N2 belong to C
and L connects NI to N2 then L belongs
o:graph \ :including link to C).
If a link (reference or including) belongs
o : node \..: reference link to a context then its two associated
():context nodes belong also to the context. (I.e., if
'of
L belongs to C and L connects NI to N2
then N I and N2 belong C)
If a link (reference or including) is associ-
ated to two nodes, and one of the two
Property: nodes is destroyed, then the link is also
Contexts do not have intersection. There- destroyed.
fore, they can be used to create a parti-
tion of the graph. Use ill TWIST:
Including links in TWIST are used to re-
Use ill TWIST: alized documents structures, and refer-
A context may have an intersection with ence links are used to realize references
another one, particularly a context may between documents or parts of docu-
include other contexts. ments.
A document (or a set of documents) in
TWIST is a context.
5.2.4 Node
5.2.3. Including link, Reference link From the HAM point of view, a node is
an atomic object characterized by its con-
A link is associated to a single orderly tenl.
pair of nodes. It is the only a way to con-
nect nodes in a graph. For example the Use ill TWIST:
including link IL I, in the graph G I, is as- Within TWIST, the content of a docu-
sociated to the (NI, N3) pair. ment is stored in nodes.
An including link defines an including re-
lation between two objects. A reference
link defines a simple relation between
the two nodes. 5.2.5 Attribute
An attribute is a property bound to an ob-
Properties: ject (graph, context, node, including link,
An including link and its two associated reference link). This object is character-
nodes belong to the contexts including
ized by the value of its property. An ob- The hypertext concepts [Con 87] associ-
ject may own several (attribute/value) ation is a "plus": it allows a large range
pall's. of manipulations among documents and
Attributes are not pre-defined one may set of documents. Using HAM concepts
create any property desired. [Del 86], [Del 87]" the documentation
can be viewed as an hyper-docl/mellt.
Use ill TWIST: The shating and reference (among docu-
Within TWIST, atu'ibutes are used to ments) functionalities can be easily car-
specify special properties. For example, ried out. The functionalities provided for
the pair (author/J.Smith) bound to a spe- the administrator and responsible of a
( cific node N3, means that J.Smith is the project documentation users are essen-
author of the content of the node N3. tially supported using hypertext mecha-
nisms ..
6. Conclusion
author/smith
G The starting point of our work has been a
functional description of TWIST. This
first approach assured us that providing
the user with an integrated documenta-
0: graph \ : including link tion support is not an utopia. Moreover
the concepts carried out are well-known.
0: node \. : reference link
The CUITent step consists in specifying
~ : attribute atld designing a storage component
based on the HAM concepts, aiming at
providing, for September 1989, a proto-
type which will support the three environ-
5.3 Summary ments described in this paper.
We expect that before the end of 1989, at
The two concepts previously described least one project in our company will use
concern respectively the two types of ob- TWIST.
jects manipulated by TWIST: the docu- We hope that this prototype will be the
mcnts, and the set of documents starting point of further investigations
(documentation). both in the improvement of the edition
functionalities and in the extension of the
The structured edition clearly allows an use of hypertext concepts to other stor-
easy manipulation of parts of a document, age components within ESF.
the definition of any kind of link inside the
document. The structured edition concern
esscntially the reader/writer user. The
edition in TWIST is supported by GRIF
[Quint 86], [Quint 87].
References:
[Con 87]: J. Conklin. Hypertext: An Introduc-
tion and Survey, IEEE Computer, September
1987
[Del 86]: Delisle N. and Schwartz M. - Nep-
tune : A hypertext system for CAD applica-
tions, Proceedings ACM SIGMOD '86
(Washington D.C., May 28-30, 1986), 132-
142.
[Del 87]: Delisle N. and Schwartz M. - Con-
texts : A panitioning concept for Hypertext,
ACM Transactions on Office Information sys-
tems 5,2 (April 1987), 168-186.
[Quint 86]: V.Quint, I.Vatton,. GRIF: An In-
teractive System for SU'uctured Document
Manipulation, Proceedings of the Internation-
al Conference, J.C van Vliet, ed., Cambridge
University Press 1986
[Quint 87]: V.Quint. Vne approche de
l'edition structuree des documents, These
d' eta!, Universite scielllifique Technologique
et Medicale de Grenoble, Mai 1987