![]() ![]() |
4 |
Basic Structures of the MSR Application Profile |
4.1 |
Not Content Orientated Information (ncoi) |
The figure below illustrates the structure of <ncoi-1>.
Figure 17: Structure of <ncoi-1>
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 are interchangeable between all MSR DTDs
without any changes.
4.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 system.
Figure 18: chapter content model
One advantage of using <chapter> for all
levels is the option to move a chapter using cut &
paste to any place in the document at any
level.
4.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 19: Structure of <topic-1>
4.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"> |
<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
defined |
<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 |
4.1.3.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:
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.
4.1.3.2 | Figure |
<figure> is used to insert graphics into the document. A figure can be defined in three different ways.
1. |
2. |
3. |
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.
The scaling attribute precedence is:
4.1.3.3 | Formula |
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.
4.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.
4.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.
4.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. |
4.1.4.2 | Semantically Oriented Character Level Elements |
Element |
use for |
example |
---|---|---|
Use for any technical term. The type of that term
is determined by the attribute [type] 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. |
||
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. |
||
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: ]. |
|
Is used to create footnotes |
||
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. |
|
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] |
|
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] |
type |
use for |
example |
---|---|---|
Used to describe SGML tags including attributes |
||
Used to describe SGML attributes outside of tags |
||
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. |
||
Used to mention specific products. |
||
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 reports |
The initialization is controlled by the environment variable MMRC. |
|
Used to mention a state for example of a process. |
The documents must at least be revised if they are submitted to the customer. |
|
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. |
|
Used to mention material. |
||
Used to mention control elements of tools like push-buttons, menu items, switches etc. as well as keyboard keys. |
||
Used to markup program in line code sequences |
||
Used to markup the name of an organization. |
||
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]. |
Element |
use for |
example |
---|---|---|
Used to markup the document ISBN resp. the standard number |
ISBN 0-7923-9432-1 |
|
Used to markup the state of the referred document resp. standard. |
released |
|
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 |
|
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 |
|
Markup the relevant position in the referenced document resp. standard. |
Chapter 5.2 - Architectural forms |
|
Used to markup the subtitle of the referenced document or standard if there is one. |
HyTime |
|
Used to markup the document identifier |
SGML |
|
Used to markup the main title of the referenced object. |
Making Hypermedia work |
|
Used to markup the file access information. This is intended to be processed by external systems. |
[External FILE: MOTRONIC wiring diagram / Filename: motronic.asc] |
4.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. |
4.1.6 | Parameter tables |
For structured
documentation of individual numerical and/or alpha-numerical
requirements, so-called parameters are available. They
have the following
structure:
Figure 22: Structure of prms
× parameter |
|
The following representation example can be drawn from this structure:
<short-name> UB |
Operating voltage |
UB |
10,8 |
14,2 |
V |
||||
13,5 |
V |
5 % |
||||||
Colour of housing |
red, green and blue |
|||||||
Function state |
active |
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. |
4.2 |
Predefined Document Structure |
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 23: Principles of
information acquisition
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>.
4.3 |
Project Data |
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 24: Structure of <project-data>
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. |
4.4 |
Administrative Data |
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>:
|
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 ( |
4.5 |
Variant Concept |
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. |
4.6 |
Multilinguality |
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 26: Multilingual
Paragraph
![]() ![]() |