2 User guide | A Processing hints |
All MSR DTDs are using some common data structures. These operating models are described in this chapter.
<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>.
<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.
<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:
Use <topic> to create bridge titles instead of one line paragraphs with entirely emphasized contents. Note that <topic>can be referenced by <xref>.
Use<labeled-list> to create explanations or even bridge titles for very short topics instead of bulleted lists with emphasized initial words.
Use <labeled-list> instead of two column tables if the first column cells almost contain one word.
User defined text(<verbatim>) allows the use of tab and return keys just like in an ordinary text editor. Use <verbatim> to print program listings etc. It can even be used to show simple things with simple graphics.
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 defined8.
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.
Think twice before choosing a certain element. With paragraph level elements it is sometimes tough to change elements especially in respect to the recommendations above (e.g. to change a <table> to a <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.
<figure> is used to insert graphics into the document. A figure can be defined in three different ways.
as a real <graphic>
as an ASCII graphic (<verbatim>)
The treatment of the graphic is determined by the attributes of <graphic>:
The scaling attribute precedence is:
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.
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.
The rendition oriented character level elements are:
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 |
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>. |
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 |
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:
<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:
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.
For structured documentation of individual numerical and/or alpha-numerical requirements, so-called parameters are available. They have the following structure:
The following representation example can be drawn from this 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 |
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.
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>.
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.).
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
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 Chapter 3.6, 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 (doc-related) or to the subject of the document (content-related).
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:
Within the MSR DOC DTD variant-specific specifications could be made at different positions. These are:
part-types
modules of a part-type
ports of a part-type
functions of a part-type
signals within a part type
connections within a part type
connection components within a part type
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).
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.
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 |