16

   

Basic Structures of the MSR Application Profile

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

16.1

   

Not Content Orientated Information (ncoi)

<ncoi-1> contains all basic descriptive elements. There are also elements like <chapter> or <fail-save-concept> in the MSRSYS DTD which have the same content model as <ncoi-1>.

The figure below illustrates the structure of <ncoi-1>.
Figure 113: Structure of <ncoi-1>

ncoi-1.eps


There also are two weaker ncoi models ( ncoi-2 and ncoi-3) with lesser elements than <ncoi-1>. ncoi-2 has no <chapters>. ncoi-3 has also no chapters and futhermore another "topic" model without <prms>.

The components of ncoi FOOTNOTE are interchangeable between all MSR DTDsFOOTNOTE without any changes.

16.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 systemFOOTNOTE.
Figure 114: chapter content model

chapter.eps


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

16.1.2     Topic

Use <topic-1> or <topic-2> to create bridge titles instead of one line paragraphs with entirely emphasized contents. Note that these elements can be referenced by <xref>. In difference to <topic-1>, <topic-2> has no <prms>.
Figure 115: Structure of <topic-1>

topic-1.eps


16.1.3     Paragraph Level Elements

"Paragraph level elements" are elements which occur on the same level as <p>.

The user should first look for an appropriate one among the available elements before trying to simulate things by using inadequate elements. In that respect the following hints are given:
<p>

Paragraph

<verbatim>

Preformatted text which is usually set in monospaced font. Tabs, line spaces and carrige returns are considered.

Use <verbatim> to print program listings etc. It can even be used to show simple diagrams.

<figure>

See chapter Figure.

<formula>

See chapter Formula.

<list>

A ordered or unordered list of items.

For an unordered set of items, use <list type="unnumbered">. For a ordered list of items use <list type="numbered">FOOTNOTE.

<def-list>

Use <def-list> to create definition lists which might be collected into an overall definition list or a glossary. In this case <labeled-list> might lead to the same rendition but has no information about the fact that terms are definedFOOTNOTE.

<labeled-list>

Use<labeled-list> to create explanations or even bridge titles for very short topics instead of bulleted lists with emphasized initial words. See also Labeled List

Use <labeled-list> instead of two column tables if the first column cells almost contain one word.

<note>

See chapter Note

16.1.3.1     Labeled List

Figure 116: Structure of <labeled list>

labeled-list.eps


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

XX      XXXXXXXXXXXXXX
        XXXXXXXXXXXXXX

XXXXXX  XXXXXXXXXXXXXX
        XXXXXXXXXXXXXX

XXXXX   XXXXXXXXXXXXXX
        XXXXXXXXXXXXXX

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"):

XXXXXXXXXX  
        XXXXXXXXXXXXXX
        XXXXXXXXXXXXXX
XXXXXX  XXXXXXXXXXXXXX
        XXXXXXXXXXXXXX
XXXXXX  XXXXXXXXXXXXXX
        XXXXXXXXXXXXXX

If the attribute has the value [item-label-pos]="newline" the item-body 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.

16.1.3.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 FOOTNOTE

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

Do not enter annotating text to <long-name>in<figure> or <table>(like Figure 1: ...). This embellishment is the task of the processing system, not of the author. If the author adds these things, they will be there twice since the rendition system will add it again.
[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)FOOTNOTE.

[fit]
0

figure is placed in original size. If it does not fit on the page or the available space, 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 90o 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 90o. 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 90o 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:
  •  
  •  

    [scale] has precedence over all

  •  
  •  

    [fit]has precedence over [width]and/or [height]

    16.1.3.3     Formula

    Figure 117: Structure of <figure>

    formula.eps


    A formula can be described in five different ways which can exist parallel. These are:
    <graphic>

    A formula prerendered as a figure.

    <verbatim>

    A simple ASCII formula.

    <tex-math>

    A TeX math formula which can be processed by a TeX or LaTeX processor.

    <c-code>

    A formula which is defined as c-code.

    <generic-math>

    This element is intended for the definition of semantic math descriptions which can be processed by math processors. Actually there is no recommentation for the language of the formula specification or usage of a special rendering system.

    It is up to the rendering system which of the available representations is used.

    16.1.3.4     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:
  •  
  •  

    caution

  •  
  •  

    hint

  •  
  •  

    tip

  •  
  •  

    instruction

  •  
  •  

    exercise

  •  
  •  

    other

    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.

    16.1.4     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.

    16.1.4.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.

    16.1.4.2     Semantically Oriented Character Level Elements

    Table 39: 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]FOOTNOTE.

    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 [External Document: / Relevant Position: ].

    <ft>

    Is used to create footnotes

    Footnotes seem to be small and unimportantFOOTNOTE.

    <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 [External FILE: MOTRONIC wiring diagram / Filename: motronic.asc]

    <std>

    Is used to refer to a standard.

    SGML is defined in [Standard: Information Processing - Text and Office Information Systems / Subtitle: Standard Generalized Markup Language / State: standard / Date: 1986 / Relevant Position: entire document]

    Table 40: 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 reportsFOOTNOTE. 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 41: 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.

    [External FILE: MOTRONIC wiring diagram / Filename: motronic.asc]

    16.1.5     Table

    <table> is implemented as CALS table (see [External Document: CALS table spec / Relevant Position: all] at www.oasis.org). Capturing these kind of tables must be supported by the SGML editor, so only some hints are given here:
  •  
  •  

    CALS tables consist of mainly three parts within <tgroup>: <thead>, <tbody>, <tfoot>.

  •  
  •  

    Each part is made of <row>s of <entry>s. Each of these elements have attributes to control the layout of the table.

  •  
  •  

    <tgroup> also receives a set of <colspec>s having information about the table columns.

  •  
  •  

    One of the major problems if CALS tables do not work is, that the amount of <colspec> elements and <entry> does not match the value of the attribute [columns] in <tgroup>.

  •  
  •  

    Within <entry> most of the paragraph level elements are allowed.

    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.

    16.1.6     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:
    Figure 118: Structure of prms

    prms.eps


    × parameter
    × long-name
    × short-name
    × description
    × parameter characteristics
    × condition
    ((× absolute value and toleranceFOOTNOTEor
    × minimum, typical, maximum valueFOOTNOTE)
    × unit) or
    × textFOOTNOTE

    The following representation example can be drawn from this structure:
    <short-name> UB

    Table 42: 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

     

  •  
  •  

    Defined Parameters

    There are many pre-defined parameters in the MSR DOC DTD. The only difference between them and user defined parameters is that the designation (long-name element) of the parameter is pre-defined.

    16.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 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 119: 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>.

    16.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 120: Structure of <project-data>

    project-data.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. Company-specific details about the project can be specified in <general-project-data> on the following items:
    System overview <system-overview>

    This chapter can be used to define information about a global system, e.g. a certain car model.

    Order justification <reason-order>

    This may be used to specify information about the reasons for the order of the described component resp. for making the specification of such a component.

    Objectives <objectives>

    This chapter can be used to specify information about the project objectives. E.g. "Development and system release of the engine-managment-system for the model NEW-BEETLE"

    Models <sample-spec>

    This structure is used to define development samples like A-,B-,C-,D-sample. These samples represent the results of the different development phases.

    Variant specification <variant-spec>

    This section is used to specify all variant definitions and their corresponding variant characteristics. See also Variant Concept.

    Limits to other projects <demarcation-other-projects>

    This chapter is used to describe the demarcation to other projects.

    Parallel developments <parallel-design>

    This can be used to give an overview of the work in parallel projects.

    Integration capability <integration-capability>

    In this chapter requirements on the capabilities of integration in other systems can be described.

    Acceptance conditions<acceptance-cond>

    This chapter is used to define the general conditions for the acceptance of the described components.

    Schedule and plans <project-schedule>

    This chapter is used to define the project-schedule, e.g. project milestones, dates, time limits etc.

    Purchasing conditions <purchasing-cond>

    This is used to define purchasing conditions like amount of devices per year, delivery times, storage quantities, etc. .

    Protocols, minutes of meeting <protocols>

    This is the place where project minutes and other arrangements can be mentioned.

    Handed over documents and data<dir-hand-over-doc-data>

    This is the directory of the handed over documents and data.

    Additional project specifications<add-spec>

    Any kind of additional project description which can't be described with the chapters mentioned above.

    16.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 121: Support of DTD fragmentation through administrative data

    admin-data.eps


    The operating model is
  •  
  •  

    The document respectively the fragment is written in a certain language which can be defined in the element <language>. This element can be used to control a SGML system, e.g. to set the correct prefix strings for elements.

  •  
  •  

    The DTD can be configured for the multilingual operation. In this case <language> contains the language of the origin document. All languages used in a document have to be defined within <used-languages>, that is each language is defined with a <l-10>-element which contains the full language name and in the Attribute [l] the short language name (see Multilinguality).

  •  
  •  

    The document (or the fragment) is handled in all companies participating in the project.

  •  
  •  

    The data management in the various companies is different. For that reason, each participant can enter information about their document management facilities in <company-doc-info>:
    <doc-label>

    this is the label under which the document is managed in the company denoted by <company-ref>

    <private-code>

    allows to transport company specific information in a private notation. This is the place, where for example PDMS (Product Data Management Systems) can place pointers and document ids required to resynchronize after a document exchange.

    <entity-name>

    It might be the case that each participating company uses a different fragmentation strategy. In order to support this, <entity-name> can receive information useable by a split utility which creates the desired fragments out of the entire document.

  •  
  •  

    If a new release of the document or the fragment is given, each participating site may use a specific scheme for revision numbers. For that reason, each <doc-revision> can receive <company-revision-info> which holds the participant specific information for the actual document revision.

    It is up to a semantical check utility to keep sure that there is only one entry per company.

  •  
  •  

    nevertheless, the actual revision is initiated by one individual denoted by <team-member-ref> at one certain point of time denoted by <date>.

  •  
  •  

    Finally the modifications made in that revision are stored in <modifcations> where the actual <change> as well as the <reason> for that change is notified. If possible, the change can be located by <xref>.

  •  
  •  

    For each <modifcation> the attribute [type] determines, if the change is made to the document only (doc-related) or to the subject of the document (content-related).

    16.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:
  •  
  •  

    characteristics which lead to a new subject number(<variant-char [type="new-part-number"]>). For this only the existence of such a characteristic is enough to establish a new subject number for this variant!

  •  
  •  

    characteristics which don't lead to a new subject number (<variant-char [type="no-new-part-number"]>).

  •  
  •  

    characteristics which lead to a new subject number according to shaping.

    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.

    16.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 [Standard: Code for the representation of names of languages / Relevant Position: Part1]


    Figure 122: Multilingual Paragraph

    mlingual.eps