Top left banner Top right banner
Bottom left banner Bottom right banner
Home : Home : Warfare Centers : NSWC Carderock : Resources : Technical Information Systems : Navy XML/SGML Repository : DTDs & Schemas : PMS : Tagging Conventions
Tagging Conventions for the PMS DTD

July 29, 1999

1.

Most SGML software applications, e.g., data base management systems, browsers, editors, work best with a normalized instance. This means all end-tags should be provided with the exception of those element types having EMPTY declared content such as "colspec", "spanspec", etc. Their start-tags must not be followed by any content or end-tags. Also all attribute values needed by the application should be specified on their tags, otherwise a needed but unspecified attribute default value may not be available for the application's processing.

An instance can be normalized in one of two ways:

  1. When the instance is being prepared, include all end-tags except for those element types with EMPTY declared value. Also be sure to specify all attribute values that could be needed by the software application on the appropriate tags even though these attribute values may be their attributes' default values.
  2. Some SGML parsers have the output option of providing a parseable normalized instance. Examples of such software are the proprietary Exoterica and EMA parsers and James Clark's public domain parsers.

The use of normalizing software is recommended as being the most efficient and cost-effective.

2.

Much of the content of PMS documents consists of enumerated items, i.e., sequential lists. The enumeration scheme for these lists and their sublists is: "1.", "a.", "(1)", "(a)", "-1-", "-a-" (the last two "dashes" enumerations occur only in MRCs). The value of the "numstyle" attribute on the "seqlist" tag is chosen so as to provide the same enumeration used in the PMS document files as follows:

NUMSTYLE ATTRIBUTE VALUE ENUMERATION
arabic 1., 2., ...
alphalc a., b., ...
arabic-parens (1), (2), ...
alphalc-parens (a), (b), ...
arabic-dashes -1-, -2-, ...
alphalc-dashes -a-, -b-, ...

In addition, there is a no list enumeration option corresponding to the "numstyle" attribute value of "none".

NOTE: According to the PMS DTD, the "numstyle" attribute may also take the values of "romanlc" (lower-case roman), "romanuc" (upper-case roman), and "alphauc" (upper-case alphabetic) in addition to the above values. However, the enumerations corresponding to these three values are NOT used in PMS documents, and consequently these three values MUST NOT be specified as "numstyle" values on "seqlist" tags. They are included with the acceptable "numstyle" values to ensure compatibility with data tagged against other NAVSEA DTDs.

NOTE: The "label" attributes should not be specified on the "item" tags since the enumeration of sequential lists is automatically generated by the application software. However, the "numstyle" attribute must always be specified on the "seqlist" tag.

              

3.

Do not use the "emphasis" tag to underline or bold such things as WARNING text, titles, column headings, etc. The PMS application FOSI/style sheet takes care of all such underlining and bolding. The "emphasis" tag is to be used only for author discretionary emphasized text.

 

4.

Now and then, tables occur in the MIP Configuration block and the MRC Procedural block. First of all, there are those tables whose titles contain the word "TABLE". Then there are those tables which do not contain "TABLE" in their title. These are the so-called work sheets, checkoff lists, etc. Finally, there are implicit tables "embedded" in the text. These tables may not have titles and often do not have column headings. Their table bodies usually consist of a small number of rows. See item 10.9 concerning the placement of table markup in the content of the MRC procedural block.

The following rules/considerations apply to the tagging of all PMS tables with respect to the CALS table model.

  1. On the "table" tag, provide appropriate values for the "frame", "colsep", "rowsep", "orient", and "pgwide" attributes.
     
  2. On the "tgroup" tag, specify the "cols" attribute value as the number of columns in this table group. Use the "align" attribute to specify the alignment of the columns in this table group as "left", "center", or "right" (do not use the "justify" or "char" values). If the row and column separations for the columns of this table group differ from those specified on the "table" tag, the "rowsep" and "colsep" attributes can be re-defined for the columns in this table group either on the "tgroup" tag or on their "colspec" tags (see below). The "charoff" and "char" attributes are not used in the PMS application.
     
  3. Always specify the "colname" attribute as "1", "2", "3", etc. on each "colspec" tag for each consecutive column. (Do not confuse the "colname" attribute with the "colnum" attribute which you do not specify on the "colspec" tag.)

    Specify the value of the "colwidth" attribute on the "colspec" tag as the column width in terms of the maximum number of characters in the column + 2 (or greater). For a "portrait" oriented table, the sum of the "colwidth" attribute values in a table group should not exceed 70. Likewise the sum of the "colwidth" values should not exceed 110 for a "landscape" oriented table.

    If the alignment or the row/column separation of some columns differ from that specified on the "table" or appropriate "tgroup" tag, re-define the "align", "rowsep", or "colsep" attributes on those "colspec" tags.

    Do not specify the "colnum", "charoff", or "char" attributes on the "colsep" tag.
     
  4. On the "spanspec" tags (if any), specify the values of the "namest" and "nameend" attributes as the values of the "colname" attributes of the leftmost and rightmost columns of the span. Specify the value of the "spanname" attribute as these two values joined with a dash ("-"), e.g., "1-4".

    Specify the "align" attribute value as "center", "right", or "left" as the situation warrants. (Do not specify the "justify" or "char" values for the "align" attribute.) Also specify appropriate values for the "colsep" and "rowsep" attributes.

    Do not specify the "charoff" or "char" attributes on the "spanspec" tag.
     
  5. The "spanspec" and "namest"-"nameend" attributes of "entry" seem to work equally well. 
  6. Do not specify the "valign" attribute on any of the tags.
     
  7. Do not use the "tfoot" tag.
     
  8. Do not use the "entrytbl" tag in table bodies.
     
  9. Do not specify the "rotate", "valign", "charoff", or "char" attributes on the "entry" tag.
     
  10. If the table rows are enumerated, the enumeration is to be considered a column in its own right and tagged accordingly.
     
  11. Very rarely it will be found that a large table has been split up into two tables, e.g., "Table 1" and "Table 1 (contd.)" due to page space limitations. Since such page space limitations do not apply to screen displays, such tables are to be combined.
     
  12. At present, the "chart" element type is not used to tag tabular material in the PMS application.

 

5.

Special characters are those characters which in some contexts could have an SGML delimiter significance (and could cause parsing problems) or which can not be entered from the keyboard.

  1. Some special characters such as "%", ">", '"' (double quote), "'" (single quote), etc. can be entered directly from the keyboard. These characters will never have an SGML delimiter significance in the text of #PCDATA, CDATA, or RCDATA content.
     
  2. The less than sign "<" and the ampersand "& are recognized as SGML delimiters in the text of #PCDATA content when they are followed directly by a letter of the alphabet, e.g., "1<b" and "R&D". In such cases replace "<" with "&lt;" and "&" with "&amp;". The same holds true for "&" in the text of RCDATA content but "<" is not recognized as a delimiter in the text of RCDATA content. Finally neither "<" nor "&" is recognized as a delimiter in CDATA content.
     
  3. However, it will be necessary to use general entity references from the ISO character sets to obtain certain special characters such as the degree sign ("&deg;"), the plus/minus sign ("&plusmn;"), etc. which can not be entered from the keyboard.

 

6.

The following tagging conventions apply to the tagging of the so-called "special paragraphs", i.e., warnings, cautions, and notes. A special paragraph always stands alone. This means the markup of a special paragraph is not absorbed into the preceding or following element content (e.g., "item" content). The placement of special paragraph markups in PMS document instances will be crucial for future database applications.

  1. Only notes can occur in MIP documents. They may occur in the CONFIGURATION block and following the lists of procedures in the MAINTENANCE REQUIREMENT DESCRIPTION column. It is assumed that a note in a MIP always pertains to the material preceding it.
     
  2. On the other hand it is assumed that a special paragraph in an MRC always pertains to the material following it. Since warnings, cautions, and notes are inclusions exceptions to the MRC "procblk" element type, their markups can occur between the "procblk" start- and end-tags as follows:
     
    • Between the "PROCEDURE" and "Preliminary" (if any) headings
    • Between the "Preliminary" heading and the first item of the Preliminary Steps list (if any)
    • Between any two items of the Preliminary Steps list (if any)
    • After the last item of the Preliminary Steps list (if any)
    • Before the title of any Maintenance Requirement Description in the Procedures
    • Between the title of any Maintenance Requirement Description and the first item following it in the Procedures
    • Between any two items in a Maintenance Requirement Description in the Procedures
    • After the last item in a Maintenance Requirement Description in the Procedures
    • After the last Maintenance Requirement Procedure Description in the Procedures

 

7.

Each instance of the PMS DTD must be headed by the document type "DOCTYPE" declaration for the PMS DTD. The declaration subset of this DOCTYPE declaration must contain a ENTITY declaration for the general entity "date" such as

<!ENTITY date "November 1996">

The "date" general entity will be referenced to provide both the document's date of issue and date of distribution. If such a "date" entity has not been provided, a #DEFAULT entity will provide a warning in the spaces for the date.

The DOCTYPE declaration subset for MIP documents will contain only this "date" ENTITY declaration since MIPs do not contain figures or graphics. However, the Preliminary Steps and Procedural Steps information in MRC documents may contain figures or graphics. In this case, an appropriate ENTITY declaration such as

<!ENTITY fig1 SYSTEM "C:\pmsgraphics\fig1" NDATA tiff>

must be provided in the DOCTYPE declaration subset for each externally-stored non-SGML "NDATA" data entity whose name is given as the value of the "boardno" attribute on a "graphic" tag.

 

8.

A standard distribution statement is provided by referencing one of the standard distribution general entities ("distriba", distribb", etc.) provided in the standard text file. The replacement text of these entities consists of the "distrib" start-tag, the text of the distribution statement, and the "distrib" end-tag. However, the text of a non-standard distribution statement may be entered directly between the "distrib" start-tag (be sure to specify the value of the "type" attribute) and the "distrib" end-tag in the PMS document instance.

 

9.

MIP Considerations

9.1 MIP documents may contain footnote references and footnote text as well as notes in the Configuration block. Such material is to be tagged in terms of the corresponding element types.

9.2 MIP documents may also contain one or more texts beginning with "*", "**", "#", "K", "M", "N", "R", or "X" after the Scheduling Aid(s) section. If so corresponding "*" or "**" symbols will occur in entries of the Periodicity Code column. A corresponding "#" symbol would occur in entries of the Related Maintenance column. Corresponding "K", "M", "N", "R", and "X" characters would occur in the OTHER column (possibly followed by the security classification characters "C" or "S"). These eight symbols are to be tagged as footnote references and the corresponding texts as footnote texts. General entity references to facilitate this tagging are provided in the standard texts entity file accompanying the PMS DTD file.

9.3 The "mrccno" element has an "noentry" attribute for the following reason. The MRC control numbers provided for the required procedures in a MIP are tagged in terms of "extref" content to enable the hyperlinking of the MIP and its MRCs. However, a required procedures in an MIP may not be described in an MRC, i.e., there is no MRC control number for that required procedure. In this case, the #CONREF "noentry" attribute on the "mrccno" tag is specified to provide an mrccno start-tag '<mrccno noentry="yes">' to satisfy the "mrccno" content requirement of the "extref" content model (i.e., serve as a place holder).

9.4 Now and then, the first and possibly other following notes will contain a continuation (due to the space limitations of the hardcopy document which do not apply to screen display) of one of the preceding blocks. The material in the note will be added to the appropriate element content, and the note will be removed.

9.5 It is possible that a few MIP documents may contain anomalies that have not been eliminated or corrected by FTSC. Such anomalies may be one of the following.

  1. A "*" occurs in the CONFIGURATION block but there is no corresponding "*" text in the CONFIGURATION block. (Any "*" text following the "Scheduling Aid(s)" section pertains to the PERIODICITY CODE column and not the CONFIGURATION block.) This MIP is to be referred to FTSC for clarification of this situation.
     
  2. A note occurs immediately before or after the "Scheduling Aid(s)" section. The content of the note is to be entered as an item in the "Scheduling Aid(s)" section with the following exception. If a note immediately follows (i.e., on the next line) the last "Scheduling Aid(s)" item, then that note is considered to accompany that last item and should be referred to the FTSC for their consideration since notes are not supposed to occur in "Scheduling Aid(s)".

    However, if a note is separated from the last "Scheduling Aid(s)" item by one or more blank lines, then that note is converted into a new last "Scheduling Aid(s)" item. However, this does not pertain to any notes that are continuations of the CONFIGURATION or REFERENCE PUBLICATIONS blocks. The text of any such note is to be placed in the content of the appropriate element.
     
  3. A note occurs immediately after the MAINTENANCE REQUIREMENT DESCRIPTION heading but there is no "Scheduling Aid(s)" section. The content of the note is to be entered as an item of a "Scheduling Aid(s)" section. However, this does not pertain to any notes that are continuations of the CONFIGURATION or REFERENCE PUBLICATIONS blocks. The markup of any such note is to be placed in the content of the appropriate element.
     
  4. A "*", "**", "#", "K" "M" "N" "R" or "X" footnote text follows the "Scheduled Aid(s)" section but there is no corresponding footnote reference. This MIP is to be referred to FTSC for clarification of this situation.
     
  5. A "*", "**", "#", "K", "M", "N", "R", or "X" footnote reference occurs in its respective column but there is no corresponding footnote text after the "Scheduling Aid(s)" section. The standard text corresponding to this symbol is to be provided by referencing the appropriate general entity (declared in the standard text file) in "legend" content.
     
  6. A footnote text using the symbol "***" or any symbol other than "*", "**", "#", "K" "M" "N" "R" or "X" occurs after the "Scheduling Aid(s)" section. This MIP is to be referred to FTSC for clarification of this situation.
     
  7. A non-standard footnote text with "*", "**", "#", "K", "M", "N", "R", or "X" symbols occurs after the "Scheduling Aid(s)" section. This MIP is to be referred to FTSC for clarification of this situation. However, it is acceptable to use "*" as a footnote symbol for any footnote text in the CONFIGURATION information.
     
  8. Texts such as "MRC deleted", "Reserved for future development", "Periodicity changed to S-1R", etc. occur in the MAINTENANCE REQUIREMENT Description column. Delete all occurrences of these texts.

 

10.

MRC Considerations

10.1 The value for the required "idref" attribute on the "topic" tag(s) in the "maintreqdes" content (MAINTENANCE REQUIREMENT DESCRIPTION information) in MRC documents is specified as follows. Take the first word of the "topic" content and append the digit "1" to it. If there is a second topic, take the first word of that "topic" content and append the digit "2" to it. Proceed in like manner for any additional topics. These "idref" values will be the values of the "id" attribute on the "title" tags of the sequential lists for each of the procedural steps (following the preliminary steps) in the "procblk" content corresponding to these topics.

NOTE: In the event that the first character of the first word of any of the "topic" contents is a digit ("0", "1", ... "9"), the character "i" must also be prefixed to the word. If the first word of any of the "topic" contents contains characters other than ".", "-", "0", "1", .., "A", "a" ... "Z", "z", those characters must be deleted.

10.2 The values for the "id" attribute on the "warning" tags in the "procblk" content (PROCEDURE information) in MRC documents are specified as "warn1" for the first warning, "warn2" for the second warning", etc. These "id" values will be the values of the "idref" attribute on the "item" tags containing the warning texts in the "safeprecs" content (SAFETY PRECAUTIONS) in order to enable their cross-referencing.

NOTE: The text of certain very general safety precautions will not occur in a corresponding warning.

10.3 It is PMS policy that all cross-referencing be tagged. Usually this cross-referencing is tagged in terms of the "xref" element as follows. For example, the citation.

NOTE 4. Have documentation available.
...
(See NOTE 4.)

is tagged as

<note id="noteref"><paratext>Have documentation
available.</paratext></note>
...
(See NOTE <xref idref="noteref" type="text">.)

Similarly, the following "Go To"

1. Start emptying the tank.
a. Make sure pump is operating correctly.
...
10. If the tank is not now completely empty go back to step 1.a.

is tagged as

<item><paratext>Start emptying the tank.</paratext>
<seqlist numstyle="alphalc">
<item id="itemref">
<paratext>Make sure pump is operating correctly.</paratext></item>
...
</seqlist>
</item>
...
<item><paratext>If the tank is not now completely empty go back to step <xref xrefid="itemref" type="text">.
</paratext></item>

NOTE: Such cross-references may be implicit as in the text "the procedures in steps 12 through 16". The "12" and "16" are to be cross-referenced to the "item" tags containing these steps.

10.4 A SWAB group number consists solely of three or four integers, e.g., "710", "7112", etc. Any alphabetic characters appended to or following a SWAB group number are to be discarded and not entered into "swabgrp" content. Any integers in the fifth or sixth places from the left are likewise discarded. Multiple SWAB group numbers may occur separated by a comma or a space. If a sequence of eight integers occurs, check with FTSC to see if this could be two SWAB group numbers run together.

10.5 It is possible that a few MRC documents may contain anomalies that have not been eliminated or corrected by FTSC. Such anomalies may be one of the following.

  1. A "*" occurs before the enumeration of certain items in the PROCEDURE block. This "*" should be moved to the beginning of the "item" content. If "*" or "(*)" occurs after the enumeration as part of the "item" text, this is acceptable and is not to be changed.
     
  2. The UNKNOWN heading followed by a list of items occurs in the TOOLS, PARTS, MATERIAL, TEST EQUIPMENT section. This MRC is to be referred to FTSC for clarification of this situation.

10.6 FTSC policy is to convert all graphics into figures by providing them with titles. However, there is one exception: graphics without titles are allowed in the markup of mathematical notation. In the event that a graphic without a figure occurs in a PMS document, see if the surrounding material would be tagged as mathematical notation. If this is not the case, refer the matter to FTSC for their consideration.

10.7 The following conventions apply to the tagging of tables in the MRC Procedures block. Tables can occur in the following situations:

  • Between the items of the Preliminary Steps (if any)
  • After the last item of the Preliminary Steps (if any)
  • Between the items of the Procedures
  • After the last item of the Procedures

Tables can NOT occur in the following situations:

  • Before the first item of the Preliminary Steps (if any)
  • Inside any item of the Preliminary Steps (if any)
  • Before the first item of the Procedures.
  • Inside any item of the Procedures

Any such table which seems to occur where it should not must to be referred to FTSC for their consideration.

 

11.

Changes implemented in the 990729 PMS DTD require the following changes to the tagging conventions.

11.1 The SPMIG Note standard text will now be provided by referencing the "spmignote" general entity in "spmignote" content, i.e., "<spmignote>&spmignote;</spmignote>".

11.2 The MER standard text will now be provided by referencing the "merstatement" general entity in "mer" content, i.e., "<mer>&merstatement;</mer>".

11.3 The Inactive Equipment Maintenance standard text will now be provided by referencing the "inactnote" general entity in "inactnote" content, i.e., "<inactnote>&inactnote;</inactnote>".

11.4 The Hazardous Material Statement standard text will now be provided by referencing the "hazmatpara" general entity in "hazmatpara" content, i.e., "<hazmatpara>&hazmatpara;</hazmatpara>".

11.5 The CONFIDENTIAL security classification standard text will now be provided by referencing the "confid" general entity in "mrcclass" content, i.e., "<mrcclass>&confid;</mrcclass>".

11.6 The NOFORN security classification standard text will now be provided by referencing the "noforn" general entity in "mrcclass" content, i.e., "<mrcclass>&noforn;</mrcclass>".

11.7 The SECRET security classification standard text will now be provided by referencing the "secret" general entity in "mrcclass" content, i.e., "<mrcclass>&secret;</mrcclass>".

11.8 The "stowed" standard text specifying the location of the classified material will now be provided by referencing the "stowed" general entity in "stowed" content, i.e., "<stowed>&stowed;</stowed>".