Back to Home Page
E-mail to SPA staff
[Mirrored from: http://stdsbbs.ieee.org/aboutSPA/spasgml/sect3.html]
The main component of the SPAsystem SGML application is a suite of SGML document type definitions (DTDs) designed to guide the author through the document development process. As described in 2.2, this suite comprises a number of small DTDs, each of which represents a major structural component of an IEEE standards document. In addition to the DTD modules, the suite contains a DTD for a complete IEEE standards document. Working groups who choose to develop documents with the full-document DTD are free to do so, but they may find that the modules provide a simpler and more flexible authoring environment.
The SPAsystem authoring DTD suite is comprised of the following DTDs:
a) Clause DTD (bdy_cls.dtd)
b) References clause DTD (ref_cls.dtd)
c) Definitions clause DTD (def_cls.dtd)
d) Bibliography clause DTD (bib_cls.dtd)
e) Annex DTD (annex.dtd)
f) IEEE standard DTD (ieeestd.dtd)
The following subclauses describe each component of the DTD suite and how it is to be used. The SGML tags that represent the elements being described are shown in boldface.
The clause title (<cls.tit>) is the heading for a clause or subclause. It contains text and inline elements (see 3.1.1.2.1).
The second-level subclause (<bdy2.cls>) can be subdivided into one or more third-level subclauses (<bdy3.cls>). A second-level subclause (<bdy2.cls>) always begins with a number (<no>) followed by a clause title (<cls.tit>). This is followed by either text or one or more third-level subclauses (<bdy3.cls>). If the second-level subclause (<bdy2.cls>) does contain text, one or more third-level subclauses (<bdy3.cls>) may occur following the text.
The third-level subclause (<bdy3.cls>) can be subdivided into one or more fourth-level subclauses (<bdy4.cls>). A third-level subclause (<bdy3.cls>) always begins with a number (<no>) followed by a clause title (<cls.tit>). This is followed by either text or one or more fourth-level subclauses (<bdy4.cls>). If the third-level subclause (<bdy3.cls>) does contain text, one or more fourth-level subclauses (<bdy4.cls>) may occur following the text.
The fourth-level subclause (<bdy4.cls>) can be subdivided into one or more fifth-level subclauses (<bdy5.cls>). A fourth-level subclause (<bdy4.cls>) always begins with a number (<no>) followed by a clause title (<cls.tit>). This is followed by either text or one or more fifth-level subclauses (<bdy5.cls>). If the fourth-level subclause (<bdy4.cls>) does contain text, one or more fifth-level subclauses (<bdy5.cls>) may occur following the text.
The fifth-level subclause (<bdy5.cls>) is the smallest structural unit in an IEEE standard and cannot be subdivided. A fifth-level subclause (<bdy5.cls>) always begins with a number (<no>) followed by a clause title (<cls.tit>) followed by text.
Text within a clause can consist of any number of paragraphs, floats, lists, notes, computer code listings, and/or equations.
A paragraph (<para>) can consist of words, inline elements, floats, lists, and notes.
There are four types of inline elements (i.e., elements that can appear in-line with text) that can occur within a paragraph:
a) Stylistic emphasis (<emph>). This element is used to emphasize words or phrases according to their intended appearance. The format of the emphasis (bold, italic, etc.) is determined by the "type" attribute of the <emph> element.
b) Structural emphasis (<emph2>). This element is used to emphasize words or phrases according to their meaning. The type of emphasis (caution, warning, etc.) is determined by the "type" attribute of the <emph2> element. The <emph2> element is typically applied to entire paragraphs.
c) Cross-reference (<xref>). This element is used to establish a link between a word or phrase and another element within the document instance (i.e., hyper link). To establish a link, the value of the "refid" attribute of the <xref> element must match the "id" attribute value of the target element.
d) Footnote (<ftn>). This element is used to provide short annotations to inline text. The presence of the <ftn> element will cause the processing system to generate a footnote reference at the point in text at which the footnote occurs.
Floats are elements that can "float" on the page, depending on the rules established by the processing system. There are two types of floats: figures (<figure>) and tables (<table>).
The <figure> element may contain only the figure title (<caption>), or it may contain the figure title (<caption>) and/or a pointer to an external graphical entity (<art>). If the author chooses to insert only the <caption> element, the IEEE Standards Department Project Editor will insert the <art> element and figure entity. If the author chooses to insert the <art> element, then he/she must also insert a figure entity at the beginning of the document instance; see 4.3. The <caption> may be followed by zero or more figure notes (<fig.note>), which are considered a normative part of the document.
The <table> element may contain a table title (<caption>), followed by either an external graphical entity (<art>, see above) or by a CALS table (<t.group>). If your SGML text editor does not provide CALS table support, you may submit the table in a proprietary format (such as MS Word or Excel) and it will be converted into CALS by the IEEE Standards Department. The <t.group> element may be followed by zero or more table notes (<tab.note>), which are considered a normative part of the document.
There are three types of lists that may appear within clause text: ordered lists (<ol>), unordered lists (<ul>), and descriptive lists (<dl>).
a) Ordered or lettered list (<ol>). This is a list in which each list item (<li>) is preceded by a letter or number (<no>). The <no> element in an ordered list (<ol>) should contain only the letter or number of the list item (<li>) (example: a, b, c, ... 1, 2, 3, ... or i, ii, iii); it should not contain any separators. Separators should be generated by the processing system and not included in the source file.
Example:
<ol><no>a</no><li><l.para>List item.</l.para></li></ol> is correct, but <ol><no>a)</no><li><l.para>List item.</l.para></li></ol> is incorrect.
b) Unordered or dashed list (<ul>). This is a list in which the list items (<li>) are not ordered. The type of stub (em dash, bullet, etc.) that appears before each <li> element is determined by the "stub" attribute of the <ul> element.
Example:
<ul stub="mdash"><li><l.para>List item 1.</l.para></li></ul>
c) Descriptive list (<dl>). This is a list of descriptive list items (<dli>). The <dli> element is comprised of a descriptive term (<dt>) followed by the term's description (<dd>). The descriptive list (<dl>) is used most commonly for variable lists that occur after an equation. In a variable list, the variable itself would be the <dt> element, and the description of the variable would be the <dd> element.
Example:
<dl><dli><dt>V</dt><dd><l.para>is the voltage</l.para></dd></dli></dl>
List items (<li>,<dli>) can contain any number of list paragraphs, floats, lists, notes, computer code listings, and/or equations.
List paragraphs (<l.para>) have the same structure as paragraphs (<para>, see 3.1.1.2.1) except that list paragraphs (<l.para>) cannot contain lists.
A note (<note>) is an informative annotation to text that is comprised of one or more note paragraphs (<nt.para>). The <nt.para> has the same structure as a <para> (see 3.1.1.2.1) except that it cannot contain another note (i.e., notes are not recursive).
If two or more notes (<note>) occur consecutively, they should be contained within a note group (<note.gr>), and each <note> element should be preceded by a number (<no>).
Example:
<note.gr>
<no>1</no><note><nt.para>First note in group.</nt.para></note>
<no>2</no><note><nt.para>Second note in group.</nt.para></note>
</note.gr>
A computer code listing(<code>) is a source code listing in a given computer language. To allow for formatting, each line of code (<line>) should be tagged separately. This allows the processing system to apply a fixed-spaced font to the listing and maintain its physical appearance. To reuse the code, the <line> and </line> tags can be stripped out, and the "language" attribute can be used to inform the system which compiler to use.
At this time, equations (<eqn>) can be dealt with either as <para> text (using emphasis [<emph>] and special character entities) or as an external graphical entity (see 4.3). In order to harmonize with the international standards community, the IEEE Standards Department has adopted, in principle, the use of the ISO 12083 DTD math fragment for equations and formulae. At the present time, however, there is no software support for ISO 12083. When software becomes available, SPAsystem will switch over to a tagged math implementation. In the interim, the IEEE Standards Department will accept equations in any of the accepted graphics format; see 4.3.2.
The references clause (<ref.cls>) is a special type of clause that contains a references list. A references clause (<ref.cls>) always begins with a number (<no>) followed by a clause title (<cls.tit>). This can be followed by one or more optional introductory paragraphs (<para>, see 3.1.1.2.1), followed by the references list (<ref.l>).
The references list (<ref.l>) is a list of one or more references (<ref>).
References (<ref>) are pointers to consensus documents that contain information that constitutes a normative part of an IEEE standards document. A reference is comprised of the standard designation (<stddes>) and the standard title (<stdtit>).
The standard designation (<stddes>) is the alphanumeric designation assigned to a consensus document by the developing organization. The <stddes> element can contain words and inline elements; see 3.1.1.2.1.
The standard title (<stdtit>) is the full title of the consensus document as listed by the developing organization. The <stdtit> element can contain words and inline elements; see 3.1.1.2.1.
Example:
<ref><stddes>IEEE Std 100-1992</stddes><stdtit>The New IEEE Standard Dictionary of Electrical and Electronics Terms (ANSI).</stdtit></ref>
The definitions clause (<def.cls>) is a special type of clause that contains a definitions list (<def.l>) and/or an abbreviations and acronyms list (<acr.l>). If further granularity is needed, a definitions clause (<def.cls>) can be subdivided into one or more second-level definitions subclauses (<def2.cls>). A definitions clause (<def.cls>) always begins with a number (<no>) followed by a clause title (<cls.tit>). This can be followed by one or more optional introductory paragraphs (<para>, see 3.1.1.2.1), followed by either a definitions/abbreviations and acronyms list (<def.l>,<acr.l>) or one or more second-level definitions subclauses (<def2.cls>). If the definitions clause (<def.cls>) does contain a definitions or acronyms list (<def.l>,<acr.l>), one or more second-level definitions subclauses (<def2.cls>) may follow the list.
The second-level definitions clause (<def2.cls>) can be subdivided into one or more third-level definitions subclauses (<def3.cls>). A second-level definitions subclause (<def2.cls>) always begins with a number (<no>) followed by a clause title (<cls.tit>). This can be followed by one or more optional introductory paragraphs (<para>, see 3.1.1.2.1), followed by either a definitions/abbreviations and acronyms list (<def.l>,<acr.l>) or one or more third-level definitions subclauses (<def3.cls>). If the second-level definitions subclause (<def2.cls>) does contain a definitions or abbreviations and acronyms list (<def.l>,<acr.l>), one or more third-level definitions subclauses (<def3.cls>) may follow the list.
The third-level definitions clause (<def3.cls>) can be subdivided into one or more fourth-level definitions subclauses (<def4.cls>). A third-level definitions subclause (<def3.cls>) always begins with a number (<no>) followed by a clause title (<cls.tit>). This can be followed by one or more optional introductory paragraphs (<para>, see 3.1.1.2.1), followed by either a definitions/abbreviations and acronyms list (<def.l>,<acr.l>) or one or more fourth-level definitions subclauses (<def4.cls>). If the third-level definitions subclause (<def3.cls>) does contain a definitions or abbreviations and acronyms list (<def.l>,<acr.l>), one or more fourth-level definitions subclauses (<def4.cls>) may follow the list.
The fourth-level definitions clause (<def4.cls>) can be subdivided into one or more fifth-level definitions subclauses (<def5.cls>). A fourth-level definitions subclause (<def4.cls>) always begins with a number (<no>) followed by a clause title (<cls.tit>). This can be followed by one or more optional introductory paragraphs (<para>, see 3.1.1.2.1), followed by either a definitions/abbreviations and acronyms list (<def.l>,<acr.l>) or one or more fifth-level definitions subclauses (<def5.cls>). If the fourth-level definitions subclause (<def4.cls>) does contain a definitions or abbreviations and acronyms list (<def.l>,<acr.l>), one or more fifth-level definitions subclauses (<def5.cls>) may follow the list.
The fifth-level definitions subclause (<def5.cls>) is the lowest-level definitions subclause in an IEEE standard and cannot be subdivided. A fifth-level definitions subclause (<def5.cls>) always begins with a number (<no>) followed by a clause title (<cls.tit>). This can be followed by one or more optional introductory paragraphs (<para>, see 3.1.1.2.1), followed by either a definitions list (<def.l>) or an abbreviations and acronyms list (<acr.l>).
The definitions list (<def.l>) is a list of terms that are uniquely defined within the document. The definitions list contains one or more definitions (<def>).
The definition (<def>) is the explication of a term that is uniquely defined within the document. The definitions always begins with a number (<no>) followed by a definition term (<def.t>) followed by a definition description (<def.d>).
The definition term (<def.t>) is the actual word or phrase that is being defined within the document. It can contain words and inline elements (see 3.1.1.2.1).
The definition description (<def.d>) is a phrase that describes the definition term (<def.t>). It always contains at least one paragraph, which can be followed by text (see 3.1.1.2).
Example:
<def><def.t>definition</def.t><def.d><para>A term that is uniquely defined within the document.</para></def.d></def>
The abbreviations and acronyms list (<acr.l>) is a list of abbreviations and/or acronyms that are used within the document. The abbreviations and acronyms list (<acr.l>) contains one or more acronyms (<acronym>).
The acronym (<acronym>) is the explanation of an acronym or abbreviation that appears within the document. The acronym (<acronym>) contains an acronym term (<acr.t>) followed by an acronym description (<acr.d>).
The acronym term (<acr.t>) is the actual acronym or abbreviation as it appears within the document. It can contain words and inline elements (see 3.1.1.2.1).
The acronym description (<acr.d>) is the expansion of the acronym term (<acr.t>). It can contain words and inline elements (see 3.1.1.2.1).
Example:
<acronym><acr.t>SGML</acr.t><acr.d>Standard Generalized Markup Language</acr.d></acronym>
The bibliography clause (<bib.cls>) is a special type of clause that contains a bibliography list (<bib.l>). A bibliography clause (<bib.cls>) always begins with a number (<no>) followed by a clause title (<cls.tit>). This can be followed by one or more optional introductory paragraphs (<para>, see 3.1.1.2.1), followed by either a bibliography list (<bib.l>) or one or more second-level bibliography subclauses (<bib2.cls>). If the bibliography clause (<bib.cls>) does contain a bibliography list (<bib.l>), one or more second-level bibliography subclauses (<bib2.cls>) may follow the list.
The second-level bibliography clause (<bib2.cls>) can be subdivided into one or more third-level bibliography subclauses (<bib3.cls>). A second-level bibliography subclause (<bib2.cls>) always begins with a number (<no>) followed by a clause title (<cls.tit>). This can be followed by one or more optional introductory paragraphs (<para>, see 3.1.1.2.1), followed by either a bibliography list (<bib.l>) or one or more third-level bibliography subclauses (<bib3.cls>). If the second-level bibliography subclause (<bib2.cls>) does contain a bibliography list (<bib.l>), one or more third-level bibliography subclauses (<bib3.cls>) may follow the list.
The third-level bibliography clause (<bib3.cls>) can be subdivided into one or more fourth-level bibliography subclauses (<bib4.cls>). A third-level bibliography subclause (<bib3.cls>) always begins with a number (<no>) followed by a clause title (<cls.tit>). This can be followed by one or more optional introductory paragraphs (<para>, see 3.1.1.2.1), followed by either a bibliography list (<bib.l>) or one or more fourth-level bibliography subclauses (<bib4.cls>). If the third-level bibliography subclause (<bib3.cls>) does contain a bibliography list (<bib.l>), one or more fourth-level bibliography subclauses (<bib4.cls>) may follow the list.
The fourth-level bibliography clause (<bib4.cls>) can be subdivided into one or more fifth-level bibliography subclauses (<bib5.cls>). A fourth-level bibliography subclause (<bib4.cls>) always begins with a number (<no>) followed by a clause title (<cls.tit>). This can be followed by one or more optional introductory paragraphs (<para>, see 3.1.1.2.1), followed by either a bibliography list (<bib.l>) or one or more fifth-level bibliography subclauses (<bib5.cls>). If the fourth-level bibliography subclause (<bib4.cls>) does contain a bibliography list (<bib.l>), one or more fifth-level bibliography subclauses (<bib5.cls>) may follow the list.
The fifth-level bibliography subclause (<bib5.cls>) is the lowest-level bibliography subclause in an IEEE standard and cannot be subdivided. A fifth-level bibliography subclause (<bib5.cls>) always begins with a number (<no>) followed by a clause title (<cls.tit>). This can be followed by one or more optional introductory paragraphs (<para>, see 3.1.1.2.1), followed by a bibliography list (<bib.l>).
The bibliography list (<bib.l>) is a list of bibliographic entries. The bibliography list (<bib.l>) can contain any number of general bibliographic entries (<gen.bib>) or standard bibliographic entries (<std.bib>).
The general bibliographic entry (<gen.bib>) is a bibliographic reference to a non-consensus document (e.g., book, journal, technical paper, proceeding, etc.). The general bibliographic entry (<gen.bib>) always begins with a number (<no>) preceded by the letter "B." This is followed by words and stylistic emphasis (<emph>, see 3.1.1.2.1), followed by an optional annotation (<annotat>), followed by an optional footnote (<ftn>, see 3.1.1.2.1).
The annotation (<annotat>) is used to annotate bibliographic references, where necessary. The annotation (<annotat>) can contain words and inline elements (see 3.1.1.2.1).
Example:
<gen.bib>
<no>B1</no>Smith, J. "A sample article," <emph type=ital>Any Magazine</emph>, pp. 1–3, Jan. 1988.<annotat><emph type=ital>Any Magazine</emph> is no longer available. However, reprints of this article are available from the U.S. Government Printing Office.</annotat>
</gen.bib>
The standard bibliographic entry (<std.bib>) is a bibliographic reference to a consensus (standards) document. The standard bibliographic entry (<std.bib>) always begins with a number (<no>) preceded by the letter "B." This is followed by the standard designation (<stddes>, see 3.1.2.1.1) and standard title (<stdtit>, see 3.1.2.1.1), followed by an optional annotation (<annotat>, see 3.1.4.2.1), followed by an optional footnote (<ftn>, see 3.1.1.2.1).
Example:
<std.bib>
<no>B1</no><stddes>IEEE Std 100-1992</stddes><stdtit>The New IEEE Standard Dictionary of Electrical and Electronics Terms</stdtit><annotat>This standard is currently under revision. When completed, the latest version of this standard should apply.</annotat>
</std.bib>
The annex (<annex>) is an appendix to the document. The annex begins with a letter (<no>), such as "A," "B," "C," etc., followed by an annex title (<annx.tit>). This can be followed by either text or one or more clauses (<bdy.cls>), bibliography clauses (<bib.cls>), or bibliography lists (<bib.l>). If the annex contains text, then one or more clauses (<bdy.cls>), bibliography clauses (<bib.cls>), or bibliography lists (<bib.l>) may follow the text.
In other words, an annex can have several possible structures: an annex can contain only text; an annex can contain multiple clauses; an annex can contain a bibliography clause; or an annex can contain a bibliography list, making the annex itself a bibliography to the document.
The "norm" attribute of the <annex> element is used to indicate whether the <annex> is normative or informative. The default value for the <annex> element is informative; see 4.2.6.
NOTE--If a document contains only one annex (<annex>), it is unnecessary to put a letter (<no>) before the annex title (<annx.tit>).
The IEEE standard (<ieeestd>) is a full instance of an IEEE standards document. It contains all the structures defined in the five DTD modules (see 3.1.1-3.1.5). In addition to the clause (<bdy.cls>), references clause (<ref.cls>), definitions clause (<def.cls>), bibliography clause (<bib.cls>), and annex (<annex>) elements, an IEEE standard also contains a front matter (<frntmttr>) element.
The front matter (<frntmttr>) contains bibliographic and administrative information regarding the document. The front matter (<frntmttr>) can contain an optional title page (<titlepg>), followed by an optional foreword (<foreword>), followed by a required introduction (<intro>).
The title page contains information that identifies the document instance. The title page is not necessary for document submittal; however, it is important for draft circulation and review. The title page contains the standard designation (<stddes>, see 3.1.2.1.1), followed by the standard title (<stdtit>, see 3.1.2.1.1), followed by the sponsor (<sponsor>), followed by an optional abstract (<abstract>).
The sponsor (<sponsor>) is the name of the working group sponsor. It contains the committee name (<comm>) followed by the society name (<society>). The committee name (<comm>) and the society name (<society>) are both comprised of words.
The abstract (<abstract>) is a summary of the content of the standard. It contains words and inline elements (see 3.1.1.2.1).
The foreword (<foreword>) contains information about the previous revisions of the document. The foreword contains text (see 3.1.1.2).
The introduction (<intro>) contains information about the development and history of the standard. The introduction can contain one or more clause titles (<cls.tit>), working groups lists (<wg.l>), and text (see 3.1.1.2).
The working group list (<wg.l>)is a list of the members of the working group that developed the document. The working group list is comprised of one or more members (<member>).
The member (<member>) is the name of an individual working group member. The member (<member>) contains a given name (<givname>), followed by a surname (<surname>), followed by an optional footnote (<ftn>, see 3.1.1.2.1). The given name (<givname>) and surname (<surname>) are both comprised of words.
The SPAsystem SGML declaration is compatible with the CALS SGML declaration. If your parser defaults to the CALS syntax, it is not necessary to use the SPAsystem SGML declaration.
The SPAsystem authoring DTD suite uses three public character sets:
a) ISO 8879-1986//ENTITIES General Technical//EN
b) ISO 8879-1986//ENTITIES Greek Symbols//EN
c) ISO 8879-1986//ENTITIES Added Latin 1//EN
A third set, ISO 8879-1986//ENTITIES Diacritical Marks//EN, is commented out, but can be invoked by removing the comments.
In addition to these public sets, the SPAsystem has its own special character entity set called "ieeestd.ent." This set is provided to give authors easy access the special characters found most commonly in IEEE standards.
Consult the documentation for your SGML text editor for instructions on how to include system-defined character entity sets. If you do not wish to use this set, it may be commented out of the DTD.
Next Section