To create a MIL-STD-490A document, you copy the template file MILSPEC_SAMPLE.SDML from the directory DOC$TEMPLATES into your work directory, then edit it to insert your text. Alternatively, you can create your own file. If you create a new file, you may still want to look at the template SDML input file as a guide.

To create documents that conform to MIL-STD-490A, you use the MILSPEC doctype tags in the following manner:

• Create the required cover page for the document using the <SPEC_TITLE> and <SPECIFICATION_INFO> tags in the context of the global <TITLE_PAGE> tag. The <SPEC_TITLE> tag creates a title for the document and the <SPECIFICATION_INFO> tag places additional information on the cover page of the document, and sets the running headings for the rest of the document, including the table of contents. The <SPEC_TITLE> may be too long for practical use with Bookreader. You may want to use the <ONLINE_TITLE> tag and a shorter title just before the <SPEC_TITLE> tag for use by the Bookreader Library, title bar, and topic bar. This tag is only valid for Bookreader, and is ignored when you process for printed documents. Additionally, you must include the <CONTENTS_FILE> tag if processing for Bookreader. Refer to Chapter 8 for information about online documentation.
• Create major sections (such as Section 1, Scope,) in your document using the global <CHAPTER> tag. Each <CHAPTER> tag that has paragraph text immediately following it should have a <P> tag placed between the heading and the text for correct formatting, just as in any document. Chapters that contain no pertinent information should be coded with the <CHAPTER> tag, complete with the appropriate title text and the symbol name argument. Such chapters should contain only the following standard disclaimer paragraph as specified in MIL-STD-490A.

  
  This section is not applicable to this specification.

• Create the numbered paragraphs in each major section using the appropriate global numbered heading tags (<HEAD1>, <HEAD2>, and so on). Again, each heading tag that has paragraph text immediately following it should have a <P> tag placed between the heading and the text for correct formatting, just as in any document. The MILSPEC doctype automatically inserts a period at the end of all titled numbered headings.
  To cross-reference numbered paragraphs in your document, specify them using the <REFERENCE> tag with the VALUE argument so that the default text Section does not automatically output before the paragraph number.
  Refer to Using Global Tags for information about using the <REFERENCE> tag and its arguments, such as VALUE.
  If you are processing for Bookreader, you can create hotspots to cross-reference information. Refer to Chapter 8 for information about online documentation.

Use DECdocument to create a Data Item Description document in accordance with either U.S. Department of Defense standard DOD-STD-2167 or DOD-STD-2167A. DOD-STD-2167A is a Department of Defense military standard published February 29, 1988 that supersedes DOD-STD-2167, published June 4, 1985.

Create a Data Item Description (DID) document in accordance with either DOD-STD-2167 or DOD-STD-2167A in any of the following ways:

• Copy the appropriate template file from the DOC$TEMPLATES directory into your directory and edit that file (the template files contain comments to guide you in their use).
• Edit a file with LSE and expand the appropriate LSE Data Item Description template.
• Create your own file (if you create your own new file, you may still want to look at the SDML input file templates or the LSE templates as guides).

To create a DOD-STD-2167 document, copy and edit one of the 24 Data Item Description (DID) templates listed in Table 7-3, or expand the appropriate LSE templates available in LSE.

Process your finished SDML input file using the MILSPEC.SECURITY or MILSPEC.ONLINE doctypes to have a document format that conforms to DOD-STD-2167.

See Section 7.5 for information on the tags available in the MILSPEC.SECURITY doctype and Chapter 8 for information on the additional tags needed for MILSPEC.ONLINE.

7.4.2 Creating DOD-STD-2167A Documents

To create a DOD-STD-2167A document, copy and edit one of the 17 Data Item Description (DID) templates listed in Table 7-4, or expand the appropriate LSE templates available in LSE.

You create DOD-STD-2167A formatted documents by using the MILSPEC.SECURITY doctype with certain tags enabled in that doctype. To create a document that follows the 2167A format specifications, enter the SDML code shown in Example 7-1 at the top of your SDML file (or include it from a separate file using either the <INCLUDE> tag or the /INCLUDE qualifier) and then process it using the MILSPEC.SECURITY doctype.

Example 7-1 Coding a 2167A-Formatted Document

<DOCUMENT_ATTRIBUTES> <SET_HEADINGS>(CENTERED) <SET_APPENDIX_ENUMERATION>(ALPHABETIC) <ENDDOCUMENT_ATTRIBUTES>

To create double-spaced draft output of this file, use the same procedure, but process the file using the MILSPEC.DRAFT doctype.

7.4.2.1 Using the Data Item Description Template Files

DECdocument contains Data Item Description (DID) template files to make creating DOD-STD-2167 and DOD-STD-2167A documents easier. See Table 7-3 for a list of the DOD-STD-2167 templates; see Table 7-4 for a list of the DOD-STD-2167A templates.

The template files supply a framework for each of the supported DID specifications, so that all you need supply is the text specific to your document. The document template provides all required tags, including section and paragraph headings.

Each template file is a collection of individual element files coded for a specific DID or military document. These files are concatenated into a single file to simplify use and storage. When you use one of these concatenated files, separate it into several files, one file for each major section of your document.

Each section of the template input file has comments with directions for its use. Placing each major section in a separate file makes it easier to maintain your document and lets you use the book-building features of DECdocument. When you are ready to create your book, list these files in a profile file using the <ELEMENT> tag and process the profile as a DECdocument book build.

Such a profile would appear as follows:

<COMMENT>(SDML profile for My Document) <PROFILE> <ELEMENT>(frontmatter.sdml) <ELEMENT>(scopechap.sdml) <ELEMENT>(secondchap.sdml) <ELEMENT>(thirdchap.sdml) <ELEMENT>(fourthchap.sdml) <ELEMENT>(fifthchap.sdml) <ELEMENT>(noteschap.sdml) <ELEMENT>(firstapx.sdml) <ENDPROFILE>

For example, if you were to use the file MILSPEC_DID_80025.SDML, you would place each of the six major sections in a separate file, and also place the front matter section and the symbol definition section in separate files. DECdocument would place each of these files in your document as it builds your book.

For more information about creating a profile, refer to the <PROFILE> tag description in Using Global Tags.

To use the DID template files, do the following:

1. Select the template you want by referring to either Table 7-3 for DOD-STD-2167 templates or to Table 7-4 for DOD-STD-2167A templates. The names of the template files correspond to their DID document number.
   If the template you want is not listed, use a similar template as the basis for creating your own template. You may want to read through the template to make sure it is the one you want.
2. Copy the template file you selected or created into your working directory before you modify it. Do not modify the DECdocument templates in DOC$TEMPLATES. Other users of DECdocument may also want to use them.
3. Separate the template file into separate files, placing each major section (beginning with the <CHAPTER> tag) in a separate file. Place the front matter (beginning with the <FRONT_MATTER> tag) and the symbol definitions (created using the <DEFINE_SYMBOL> and <DEFINE_BOOK_NAME> tags) in separate files.
4. Modify the appropriate text arguments to the <DEFINE_SYMBOL> tags so that the proper text (such as your product's name) automatically inserts into the template when the symbol is referenced.
   Each template file contains references to symbols created using the <DEFINE_SYMBOL> tag. Comments in the template file identify which symbols are used by all the templates and which symbols are used only in that particular template.
5. Create a book-building profile that lists each of the major sections and the front matter file as book elements. These book elements can then be built into a single book by DECdocument. You may want to include the <CONTENTS_FILE> and <INDEX_FILE> tags in your profile to automatically include your table of contents and index files into the final book.
   Do not include the file that contains the symbol definitions in the profile. Specify the symbol definitions file as an argument to the DOCUMENT /SYMBOLS qualifier when you process your profile, as shown in the following example:

   $ DOC/LIST/CONTENTS/SYMBOLS=MY_SYMBOLS.SDML $ _MYFILE.SDML MILSPEC LN03

   
   The following is a sample book-building profile for a military specification document. The <CONTENTS_FILE> and <INDEX_FILE> tags automatically include the table of contents and index files for the document.

   <PROFILE> <ELEMENT>(frontmatter.sdml) <CONTENTS_FILE> <ELEMENT>(scopechap.sdml) <ELEMENT>(secondchap.sdml) <ELEMENT>(thirdchap.sdml) <ELEMENT>(fourthchap.sdml) <ELEMENT>(fifthchap.sdml) <ELEMENT>(noteschap.sdml) <ELEMENT>(firstapx.sdml) <INDEX_FILE> <ENDPROFILE>

   
   If you have a large book element or a book element that contains sections that change a great deal, you may want to separate that book element into several files. You include these separated files, called book subelements, into the book element file with the global <INCLUDE> tag. The following sample shows the book element file thirdchap.sdml that includes several book subelement files.

   <COMMENT>(File: thirdchap.sdml) <CHAPTER>(Testing Results\test_results_chap) <INCLUDE>(testing_intro.sdml) <INCLUDE>(test1_results.sdml) <INCLUDE>(test2_results.sdml) <INCLUDE>(test3_results.sdml) <INCLUDE>(test4_results.sdml) <INCLUDE>(test5_results.sdml) <INCLUDE>(testing_conclusions.sdml)

   
   Each of these book subelements can be processed individually and have all cross-references correctly resolved after the entire book has been built. The book-building process creates the XREF cross-reference file that the subelement accesses to resolve the cross-references. See the Producing Online and Printed Documentation for more information about creating and using book build profiles, symbol definitions files and processing book subelements.

6. Enter the appropriate information for your document into each of the major sections of the template input file.

Table 7-3 MILSPEC Doctype DOD-STD-2167 Data Item Description Templates

Data Item Description Number	Template Description	Template Files Located in the Directory DOC$TEMPLATES
None.	Sample template for any document conforming to MIL-STD-490A	MILSPEC_SAMPLE.SDML
DI-CMAN-80008 AMSC No. N3584	System/Segment Specification	MILSPEC_DID_80008.SDML
DI-MCCR-80009 AMSC No. N3585	Software Configuration Management Plan	MILSPEC_DID_80009.SDML
DI-MCCR-80010 AMSC No. N3586	Software Quality Evaluation Plan	MILSPEC_DID_80010.SDML
DI-MCCR-80011 AMSC No. N3587	Software Standards and Procedures Manual	MILSPEC_DID_80011.SDML
DI-MCCR-80012 AMSC No. N3588	Software Top Level Design Document	MILSPEC_DID_80012.SDML
DI-MCCR-80013 AMSC No. N3589	Version Description Document	MILSPEC_DID_80013.SDML
DI-MCCR-80014 AMSC No. N3590	Software Test Plan	MILSPEC_DID_80014.SDML
DI-MCCR-80015 AMSC No. N3591	Software Test Description	MILSPEC_DID_80015.SDML
DI-MCCR-80016 AMSC No. N3592	Software Test Procedure	MILSPEC_DID_80016.SDML
DI-MCCR-80017 AMSC No. N3593	Software Test Report	MILSPEC_DID_80017.SDML
DI-MCCR-80018 AMSC No. N3594	Computer System Operator's Manual	MILSPEC_DID_80018.SDML
DI-MCCR-80019 AMSC No. N3595	Software User's Manual	MILSPEC_DID_80019.SDML
DI-MCCR-80020 AMSC No. N3596	Computer System Diagnostic Manual	MILSPEC_DID_80020.SDML
DI-MCCR-80021 AMSC No. N3597	Software Programmer's Manual	MILSPEC_DID_80021.SDML
DI-MCCR-80022 AMSC No. N3598	Firmware Support Manual	MILSPEC_DID_80022.SDML
DI-MCCR-80023 AMSC No. N3599	Operational Concept Document	MILSPEC_DID_80023.SDML
DI-MCCR-80024 AMSC No. N3600	Computer Resources Integrated Support Document	MILSPEC_DID_80024.SDML
DI-MCCR-80025 AMSC No. N3601	Software Requirements Specification	MILSPEC_DID_80025.SDML
DI-MCCR-80026 AMSC No. N3602	Interface Requirements Specification	MILSPEC_DID_80026.SDML
DI-MCCR-80027 AMSC No. N3603	Interface Design Document	MILSPEC_DID_80027.SDML
DI-MCCR-80028 AMSC No. N3604	Data Base Design Document	MILSPEC_DID_80028.SDML
DI-MCCR-80029 AMSC No. N3605	Software Product Specification	MILSPEC_DID_80029.SDML
DI-MCCR-80030 AMSC No. N3606	Software Development Plan	MILSPEC_DID_80030.SDML
DI-MCCR-80031 AMSC No. N3607	Software Detail Design Document	MILSPEC_DID_80031.SDML

Table 7-4 MILSPEC.SECURITY Doctype DOD-STD-2167A Data Item Description Templates

Data Item Description Number	Template Description	Template Files Located in the Directory DOC$TEMPLATES
DI-CMAN-80008A AMSC No. F4328	System/Segment Specification	MILSPEC_DID_80008A.SDML
DI-CMAN-80534 AMSC No. N4329	System/Segment Design Document	MILSPEC_DID_80524.SDML
DI-MCCR-80012A AMSC No. N4330	Software Design Document	MILSPEC_DID_80012A.SDML
DI-MCCR-80013A AMSC No. N4331	Version Description Document	MILSPEC_DID_80013A.SDML
DI-MCCR-80014A AMSC No. N4332	Software Test Plan	MILSPEC_DID_80014A.SDML
DI-MCCR-80015A AMSC No. N4333	Software Test Description	MILSPEC_DID_80015A.SDML
DI-MCCR-80017A AMSC No. N4334	Software Test Report	MILSPEC_DID_80017A.SDML
DI-MCCR-80018A AMSC No. N4335	Computer System Operator's Manual	MILSPEC_DID_80018A.SDML
DI-MCCR-80019A AMSC No. N4336	Software User's Manual	MILSPEC_DID_80019A.SDML
DI-MCCR-80021A AMSC No. N4337	Software Programmer's Manual	MILSPEC_DID_80021A.SDML
DI-MCCR-80022A AMSC No. N4338	Firmware Support Manual	MILSPEC_DID_80022A.SDML
DI-MCCR-80024A AMSC No. N4339	Computer Resources Integrated Support Document	MILSPEC_DID_80024A.SDML
DI-MCCR-80025A AMSC No. N4340	Software Requirements Specification	MILSPEC_DID_80025A.SDML
DI-MCCR-80026A AMSC No. N4341	Interface Requirements Specification	MILSPEC_DID_80026A.SDML
DI-MCCR-80027A AMSC No. N4342	Interface Design Document	MILSPEC_DID_80027A.SDML
DI-MCCR-80029A AMSC No. N4343	Software Product Specification	MILSPEC_DID_80029A.SDML
DI-MCCR-80030A AMSC No. N4344	Software Development Plan	MILSPEC_DID_80030A.SDML

7.5 MILSPEC Doctype Tag Reference

This part of this chapter contains reference information on all the tags available in the MILSPEC doctypes. The MILSPEC doctypes are a full implementation of the United States Military Specification Standard MIL-STD-490A.

Places an example of code in a proportionally spaced font.

Syntax

<CODE_EXAMPLE>

code example text

.
.
.

<ENDCODE_EXAMPLE>

ARGUMENTS

code example text

Specifies a code fragment you want to insert into your text.

related tags

• The global <INTERACTIVE> tag
• The global <LINE_ART> tag
• The global <VALID_BREAK> tag

restrictions

Valid only in the context of the MILSPEC doctypes; all other doctypes use the global <CODE_EXAMPLE> tag, which accepts arguments and has a different format than the MILSPEC <CODE_EXAMPLE> tag.

Do not use indexing tags (<X> and <Y> ) in code examples.

Do not use tab characters to format code examples. Use spaces rather than tabs.

Do not use text element tags in <CODE_EXAMPLE> (for example, <P>, <LIST>, or <NOTE>).

required terminator

<ENDCODE_EXAMPLE>

DESCRIPTION

The <CODE_EXAMPLE> tag places an example of code in a proportionally spaced font. It causes the one or more lines of code example text to be indented from the text that surrounds it.

The size of the example, whether it will be indented, and how much it will be indented from the current left margin of text is controlled by the document design.

Enter the code example text between the <CODE_EXAMPLE> and <ENDCODE_EXAMPLE> tags. Character spaces and blank lines that you enter to format the code will be retained. Also, use the <ELLIPSIS> tag in this context to a vertical ellipsis to indicate you omitted some lines of code. If your code example is longer than a few lines, use the global <VALID_BREAK> tag to indicate the acceptable points for a page break.

Use the global <LINE_ART> or <INTERACTIVE> tags to create monospaced code examples in the MILSPEC doctypes.

Example

The following example shows the coding of a proportionally spaced code example.

<CODE_EXAMPLE> 
<KEYWORD>(type) DURATION <KEYWORD>(is) <KEYWORD>(delta) 
      <EMPHASIS>(implementation_defined) 
      <KEYWORD>(range) <EMPHASIS>(implementation_defined); 
<ENDCODE_EXAMPLE> 
 

This example produces the following output:

type DURATION is delta implementation_defined range implementation_defined;