____________________ | NON-MEASUREMENT | | SENSITIVE | ____________________ MIL-M-28001A 20 July 1990 ____________ SUPERSEDING MIL-M-28001 26 February 1988 MILITARY SPECIFICATION MARKUP REQUIREMENTS AND GENERIC STYLE SPECIFICATION FOR ELECTRONIC PRINTED OUTPUT AND EXCHANGE OF TEXT 1. SCOPE 1.1 Scope. This military specification establishes the requirements for the digital data form of page-oriented technical publications. Data prepared in conformance to these requirements will facilitate the automated storage, retrieval, interchange, and processing of technical documents from heterogeneous data sources. The requirements set forth by this military specification include: a. procedures and symbology for markup of unformatted text in accordance with this specific application of the Standard Generalized Markup Language (SGML), b. SGML compatible codes that will support encoding of a technical publication to specific format requirements applicable to technical manuals, c. output processing requirements that will format a conforming SGML source file to the style and format requirements of the appropriate Formatting Output Specification Instance (FOSI) based on the Output Specification (OS). ______________________________________________________________________ |Beneficial comments (recommendations, additions, deletions) and any | |pertinent data which may be used in improving this document should be| |addressed to: Director, CALS Policy Office, OASD(P&L)WSIG Pentagon, | |Room 2B322, Washington, DC 20301, by using the self addressed | |Standardization Document Approval Proposal (DD Form 1426) appearing | |at the end of this document or by letter. | |_____________________________________________________________________| AMSC N/A AREA ILSS DISTRIBUTION STATEMENT A: Approved for public release; distribution is unlimited. -1- MIL-M-28001A 1.2 Specifications Covered. This specification establishes the requirements for the digital encoding of all technical publications. The following table displays the specification along with the public identifier of its associated document type declaration set. Data files satisfying the requirements of this specification will be one of the following types, as specified (see 2.1 for full titles): Type I --- Technical manuals conforming to MIL-M-38784 or related specifications having public document type declaration sets. Documents based on MIL-M-38784 and specifically on: _______________________________________________________________________ | Mil Spec | Associated Public Identifier | |___________________________|__________________________________________| | | | |Type Ia -- MIL-M-21742 | "-//USA-DOD//DTD MIL-M-21742 900102//EN" | | | | |Type Ib -- MIL-M-26788 | "-//USA-DOD//DTD MIL-M-26788 900102//EN" | | | | |Type Ic -- MIL-M-38812 | "-//USA-DOD//DTD MIL-M-38812 900102//EN" | | | | |Type Id -- MIL-M-63004 | "-//USA-DOD//DTD MIL-M-63004 900102//EN" | | | | |Type Ie -- MIL-M-63036 | "-//USA-DOD//DTD MIL-M-63036 900102//EN" | | | | |Type If -- MIL-M-63038 | "-//USA-DOD//DTD MIL-M-63038 900102//EN" | | | | |Type Ig -- MIL-M-63041 | "-//USA-DOD//DTD MIL-M-63041 900102//EN" | | | | |Type Ih -- MIL-M-6675 | "-//USA-DOD//DTD MIL-M-6675 900102//EN" | | | | |Type Ii -- MIL-M-83493 | "-//USA-DOD//DTD MIL-M-83493 900102//EN" | | | | |Type Ij -- MIL-M-9994 | "-//USA-DOD//DTD MIL-M-9994 900102//EN" | | | | |Type Ik -- WS-10759, | "-//USA-DOD//DTD MIL-M-10759 900102//EN" | | -1, -2,-3 | | |___________________________|__________________________________________| Type II --- Technical manuals, or other documents conforming to other military specifications or requirements. It is anticipated that in the future, document type declarations and FOSIs will be appended to their respective functional specifications rather than added to this specification. -2- MIL-M-28001A 2. APPLICABLE DOCUMENTS 2.1 Government specifications and standards. The following specifications and standards form a part of this document to the extent specified herein. Unless otherwise specified, the issues of these documents are those listed in the Department of Defense Index of Specifications and Standards (DoDISS) and supplement thereto in the solicitation. SPECIFICATIONS MILITARY MIL-M-38784 - Technical Manuals: General Style and Format Requirements MIL-M-21742 - Technical Manuals: Overhaul Electronic and Interior Communications Equipment: Content Requirements for MIL-M-26788 - Technical Manuals: Operation and Operator Maintenance Instructions (For Automotive Equipment) MIL-M-38812 - Technical Manuals: Maintenance/overhaul instructions and maintenance overhaul instructions with Illustrated Parts Breakdown. MIL-M-63004 - Technical Manuals: Preparation of Lubrication Orders MIL-M-63036 - Technical Manuals: Operator's, Preparation of MIL-M-63038 - Technical Manuals: Organizational or Aviation Unit, Direct Support or Aviation Intermediate, and General Support Maintenance MIL-M-63041 - Technical Manuals: Preparation of Depot Maintenance Work Requirements MIL-M-6675 - Technical Manuals: Intermediate Maintenance Instructions -3- MIL-M-28001A MIL-M-83493 - Technical Manuals: Organizational (Flight Line) Maintenance for Remotely Piloted Vehicles (RPVs) MIL-M-9994 - Technical Manuals: Operational and Maintenance for Mobile Training Sets and Task Trainers WS-10759, -1, -2, -3 - Technical Manuals: NAVORD Spec - Purchase Description (WS) for Ordnance Publications (OP) STANDARDS FEDERAL INFORMATION PROCESSING STANDARD FIPS PUB 152 - Standard Generalized Markup Language (SGML), adopted from ISO 8879 Information Processing - Text and Office Systems -- Standard Generalized Markup Language (SGML) MILITARY MIL-STD-1840 - Automated Interchange of Technical Information (Unless otherwise indicated, copies of military specifications are available from the Naval Publications and Forms Center, (ATTN: NPODS), 5801 Tabor Avenue, Philadelphia, PA 19120-5099. Copies of the Federal Information Processing Standards (FIPS) are available to Department of Defense activities from the Commanding Officer, Naval Publications and Forms Center, 5801 Tabor Avenue, Philadelphia, PA 19120-5099. Others must request copies of FIPS from the National Technical Information Service, 5285 Port Royal Road, Springfield, VA 22161-2171.) 2.2 Order of precedence. In the event of a conflict between the text of this document and the references cited herein, the text of this document takes precedence. Nothing in this document, however, supersedes applicable laws and regulations unless a specific exemption has been obtained. 2.3 Sources of documents. 2.3.1 Other publications. Non-government documents are generally available for reference from libraries and technical groups. ISO 8879 is available from the American National Standards Institute, Inc., 1430 Broadway, New York, NY 10018. -4- MIL-M-28001A 3. REQUIREMENTS 3.1 Text markup. Textual material prepared in accordance with this specification, shall be marked up (tagged) in a manner that conforms to ISO 8879 (SGML). SGML shall be used a. to describe the logical structure of technical publications in an unambiguous grammar, b. to assure automated quality control over adherence to that structure, and c. to deliver and store technical publication text in the most easily maintained and updated form. 3.1.1 Source file delivery requirements. Textual material marked up in accordance with this specification is referred to as a source file. A complete SGML-tagged source file(s) is a mandatory part of each final product delivered in accordance with this specification. Delivery of the source file shall be in accordance with MIL-STD-1840. 3.1.2 Support file delivery requirements. When following subsections are cited by contract, delivery of that kind of support file(s) shall be in accordance with 3.2 and 3.3 of this specification and in accordance with MIL-STD-1840. 3.1.2.1 Document Type Declaration Delivery. A document type declaration. 3.1.2.2 Formatting Output Specification Instance (FOSI) Delivery. A FOSI created in accordance with the document type declaration of 3.1.2.1. 3.1.3 Output file delivery requirements. A text presentation metafile developed through use of a page description language (PDL) is referred to as an output file. When this specification is cited by the contract, delivery of an output file shall be in accordance with 3.5 of this specification. 3.1.4 Interim document delivery requirements. Interim or partial delivery of a technical publication allows for government review prior to final delivery. Interim deliverables, if required, are specified in the contract and may include a source file, output file, or other specified format. 3.2 Document structure. This section establishes requirements for SGML Document Type Declarations. A document type declaration shall be used to define the organization and logical structure of elements, entities, and attributes allowed in a particular document. It shall also be used to control automated processing functions (such as parsing) that support quality assurance requirements. -5- MIL-M-28001A 3.2.1 MIL-M-38784 conforming technical manuals. Manuals developed in general accordance with MIL-M-38784 and/or in specific accordance with those specifications cited (see 1.2) and in accordance with this specification shall conform to a document type declaration set defined in Appendix D, Section 30, of this specification or as otherwise specified in the contract. The document type declaration sets specified in Appendix D, Section 30 need not be delivered with the tagged text, but rather are cited by their public identifiers. 3.2.2 Other technical publications. Publications developed in accordance with controlling specifications other than those cited (see 1.2) shall be delivered with a document type declaration. The document type declaration shall define the structure and content of the document consistent with the controlling specification. The document type declaration should be constructed using only tags (element types and associated attributes) in the baseline tag set defined in Appendix A of this specification. Appendix A of this specification provides guidance for development of the document type declaration, and the document type declaration set in Appendix A, Section 50 may be used directly or may be used used as a guide for document type declaration development. The document type declaration sets specified in Appendix A, Section 50 and Appendix D, Section 30, need not be delivered with the tagged text, but rather are cited by their public identifiers. The document type declaration set in Appendix A, Section 50 of this specification assures conformance with the Baseline Tag Set in Appendix A, but may require addition of element rules and relationships to define the logical structure of the document. Delivery of the document type declaration shall be in accordance with MIL-STD-1840. 3.3 Output Specification (OS) and Formatting Output Specification Instance (FOSI). The OS provides a set of formatting characteristic values used to rigorously describe composition processing functions to be performed on the elements of a text document to provide the format style required by a functional specification, for example MIL-M-38784. A Formatting Output Specification Instance (FOSI) delivered with the document must contain values for characteristics for every tag used in the document type declaration, and in every context in which the tag has a unique formatting requirement and with its attributes if they affect the formatting. 3.3.1 MIL-M-38784 conforming technical manuals. Manuals encoded in accordance with this specification to functional requirements of MIL- M-38784B or other functional requirements specifications identified in Section 1.2 of this specification, shall be accompanied by a FOSI which is compatible with the document type declaration and which incorporates the requirements for output format and style stated in the controlling specification. The FOSI examples contained in Appendix B, Section 50, shall be used as a guide for development of an appropriate FOSI. -6- MIL-M-28001A 3.3.2 Other technical publications. Publications developed in accordance with controlling specifications other than those cited (see 1.2) shall be accompanied by a FOSI which is compatible with the document type declaration and which incorporates the requirements for output format and style stated in the controlling specification. The FOSI examples contained in Appendix B, Section 50, shall be used as a guide for development of the appropriate FOSI. 3.4 Page integrity. Page integrity is the maintenance of physical or logical page boundaries at specific places in a publication. Page integrity has several purposes, and is required for some but not all applications. Any requirement for page integrity shall be as specified in the contract (see 6.2). 3.5 Output files. An output file may be specified by the contract as an interim deliverable (that is, a deliverable prior to final delivery of the SGML-tagged source file) (see 6.2). An output file may also be specified by the contract as a final deliverable in addition to (but not as a substitute for) the SGML tagged source file. 3.6 Special features. Special features shall be defined by the contract (see 6.2). Examples include requirements for start tags, processing instructions, manual or automatic numbering and in-text references to numbered items, table handling, additional ISO 8879 features (e.g. SHORTTAG, CONCUR). -7- MIL-M-28001A 4. QUALITY ASSURANCE PROVISIONS 4.1 Responsibility for inspection. Unless otherwise specified in the contract or purchase order, the contractor is responsible for the performance of all inspection requirements (examinations and tests) as specified herein. Except as otherwise specified in the contract or purchase order, the contractor may use his own or any other facilities suitable for the performance of the inspection requirements specified herein, unless disapproved by the Government. The Government reserves the right to perform any of the inspections set forth in the specification to ensure that supplies and services conform to prescribed requirements. 4.2 Responsibility for compliance. Contract deliverables shall meet the requirements of Section 3. The inspection set forth in this specification shall become a part of the contractor's overall inspection system or quality program. The absence of any inspection requirements in the specification shall not relieve the contractor of the responsibility of ensuring that all products or supplies submitted to the Government for acceptance comply with all requirements of the contract. Sampling in quality conformance does not authorize submission of known defective material, either indicated or actual, nor does it commit the Government to acceptance of defective material. 4.3 Quality assurance requirements. MIL-M-38784 identifies quality assurance requirements for technical publications. An SGML Document Type Declaration and appropriate FOSI shall be used to support the accomplishment of technical publication verification. -8- MIL-M-28001A 5. PACKAGING 5.1 Packaging requirements. The requirements for packaging shall be in accordance with MIL-STD-1840. -9- MIL-M-28001A 6. NOTES 6.1 Intended use. Preparation of technical publications in an automated support environment can be viewed as a several-step process: a. creating a document type declaration for publication control; b. creating a FOSI to specify the formatting to be applied to documents conforming with the document type declaration; c. authoring the publication and inserting SGML markup tags; d. verifying that the syntax is correct according to the rules of SGML; e. using a FOSI and document type declaration to direct the composition of the document so that the produced (printed or displayed) copy corresponds to the proper format and style; and f. optionally, generating a text presentation metafile in a page description language (PDL) to drive the display device, such as a printer or typesetter. This specification addresses all the steps in the publication preparation process. By implication, this specification defines functional capabilities of automated systems used to author and process technical publications. However, there are no explicit requirements for a particular automated system or system configuration. It is in the interest of both DoD and industry to agree on the most widely applicable set of conventions for the preparation and interchange of technical publications for both defense and non-defense use. The preparing office for this specification encourages proposals that would contribute toward this goal. For example, the Air Transport Association (ATA) is developing an SGML application for use within the commercial airline industry, and both ATA and DoD have expressed interest in collaborating on common specifications. The Society of Automotive Engineers (SAE) has already published a specification (AS 4159) that makes use of DoD specifications and standards for automated interchange of technical standards. 6.1.1 Source file delivery. Appendices A, B, and C provide the tools for steps a, b, and c above, the result of which is a complete publication source file, or input file, together with a document type declaration support file when required by 3.2.2. Delivery requirements for source files are in 3.1. It is the source file to which all subsequent changes and updates must be made to maintain the technical publication throughout its operational life. Therefore, the source file is a mandatory final deliverable when this specification is cited -10- MIL-M-28001A in the contract. Source files containing either the complete text of the technical publication, or portions of the text, may be delivered as interim products. Through the use of the SGML declaration (Appendix A, Section 30), the document type declaration, the tag descriptions (Appendix A, Section 70), the output specification (Appendix B, Section 30), and a FOSI, the delivered source will contain the complete intelligence required for subsequent processing. Subsets of the DoD Baseline Tag Set in Appendix A, Section 70, are permissible in specific conforming applications to simplify operations and reduce costs. An appropriate SGML document type declaration, conforming to the guidelines in Appendix A, Section 40, should be developed and used in conjunction with an Appendix A subset of the baseline tag set, both for document preparation, and for technical publication verification that the document conforms to the logical constructs within the document type declaration. 6.1.2 Support file delivery. An SGML document type declaration is used in steps a, b, and c above. Appendix B provides an output style and formatting specification used to accomplish step e in the document preparation process. The document type declaration and the FOSI are support files, delivery requirements for which are in 3.1. If a public document type declaration set is used as publicly defined, it need only be cited with the delivery. However, the text of the document type declaration set support file must be delivered with the source file when the technical publication does not conform to the requirements of public document type declaration sets identified in Appendixes A and D. A complete FOSI must be delivered with the source file until publicly identified FOSIs are available. 6.1.3 Output file delivery. Step f in the document preparation process uses a page description language (PDL) to produce an output file, sometimes called a text presentation metafile, to drive an output device such as a printer. Delivery requirements for output files are in 3.1. 6.1.4 Illustration files. This specification provides the tags by which raster or vector illustration files can be referenced in the source file, and incorporated in the final composed technical publication document. Preparation requirements for technical publication illustration files are addressed in MIL-STD-1840. Delivery requirements for technical publication illustration files are in MIL- STD-1840. 6.1.5 Tables. Tables are typically included as SGML-tagged text in the source file. The definition of the table may be explicitly included in the document instance or may be included through the use of an entity reference to an external or internal table definition. If an external entity is used, it may be one that is publicly identified in Appendix C, Section 60, or one that is created for use with a particular document instance and is known as a "SYSTEM" external -11- MIL-M-28001A entity. A publicly identified entity need not be submitted with a MIL-STD-1840-compliant deliverable, although it must be cited in the document type declaration submitted with the document instance. A "SYSTEM" external entity declaration must be submitted with the MIL- STD-1840-compliant deliverable. When using the template document type declaration from Appendix A, Section 50 to create a document type declaration for a specific document or contract, tables can also be delivered as illustration files (using the "graphic" element type) where preparation requirements make this alternative more cost effective, or where preparation requirements exceed the capability of the markup tags in Appendix A. Delivery of tables as separate illustration files seriously limits their utility for additional processing, and is discouraged. 6.1.6 Hardcopy and softcopy application. The delivery options in this specification (see 6.1.2, 6.1.3, 6.1.4, and 6.1.5) should be applied based on an analysis of how the information is to be used. For example, an output (PDL) file can be used for both electronic publishing of hardcopy and electronic softcopy display, but it cannot support interactive retrieval as can an SGML-tagged text source file. 6.2 Ordering data. Acquisition documents used to order SGML source files should specify the following: a. Title, number, and date of this specification b. Type of data file (see 1.2) c. Page integrity requirements (see 3.4 and 6.5.1.3) d. Output file requirements (see 3.5) e. Special features (see 3.6) f. Spell checking and hyphenation (see 6.5.2.3) g. Public character entity sets selected from Appendix C, Section 30, that are required in addition to those specified within the document type declaration beginning with Appendix A, Section 50 or Appendix D, Section 30 h. Data content notations selected from Appendix C i. Font and character set notations selected from Appendix C j. Entity declarations for inclusion of constant text selected from Appendix C -12- MIL-M-28001A 6.3 Application of non-government standards. Current national and international non-government standards do not adequately address all six steps of the publication preparation process (6.1). ISO 8879 (SGML) addresses steps a, b, and c. Appendices A, B, and C of this specification provide a common DoD-wide implementation of ISO 8879. No approved national or international standards exist to support steps d and e. Work is underway in these areas, however: a. Document Style Semantics and Specification Language (DSSSL). b. Standard Page Description Language (SPDL). As work matures in these areas, this specification will be extended or companion military specifications will be developed to define their implementation and application within DoD. In the interim, Appendix B of this specification supports step e of the publication preparation process (6.1). Step f is supported by public domain specifications for commercially available, widely implemented page description languages. 6.4 Baseline publication types. The many types of technical publications in the DoD inventory are developed to numerous specifications and contract requirements. Technical manuals, which constitute one major category of technical publication, contain instructions for the installation, operation, maintenance, training, and support of weapon systems, weapon system components, and support equipment. 6.4.1 MIL-M-38784 application. In many cases, MIL-M-38784 is used as the baseline to define the general structure, format, and style requirements for development of technical manuals. However, other specifications may be cited in addition to, or in place of MIL-M-38784 (such as those cited in 1.2). Even when MIL-M-38784 is cited, the technical publication may not conform to general structure, style, or format conventions, either because deviations have been explicitly authorized or because the requirements of MIL-M-38784 allow the author latitude in these areas. Text markup procedures must provide the flexibility to accommodate technical publications that do not adhere to a rigidly consistent structure or format. 6.4.2 General application. A second objective of this specification is to provide guidance for the user in developing document type declarations for technical publications controlled by military specifications or specific contract requirements other than those cited in this specification (see 1.2). This would be accomplished by defining a set of SGML elements, attributes, entities, and other SGML constructs (with the exception of the SGML Declaration) applicable to the non-standard publication. Appendix D, Section 30, of this specification provides document type declaration sets for use in document type declarations for technical publications conforming to -13- MIL-M-28001A the cited specifications (see 1.2). Appendix A, Section 50, provides a document type declaration set to be used directly or as a template for development of document type declarations for publications conforming to other specifications or requirements. Appendix A, Section 70, Table I of this specification defines a baseline tag set that lists all element types and their attributes (tags) that may be used when creating document type declarations. No distinction is made between technical publications which conform and those that do not conform to the cited specifications (see 1.2). Appendix B, Section 50, provides examples of portions of a FOSI that can be used to create a full FOSI written in accordance with a document type declaration. Accordingly, this specification, including its appendices, will support most automated publishing applications within the Department of Defense. 6.4.3 SGML document type declarations. Appendix D, Section 30, provides the Document Type Declaration Sets to describe the structure of a technical publication conforming to the requirements of MIL-M- 38784 and other specifications cited (see 1.2). It should be used for preparation of the SGML-tagged text of any technical publication developed in accordance with these specifications. While there are alternative ways to write a technically correct document type declaration for MIL-M-38784 conforming technical publications, the document type declaration set in Appendix D, Section 30, is the preferred version, and should not be modified arbitrarily. When one of these specifications is not cited as a contract requirement, when deviations from the requirements of these specifications have been authorized, or when the requirements of these specifications have been interpreted differently, an alternative document type declaration must be developed and delivered. Appendix A, Section 50, provides a template document type declaration set that may be used directly or as a guide for development of alternative document type declarations. 6.4.4 Formatting Output Specification Instance (FOSI). Appendix B, Section 50, provides examples of portions of a FOSI (format and style guide) for composition and display of document text tagged in accordance with Appendix A, Section 50. These fragments can be used as examples or as models to create FOSIs for document type declarations created in accordance with this specification. These FOSI portions can be tailored or modified to satisfy the format and style requirements cited in the governing specification or in the contract. An objective of the FOSI is to rigorously define the format and style of the document produced from the SGML-tagged text. Together with the markup tags specified in Appendix A, Section 70, the FOSI provides a basic vocabulary from which changes in output processing statements (macros) can be constructed. -14- MIL-M-28001A 6.4.5 Page description languages. While the FOSI in Appendix B, Section 50, defines format and style requirements for a technical publication, specific electronic publishing systems may define additional processing limitations, such as font variations, kerning, or hyphenation. A page description language can be used to ensure that the composed document produced by the electronic publishing system would produce nearly identical hardcopy output on the widest possible spectrum of printer devices. Even then, additional content or processing restrictions may be needed. Although no standard page description language exists, specifications have been placed in the public domain for several machine-independent languages that are implemented commercially on many printers and typesetters. The standard page description language (SPDL) that will be supported by this specification when developed is expected to provide comparable features and capabilities. 6.4.5.1 Interim deliverables. Source files are one form of interim deliverable that may be contractually required. However, early in the acquisition cycle, a page description language file may be the most appropriate digital product for delivery to the government customer for content and format review. This is particularly true if the performing contractor's processing system requires addition of elements to produce the source file (SGML-tagged text) that must be provided as a final deliverable, or requires additional processing steps to compose text and graphics for technical publication verification. In such cases, the cost and schedule implications of premature capture of processable source data should be carefully evaluated. 6.4.5.2 Additional final deliverable. Life cycle maintenance of the technical publication requires delivery of the source file (and support files, if appropriate) as a final deliverable. However, contract requirements may specify that a page description language file be delivered as an optional, additional product. 6.4.6 Specification revisions. Future revisions to this specification will broaden its application on a cost-effective basis. This may be accomplished by: a. including in Appendix A additional SGML markup tags; and b. including in Appendix B additional format and style options consistent with any changes made to future Appendices. -15- MIL-M-28001A Further, examination of military specifications and standards other than those cited (see 1.2) governing preparation of technical publications may identify requirements which can be satisfied without such additions. Users are encouraged to submit suggestions for update of this specification to the Preparing Activity. Procedures for registration and control of support files for technical publications will be established. This specification addresses automated publishing and softcopy (on- screen display) requirements for page-oriented technical publications. Automation requirements for non-page oriented (pageless) technical publications will be addressed in a separate military specification. Additional material may be incorporated in this specification in the future to ensure that requirements for both page-oriented and pageless technical publications remain compatible and consistent. Through its TMSS (Technical Manual Specification and Standards) program, the Department of Defense is consolidating the large number of military specifications currently used to define functional requirements for page-oriented technical publications. Through revisions to this specification or additions to the consolidated functional specifications, DoD will implement automated publishing requirements for the consolidated set of TMSS requirements documents. DoD objectives are to: - Have a minimum number of generic TMSS specifications and standards to address most DoD functional requirements for technical publications. - Support the consolidated set of TMSS documents with a minimum number of generic document type declarations and FOSIs to address most DoD automated publishing requirements for technical publications. These objectives will be achieved in an evolutionary fashion. They will result in publication of new TMSS specifications to replace those currently in use, and corresponding updates to this specification. Development of document type declarations and FOSIs to meet common DoD requirements will be prioritized for incorporation in this specification. Users are encouraged to assist in establishing the priorities for these document type declarations and FOSIs, and to make use of them as they become available. Development of program-specific document type declarations and FOSIs is not prohibited, but is actively discouraged for both cost and technical reasons. Where program-specific requirements exist, the user must register the proposed document type declaration/FOSI development. Registration will be used to control the proliferation of document type declarations and FOSIs, and to assist users in determining how program requirements can be met without beginning development of document type declarations and FOSIs for one-time use. -16- MIL-M-28001A 6.5 Publication management and processing considerations. 6.5.1 Technical publication management considerations. This specification provides the contractor and government technical publication manager with tools to be used in determining if a given document is in or out of conformance with the governing specification (MIL-M-38784 or other), or contract requirements. 6.5.1.1 Preparation of document type declarations. Constructing and maintaining SGML document type declarations in accordance with ISO 8879 is necessary to facilitate the automated preparation, storage, retrieval, interchange, and processing of technical publications. The technical publication manager must maintain full control over the technical publication's structure, content, and format. When a cited specification (see 1.2) is not applicable, an alternative document type declaration must be prepared. Even when one of these specifications is contractually cited, the resultant technical publication may diverge from its requirements for a variety of reasons: a. Military specifications such as those cited are permissive with regard to precise document construction, and contain language giving precedence to contract provisions. b. Authors often write to multiple military specifications in a given document (when these specifications are cited in the contract), or to specific statement of work requirements, and these requirements may conflict with or override the specifications listed in 1.2. c. Authors purposely use variant document structures in the interest of content clarity. d. Document construction requirements in the cited specifications (see 1.2) may change when that specification changes. Consequently, there are legitimate reasons why the document type declaration sets in Appendix D, Section 30, are not applicable. However, where a cited specification (see 1.2) is contractually required, the government technical publication manager should carefully weigh the implications before defining unique requirements which would preclude use of the document type declaration sets in Appendix D, Section 30. It is an objective of this specification to minimize the number of unique document type declarations that must be created, managed, and maintained. This objective will be met through control of requirements by the government technical publication manager, and through the registration process in 3.7. -17- MIL-M-28001A 6.5.1.2 Use of document type declarations. The appropriate SGML document type declaration provides a basis for electronically preparing a given publication, and then determining whether the document conforms to the logical constructs within the document type declaration. A syntactic analysis is made by parsing the document. Parsing will verify whether or not the string of tokens conforms to the grammar. 6.5.1.3 Page integrity. Page integrity is one technique for maintaining configuration control of technical publication changes. Page integrity is also used to support a loose-leaf or page update printing and distribution system for applications which require it. Both of these objectives are different from document-specific page formatting, in which page breaks are used to assist in communicating the information content of the publication. The requirement for page integrity is optional, and should be carefully evaluated in terms of cost and utility. When specified by the contract, page integrity should be implemented using forced page breaks in accordance with the following rule: Once a document's configuration baseline has been established, page integrity should be maintained in both the primary and any secondary processing systems until the configuration control baseline is redefined by the technical publication manager. (see definition of terms 6.7) 6.5.2 Processing system considerations. The processing system is a tool of the author and the technical publication manager. The processing system should not abrogate the authority of the manager to: a. determine whether document corrections are warranted, and b. set an orderly plan and schedule for such correction. Likewise, the author's authority over interpretation of contract requirements for content, style, and format should not be abrogated by the processing system unless expressly authorized by the technical publication manager. 6.5.2.1 Source file configuration control. Ideally, the processing system should have the capability to utilize the SGML-tagged source file (plus illustration files) as input to the subsequent composition and output processes. However, this is not a requirement, and intermediate files may be used. Configuration control of changes to either intermediate or output files is necessary, since the final deliverable product is the SGML-tagged source file. All system processing should be governed by the following rule: When corrections are made to a working, intermediate, or output file, corrections must be incorporated in the source file which is the primary final deliverable product under the contract. -18- MIL-M-28001A 6.5.2.2 Spell checking and hyphenation. Requirements for spell checking and hyphenation should be specified in the contract (see 6.2). Since processing systems may differ in the way they treat these subjects, users should not expect consistent treatment across system boundaries unless specific requirements are established in advance. 6.5.2.3 Processing instructions. Processing instructions are a tool provided by SGML to handle unique or unusual conditions. Their use is discouraged, but not disallowed, because it is recognized that in some situations processing instructions are a necessary part of document processing. They are usually system-unique and are ignored by an SGML parser, precluding all control except cursory syntax checks unless additional processing system software is used. Their use or exclusion is controlled by contract restrictions. 6.6 Technical publication data requirements. When this specification is cited in a contract, a contract exhibit must be prepared to fully describe statement of work criteria and delivery instructions, and cite this and any other applicable specifications. The technical publications must be acquired by a separate Contract Line Item Number (CLIN) in the contract. 6.7 Definition of terms. The following is a collection of definitions for terms used throughout this specification. 6.7.1 Definitions for SGML constructs. These definitions are based on those available in ISO 8879 and are repeated here for convenience only. For a complete glossary of terms, see ISO 8879, clause 4. ATTRIBUTE (of an element): A characteristic quality, other than element_type or content. ATTRIBUTE DEFINITION: A member of an attribute definition list within an attribute list declaration; it declares an attribute name, specifies the form and SGML-specific aspects of possible values, and specifies the action (such as providing a default value) to be taken if an attribute's value is not specified. In the display under ATTRIBUTE (DEFINITION) LIST DECLARATION, each attribute definition is shown as: name_of_attribute allowable_values default -19- MIL-M-28001A ATTRIBUTE (DEFINITION) LIST DECLARATION: A markup declaration that associates an attribute definition list with one or more element types, shown as: ATTRIBUTE (SPECIFICATION) LIST: Markup that is a set of one or more attribute specifications, shown as: attribute=value attribute=value attribute=value Used within a Start Tag, as in: DECLARATION: Markup declaration. DECLARATION SUBSET: A delimited portion of a markup declaration in which other declarations can occur. DOCUMENT TYPE DECLARATION: A markup declaration that contains the formal specifications of a document type definition, shown as: DOCUMENT TYPE DEFINITION: An abstract collection of rules, determined by an application, that apply SGML to the markup of documents of a particular type. DTD: Document type definition. (NOTE: "DTD" is commonly--but not in compliance with current ISO 8879 terminology--used as an abbreviation for "document type declaration"; it is also an SGML reserved word used in formal public identifiers to indicate that the identified entity is a document type declaration set.) ELEMENT: A component of the hierarchical structure defined by a document type declaration. It is identified in a document instance by descriptive markup, usually a start-tag and end-tag, shown as: content of the element -20- MIL-M-28001A ELEMENT TYPE DECLARATION: A markup declaration that contains the formal specification of the part of the definition of an element type that deals with the content and markup minimization, shown as: ENTITY: A collection of characters or other data that can be referenced as a unit. ENTITY DECLARATION: A markup declaration that assigns an SGML name to an entity so that it can be referenced, shown as: ENTITY REFERENCE: A reference that is replaced by an entity, shown as: &entity_name; or %entity_name; The ampersand is used for general entities (referenced in the document element); the percent sign is used for parameter entities (typically referenced in the document type declaration). ENTITY SET: A set of entity (and comment) declarations that are used together. SGML: Standard Generalized Markup Language, as detailed in International Standard 8879. It is a metalanguage that "provides a coherent and unambiguous syntax for describing whatever a user chooses to identify within a document." SGML DECLARATION: A markup declaration that specifies the character set, concrete syntax, optional features, and capacity requirements of a document's markup. It applies to all of the SGML entities of a document. SGML ENTITY: An entity whose characters are interpreted as markup or data in accordance with ISO 8879. -21- MIL-M-28001A 6.7.2 Definitions for terms created for or used by this specification. BASELINE TAG SET: Those element types and their attributes, defined in this specification, that may be used to build document type declarations in accordance with this specification. The content model or declared content of the element type may vary between document type declarations as may the tag minimization. However, the attributes and their declared and default values remain identical across all document type declarations. The semantics associated with the element type and its attributes is also constant across document type declarations. DECLARATION SET: A set of declarations that are used together. DOCUMENT TYPE DECLARATION SET: A declaration set intended for inclusion within a document type declaration. It consists of one or more entity sets and/or element type sets and/or short reference sets. (NOTE: Short reference declarations are not currently used in documents covered by this specification.) DOCUMENT TYPE DECLARATION SUBSET: The declaration subset of a document type declaration. It consists of a document type declaration set. (NOTE: This definition has been modified to incorporate the semantics employed by this specification. It has, therefore, been included in this subsection.) ELEMENT TYPE SET: A set of element type, attribute list, and notation (and comment) declarations that are used together. FORMATTING OUTPUT SPECIFICATION INSTANCE: An instance of the Output Specification (OS) that assigns values to the style characteristics for a particular document type declaration. The FOSI uses the syntax of an SGML document instance. OUTPUT SPECIFICATION: A finite set of style characteristics to convey formatting intent for interchange of technical publications coupled with a mechanism for binding the style characteristics to logical elements in an SGML document type declaration. The OS uses the syntax of an SGML document type declaration. PAGE FIDELITY: The ability to preserve the exact presentation characteristics in addition to the same information on pages exchanged between systems. PAGE INTEGRITY: The ability to preserve the exact same information on each page in a manual as it is exchanged between systems. This does not mean that the information will be presented exactly the same way, but only that it appear between the same page boundaries. -22- MIL-M-28001A TECHNICAL PUBLICATION VERIFICATION: This term refers to the parsing of the digital data stream containing a technical publication to assure compliance with the standard (SGML, CCITT, CGM, IGES) to which it was written. There is no intent in this term to imply the validation/verification process used to certify the content of the technical publication. 6.8 Changes from previous issue. Marginal notations are not used in this revision to identify changes with respect to the previous issue due to the extensiveness of the changes. 6.9 Subject term (key word) listing. The following subject terms (key words) are applicable: Language, Page Description Manuals, Technical Orders, Technical Page Description Language Publications, Technical Publishing, Electronic Standard Generalized Markup Language Tagging, Generic Text Composition Language Text Presentation Metafile -23-