MSR-Documentation MSR
Contents
1. 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 lt l1 gt lt I2 gt lt I3 gt lt l4 gt lt 110 gt to build an aggregate of terminal elements These language elements provide an attribute I where the language of this element can be specified The content of the attribute I have to be defined as two letter lower case symbols according to the Standard Code for the representation of names of languages URL Relevant Position Part1 mi data 1 gt Figure 13 Multilingual Paragraph All rights by MSR MEDOC We reserve all rights of disposal such as copying and passing on to third parties 06 09 2002 14 46 15 msrrep sp en xml MSR Report Page 29 34 msrrep Sp Date 2002 02 07 MSR Sample Tables from changes State RD App A Processing hints MSRREPDTD is not very content oriented Nevertheless some aspects of semantic processing shall be mentioned here App A 1 technical terms lt tt gt can be used to generate specific lists or indexes even if all types are rendered in the same manner App A 2 reference checking all references should be checked App A 3 changes The strongest semantics is there in lt changes gt Therefore the following processing is recom mended Table of object revisions lt chg object revisions gt sorted by object2. Order justification lt reason order gt This may be used to specify infor mation about the reasons for the order ofthe described component resp for making the specification of such a component Objectives lt objectives gt This chapter can be used to spec ify information about the project objectives E g Development and system release of the engine managment system for the model NEW BEETLE Models lt sample spec gt This structure is used to define development samples like A B C D sample These samples represent the results of the dif ferent development phases Variant specification lt variant spec gt This section is used to specify all variant definitions and their corresponding variant character istics See also Topic 3 5 Variant Concept p 27 All rights by MSR MEDOC We reserve all rights of disposal such as copying and passing on to third parties 06 09 2002 14 46 15 msrrep sp en xml MSR Report msrrep sp Administrative Data Page 26 34 Date 2002 02 07 State RD 3 4 Limits to other projects lt demarcation other projects gt Parallel developments lt parallel design gt Integration capability lt integration capability gt Acceptance conditions lt acceptance cond gt Schedule and plans lt project schedule gt Purchasing conditions lt purchasing cond gt Protocols minutes of meeting lt protocols gt Handed over documents and data lt dir hand over doc data gt Additi
3. This element receives some notes about the next actions as well as a formal state using the attribute state with the selection of open in progress passed rejected or done open The request is captured but no further action has been taken on it in progress The request is accepted and is in implementation All rights by MSR MEDOC We reserve all rights of disposal such as copying and passing on to third parties 06 09 2002 14 46 15 msrrep sp en xml MSR Report Page 12 34 msrrep sp Date 2002 02 07 report rear State RD 2 5 passed The request is accepted but no implementation started up to now rejected The request is rejected It will not be implemented done The request is implemented It is highly recommended that the lt chg release notes gt is completely filled now for each changed object If there are change requests related to the actual one this can be documented using lt chg related requests gt and lt chg request ref gt It is possible to express if the related change is a prerequisite to the actual one Further informatione about the relationship can be entered as text in lt chg request ref gt For the lt chg request gt the responsibility is specified in lt chg responsibility gt The as signment is done verbally using lt desc gt or as a set of lt team member ref gt s in lt chg responsible gt The latter style is treated formally and can be used to generate task lists for team memb
4. We reserve all rights of disposal such as copying and passing on to third parties 06 09 2002 14 46 15 msrrep sp en xml MSR Report Page 32 34 msrrep sp Date 2002 02 07 Documentadministration State RD Documentadministration Table team members comey SCS Dipl Inform H Gengenbach MSR MEDOC Arbeitsgruppe DTD Dipl Math M Krause MSR MEDOC Arbeitsgruppe DTD Dipl Inform P Rauleder MSR MEDOC Arbeitsgruppe DTD Dipl Ing B Weichel MSR MEDOC Arbeitsgruppe DTD Dipl Inform J Wieland MSR MEDOC Arbeitsgruppe DTD MSR MEDOC Arbeitsgruppe Department STZ XI Works DTD Table version overview ates a 21 6 96 Dipl Ing B Weichel Table modifications Related to Create index technical terms and reference Convert to MSRREP V210 Content XML Reason Change to new document strategy Content ee chg responsible can be specified formally as well as informally Content Reason This maintains the flexibility of the informal assignment and provides the option to link to project managment systems Document changes as alternate content model for chapter Topic App A 3 changes p 29 Reason This allows the author to decide himself wehre to put changes It furhteron allows to run multiple change managements within one project All rights by MSR MEDOC We reserve all rights of disposal such as copying and passing on to third parties 06 09 2002 14 46 15 msrrep sp
5. LABEL F PCDATA COMPANY REVISION INFOS OMPANY REVISION INFO STATE PCDATA P INTRODUCTION COMPANY DOC INFOS F1 LOMPANY DOC INFO TEAM MEMBER REF P C DATA PCDATA DOC REVISION frer MODIFICATIONS ODIFICATION Fj ES Figure 1 MSRREP DTD and administrative data In the top level element lt report head gt there is also lt admin data gt see Topic 2 2 admin data p 9 providing means to describe the document versions revisions etc It is not treated as a document part since it is mainly metadata This element is included also on a chapter level if the document is fragments into entities All three sections contain a generic structure which allows to define an unlimited chapter hierarchy lt chapter gt It is up to the user to take sure that the number of chapter nesting does not exceed the capability of the SGML processing systems All rights by MSR MEDOC We reserve all rights of disposal such as copying and passing on to third parties 06 09 2002 14 46 15 msrrep sp en xml MSR Report Page 7 34 msrrep sp Date 2002 02 07 Concepts State RD Cross referencing is done in a non semantical way using lt xref gt A subset of the MSRDOC DTD id classes are supported in MSRREPDTD also These are mainly the organizational ones but not the technical ones of MSRDOC DTD MSRREPDTD adds some id classes with the change management support Some semantic references are also provided MSR
6. Used to mention a variable infor The initialization is controlled by the mally This is used to control the environment variable MMRC rendition as well as for generating variable lists This is mainly for in formal reports It is also possible to use this to mention a variable in the ECU software if no lt sw data dictionary gt is part of the documen t In a later process step this can be turned over to a formal lt xre f gt The initial advanced angle is calculat ed based on Nand TL lt tt type state gt Used to mention a state for example The documents must at least be re of a process vised if they are submitted to the cus tomer lt tt type prm gt Used to mention a state for example The initial advanced angle is calculat of a process It is also possible to ed using a lookup table KFZW use this to mention a calibration parameter in the ECU software if no lt sw data dictionary gt is part of the document In a later process step this can be turned over to a formal lt xref gt lt tt type material gt Used to mention material Furniture is usually made of wood and plastic lt tt type control Used to mention control elements of To finish the dialog push the OK but element gt tools like push buttons menu items ton switches etc as well as keyboard keys lt tt type code gt Used to markup program in line MetaMorphosis is invoked with mm code sequences crp sgm lt tt type organisat
7. msrrep Sp Date 2002 02 07 M SR Variant Concept State RD The document respectively the fragment is written in a certain language which can be defined in the element lt language gt 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 lt language gt contains the language of the origin document All languages used in a document have to be defined within lt used languages gt that is each language is defined with a lt I 10 gt element which contains the full language name and in the Attribute I the short language name see Topic 3 6 Multilinguality p 28 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 lt company doc info gt lt doc label gt this is the label under which the document is managed in the company denoted by lt company ref gt lt private code gt allows to transport company specific information in a private notation This is the place where for example PDMS Product Data Management System s can place pointers and document ids required to resynchronize after a document exchange lt entity name gt It might be the case that each participating company uses a different fragmentation
8. strategy In order to support this lt entity name gt 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 lt doc revision gt can receive lt company revision info gt 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 e nevertheless the actual revision is initiated by one individual denoted by lt team member ref gt at one certain point of time denoted by lt date gt Finally the modifications made in that revision are stored in lt modifcations gt where the actual lt change gt as well as the lt reason gt for that change is notified If possible the change can be located by lt xref gt For each lt modifcation gt the attribute type determines if the change is made to the docu ment only doc related or to the subject of the document content related 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 firs
9. task force the task force could be treated as an organization of its own behalf and entered as the only company In this case the native organization of the team members can be entered into lt department gt like the following example Usually lt general product data gt is filled with lt na gt If MSRREPDTD is used for accompanying reports in a certain project context lt general product data gt could be used to add project related information For further details see External Document Concepts of the MSR DOC DTD URL Relevant Position 2 1 3 abstract lt abstract gt can be used to give a short overview of the document The contents of this element is bound to be transmitted to a document management system of a document catalog So it should not have more than a few hundred words In order to provide a unified content model lt abstract gt can get all the paragraph level elements But these means should be used with great care 2 1 4 chapter in report head lt chapter gt in lt report head gt can be used to enter excessive forewords meta information etc In order to provide a unified content model there is no restriction here Nevertheless it is recom All rights by MSR MEDOC We reserve all rights of disposal such as copying and passing on to third parties 06 09 2002 14 46 15 msrrep sp en xml MSR Report Page 9 34 msrrep Sp Date 2002 02 07 Change management support State RD 2 2 2 3 2 4 m
10. 06 09 2002 14 46 15 msrrep sp en xml MSR Report Page 1 34 msrrep sp Date 2002 02 07 MS R State RD MSR Documentation MSR Report Concepts of MSRREP DTD MSR MEDOC Arbeitsgruppe DTD Roman Reimer STZ XI Works All rights by MSR MEDOC We reserve all rights of disposal such as copying and passing on to third parties 06 09 2002 14 46 15 msrrep sp en xml MSR Report Page 2 34 MaSPED Date 2002 02 07 Table of Contents State RD Table of Contents Table of Contents 2 Introduction 4 1 Introduction 5 1 Concepts 6 2 User guide 8 2 1 report head 8 2 1 1 report subject 8 2 1 2 companies 8 2 1 3 abstract 8 2 1 4 chapter in report head 8 2 2 admin data 9 28 report body 9 2 4 Change management support 9 2 4 1 change objects 10 2 4 2 chg request 10 2 4 3 chg treatment 11 2 5 report rear 12 3 Basic Structures of the MSR Application Profile 13 3 1 Not Content Orientated Information ncoi 13 3 1 1 Chapter 13 3 1 2 Topic 14 3 1 3 Paragraph Level Elements 15 3 1 3 1 Labeled List 16 3 1 3 2 Figure 17 3 1 3 3 Formula 18 3 1 3 4 Note 18 3 1 4 Character Level Elements 19 3 1 4 1 Rendition Oriented Character Level Elements 19 3 1 4 2 Semantically Oriented Character Level Elements 19 3 1 5 Table 22 3 1 6 Parameter tables 22 ae Predefined Document Structure 24 3 3 Project Data 24 3 4 Administrative Data 26 35 Variant Concept 27 3 6 Multilinguality 28 All rights by MSR MEDOC We reserve all rights of disposal such
11. REPDTD provides paragraph level markup as paragraphs an ordinary paragraph tables implemented as CALS tables lists provided as numbered unnumbered and labelled lists Each Item can mainly contain all paragraph level markup figures Allowing to include sizeable graphics verbatim for preformatted text topic which allows to insert bridge titles There are some elements providing character level markup Most of them represent a certain semantics as it is the case in MSRDOC DTD Elements taken from MSRDOC DTD are not changed except lt xref gt which supports only the id classes in MSRREPDTD This leads to some structures which could be considered as overde signed mainly in the metadata where lt company gt still has all the project oriented elements of MSRDOC DTD All elements have an attribute signature which is targeted to be filled by a check routine It can be used to find out changes in the document All rights by MSR MEDOC We reserve all rights of disposal such as copying and passing on to third parties 06 09 2002 14 46 15 msrrep sp en xml MSR Report Page 8 34 msrrep sp Date 2002 02 07 MSR chapter in report head State RD 2 User guide When starting a new document first the lt report head gt see Topic 2 1 report head p 8 has to be filled with all the meta information interjectionally stuff etc The actual document is entered in lt report body gt which receives lt changes gt see Topic 2 4 1 c
12. SR 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 lt overall project gt by a lt label gt an a short description in lt desc gt 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 All rights by MSR MEDOC We reserve all rights of disposal such as copying and passing on to third parties 06 09 2002 14 46 15 msrrep sp en xml MSR Report Page 25 34 msrrep sp Date 2002 02 07 M S R Project Data State RD Figure 11 Structure of lt project data gt Project data can be described by a PDM system in an integrated SGML Editor and PDM environ ment This is information on the current project and possibly the main project Company specific details about the project can be specified in lt general project data gt on the following items System overview lt system overview gt This chapter can be used to de fine information about a global system e g a certain car model
13. able Parameters For structured documentation of individual numerical and or alpha numerical requirements so called parameters are available They have the following structure All rights by MSR MEDOC We reserve all rights of disposal such as copying and passing on to third parties 06 09 2002 14 46 15 msrrep sp en xml MSR Report Page 23 34 msrrep sp Date 2002 02 07 M S R Parameter tables State RD Figure 9 Structure of prms parameter long name short name description 1718 condition absolute value and tolerance or minimum typical maximum value unit or text The following representation example can be drawn from this structure lt short name gt UB Table 4 Parameter structure Element lt long name gt Operating voltage Colour of housing Eu red green and blue Function state Jaetive All rights by MSR MEDOC We reserve all rights of disposal such as copying and passing on to third parties 06 09 2002 14 46 15 msrrep sp en xml MSR Report Page 24 34 msrrep sp Date 2002 02 07 Project Data State RD 3 3 Defined Parameters There are many pre defined parameters in the MSR DOC DTD The only difference be tween them and user defined parameters is that the designation long name element of the parameter is pre defined Predefined Document Structure The automotive systems to be described with the help of this DTD possess v
14. are collected the SGML pro cessing system could assort the topics based on their lt long names lt chg implementation gt can be ther more than once if the solution touches more than one lt chg object gt report rear lt report rear gt receives a number of lt chapter gt SGML formatting systems can add additional chapters like crossreference indexes or reports generated for lt tt gt All rights by MSR MEDOC We reserve all rights of disposal such as copying and passing on to third parties 06 09 2002 14 46 15 msrrep sp en xml MSR Report Page msrrep sp Date M SR Chapter State 13 34 2002 02 07 RD 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 lt ncoi 1 gt contains all basic descriptive elements There are also elements like lt chapter gt or lt fail save concept gt in the MSRSYS DTD which have the same content model as lt ncoi 1 gt The figure below illustrates the structure of lt ncoi 1 gt gt gt FIGURE J gt DEF LIST gt LABELED LIST J gt TOP IC 1 gt CHAP TER gt Figure 4 Structure of lt ncoi 1 gt There also are two weaker ncoi models ncoi 2 and ncoi 3 with lesser elements than lt ncoi 1 gt ncoi 2 has no lt chapters gt ncoi 3 has also no chapters an
15. as copying and passing on to third parties 06 09 2002 14 46 15 msrrep sp en xml MSR Report Page 3 34 MSTO Sp Date 2002 02 07 MSR Table of Contents State RD App A Processing hints 29 App A 1 technical terms 29 App A 2 reference checking 29 App A 3 changes 29 App A 3 1 Sample Tables from changes 29 App B Zus tzliche Anmerkungen zum Dokumentstand 1 0 am 13 7 98 31 Documentadministration 32 All rights by MSR MEDOC We reserve all rights of disposal such as copying and passing on to third parties 06 09 2002 14 46 15 msrrep sp en xml MSR Report Page 4 34 msrrep Sp Date 2002 02 07 MS R Introduction State RD Introduction Companies MSR MEDOC Arbeitsgruppe DTD MSR AG DTD Name Departement Address Contact Roles Dipl Inform H Gen genbach Dipl Math M Krause Dipl Inform P Rauleder Dipl Inform J Wieland Document Part Version Information company Version Stato Romane 2002 02 07 Roman Reimer For details refer to All rights by MSR MEDOC We reserve all rights of disposal such as copying and passing on to third parties 06 09 2002 14 46 15 msrrep sp en xml MSR Report Page 5 34 msrrep sp Date 2002 02 07 MS R Introduction State RD 1 Introduction MSRREPDTD is an SGML doctype definition designed in the MSR environment considering the following objectives e useable to produce documentation and reports in the MSR working group e gathering e
16. 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 lt item label gt should be handled The default value of the attribute is item label pos no newline If an lt item label gt is wider than lt ident sample gt the most general case is to start the item body in anew line if necessary item label pos newline if necessary If the attribute has the value item label pos newline the item body starts generally in a new line Note that lt indent sample gt can be used to adjust the indentation if there are multiple lt labeled list gt s which should have the same indentation 3 1 3 2 Figure lt figure gt is used to insert graphics into the document A figure can be defined in three different ways 1 as areal lt graphic gt 2 as an ASCII graphic lt verbatim gt 3 asa pure textual description lt desc gt of the graphic The treatment of the graphic is determined by the attributes of lt graphic gt Do not enter annotating text to lt long name gt in lt figure gt or lt table gt like Figure 1 This embel lishment 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 figur
17. d futhermore another topic model without lt prms gt The components of ncoi are interchangeable between all MSR DTDs without any changes 3 1 1 Chapter lt chapter gt is a sequence of paragraph level elements mixed with lt chapter gt lt chapter gt 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 All rights by MSR MEDOC We reserve all rights of disposal such as copying and passing on to third parties 06 09 2002 14 46 15 msrrep sp en xml MSR Report msrrep sp Topic Page Date State 14 34 2002 02 07 RD gt 7 SHORT NAMEF PCDATA PCDATA E TERBATIMJ PCDATA nid DEF LIST DEF ITEM gt CONG NAME gt PISHORT NAMEI gt p gt ERBAT gt H TOPIC 1 FIGURE gt UFICHAPTERS lt Figure 5 chapter content model One advantage of using lt chapter gt for all levels is the option to move a chapter using cut amp paste to any place in the document at any level All rights by MSR MEDOC We reserve all rights of disposal such as copying and passing on to third parties 06 09 2002 14 46 15 msrrep sp en xml MSR Report Page 15 34 msrrep S
18. e Index since the processing for MSRREPDTD recommends to create a list of SGML tags automatically The schematic is found in External FILE MOTRONIC wiring diagram URL motronic asc SGML is defined in Standard Infor mation Processing Text and Office Information Systems Subtitle Stan dard Generalized Markup Language State standard Date 1986 URL Relevant Position entire documen t example lt tt type sgmltag gt Used to describe SGML tags includ To describe SGML tags use lt t ing attributes t type sgmlitag gt lt tt type sgml sed to describe SGML attributes The sgmitag is denoted by the at attribute gt outside of tags tribute type lt tt type tool gt Used to mention tools used for ex ample in a process This can be soft ware as well as mechanical tools The tool should be specified by it s nature not by the specific product name SGML files are processed using an SGML processing system All rights by MSR MEDOC We reserve all rights of disposal such as copying and passing on to third parties 06 09 2002 14 46 15 msrrep sp en xml MSR Report Page 21 34 msrrep sp Date 2002 02 07 Semantically Oriented Character Level Elements State RD Table 2 Cont usage of technical terms tye usefor OOOO example lt tt type product gt Used to mention specific products This document is processed using MetaMorphosis lt tt type variable gt
19. ed objects resp object revisions lt chg object revision ref gt The referred objects are the ones to be improved resp causing the problem to be solved by the required change Thus no lt chg request gt can be there without respect to a lt chg object revision gt If necessary a fake lt chg object revision gt should be introduced For each lt chg request gt the following can be entered lt long name gt A working title for the change request This can be used in verbal communication as well as anntoatin in overview reports lt short name gt A label for the change request This can be used to refer to link the document to Project Management Systems All rights by MSR MEDOC We reserve all rights of disposal such as copying and passing on to third parties 06 09 2002 14 46 15 msrrep sp en xml MSR Report Page 11 34 EP Date 2002 02 07 M SR chg treatment State RD lt chg keywords gt it is possible to enter blank separated keywords here These can be used for retrieval purposes as well as in overview reports It could also be used to enter notes for the project manager like assignments to indiviuals etc lt chg proposed by gt can receive the names or initials of the individual s who proposed the change request lt chg priority gt Allows to qualify the priority of the requested changes The priorization model is up to the author The SGML processing system can use this element to order the requested change
20. en xml MSR Report Page 33 34 msrrep Sp Date 2002 02 07 Documentadministration State RD Table Cont modifications Related to first edition accord ing to session from 19 6 96 Reason there was no introduction to MSRREPDTD esp changes Content Content Table modifications included Dae Chapler Related to Nr 1 2002 02 07 Gesamt Create index technical terms and refer Content ence Convert to MSRREP V210 XML Nr 2 13 7 98 Gesamt Change to new document strategy Content EEE a e Nr 3 10 7 96 Gesamt chg responsible can be specified formally Content as well as informally Reason This maintains the flexibility of the informal assignment and provides the option to link to project managment systems added examples for chages reports Topic Document App A 3 1 Sample Tables from changes p 29 Reason Nr 4 24 6 96 Gesamt changes as alternate content model for Content chapter Topic App A 3 changes p 29 Reason This allows the author to decide himself wehre to put changes It furhteron allows to run multiple change manage ments within one project chg responsible now is a set of team Content member ref Topic 2 4 3 chg treatment p 11 Reason make assignments formally cor rect redesign implementation and placement Content of chg release notes Topic 2 4 3 chg treat ment p 11 Reason to allow design object specific release no
21. ended not to enter the entire document at this place For more details about lt chapter gt see Topic 3 1 1 Chapter p 13 admin data lt admin data gt is used to markup document adminstrative data see Figure 1 MSRREP DTD and administrative data p 6 such as revisions etc The operating model is 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 echa participant can enter information about their document management facilities in lt company doc info gt lt doc label gt this is the label under which the document is managed in the company denoted by lt company ref gt lt private code gt allows to transport company specific information in a private notation This is the place where for example PDMS Product Data Management System s can place pointers and document ids required to resynchronize after a document exchange lt entity name gt It might be the case that each participating company uses a different fragmentation strategy In order to support this lt entity name gt 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 lt doc revision gt can receive lt company revision info gt which holds t
22. ers The possible solutions to the problem can be documented in lt chg solution gt where each option can be specifed in lt chg solution spec gt and discussed using lt chg solution pro gt lt chg chg solution con gt Also the estimated effort can be assinged using lt chg effort gt This is treated as a single value It is up to the user to decide if the effort is measured in hours days weeks or months Since a SGML processing system can sumarize the effort it is recommended to use the same units Finally there should be a conclusion documented in lt chg conclusion gt with the following aspects lt chg solution spec gt This is the place to document internals of the chosen solution as well as technical consequences etc lt chg implementations gt is a set lt chg implementation gt s each consisting of a pointer lt chg object revision ref gt to lt chg object revision gt to show in which ones of the revisions the solution is or will be imple mented lt chg implementation gt also receives the lt chg release notes gt which receives the information for the release notes regarding the change object denoted by lt chg object revision ref gt This information should be extracted into an entity holding a lt chapter gt by an SGML processing system If the author wants to specify the detailled location of the imple mentation e g the changed files he can do this by introducing lt topic gt s When the release notes
23. ery different specifi cations 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 lt na gt not applicable lt tbd gt to be defined and lt tbr gt to be resolved as shown in Figure 10 Principles of information acquisition p 24 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 not applicable topic _ to be defined applicable _ to be resolved SS N specification Figure 10 Principles of information acquisition If a certain topic is not applicable it has to be marked with lt na gt If it is applicable it can be marked with either with lt tbd gt which indicates that someone has to do a job or it can be marked with lt tbr gt which indicates that a specification already exists but it hasn t yet been included or a detail specification can be defined The elements lt na gt and lt tbr gt can be described with a short description Within the element lt tbd gt the persons responsible for the definitions that have to been made can be specified with lt team member ref gt s The schedule for the definitions can be defined within lt schedule gt Project Data Registering and documenting development of a M
24. es 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 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 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 All rights by MSR MEDOC We reserve all rights of disposal such as copying and passing on to third parties 06 09 2002 14 46 15 msrrep sp en xml MSR Report Page 18 34 msrrep sp Date 2002 02 07 MSR Formula State RD 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 wil
25. hange objects p 10 as the last chapter This is the place to support the revision planning and change management lt report rear gt Topic 2 5 report rear p 12 receives all the appendices 2 1 report head 2 1 1 report subject lt report subject gt allows to specify the subject of the document lt overall title gt specifies the overall environment the document belongs to This could be the title of an overall project an entire system the overall title of a multipart book etc If nothing of this matches this element can be left out lt main title gt specifies the major title of the document This could be the title of a working group the name of a subsystem the title of a partial document etc lt sub title gt specifies the subtitle of the document This could be the type of the document e g user manual etc lt short name gt specifies a short name under which the document is known in the project envi ronment or the user community This could be a mnemonic label 2 1 2 companies lt companies gt allows to enter all the information about the related companies their team members etc This element is taken from MSRDOC DTD as is The persons involved in the document related project are listed as lt team member gt within their lt company gt Each lt team member gt has a lt role gt in the process for example project leader expert secretary supervisor etc If the document is mainly maintained by one person in a
26. he participiant 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 lt team member ref gt at one certain point of time denoted by lt date gt Finally the modifications made in that revision are stored in lt modifcations gt where the actual lt change gt as well as the lt reason gt for that change is notified If possible the change can be located by lt xref gt For each lt modifcation gt the attribute type determines if the change is made to the docu ment only doc related or to the subject of the document part related report body lt report body gt receives an unlimited amount of lt chapter gt s or lt chg chapter gt s which receive the actual information Change management support Change manangement support is provided using lt changes gt which is placed into lt chg chapter gt This allows to maintain multiple change mananagements within one document All rights by MSR MEDOC We reserve all rights of disposal such as copying and passing on to third parties 06 09 2002 14 46 15 msrrep sp en xml MSR Report Page 10 34 msrrep Sp Date 2002 02 07 chg request State RD 2 4 1 2 4 2 CHG OBJECT I CHG OBJECT REVISIONS Figure 2 Change management support This feature is based on the following model W
27. ipdsed to markup the name of an SGML is standardized by SO organization lt tt type other gt Used to mention a special term This is a thing not covered by lt tt gt which does not fit to the other type s This is a back door for the def inition of user defined types They have to be specified within the at tribute user defined type A for matter uses this user defined type only if type other All rights by MSR MEDOC We reserve all rights of disposal such as copying and passing on to third parties 06 09 2002 14 46 15 msrrep sp en xml MSR Report msrrep sp Parameter tables Page 22 34 Date 2002 02 07 State RD Table 3 sub elements for xdoc and xfile Element lt number gt lt state gt lt publisher gt lt position gt lt subtitle gt lt short name gt lt long name gt 3 1 5 Table use for Used to markup the document ISBN resp the standard number Used to markup the state of the re ferred document resp standard 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 Markup the publisher of the document or the standard This can be the author as well as the publishing organization Markup the relevant position in the referenced document resp standard Used to markup the subtitle of the ref erenced document or standard if there is one Used to markup the docu
28. ithin one document there are several lt chg objects gt to be considered in the actual project domain These objects can be any deliverable in the process either documents products or even libraries These objects exist in multiple revisions lt chg object revisions gt within the process e Requested changes can be captured and attached to these lt chg object revision gt s The treatment of the requested changes can be managed using element in lt chg treatment gt change objects Within one document there are several lt chg objects gt to be considered in the actual project domain These objects can be any deliverable in the process either documents products or even libraries The development of lt chg object gt takes place by creating new revisions These lt chg object revision gt s are characteriezed by lt long name gt receiving the work title of the revision e g Summer 95 release lt short name gt holding the revision number lt date gt holding the release date The lt chg object revision gt s are referred to from within lt chg request gt This allows to generate lt chg object revision gt related tables and lists It is recommended not only to capture existing revisions but also future ones This allows to refer them in order to receive complente release notes etc chg request In the project there are any requested changes lt chg requests gt For each lt chg request gt there is one or more relat
29. l 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 scale has precedence over all fit has precedence over width and or height 3 1 3 3 For
30. ment identifi er Used to markup the main title of the referenced object Used to markup the file access infor mation This is intended to be pro cessed by external systems example ISBN 0 7923 9432 1 released Steven J DeRose and David G Durand Kluwer Academic Publishers Chapter 5 2 Architectural forms SGML Making Hypermedia work External FILE MOTRONIC wiring di agram URL motronic asc lt table gt is implemented as CALS table see External Document CALS table spec URL Relevant Position at www oasis org Capturing these kind of tables must be supported by the SGML editor so only some hints are given here e CALS tables consist of mainly three parts within lt tgroup gt lt thead gt lt tbody gt lt tfoot gt Each part is made of lt row gt s of lt entry gt s Each of these elements have attributes to control the layout of the table e lt tgroup gt also receives a set of lt colspec gt s having information about the table columns One of the major problems if CALS tables do not work is that the amount of lt colspec gt elements and lt entry gt does not match the value of the attribute columns in lt tgroup gt Within lt entry gt most of the paragraph level elements are allowed Note It is highly recommended to insert lt thead gt This creates a table heading which is repeated on each page if a pagebreak falls into the table Parameter tables User Defin
31. mula Figure 8 Structure of lt figure gt A formula can be described in five different ways which can exist parallel These are lt graphic gt A formula prerendered as a figure lt verbatim gt A simple ASCII formula lt tex math gt A TeX math formula which can be processed by a TeX or LaTeX processor lt c code gt A formula which is defined as c code lt generic math gt 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 All rights by MSR MEDOC We reserve all rights of disposal such as copying and passing on to third parties 06 09 2002 14 46 15 msrrep sp en xml MSR MSR Report Page 19 34 msrrep Sp Date 2002 02 07 Semantically Oriented Character Level Elements State RD 3 1 3 4 3 1 4 3 1 4 1 3 1 4 2 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 e caution e hint e tip instruction exercise e other If the attribute notetype has a value of other the user has to specify a own type within the attribute user defi
32. ned 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 lt label gt can be used to define a title of the note Character Level Elements Character level elements can occur within element like lt p gt lt item label gt There are rendition oriented elements like lt e gt emphasis lt sub gt as well as semantically oriented Elements as lt tt gt technical term or lt std gt referring to an external standard It is highly recommended to use rather semantically oriented elements than rendition oriented ones Rendition Oriented Character Level Elements The rendition oriented character level elements are lt e gt Emphasizes the text The attribute type determines the rendition style lt sub gt Subscript places the contents with smaller font below the base line lt sup gt Superscript places the contents with smaller font above the base line Semantically Oriented Character Level Elements Table 1 semantically oriented character level elements Element user example lt tt gt Use for any technical term The type This is an SGML tag lt t of that term is determined by the ttype sgmitag gt attribute type we can collect all lt tt gt s This element could be treated as a back door to markup information which is not totally semantic The SGML processing system can gen erate list of technical term
33. onal project specifications lt add spec gt Administrative Data This chapter is used to describe the demarcation to other projects This can be used to give an overview of the work in parallel projects In this chapter requirements on the capabilities of integration in other systems can be described This chapter is used to define the general conditions for the accep tance of the described compo nents This chapter is used to define the project schedule e g project milestones dates time limits etc This is used to define purchasing conditions like amount of devices per year delivery times storage quantities etc This is the place where project minutes and other arrangements can be mentioned This is the directory of the handed over documents and data Any kind of additional project description which can t be de scribed with the chapters men tioned above 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 12 Support of DTD fragmentation through administrative data The operating model is All rights by MSR MEDOC We reserve all rights of disposal such as copying and passing on to third parties 06 09 2002 14 46 15 msrrep sp en xml MSR Report Page 27 34
34. p Date 2002 02 07 Paragraph Level Elements State RD 3 1 3 Topic Use lt topic 1 gt or lt topic 2 gt to create bridge titles instead of one line paragraphs with entirely emphasized contents Note that these elements can be referenced by lt xref gt In difference to lt topic 1 gt lt topic 2 gt has no lt prms gt gt ABELED LIST J gt gt Figure 6 Structure of lt topic 1 gt Paragraph Level Elements Paragraph level elements are elements which occur on the same level as lt p gt 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 lt p gt Paragraph lt verbatim gt Preformatted text which is usually set in monospaced font Tabs line spaces and carrige returns are considered Use lt verbatim gt to print program listings etc It can even be used to show simple diagrams lt figure gt See chapter Topic 3 1 3 2 Figure p 17 lt formula gt See chapter Company 3 1 3 3 Formula p 18 lt list gt A ordered or unordered list of items For an unordered set of items use lt list type unnumbered gt For a ordered list of items use lt list type numbered gt lt def list gt Use lt def list gt to create definition lists which might be collected into an overall definition list or a glossary In this case lt labeled list gt might lead to the
35. revision with lt short name gt lt long names revision release date see Table 5 object revisions p 30 Tables of requested changes sorted by lt chg state gt open in progress passed rejected lt chg priority gt related objects lt short name gt This will actally be one table per lt chg state gt Each entry should refer to the change itself Thus these tables can serve as a directory of change requests see examples in Table 6 open changes p 30 resp Table 7 in progress changes p 30 etc Table of requested changes sorted by lt chg state gt open in progress passed rejected lt chg priority gt related objects lt short name gt This will actally be one table per lt chg object gt Each entry should refer to the change itself Thus these tables can serve as a directory of change requests Table of planned revisions with summarized effort Release notes either one file per revision or only for one specific revision which is specified as a runtime argument The release notes should be generated as fragment of a MSRREP DTD instance where a chapter is generated for each lt chg request gt It is recommended to include the release notes not directly into lt report body gt because lt chapter gt on level 1 usually starts a new page If the author wants to specify the detailled location of the implementation e g the changed files he can do this by introducing lt topic gt s When the release note
36. s according to their priority Therfore the highest priority should be of low lexical order It can either be a simple number high priorities get low values deter mining the priority Another model is a letter digit combination The letter characterizes the importance the digit the urgency e g A 2 says very important and medium urgent lt chg class gt allows to classify the requested change This element should receive something like enhancement error lt chg related objects gt This element receives links to the related object revidions The semantic of this link is that the referred object revision is causing the problem e g with a bug report or must be enhanced in case of an enhance ment request All objects concerned by the change request should be mentioned lt chg subject gt This is the place to describe all the aspects of the change request All paragraph level elements can be used lt chg reason gt This element receives the justification of the change request In this element all problems should be mentioned which shall be solved by the requested change 2 4 3 chg treatment The treatment of the reugested changes can be documented in lt chg treatment gt ICHG RELATED REQUESTS je gt CHG TREATMENT Figure 3 Change treatment The treatment of one change request is expected in following steps The request goes through a life cycle which is documented in lt chg state gt
37. s are collected the SGML processing system could assort the topics The set of tables to produce should be controlled either by a processing instruction lt chg 1246 gt or by a runtime argument It is also possible to export the changes into other tools like Project Management Systems or Spreadsheets All rights by MSR MEDOC We reserve all rights of disposal such as copying and passing on to third parties 06 09 2002 14 46 15 msrrep sp en xml MSR Report Page 30 34 msrrep sp Date 2002 02 07 MSR Sample Tables from changes State RD App A 3 1 Sample Tables from changes Table 5 object revisions msrrep dtd DTD for genereic reports aE improved changes july 96 msrdoc dtd DTD for MSR engineering doucumentation 615 perorming major test Table 6 open changes change priority related repsonsi object ble a ee EN 9 a efforts zn tite related obiect effort page ne _ imp improve msrrep dtd treatment chg tt Introduce tt msrrep dtd msrdoc dtd Summary of A Changes All rights by MSR MEDOC We reserve all rights of disposal such as copying and passing on to third parties 06 09 2002 14 46 15 msrrep sp en xml MSR Report Page 31 34 msrrep sp Date 2002 02 07 MSR Zus tzliche Anmerkungen zum Dokumentstand 1 0 am 13 7 98 State RD App B Zus tzliche Anmerkungen zum Dokumentstand 1 0 am 13 7 98 Status dieses Dokument cd All rights by MSR MEDOC
38. s which makes it easier to find misspellings and other errors All rights by MSR MEDOC We reserve all rights of disposal such as copying and passing on to third parties 06 09 2002 14 46 15 msrrep sp en xml MSR Report msrrep sp Semantically Oriented Character Level Elements Page 20 34 Date 2002 02 07 State RD Table 1 Cont semantically oriented character level elements Element user example Used to create links in the docu ment The role of the target is de termined by the attribute id class receiving the value of the target s fixed attribute f id class The at tributes of lt xref gt should be main tained by the authoring system Used to refer to an external docu ment which usually is not available electronically lt xdoc gt receives a set of elements characterizing the external document lt xdoc gt Details to architectural forms can be found in External Document URL Relevant Position lt ft gt Is used to create footnotes Footnotes seem to be small and u nimportant lt ie gt creates index entries Is used to create pointers to external files which are not to be processed by the native SGML processing sys tem The contents of lt xfile gt can be used to connect to appropriate sys tems in later steps of the processing chain Is used to refer to a standard Table 2 usage of technical terms It is not necessary to put SGML tags into th
39. same rendition but has no information about the fact that terms are defined lt labeled list gt Use lt labeled list gt to create explanations or even bridge titles for very short topics instead of bulleted lists with emphasized initial words See also Topic 3 1 3 1 Labeled List p 16 Use lt labeled list gt instead of two column tables if the first column cells almost contain one word All rights by MSR MEDOC We reserve all rights of disposal such as copying and passing on to third parties 06 09 2002 14 46 15 msrrep sp en xml MSR Report Page msrrep sp Date Labeled List State MSR 16 34 2002 02 07 RD lt note gt 3 1 3 1 Labeled List INDENT SAMPLE F See chapter Topic 3 1 3 4 Note p 18 FTZH PCDATA H PCDATA H PCDATA Figure 7 Structure of lt labeled list gt lt labeled list gt is one of the most powerful elements If possible it is rendered as a label followed by the item body The indentation is determined by the rendition system which should take into account the biggest lt item label gt All rights by MSR MEDOC We reserve all rights of disposal such as copying and passing on to third parties 06 09 2002 14 46 15 msrrep sp en xml MSR Report Page 17 34 msrrep sp Date 2002 02 07 MSR Figure State RD Sometimes the author wants some influence to the indentation For this respect lt indent sample gt can receive any
40. t 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 lt variant char gt The characteristics have to be subdivided in three classes These are e characteristics which lead to a new subject number lt variant char type new part number gt For this only the existence of such a characteristic is enough to establish a new subject number for this variant All rights by MSR MEDOC We reserve all rights of disposal such as copying and passing on to third parties 06 09 2002 14 46 15 msrrep sp en xml MSR Report Page 28 34 msrrep sp Date 2002 02 07 MSR Multilinguality State RD e characteristics which don t lead to a new subject number lt variant char type no new part number gt 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 char acteristics Variant Coding Allocation of all variant definitions to their corresponding subject and drawing numbers and the respective development versions 3 6 Multilinguality The MSR DTDs can be configured for multilingual operation To use the multilingual DTD config uration the DTD switch multilinguality YES or NO have to be set
41. te processing All rights by MSR MEDOC We reserve all rights of disposal such as copying and passing on to third parties 06 09 2002 14 46 15 msrrep sp en xml MSR Report Page 34 34 msrrep sp Date 2002 02 07 MS R Documentadministration State RD Table Cont modifications included Dae Chapter Related to Nr 5 21 6 96 first edition according to session from Content 19 6 96 Reason there was no introduction to M SRREP DTD esp changes All rights by MSR MEDOC We reserve all rights of disposal such as copying and passing on to third parties
42. xperiences with the lt ncoi gt type of element in the MSRDOC DTD e performing revision and change planning e probably useful to carry reports not coverable by the very content oriented MSRDOC DTD prose data should be interchangeable between MSRREPDTD and MSRDOC DTD without any changes This document is not intended to provide a 100 detailled description of all aspects of MSR REPDTD It covers the main concepts of MSRREPDTD and gives hints to take best advantages of these concepts In respect of prose this document can be helpful for users of MSRDOC DTD also All rights by MSR MEDOC We reserve all rights of disposal such as copying and passing on to third parties 06 09 2002 14 46 15 msrrep sp en xml MSR Report Page 6 34 msrrep sp Date 2002 02 07 RD M S R Concepts State 1 Concepts MSRREPDTD is derived from MSRDOC DTD Only a few elements are added Therefore it is possible to derive most of the processing also The DTD mainly consists of three parts lt report head gt see Topic 2 1 report head p 8 carries all the document metadata as well as project related information lt report body gt see Topic 2 3 report body p 9 carries the main part of the document as well as the change management support see Topic 2 4 1 change objects p 10 lt report rear gt See Topic 2 5 report rear p 12 taking all appendices PCDATA PCDATA PCDATA PCDATA PCDATA PCDATA PCDATA 4D MIN DATA REVISION
Download Pdf Manuals
Related Search