2 User guide A Processing hints

3 Basic Structures of the MSR Application Profile

All MSR DTDs are using some common data structures. These operating models are described in this chapter.

3.1 Not Content Orientated Information (ncoi)

<ncoi-1> contains all basic descriptive element. There also are two weaker ncoi models ( <ncoi-2> and <ncoi-3>) with lesser elements than <ncoi-1>.

3.1.1 Chapter

<chapter> is a sequence of paragraph level elements mixed with <chapter>. <chapter>s can be nested as deeply as required. It is up to the author to make sure, that the nesting of the chapters can be handled by the processing system5.

Figure 4: chapter content model (crpchapt.eps)

One advantage of using <chapter> for all levels6 is the option to move a chapter using cut & paste to any place in the document at any level.

3.1.2 Paragraph Level Elements

<chapter> usually is a sequence of paragraphs <p>. For an unordered set of items, use <list type="unnumbered">. For a sequence of items use <list type="numbered"> 7.

The user should first look for an appropriate one among the available elements (which hopefully are displayed by the SGML authoring system) before trying to simulate things by using inadequate elements. In that respect the following hints are given:

Note
<labeled-list> is one of the most powerful elements available. This note is marked up using <labeled-list> 9. It cannot be expressed enough that <labeled-list> should be used to express more structure in the text flow.

3.1.2.1 Labeled List

<labeled-list> is one of the most powerful elements. If possible it is rendered as a label followed by the item body:

term1   this is term 1
        being term 1

term2   this is term 2
        being term 2

term3   this is term 3
        being term 3

The indentation is determined by the rendition system which should take into account the biggest <item-label>.

Sometimes the author wants some influence to the indentation. For this respect <indent-sample> can receive any content which is used by the rendition system as a sample which must be rendered and measured to determine the indentation.

The attribute [item-label-pos] defines how the <item-label> should be handled. The default value of the attribute is [item-label-pos="no-newline"] . If an <item-label> is wider than <ident-sample> the most general case is to start the item body in a new line if necessary([item-label-pos="newline-if-necessary"] ):

term1 which is overlong
         this is term 1
         being term 1

If the attrbute has the value [item-label-pos="newline"] the item-body is starts generally in a new line.

Note that <indent-sample> can be used to adjust the indentation if there are multiple <labeled-list>s which should have the same indentation.

3.1.2.2 Figure

<figure> is used to insert graphics into the document. A figure can be defined in three different ways.

  1. as a real <graphic>

  2. as an ASCII graphic (<verbatim>)

  3. as a pure textual description (<desc>) of the graphic 10

The treatment of the graphic is determined by the attributes of <graphic>:

[category]
Denotes the category of the graphic. This information can be used to generate more specific list of figures
[filename]
Denotes the system filename where the rendition system can find the graphic. This is not necessarily the final format. It is up to the rendition system to locate the graphic in the company specific environment, to change the file extension to get the appropriate graphic representation.
The type of this attribute can be turned from SDATA toENTITY in the DTD file in order to allow SGML tools access to the file using its entity manager. In this case, the entity name should be chosen in the style of a filename (e.g. crpctmt.wmf)11.
[fit]
0
figure is placed in original size. If it does not fit on the page, it is scaled down.
1
the figure is scaled up or down to fit the page as possible. This value will be ignored if [width] or [height] is specified in addition.
2
the figure is rotated counterclockwise by 90° if it is landscape and is wider than the actual text area. It is scaled down to the page size if it does not fit otherwise. This value will be ignored if [width] or [height] is specified in addition.
3
the figure is always rotated counterclockwise by 90°. If it does not fit on the page it will be scaled down. If [width] or [height] is specified in addition, the figure will be rotated and then scaled to the specified values.
4
the figure is always rotated counterclockwise by 90° and scaled up or down for best fit on the page. This value will be ignored if [width] or [height] is specified in addition.
[height]
If this attribute has a value, the figure will be scaled to the defined height which is a real value with dimensions (e.g. "10cm", "150mm", "12.5in"). If also [width] is specified the figure will be distorted. This value always specifies the width of the "figure box" on the page after possible scaling/rotating.
[notation]
This attribute specifies the format of the graphic file if used by an SGML Application supporting notations.
[scale]
If this attribute receives a value, the figure will be scaled by the given factor which must be a signed real number. Numbers greater 1 increase the size of the figure, values less than 1 make the figure smaller. For example with scale="0.5" the a figure of the size 10x10 cm will appear as 5*5cm.
[width]
If this attribute has a value, the figure will be scaled to the defined width which is a real value with dimensions (e.g. "10cm", "150mm", "12.5in"). If also [height] is specified the figure will be distorted. This value always specifies the width of the "figure box" on the page after possible scaling/rotating.

The scaling attribute precedence is:

3.1.2.3 Note

A note is an object to express a combination of an icon with descriptive text and an additional label. This is useful for things like cautions, hints etc..

The attribute [notetype] defines the note category. The following values are available:

If the attribute [notetype] has a value of "other" the user has to specify a own type within the attribute [user-defined-type] .

A formatter has to place the right icon before the descriptive text according to the value of [notetype] or [user-defined-type] . The optional <label > can be used to define a title of the note.

3.1.3 Character Level Elements

Character level elements can occur within element like <p>, <item-label>. There are rendition oriented elements like <e> (emphasis), <sub> as well as semantically oriented Elements as <tt> (technical term) or <std>(referring to an external standard). It is highly recommended to use rather semantically oriented elements than rendition oriented ones.

3.1.3.1 Rendition Oriented Character Level Elements

The rendition oriented character level elements are:

<e>
Emphasizes the text. The attribute [type] determines the rendition style.
<sub>
Subscript - places the contents with smaller font below the base line.
<sup>
Superscript - places the contents with smaller font above the base line.

3.1.3.2 Semantically Oriented Character Level Elements

Table 1: semantically oriented character level elements
Element use for example
<tt> Use for any technical term. The type of that term is determined by the attribute [type] 12.
This element could be treated as a back-door to markup information which is not totally semantic. The SGML processing system can generate list of technical terms which makes it easier to find misspellings and other errors.
This is an SGML tag <tt type=sgmltag>
we can collect all <tt>s
<xref> Used to create links in the document. The role of the target is determined by the attribute [id-class] receiving the value of the target's fixed attribute [f-id-class] . The attributes of <xref> should be maintained by the authoring system.  
<xdoc> Used to refer to an external document which usually is not available electronically. <xdoc> receives a set of elements characterizing the external document Details to architectural forms can be found in , Pos. .
<ft> Is used to create footnotes Footnotes seem to be small and unimportant13.
<ie> creates index entries It is not necessary to put SGML tags into the Index, since the processing for MSRREP.DTD recommends to create a list of SGML tags automatically.
<xfile> Is used to create pointers to external files which are not to be processed by the native SGML processing system. The contents of <xfile> can be used to connect to appropriate systems in later steps of the processing chain. The schematic is found in MOTRONIC wiring diagram, FILENAME: motronic.asc, NOTATION: concept-ascii-format, TOOL: concept, TOOL-VERSION: 2.7
<std> Is used to refer to a standard. SGML is defined in Information Processing - Text and Office Information Systems, Standard Generalized Markup Language, Nr. ISO 8879, v. 1986, Status: standard, Pos. entire document
Table 2: usage of technical terms
type use for example
<tt type=sgmltag> Used to describe SGML tags including attributes To describe SGML tags use <tt type=sgmltag>.
<tt type=sgml-attribute> Used to describe SGML attributes outside of tags The sgmltag is denoted by the attribute [type]
<tt type=tool> Used to mention tools used for example in a process. This can be software, as well as mechanical tools. The tool should be specified by its nature not by the specific product name. SGML files are processed using an SGML processing system.
<tt type=product> Used to mention specific products. This document is processed using MetaMorphosis.
<tt type=variable> Used to mention a variable informally. This is used to control the rendition as well as for generating variable lists. This is mainly for informal reports14. It is also possible to use this to mention a variable in the ECU software if no <sw-data-dictionary> is part of the document. In a later process step, this can be turned over to a formal <xref> The initialization is controlled by the environment variable MMRC.
The initial advanced angle is calculated based on NandTL.
<tt type=state> Used to mention a state for example of a process. The documents must at least be revised if they are submitted to the customer.
<tt type=prm> Used to mention a state for example of a process. It is also possible to use this to mention a calibration parameter in the ECU software if no <sw-data-dictionary> is part of the document. In a later process step, this can be turned over to a formal <xref> The initial advanced angle is calculated using a lookup table KFZW.
<tt type=material> Used to mention material. Furniture is usually made of wood and plastic
<tt type=control-element> Used to mention control elements of tools like push-buttons, menu items, switches etc. as well as keyboard keys. To finish the dialog push the OK button.
<tt type=code> Used to markup program in line code sequences MetaMorphosis is invoked with mm crp.sgm
<tt type=organisation> Used to markup the name of an organization. SGML is standardized by ISO
<tt type=other> Used to mention a special term which does not fit to the other types. This is a back-door for the definition of user defined types. They have to be specified within the attribute [user-defined-type] . A formatter uses this user defined type only if [type=other] . This is a thing not covered by <tt>.
Table 3: sub-elements for xdoc and xfile
Element use for example
<number> Used to markup the document ISBN resp. the standard number ISBN 0-7923-9432-1
<state> Used to markup the state of the referred document resp. standard. released
<date> Used to markup the release date of the referred document resp. standard. This could be expressed as year only, if the exact date is not known. 1994
<publisher> Markup the publisher of the document or the standard. This can be the author as well as the publishing organization. Steven J. DeRose and David G. Durand / Kluwer Academic Publishers
<position> Markup the relevant position in the referenced document resp. standard. Chapter 5.2 - Architectural forms
<subtitle> Used to markup the subtitle of the referenced document or standard if there is one. HyTime
<short-name> Used to markup the document identifier SGML
<long-name> Used to markup the main title of the referenced object. Making Hypermedia work
<file> Used to markup the file access information. This is intended to be processed by external systems. MOTRONIC wiring diagram, FILENAME: motronic.asc, NOTATION: concept-ascii-format, TOOL: concept, TOOL-VERSION: 2.7

3.1.3.3 How To Change Paragraph Level Elements

If the author decides to turn the markup style e.g. from a <list> to a <labeled-list> certain procedures can be helpful. In most cases (unless there is an automatic conversion tool controlled by processing instructions) the easiest way is to create the new structure and to move the data using cut & paste. In some cases, there are better ways:

<list> to <labeled-list>
  1. Turn off rules checking
  2. change the <list> into <labeled-list> 15
  3. change all <item>s into <labeled-item>
  4. insert <item-label>s or change the appropriate <p>
  5. Turn on rules checking and validate the selection
<labeled-list> to <list>
  1. Turn off rules checking
  2. change the <labeled-list> to <list>
  3. change all <labeled-item>s into <item>
  4. change all <item-label>s to <p>
  5. Turn on rules checking and validate the selection
sequence of <p> to <list>
  1. Turn off rules checking
  2. Insert or a <list> ahead of the area to change
  3. move the desired <p>s into the first <item>
  4. turn on rules checking
  5. perform a splitat the appropriate locations to split the one <item>
  6. validate the selection
sequence of <p> to <labeled-list>
  1. Turn off rules checking
  2. Insert or a <labeled-list> ahead of the area to change
  3. move the desired <p>s into the first <item>
  4. perform a split at the appropriate locations to split the one <labeled-item>
  5. insert <item-label>s or change the appropriate <p>
  6. turn on rules checking
  7. validate the selection

3.1.4 Table

<table> is implemented as CALS table . Capturing these kind of tables must be supported by the SGML editor, so only some hints are given here:

Note
It is highly recommended to insert <thead>. This creates a table heading which is repeated on each page, if a pagebreak falls into the table.

3.1.5 Parameter tables

User Definable Parameters

For structured documentation of individual numerical and/or alpha-numerical requirements, so-called parameters are available. They have the following structure:

* parameter
* long-name
* short-name
* description
* parameter characteristics
* condition
((* absolute value and tolerance16or
* minimum, typical, maximum value17)
* unit) or
* text18

The following representation example can be drawn from this structure:

<short-name> UB
Table 4: Parameter structure
    <prm-char>  
Element: <long-name> Element: <short-name> Element: <min> Element: <typ> Element: <max> Element: <abs> Element: <unit> Element: <tol>  
Operating voltage UB 10,8   14,2   V    
      13,5 V 5 %  
Colour of housing   red, green and blue  
Function state   active  

3.2 Predefined Document Structure

The automotive systems to be described with the help of this DTD possess very different specifications. Because of this, the specification of a particular topic, e.g. "acoustic characteristics" might not make sense or might only become necessary later on, depending on the project.

This situation was also taken into account in the DTD through the elements "<na>" (not applicable), "<tbd>" (to be defined) and "<tbr>" (to be resolved) as shown in Figure 5, Principles of information acquisition. This is a mechanism is located at each element on chapter level and works like a check list. A user has to make a statement for each topic.

Figure 5: Principles of information acquisition (graf010.eps)

If a certain topic is not applicable it has to be marked with <na>. If it is applicable it can be marked with either with <tbd> which indicates that someone has to do a job, or it can be marked with <tbr> which indicates that a specification already exists but it hasn't yet been included, or a detail specification can be defined.

The elements <na>and<tbr> can be described with a short description. Within the element <tbd> the persons responsible for the definitions that have to been made can be specified with <team-member-ref>s. The schedule for the definitions can be defined within <schedule>.

3.3 Project Data

Registering and documenting development of a MSR system is project-oriented, whereby there may be several versions of the product data of a project. The projects can be combined with the help of main projects. This can be defined within <overall-project> by a <label> an a short description in <desc>. Each project is assigned to a maximum of one main project.

The documentation and continuation of project phases occurs in versions. We differentiate between active versions, the data of which can still be modified, and fixed versions, the data of which can no longer be modified. New versions can be designed on the basis of a fixed version. New versions can reuse complete fixed versions of a document or even parts of such a document. This is illustrated by the following figure:

Figure 6: Project structure (graf004.eps)

Project data can be described by a PDM system in an integrated SGML-Editor and PDM environment. This is information on the current project and possibly the main project. A typical example of this is company-specific information on the <team-member>s and <general-project-data> (goals, parallel developments, reasons for order, etc.).

3.4 Administrative Data

Since the respective companies explode the interchange DTD into fragments and use it for the respective acquisition DTDs (perhaps in different departments), the administrative dataappears in many places in the DTD. Each of these places can be used as such a fragment(see below).

Figure 7: Support of DTD fragmentation through administrative data (graf011.eps)

The operating model is

3.5 Variant Concept

Especially in the automotive sector there is a multiplicity of different variants of a part type. Normally there is not only one variant documented in the system requirements respectively the product specification of such part types.

To understand the implementation of the variant concept in the MSR DTDs, first some definitions have to be made:

Variant Characteristic
Characteristics that lead to a new variant e.g. engine, product line, country, etc. Characteristics are defined in <variant-char>. The characteristics have to be subdivided in three classes. These are:
Variant Definition:
Definition of several variants with their variant characteristics for a part type.
Variant:
A variant of a part type is defined through the values of it's variant characteristics.
Variant Coding:
Allocation of all variant definitions to their corresponding subject- and drawing- numbers and the respective development versions.

Within the MSR DOC DTD variant-specific specifications could be made at different positions. These are:

The following the example shows a coarse specification of a harness with two different variants.

It is accepted, that the system consists of a control unit, a sensor and the harness. The harness has one variant (==> a subject number) for USA (I) and Japan ([II]) and one variant (==> a subject number) for Europe ([III]).

This is illustrated by the following figure:

Figure 8: harness variants (variant2.eps)

The specification of the harness in the MSR DOC DTD occurs within the system specification in following the type and manner:

First the three part types "control unit," "sensor" and "system" have to be defined. For the project the variant definitions with the variant characteristic "country hardware" have to be defined.

After this a further part type "harness" with two variants (==> two subject numbers) named "I, II" and "III" have to be defined. At the interface specification no variant definition (optional element < variant-def-refs>) is required. This means that the interface specification is valid for all variants of the part type! The definition of the signal specification within the harness can be proceeded in the same way. Next the (internal) signals of the part type "harness" have to be assigned to the pins of the (rear of the) plug-type connector. This happens with the< connection> elements. At the assignment of pin 1 of the plug-type connector for the control unit the variant No. III has to be defined for this connection. Thereby this connection is dropped automatically for the variant "I, II" ( see Figure 8, harness variants).

Caution
Because the lines within a cable-tree also have to be specified, the possibility to specify connection components (<connection-comp>) at the signal-pin assignment is required.

After the harness has been defined as a part type, this could be built in as a part within the part type "system". Next the signals on the system-level, i.e. within the part type "system", have to be assigned to the harness interfaces. Because the harness variants are identically installed within the system part type, there is no need to make a variant definition (with optional element variant-def-refs) at this place.

With the MSR DOC DTD it is possible to specify the essential harness specifications out of control unit's point of view. A complete specification of a harness naturally takes place with EDA-tools.

3.6 Multilinguality

The MSR DTDs can be configured for multilingual operation. To use the multilingual DTD configuration the DTD switch "multilinguality : YES or NO" have to be set.

The description of multilingual texts is made through multiple terminal elements that is multiple elements with content of #PCDATA. Multilingual elements get one of the additional language elements <l1>,<l2>, <l3>,<l4>,<l10> to build an aggregate of terminal elements. These language elements provide an attribute [l] where the language of this element can be specified. The content of the attribute [l] have to be defined as two-letter lower-case symbols according to the Code for the representation of names of languages, Nr. ISO639:1988(E/F), Pos. Part1

 

Figure 9: Multilingual Paragraph (mlingual.eps)

2 User guide A Processing hints