Metanorma: Aequitate Verum

Metanorma for IEEE SA

Document header and metadata

General

The header contains information about the document (metadata). You specify these metadata by using predefined document attributes, that look like this:

:document-attribute: some-value

Most of the attributes take a value, while others are simple flags without a value, like:

:draft:

Some of the metadata will be visible in your document, such as :title:, while others are not visible but still affect how your document is generated.

Note
 The order of attributes does not matter in Metanorma.

Specifying IEEE metadata

In an IEEE SA document, you can specify metadata about:

  • Contributors: working group participants, ballot group members, standardization board members

  • Document info: document type, document stages (draft, published, etc.).

  • Dates: draft dates, revision dates, publishing date, copyright year, etc.

  • Identifiers: document numbers, ISBNs, STD numbers

Note
 Other metadata influence how the document is generated and should only be used by advanced users. Please refer to the IEEE SA document attributes.

At a minimum, you will need to specify:

  • Title

  • Metanorma document class as ieee

  • Document number

  • Document type, and optionally subtype

  • Document stage

  • Committee

  • Author or editor

Note
 Please refer to reference documentation to see the full list of IEEE SA-specific document attributes.
Note
 In this section we use the document header from the IEEE Style Manual document example to explain.

Document-specific attributes and basic operations

These are the basic document attributes for IEEE SA.

Example 1. Setting basic document attributes for IEEE SA
= Recommended Practice for Preparing an IEEE Standards Draft (1)
:docnumber: 987.6 (2)
:docstage: draft (3)
:draft: 3 (4)

  1. IEEE SA document title.

  2. IEEE SA document number. If draft, omit the "P" prefix as it will be automatically added.

  3. IEEE SA document stage.

  4. If :docstage: is draft, enter the draft number in :draft:.

These are operational concerns that are useful for the author.

  • :mn-document-class: must be set in order to set the flavor to IEEE SA.

  • :mn-output-extensions: determines what output to be produced.

Example 2. Setting IEEE SA-specific attributes
:mn-document-class: ieee (1)
:mn-output-extensions: xml,html,doc,pdf,rxl (2)
:local-cache-only: (3)

  1. Metanorma flavor. For IEEE SA, enter ieee.

  2. Metanorma output formats. For IEEE SA, supported formats are xml, html, pdf, doc and rxl.

  3. Metanorma option to store data cache in the current directory.

Document types and subtypes

IEEE SA offers three types of documents that differ in the level of the obligation of requirements.

The type is to be set via these two attributes:

:doctype:

for the document type

:docsubtype:

for the document subtype, necessary for certain :doctypes:

Document types, set using the :doctype: attribute, include:

standard

This document is a Standard (default). This document provides mandatory requirements.

recommended-practice

This document is a Recommended Practice. This document only provides recommendations, not requirements.

guide

This document is a Guide. This document only provide guidelines, not requirements.

For each of these types, modification documents can be issued by using :docsubtype: with the following values:

document

This document is the standardization deliverable itself. (default)

amendment

This document details amendments made to the base document.

corrigendum

This document details technical error corrections made to the base document.

errata

This document details publication error corrections made to the base document.

Example 3. Setting document type
:doctype: standard (1)

  1. IEEE SA document type.

Example 4. Setting document type with subtype for an Amendment
:doctype: standard
:docsubtype: amendment (1)

  1. IEEE SA document subtype.

Document stages and progress dates

IEEE SA deliverables go through various stages of approval.

The document stage is set via the :docstage: attribute.

Typically, a document goes through these processes:

  1. Started off as a draft. where :docstage: draft is set, and draft number set to 1 :draft: 1. The :copyright-year: should always be set to the current year.

  2. Draft number increases, e.g. :draft: 2, as the working group progresses.

  3. The draft gets balloted by the working group when ready.

  4. Once the balloting group approves the document, it will be represented to the SA standardization board for approval.

  5. After approval, the date of approval should be entered as metadata using :issued-date:.

  6. Once the document is ready to be published, set :docstage: published and remove the :draft: attribute.

Note
 IEEE SA documents can also be marked inactive by :docstage: inactive.
Example 5. Setting document stage and progress dates
:docstage: draft (1)
:draft: 3 (2)
:copyright-year: 2021 (3)
:issued-date: 2021-01-01 (4)

  1. Document stage.

  2. Document draft number.

  3. Copyright year of document.

  4. Date of approval by the standards board.

Authorship and other preface information

In IEEE SA documents there are several types of contributor information to be entered:

  • society name

  • standardization committee

  • working group information

    • name of working group

    • members of working group

  • balloting committee members

  • SA standardization board members

All membership information is encoded in a participants clause.

Example 6. Usage of authorship information outside of memberships
:society: Computer Society (1)
:committee: C/AISC - Artificial Intelligence Standards Committee (2)
:working-group: Spatial Web Working Group (3)

  1. IEEE Society.

  2. IEEE Committee sponsor of the document.

  3. IEEE SA working group that produces the document.

Participants and contributors

tag::participants-ieee[]

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 7. 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 8. 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 9. 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 10. 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 11. 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 12. 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 13. 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 14. 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.

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

Table of contents: figures and tables

In IEEE SA documents, a list of figures and tables are often provided in the TOC.

The following Metanorma setting will enable these tables of contents.

Example 15. Enabling figures and tables in the Table of Contents
:toc-figures: true (1)
:toc-tables: true (2)

  1. Enables the TOC for figures.

  2. Enables the TOC for tables.

Other metadata

Every IEEE SA document has a list of keywords (for searching purposes) and is also issued identifiers like the ISBN.

This information can be set as follows.

Example 16. Setting other identifying metadata
:keywords: data fusion, IEEE 2830™, shared machine learning, SML, ... (1)
:isbn-pdf: 978-1-5044-7724-6 (2)
:isbn-print: 978-1-5044-7725-3 (3)
:stdid-pdf: STD24807 (4)
:stdid-print: STDPD24807 (5)

  1. List of keywords, comma-delimited.

  2. ISBN-13 for the PDF version.

  3. ISBN-13 for the printed version.

  4. STDID for the PDF version.

  5. STDID for the printed version.