Metanorma for IEEE SA markup

Clause structure

The following clause structure is mandated by the IEEE SA Style Manual.

Preface segments
- Abstract and Keywords right after the inner cover page
- Important Notices and Disclaimers Concerning IEEE Standards Documents
- Participants
- Introduction
- Acknowledgements (optional)
1. Overview
- 1.1. Scope
- 1.2. Purpose (optional)
- 1.x. Word usage (last subclause of Overview)
2. Normative references
3. Definitions
4 and onwards. Document content.
Annex A (informative). Bibliography.
Annex B onwards. Document content.

Preface segments

Abstract

The abstract of the document is marked up as a clause with the style attribute [abstract].

Example 1. Example of Abstract encoding (IEEE Std 1636.1™-2007)

[abstract]
== Abstract

This standard is intended to promote and facilitate interoperability
between components of an automatic test system (e.g., between test
executive and diagnostic reasoner) where test results need to be shared.

Keywords

The keywords of the document are given as the comma-delimited :keywords: document attribute (see Document attributes).

Introduction

The introduction of the document is marked up as a clause with the title "Introduction". The initial boxed text, "This introduction is not part of P{designation}/D{draft_number}, Draft {document-type} for {par-title}" is automatically generated and populated by Metanorma. Do not provide it.

Acknowledgements

If the document refers to any externally sourced content that require permission or licensing acknowledgements, they are entered as a section with the title "Acknowledgements".

The "Acknowledgements" section shall appear immediately after the "Introduction", in accordance with the IEEE SA Style Manual (2021).

Note	The placement of the "Acknowledgements" section differs in legacy documents, some IEEE SA standards places it immediately before the "Introduction".

Example 2. Example of Acknowledgements (IEEE Std 1127™-2013)

== Acknowledgements

<<table2>> of this standard is printed with permission from BBN Corporation.

Automatic generated content

The templated material ("boilerplate") of the document front matter is all automatically provided by Metanorma:

Front page: Copyright statement, license statement
Second page: Contact information, ISBNs
Important Notices and Disclaimers Concerning IEEE Standards Documents
Participants statement (the membership of the various committees is provided in a Participants clause)
The note before the overview in amendments, indicating how formatting is to be interpreted

Participants and contributors

General

There are multiple types of contributors to an IEEE SA document, and the document displays full provenance of where the document was developed, balloted and eventually approved.

Note	Requirements of the “Participants” section is described in the IEEE Style Manual, 11.5 "Participant lists".

Other than the basic information entered through the document attributes on document contributors, the participants and members are entered in the “Participants” section.

An IEEE SA document requires listing of all members of the:

working group;
balloting group, whether the group is of entity mode or individual mode;
Standards Board (SASB), at the time of publishing the document;
any additional groups or individuals involved in the development process.

The Participants section is provided by the official IEEE template. Additional contributing groups and participants, if any, are permitted additions to the basic text.

In Metanorma, the participants section is entered as a top level section. The section contains paragraphs in the order specified in the above list.

The initial sentence before each of the Working Group, Balloting Group, and Standards Board listings is automatically supplied by Metanorma, following the defined pattern provided by the 2021 IEEE Style Manual.

The following members of the <individual/entity> balloting committee voted on this <guide/recommended practice/standard>. Balloters may have voted for approval, disapproval, or abstention.

where, the Metanorma-generated sentence describes the correct document type and the type of balloting group.

The remainder of the content is provided in three subclauses of the == Participants clause supplied by the author:

=== Working group
=== Balloting group, and
=== Standards board:

Entering participants in an IEEE document

== Participants
=== Working group
...
=== Balloting group
...
=== Standards board
...

Note	The first `== Participants` clause found in a document will be processed for boilerplate content, and removed from the document by Metanorma.

Note	If you have an actual clause titled `== Participants` which needs to be left alone, insert `[heading=clause]` before it to prevent it being recognised as a metadata Participants clause.

Representing participants

Participants can be entered in the following manners:

in an unordered list, where each list item is a personal name
Example 3. Example of representing individual participants in an unordered list
* Nikola Tesla * Thomas Edison * Henry Ford
in a definition list, with the key item pointing to a name, as a personal name
Example 4. Example of representing individual participants in a definition list
item:: Claude Elwood Shannon item:: Charles-Augustin de Coulomb
in a two-level definition list, where the key item empty, with sub-definitions containing key-value encoded attributes of the participant:
- name for persons
- company for entities
- role to describe the role of the participant. When no role is provided, it is assumed to be "Member".
Example 5. Example of representing individual participants with roles and companies
item:: name::: Arthur C. Clark role::: Chair item:: name::: Alessandro Volta role::: Vice-Chair item:: company::: Apple Inc. item:: Claude Elwood Shannon item:: Charles-Augustin de Coulomb

Participant lists should be given in the order they will be rendered in:

officers before members;
organisation members before individual members.

Documents often insert additional lists of participants and acknowledgements. Any list or definition list in the user-supplied Participants clause is treated and processed the same way.

The Word and PDF rendering of the participants listings automatically works out the differential rendering of member organisations and individual members in two or three columns.

Working group

Working group participants are entered using the method in Representing participants.

For an individual mode working group, participants are entered using personal names.

Example 6. Working group individual participants (IEEE Std 1800.2™-2020)

// Officers
item::
name::: Justin Refice
role::: Chair
item::
name::: Mark Strickland
role::: Vice Chair
item::
name::: Jamsheed Agahi
role::: Secretary
item::
name::: Joel Feldman
role::: Technical Editor
// Individual participants
name::: Mala Bandyopahdyay
name::: Martin Barnasconi
name::: Dennis Brophy
name::: Cliff Cummings
//...

Rendered as:

For an entity mode working group, there are two types of participants: entity representatives, and individuals.

Entity representative participants should be entered using both name with company, and individual participants just with name. Officers are to be entered with name, role and company.

Example 7. Working group entity participants (IEEE Std 2830™-2021)

// Officers
item::
name::: Jin Peng
role::: Chair
item::
name::: Cheng Hong
role::: Vice Chair
company::: Alibaba China Co. Ltd.
// Entity representative participants
item::
name::: Lei Wang
company::: Alipay (China) Technology Co., Ltd.
item::
name::: Guantong Su
company::: Arpacorp Limited
item::
name::: Xiaoru Li
company::: Beijng Baidu Netcom Science Technology Co., Ltd.
item::
name::: Bingzhe Wu
company::: Beijing University
// ...
// Individual participants
name::: Xiaoyuan Bai
name::: Yang Bian
name::: Wenting Chang
// ...

Rendered as:

(continued)

Balloting group

Balloting group participants are entered using the method in Representing participants.

There are two types of balloting groups.

In an individual working group, personal names are entered using the name key.

Example 8. Balloting group (individual mode) (IEEE Std 1680.1a™-2020)

The following two encodings are identical in effect.

* Robert Aiello
* Lennart Ask
* William Byrd
* Sandra Cannon
* Chris Cleet
* Jennifer Costley
//...

item:: Robert Aiello
item:: Lennart Ask
item:: William Byrd
item:: Sandra Cannon
item:: Chris Cleet
item:: Jennifer Costley
//...

In an entity working group, organization names are to be entered using the company key.

Example 9. Balloting group (entity mode) (IEEE Std 1800.2™-2020)

=== Balloting group

item::
company::: Accellera Systems Initiative, Inc.
item::
company::: Analog Devices Inc.
item::
company::: Cadence Design Systems, Inc.
item::
company::: Ericsson AB
item::
company::: Intel Corporation
item::
company::: Marvell Semiconductor, Inc.
//...

Standards board

Standards board members are entered using the method in Representing participants.

The IEEE SA Standards Board members are to be entered using name and with role when appropriate. Member Emeritus is entered with attaching an asterisk (*) at the end of the name.

The paragraph explaining the asterisk indicates Member Emeritus is inserted automatically by Metanorma.

Example 10. IEEE SA Standards Board (IEEE Std 2830™-2021)

// Officers
item::
name::: Gary Hoffman
role::: Chair
item::
name::: Jon Walter Rosdahl
role::: Vice Chair
item::
name::: John D. Kulick
role::: Past Chair
item::
name::: Konstantinos Karachalios
role::: Secretary
// Board members
item:: Ted Burse
item:: Doug Edwards
item:: J. Travis Griffith
item:: Grace Gu
item:: Guido R. Hiertz
item:: Joseph L. Koepfinger*

Note	The standards board membership is provided by the working group secretary or the IEEE editor during editing. If the information is not provided in the document, dummy values will be provided to match those in the IEEE templates.

Name markup

The forenames and surnames of participants should be marked up semantically as such, for correct generation of Word styles. This is done with the markup span:surname[], span:forename[], and [added in https://github.com/metanorma/metanorma-ieee/releases/tag/v1.2.1]. There is no need to mark up the role of participants or their status as companies, as this is already semantically differentiated in markup.

item::
name::: span:forename[Justin] span:surname[Refice]
role::: Chair
item::
name::: span:forename[Mark] span:surname[Strickland]
role::: Vice Chair

Overview

The Overview clause, and its subclauses are recognized automatically from the supplied clause headers.

The subclauses recognized include:

Scope
Purpose
Word usage

The Word Usage subclause is mandatory for normal documents (as distinct from amendments and corrigenda), and is auto-populated by Metanorma. There is no need to encode it.

References

The introductory paragraph for normative references and bibliographies is automatically generated by Metanorma.

References are automatically sorted by Metanorma:

Normative references are automatically sorted by designator.
Bibliography references are automatically sorted by designators or author and title.

Footnotes are automatically inserted for withdrawn IEEE references, and for references from Standards Defining Organizations recognised in Relaton [added in https://github.com/metanorma/metanorma-ieee/releases/tag/v1.1.11].

The bibliography is entered as a subclause of an annex: the bibliography heading is overwritten by the annex heading, but it must still be given as "Bibliography" to be recognised correctly.

[appendix]
== Bibliographic excursus

[bibliography]
=== Bibliography

Definitions clause

General

Definitions are recognised as a clause with the title "Definitions" or "Terms and definitions".

Definitions are automatically sorted by Metanorma in accordance with the IEEE SA Style Manual.

The notation for subdefinitions and cross-references in Metanorma is demonstrated in the following example.

Metanorma supports concepts, which capture terms are cross-referencable entities, including cross-references within the Definitions sections.

Note	Highlighting and cross-referencing of concepts is not supported in Metanorma for IEEE, in accordance with the IEEE SA Style Manual.

Example 11. Example with abbreviated term, multiple definitions and concept relations

=== widget
preferred:[WgT]
related:contrast[thing] // Contrast:
related:seealso[whatsit] // See also:

[.definition]
device performing an unspecified function.

[.definition]
general metasyntactic variable.

renders as:

widget (WgT): (A) device performing an unspecified function. (B) general metasyntactic variable. See also: whatsit. Contrast: thing.

Multiple definitions

IEEE SA documents supports multiple definitions per term.

Each definition is encoded using the [.definition] block.

Example 12. Example with multiple definitions (IEEE SA Style Manual 2021)

=== output

[.definition]
Data that has been processed.

[.definition]
The process of transferring data from an internal storage device to an external
storage device.

renders as:

output: (A) Data that has been processed. (B) The process of transferring data from an internal storage device to an external storage device.

Concept relations

Synonyms

Synonyms are entered using preferred:[…] or admitted:[…].

A preferred term is intended to introduce equally valid term designations, such as abbreviations and acronyms such as acronyms. Preferred terms are encoded preferred[...]. These are displayed in parentheses after the initial term.

An admitted term is intended for synonyms. Admitted terms are encoded using admitted:[...]. These are displayed using the concept relation See:, where an additional term is automatically inserted into the clause.

Note	See: terms are the opposite relations to Syn: relations, and the generated relation will point the See: term’s definition back at the original term. Please do not manually insert markup for See: terms.

Example 13. Example of definition with See: (IEEE SA Style Manual 2021)

=== coded character set
admitted:[code set]

A set of characters for which coded representation exist.

renders as:

code set: See: coded character set.

coded character set: A set of characters for which coded representation exist. Syn: code set.

Example 14. Example of definition showing preferred abbreviation and admitted term as See:

=== widget
preferred:[WgT]
admitted:[doovywhack]

device performing an unspecified function.

renders as:

doovywhack: See: widget.

widget (WgT): device performing an unspecified function. Syn: doovywhack.

Contrast

A contrasting term is one that describes an opposite meaning to the designated definition.

Example 15. Term encoded with Contrast: (IEEE SA Style Manual 2021)

=== input reference axis
related:contrast[output reference axis]

The direction of an axis as defined by the case mounting surfaces, external case
markings, or both.

renders as:

input reference axis: The direction of an axis as defined by the case mounting surfaces, external case markings, or both. Contrast: output reference axis.

Equivalence

An equivalent term is meant to cross-reference pre-existing term definitions.

Equivalent terms are encoded using the relation related:equivalent[…].

Term sources

Term sources are encoded using the [.source] syntax, and rendered within parentheses after the definition according to the IEEE SA Style Manual.

Example 17. Example on encoding term source (IEEE SA Style Manual 2021)

=== systematic drift rate

That component of drift rate that is correlated with specific operating
conditions.

[.source]
<<IEEE-260-1-2004>>

renders as:

systematic drift rate: That component of drift rate that is correlated with specific operating conditions. (IEEE Std 260.1-2004)

For terms that are modified or adapted from the source, they are encoded as "adapted from" through an adapted option on the source tag.

Example 18. Example on encoding an adapted term source (IEEE Style Manual 2021)

=== drift rate

The slope at a stated time of the smoothed curve of tube voltage drop with time
at constant operating conditions.

[.source%adapted]
<<iso-iec_9945-1>>

rendered as

drift rate: The slope at a stated time of the smoothed curve of tube voltage drop with time at constant operating conditions. (Adapted from ISO/IEC 9945-1:2003)

Annexes

Normative and informative annexes are differentiated with the obligation attribute:

[appendix,obligation=normative]
== Rules for implementation

[appendix,obligation=informative]
== Suggestions for implementation

Bibliographies are encoded as the children of informative annexes; Metanorma will take care of rendering the annex title properly, without a redundant subclause.

[appendix,obligation=informative]
== Bibliography

[bibliography]
=== Bibliography

Blocks

Notes

The footnote on first appearance of a note,

Notes to text, tables, and figures are for information only and do not contain requirements needed to implement the standard.

is automatically generated by Metanorma.

Tables

Table heads and table subheads are marked up as header cells. They are differentiated by line break:

|===
| Header1 | Header2

h| Table Row Head +
Table Row Subhead | Value

Inline

Cross-references

Omission of "clause" at the start of a sentence for cross-references to subclauses is done automatically by Metanorma. If Metanorma’s detection of the start of a sentence is incorrect, you can override Metanorma’s auto-generated text, by providing it explicitly within the cross-reference, e.g. Clause 3.1.

References to the bibliography are automatically populated by designator and bibliographic number (e.g. ISO 639-2, [B1]), if the reference is to a standard or technical report, or otherwise by title and bibliographic number. If you wish to override that, e.g. by using authors instead of title, you should populate the cross-reference text, e.g. Boswell and Johnson [B2].

Footnotes

If a footnote is repeated, Metanorma automatically detects that and converts it into a cross-reference ("See Footnote 1.")

A repeat footnote can be marked up using the footnote macro target (abc in the following example; any identifier can be used), and with the repeat footnote text left blank.

Hello.footnote:abc[This is a footnote]

Repetition.footnote:abc[]

Validation

Metanorma issues warnings for the document against the following rules from the Style Manual:

The title of the document starts as "(Draft) (Trial-Use) (Standards|Recommended Practice|Guide)" (11.3). This is done automatically by Metanorma if all the relevant document attributes are populated.
The title contains no uncapitalised words other than prepositions (11.3).
No cross-reference ranges are used: "See Figure 1, Figure 2 and Figure 3", not "See Figures 1 through 3" (17.2). This is only checked against autonumbered cross-references.
Undated references should not contain identify specific elements of the referenced text (12.3.2).
Normative references should be dated (12.3.1).
There should be no more than one ordered list within a numbered clause (13.3).
The names of supplied images in figures and tables must follow the prescribed naming conventions (17.1).
Figure headings should be capitalised (17.2).
The document must contain an Overview clause, a Scope clause, a Word Usage clause (12.2).
The Overview clause must occur first, and contain the Scope clause and the Word Usage clause (12.2).
There should be no more than five levels of subclauses (13.1).
No subclause should be the only child of its parent (13.1).
Decimal comma should not be used (14.2).
Decimals must have a leading zero if less than 1 (14.2).
There must be space before the percent sign (14.2).
There must be space between numerals and recognised SI units (14.2).
Units must be given on both value and tolerance for an SI unit (14.2).
Numbers occurring in tables should be broken up in threes, unless they are four-digit sequences and all other digits are at most three digits (16.3.2).
Table headings and header cells should be capitalised (16.2).
The document should contain Normative Refences and Definitions (12.2).
The bibliography should be either the first or the last annex of the document (19.1).
Amendment/corrigenda changes should start with one of Change, Insert, Delete, Replace, reflecting the kind of change involved (20.2.2). [added in https://github.com/metanorma/metanorma-ieee/releases/tag/v0.1.0]
Unordered lists should be no more than two levels deep.
Ordered lists should be no more than five levels deep.