Plato, SGML and revolution   Table of contents   Indexes   SGML Databases &, Content Management for the Web
 
 

Making an IETP – a real life experience
 
Karen   Lease
  Project Leader, R&D
  Sogitec Industries
4, rue Marcel Monge
Suresnes   France  92158
Email: lease@sogitec.fr
Phone: (33) 01 4118 5889
Fax: (33) 01 4118 5649
 
Biographical notice:
 
Karen Lease
 
Karen Lease is responsible for research and technological innovation in the areas of document management systems and publishing technologies at Sogitec. She was first bitten by the SGML virus at Texet in 1983 where she helped develop a pioneering WYSIWYG structured editor. Since then she has worked extensively in the development of both paper and electronic based publishing systems for documentation. Her most recent project involved the design of the publication process for the Falcon Interactive Electronic Library by Dassault (FIELD 4.0).
 
ABSTRACT:
 
This presentation discusses the major problems with which we were confronted in automating the creation of SGML interactive electronic technical publications (IETP) for aircraft maintenance. The principal topics addressed are: multiple source formats, multiple configurations, navigation mechanisms and style sheet issues.
 
 IETP 
 

Overview

 
As the title suggests, this presentation describes a real-world experience of building an SGML IETP  (Interactive Electronic Technical Publication) . It is based on the production processes which we have developed at Sogitec to produce CD-ROM based IETPs for use by aircraft maintenance technicians. The starting point is a mixture of SGML and non-SGML source data, partly managed in an SGML DMS  (Document Management System) . The destination is an integrated set of SGML electronic publications in which various navigation methods work together to provide users with rapid access to the information they need. We hope that the different issues we have confronted and resolved will be helpful to others producing SGML/XML-based publications.
 
 

Dealing with multiple source formats
 
A complete IETP is actually a set of several related technical manuals including:
  • maintenance documentation,
  • illustrated parts catalog,
  • tool and consumable information,
  • periodic service documentation (bulletins, newsflashes, etc.),
  • related documentation (eg. general repair techniques, specific equipment manuals).
 
Source formats for these manuals range from SGML to traditional databases to paper. A major task in building the IETP involves integrating these diverse documents into a unified structure. We have chosen to treat all of the manuals in our IETP as collections of SGML documents. The following sections describe the issues particular to each kind of source format. Figure shows an overview of the IETP building process.

 
Overview of the process

 
 
 

SGML sources
 
The principal maintenance documentation is stored as SGML document units in a production document management system which handles version, configuration and workflow issues. Both text and graphic components are managed in this database.

Note:

 
For the curious, the DMS is the SDI  (Système Documentaire Industriel) developed at Sogitec. This system manages SGML documents as a hierarchy of document units based on the structure of the DTD.
 
The decision to manage maintenance documentation as relatively low level document units is important for the later production of the publications. A single document unit may be included in several versions of a publication. These versions typically depend on the configuration of a particular aircraft covered by the maintenance publication. The implications of this on the production process will be treated in more detail in section .
 
 

Information stored in non-SGML databases
 
Much of the other documentation integrated into the final IETP is not stored as SGML documents. This is the case with spare part, tool and consumable information which is managed in separate databases. Each such database has its own data format, as well as its own cycle of updates. Successful integration of this kind of data in the IETP depends on:
  • coordinating the update cycle with the updates to the maintenance documentation (for example, using the same codes for the spare parts),
  • converting the data from these external sources into a form (SGML in our case) which can be used with the publication system.
 Note:  
 
When these databases are not managed by the same organization as the principal documentation, these seemingly simple requirements can lead to complications. A change in the source format which impacts the extraction format can mean changing the conversion programs and perhaps the DTD (and the style sheets...) Obviously such changes will occur from time to time. But this emphasizes the need for close communication and long-range planning concerning all the sources for an IETP .
 
Specifically, in our aircraft maintenance IETP, we use information from four different external databases:
  • a database containing spare part information (and associated illustrations),
  • a database of standard tools and equipment (and associated illustrations),
  • a database of ingredients and consumable products,
  • a database containing information about required maintenance operations.
 
For each database, we designed a specific DTD and developed a conversion program (using Omnimark for example) which takes the export format provided and creates an SGML instance conforming to the DTD. (In most cases we have little or no control over the export format provided.) These documents frequently serve as link destinations, and in some cases (such as the required maintenance operation list) as link sources. They also contain information which is used to support the creation of semantic full-text indexes. Therefore it is critical to be able to translate the pertinent information in the exported data into an appropriate DTD. Ideally, the DTDs for these documents are structure- rather than presentation- based, but certain constraints on the desired form must be taken into account during the DTD design process. (For more on the relation between SGML structure and presentation issues, see .)
 
 

Non-SGML documents
legacy documents
 
Frequently, not all the textual information which is incorporated into the IETP is stored in SGML. In our system, certain legacy documents such as previously issued newsletters or newsflashes needed to be converted into SGML for inclusion in the IETP. Depending on the form of such documents (paper, straight text, word-processing, typesetting or desktop publishing documents), they can pose difficult conversion problems. This is particularly true of documents produced over a long period of time with a variety of tools and styles.
 
In spite of these difficulties, we chose to convert such document s into SGML. This choice allows us to:
  • handle these documents with standard style sheets,
  • index them in the same collection as the rest of the documentation,
  • provide a standard user interface to all documents.
 
configuration management
data module
document unit
 

Handling multiple configurations in a single publication

 
The production DMS handles configuration and version management for individual SGML document components called DU  (Document Units) . (The AECMA 1000D calls these Data Modules.) A publication is built by selecting certain DU from the DMS and organizing the access to them. The same DU may be used in several different publications. A particular IETP may be specific to one particular configuration or may describe several different aircraft or equipment configurations.
 
In a publication containing information concerning several configurations, our IETP lets the end-user choose which information to see, based on his configuration. However, DU which are part of several configurations are not duplicated, but shared. This poses interesting problems for both hierarchical access and hypertext links.
 
 

Document units and publication units
 
The division of a manual into DU for production purposes is frequently not the same as the logical unit of the publication. For example, a work card is a typical publication unit. But a single work card frequently contains several MP  (maintenance procedures) , which may be managed as independent DU. An MP might exist in several versions, each of which is specific to a certain configuration of the equipment. When building the publication unit (the work card) for a particular configuration, the appropriate version of each individual MP is physically included. But if the publication covers several configurations, it must either:
  • include a separate version of the work card for each configuration,
  • or include all of the applicable configurations in the work card.
 
The first solution not only increases the size of the publication, but this duplication propagates upwards in the document structure, since the level which calls the work card now has several configurations. In the second case, there is no problem with duplication, but there can be a problem with redundant information. If the end-user of the documentation frequently needs to use all of the included configurations, then the inclusion of the different procedures is probably a good idea, as long as they are clearly distinguished (a job for style sheets). On the other hand, some differences should not be easily visible, for example, those which differentiate airplanes belonging to competing companies. In this case, the inappropriate information must be hidden (using style sheets for example, perhaps in combination with encryption.)
 
 

Multiple configurations and hypertext links
 
The construction of publication units is not the only problem posed by multiple configuration IETPs. A link to a different element in the publication can also bring up this question. For example, suppose that one MP refers to another. The first MP is common to several configurations, but the referenced procedure exists in several versions which are configuration-specific. The user of the IETP is assumed to be working with a particular configuration (or group of configurations). In this case, when the user activates the link, the target should be only the MP (or MPs) which are appropriate to those configurations, and not to the others.
 
This situation also occurs w ith graphic entities. It is frequent to have a document which is common to several configurations but which uses configuration-specific graphics. Only those graphics applicable to the current viewing configuration should be visible.
 
The best technique for resolving this problem depends on the browser technology being used. One possible approach is to view this as a parameter of the entity manager. In this case, the links are “generic”, which is to say, they don't specify a fully qualified destination. Another approach is to create as many links as there are possible configurations, and to only activate those which are appropriate in a given consultation environment. This solution doesn't require a specific entity manager, but does require the ability to hide the inappropriate link elements, usually with a style sheet. In either case, both the IETP production process and the viewing technology are involved in the solution.
 Note:  
 
An additional aspect of multiple configuration IETPs concerns full-text indexes. When doing a search, only the “hits” in documents which belong to the current configuration should be shown.
 
 

Building navigation mechanisms
 
A user of the IETP may access documents using hierarchical tables of contents, hypertext links, full-text searches, or direct access (for example, the number of a work card). Most of these forms of navigation are only implicit in the source documents, but must be made explicit in the IETP.
 
 

Building hierarchical tables of contents
 
Frequently a manual has several levels of structure “above” the publication unit level. This structure may either be modeled explicitly by the source DMS or be defined by an independent structure (similar to the AECMA 1000D idea of access tables). In our IETP, these levels are modeled as entries in a hierarchical table of contents. The lowest level in this table corresponds to the publication units themselves, which are accessed by hypertext links. The data preparation process automatically creates these tables of contents. As part of this process, links to the parent document, and to the preceeding and following documents may also be introduced into each publication unit to provide sequential navigation.
 
Some types of documentation, such as service documentation, have no hiearchical structure. In these cases, keyword based indexes are automatically created to facilitate access to the information. An example is an index of standard ATA  (Air Transport Association) topics in a collection of newsletters.
 
 

Creating hypertext links
 HyTime 
 clink 
hypertext navigation
 
The creation of hypertext links is the core of the publication process. It is highly dependent on the source DTD (the DTD of the DU). Since our document management system was designed with electronic publications already in mind, we are lucky to have not only a rather complete tag set for indicating semantic elements such as spare part numbers, equipment identifiers, and procedure references, but also a source base which actually uses these tags.
 
However, a tag which is called <tool> and whose content (or whose attribute) is a tool number or code, is not a hypertext link. The actual IETP uses basic HyTime clink architectural forms for expressing links. A link destination is either a complete entity or a particular element (identified by an ID) in an entity. In some cases a link may have multiple destinations, which can be a mix of entities and elements. Getting from the tag to the clink therefore involves deciding which entity contains the target, and, if it is an element, how it will be identified.
 
For each tag which will be treated as a link, one must first decide which manual (or manuals) in the IETP contain the target. Depending on the structure of the manual, one might be able to deduce the name of the entity from the link target. This is frequently the case where the link destination is an entity in the publication. For example, the name of the entity containing a work card might be built up from the number of the work card.
 
If this isn't possible, then we must build a lookup table which relates the identification of various link destinations in the source document to the entity name/element ID combination which contains the target in the IETP . Building such a lookup table usually means making a first pass over the target documents to determine the eligible targets and their localization. This information can then be used to create the links in the source documents, or to signal the non-existence of the desired target.
 Note:  
 
This latter situation should not be ignored, especially when dealing with documents which have evolved over a long period of time. Even if semantic tagging has been carefully done, identifications change over time, and references are not always updated. One of the benefits of this process of sewing everything together is finding out that a certain number of references are no longer accurate.
 
 

Custom navigation mechanisms
 
Certain kinds of access necessitate special preparation. A good example of this is graphic hotspots . These are particularly useful in manuals such as spare parts documentation. A hotspot defines an area on a graphic which can act as either a link source or destination (or both).
 
Hotspots are defined as SGML elements. They may either by created manually, or by an automated process. For example, OCR  (Optical Character Recognition) could be used to find text zones on scanned graphics. For vector formats, it is usually possible to identify text zones by analysing the graphic file. In both cases, one must develop rules to designate “interesting” text zones and to reject others. Based on the recognized text content, SGML ID and IDREF values can be automatically generated. When using automatic hotspot generation, a manual control phase is still needed to verify the results.
 
 style sheet 
 

Presentation issues

 
Although electronic publications are less constrained by formal issues than paper publications, the creation of appropriate presentation is still an important task in the development of an IETP. Typographic parameters must be adjusted to maximize the readability of the information on a display. Frequently the documentation will be viewed on a portable computer with limited screen real estate.
 
The use of electronic documentation can also motivate changes to the traditional presentation of a document. For example, users may find that tabular presentations (of for example, consumable information) are less readable on a screen than on paper. If the IETP DTD is sufficiently structured, it is usually possible to format the data in an alternative way, better suited to the medium. For example, the data for a single product can be presented in an index-card format.
 
Limitations in current SGML browser technology and/or in what can be expressed in a particular style sheet language can sometimes lead to the need for a publication DTD, distinct from the source DTD. Problems related to the DTDs of the source documents themselves can also lead to the need to transform the instance. A frequent problem is lack of a containing element on which to "hang" numbering or formatting information. For example, definition lists defined like <!ELEMENT deflist - - (term, def)+ > can cause formatting problems. It is easier to handle this definition:
 
<!ELEMENT deflist - - (defitem+)
>
<!ELEMENT defitem - - (term, def)
>
 DSSSL 
 XSL 
 
Flow Object Tree based style languages such as DSSSL  (Document Style Semantics and Specification Language) or XSL which support a richer query and scripting language than most existing style sheet languages will reduce the need to transform source document structure to IETP structure. But performance issues may still motivate source document transformations.
 
 

Conclusion
 
The mechanisms described here are currently being used to produce IETP s on CD-ROM for four families of Falcon business jets. Although we cannot (yet) pretend that there are no surprises in our production cycle, we feel that we are well on the way to a fully automatic data preparation process. The key elements of this process are:
  • source DTDs which provide sufficient information to support a rich navigation model,
  • rigorous management of source documents with version and configuration control,
  • automated conversion procedures for non-SGML document sources,
  • a powerful style sheet language.
 
Today's rapid developments in the XML and XSL areas have reinforced our conviction that the investment in SGML as both as source format and a viewing format is justified. We are looking forward to continuing progress in this area.
Plato, SGML and revolution   Table of contents   Indexes   SGML Databases &, Content Management for the Web