Metanorma: Aequitate Verum

Typical sections in IEEE

General

The easiest way to ensure that you are following the document structure that IEEE demands, is to use a Metanorma template.

If you author a document type that doesn’t have a template, check a sample document for better understanding how to structure that document.

Typically, an IEEE SA document contains the following content order:

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:

wg participants

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:

wg entity 1

(continued)

wg entity 2

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
//...
balloting individual

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.
//...
balloting entity

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*
sa standards board
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.

Terms and definitions

The terms and definitions is used to define important terms and cite them throughout the standard.

References

The references section contains normative references, it is considered a “bibliography” section.

Note
In IEEE there are two “bibliography” sections. The “References” section for normative references, and the “Bibliography” section which is for informative references.

Content sections

After the sections above, any number of content sections can be added.

Annex sections

General

Annex sections are declared by prepending the [appendix] tag above the section declaration. Annexes can be added as necessary.

An annex can either be normative or informative. By default an annex is marked informative.

In order to declare a normative annex, use the obligation attribute in the following manner: [appendix,obligation=normative]

Example 11. Example of creating a normative versus an information annex
// Without declaration, an annex is informative.
[appendix]
== Informative annex title
...

// A normative annex.
[appendix,obligation=normative]
== Normative annex title
...

// A informative annex with explicit declaration
[appendix,obligation=informative]
== Informative annex title
...

Annex clauses are placed after all content sections, right before the bibliography section.

Glossary

IEEE SA documents support an extra definitions section that represents informative terms, as a "Glossary" section in the annex.

It can be encoded as follows:

Example 12. Example of creating the Glossary section
[appendix]
== Glossary

=== My term

My definition
...

The usage and syntax of this section is identical to that of Terms and definitions. Please refer to the terms and definitions syntax on how to write out the terms in the Glossary.