Metanorma: Aequitate Verum

Metanorma for IEEE SA

Metanorma IEEE SA document attributes

Note

Document attributes listed below are unique to the processing of IEEE SA documents in Metanorma.

For common document attributes, see Document attributes reference in general Metanorma author’s documentation. That page describes attributes that apply to all Metanorma flavors, not just IEEE SA.

For an introduction to Metanorma AsciiDoc document attributes and how Metanorma uses them, see the corresponding topic.

Document information

docnumber

In IEEE SA terms: the designation number for the document. Do not include the initial "P".

Example 1. Example for IEEE SA docnumber
:docnumber: 2830
partnumber

The document part number, where applicable [added in https://github.com/metanorma/isodoc/releases/tag/v1.0.12].

subpartnumber

The document subpart number, where applicable [added in https://github.com/metanorma/isodoc/releases/tag/v1.0.12].

conformance

Specification of the conformance of the document, where applicable (e.g. Conformance 02-2021) [added in https://github.com/metanorma/isodoc/releases/tag/v1.0.12].

draft

The draft number. Use together with :docstage: draft. Do not include the initial "D".

Example 2. Example for IEEE SA docstage
:docstage: draft
:version: 2
edition

The edition number of the document. In case that a document is a draft, the edition number indicates the intended edition number.

Example 3. Example for IEEE SA edition
:edition: 1
amendment-number

(only when docsubtype is set to amendment) The number of the amendment.

corrigendum-number

(only when docsubtype is set to corrigendum) The number of the corrigendum.

isbn-pdf

The ISBN of the PDF document in ISBN-13 format.

Example 4. Example for IEEE SA isbn-pdf
:isbn-pdf: 978-1-5044-7724-6
isbn-print

The ISBN of the print document in ISBN-13 format.

Example 5. Example for IEEE SA isbn-print
:isbn-print: 978-1-5044-7725-3
stdid-pdf

The final standard identifier of the PDF document.

Example 6. Example for IEEE SA stdid-pdf
:stdid-pdf: STD24807
stdid-print

The final standard identifier of the print document.

Example 7. Example for IEEE SA stdid-print
:stdid-print: STDPD24807
docstage

Document stages. Allowed values are:

draft

This document is in draft stage, being developed.

approved

(default) This document has been approved by the IEEE SASB.

Note
 Approved does not necessarily mean published, it is a necessary stage prior to publication. However approved documents are rendered as published documents, with no draft indications.
superseded

This document has been superseded.

withdrawn

This document has been withdrawn.

doctype

Document type. Definitions of the document type are found on the IEEE SA Style Manual.

Choices:

standard

This document is a Standard (default)

recommended-practice

This document is a Recommended Practice

guide

This document is a Guide

whitepaper

This document is a White Paper

redline

This document is a Redline product document

other

This document is of a type not otherwise described

docsubtype

Document subtype. Choices:

document

Document is new or a revision (default)

amendment

Document is an amendment

corrigendum

Document is an corrigendum

erratum

Document is an erratum

icap

Document is an ICAP (IEEE Conformity Assessment Program) document (applies only to whitepaper)

industry-connections-report

Document is an Industry Connections Report document (applies only to whitepaper)

industry-affiliate-network

Document is an Industry Affiliate Network document [added in https://github.com/metanorma/metanorma-ieee/releases/tag/v1.5.3]

trial-use

Document published for a limited period of time. Can apply to any of the document types. (Default value: false.)

Note
 A Trial-Use standard is only described in the text of the introduction, it is not prominently displayed nor is it fielded data.
Note
 Please see Operations Manual, 5.7 Trial-Use standards for more details.
issued-date

The date on which the document was approved. (Applicable to drafts.) Like all dates in Metanorma, this must be supplied in YYYY-MM-DD format.

Example 8. Example for IEEE SA issued-date
:issued-date: 2021-06-16
feedback-ended-date

(conditional: used only when trial-use is set to true.) Specific to trial-use documents: the final date at which comments about the document will be accepted.

ieee-sasb-approved-date

Date that the document was approved specifically by the IEEE SA Standards Board [added in https://github.com/metanorma/metanorma-ieee/releases/tag/v1.5.3].

obsoleted-date
:keywords

Comma-delimited list of keywords associated with the document.

Example 9. Example for IEEE SA keywords (IEEE Std 2830™-2021)
:keywords: data fusion, IEEE 2830™, shared machine learning, SML, trusted execution environment, TEE
:doctitle:

Document title.

Note
 Do not include the words "{Draft/IEEE} (Trial-Use) {Guide/Standard/Recommended Practice} for", these words are supplied automatically by Metanorma.
Note
 The :doctitle: value can also be set using the first line of the Metanorma AsciiDoc markup, prefaced by `= ` instead of setting the document attribute.
Example 10. Example of default document titling
:doctitle: Spatial Web Protocol, Architecture and Governance
:docstage: approved
:doctype: recommended-practice

Document title: Spatial Web Protocol, Architecture and Governance Full document title: IEEE Recommended Practice for Spatial Web Protocol, Architecture and Governance Abbreviated document title: IEEE Rec. Prac. for Spatial Web Protocol, Architecture and Governance

:title-full:

Full document title By default, the words "(Draft/IEEE) (Trial-Use) {Guide/Standard/Recommended Practice} for" are prefixed to the supplied title automatically by Metanorma, depending on document metadata, in the form of the title used to render the document. In order to override this, users can supply the complete title of the document with this document attribute [added in https://github.com/metanorma/metanorma-ieee/releases/tag/v1.5.4].

:title-abbrev:

Abbreviated document title The full title of the document is abbreviated by Metanorma, for use in Word output headers, by constructing the full title depending on document metadata, but using a standard abbreviation for the document type. In order to override this, users can supply the abbreviated title of the document with this document attribute [added in https://github.com/metanorma/metanorma-ieee/releases/tag/v1.5.4].

Example 11. Example of user-supplied document titling
:doctitle: Spatial Web Protocol, Architecture and Governance
:docstage: approved
:doctype: recommended-practice
:title-full: IEEE Recommended Practice for Spatial Web Protocol
:title-abbrev: IEEE Rec. Prac. for SWF

Document title: Spatial Web Protocol, Architecture and Governance Full document title: IEEE Recommended Practice for Spatial Web Protocol Abbreviated document title: IEEE Rec. Prac. for SWF

:document-scheme

The document scheme that this document aligns to. Metanorma will enforce alignment as appropriate, including by supplying predefined sections.

Accepted values:

ieee-sa-2021

(default)

  • A "Word usage" subclause will be supplied at the end of the "Overview" clause with contents defined in the IEEE SA Style Manual 2021.

  • The "Participants" clause will be automatically generated according to IEEE SA requirements using the information supplied by the user-defined "Participant" clauses.

legacy

(all unsupported values fall back to legacy) Metanorma will not supply the "Word usage" subclause and will not generate or modify the "Participants" clause.

:program:

Program under which a white paper was authored [added in https://github.com/metanorma/metanorma-ieee/releases/tag/v1.1.6].

Document relationships

:merges:

This document incorporates the document(s) with the nominated identifiers (semicolon-delimited). In IEEE identifiers, indicated as incorporated.

:updates:

This document is an update of the document(s) with the nominated identifiers (semicolon-delimited). Applies to revisions, as well as to appendices and corrigenda.

:supplements:

This document is a supplement of the document with the nominated identifier [added in https://github.com/metanorma/isodoc/releases/tag/v1.0.12].

Document 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.

The basic information of these groups are entered as document attributes, including:

  • the working group

  • the balloting group

  • the standards board, at the time of publishing the document.

Members of these groups are entered in the Participants clause.

Society

An IEEE SA document is sponsored by or developed by an IEEE society. This IEEE society is prominently displayed on the cover page.

Note
 This is mandatory information.
society

The IEEE society responsible for the document. Do not include the "IEEE" prefix.

Example 12. Example for IEEE SA society
:society: Computer Society

Committee

An IEEE SA document is developed within a working group under an IEEE SA committee. This IEEE SA committee is prominently displayed on the cover page.

Note
 This is mandatory information.
committee

The committee responsible for the document.

Example 13. Example for IEEE SA committee
:committee: C/AISC - Artificial Intelligence Standards Committee
:committee: Standards Activities Board

Working group

An IEEE SA document is developed by a working group.

Note
 This is mandatory information.

An IEEE SA working group can be one of two modes (more details at process):

  • Entity-based: members are IEEE SA member organizations

  • Individual-based: members are individual contributors

    working-group

    The working group responsible for the document. Include any final "Working Group" text in the group name.

    Example 14. Example for IEEE SA working-group
    :working-group: Spatial Web Working Group

(Rendered as: the Spatial Web Working Group had the following membership:…​)

Members of the working group are to be listed in the Participants clause.

Balloting group

The balloting group, or balloting committee, is the group that recommends the document for approval as a standard by the IEEE SA Standardization board.

The balloting group is composed of voting members of the working group, or the committee that the working group belongs to.

balloting-group

The Standards Association balloting group responsible for the document. Do not supply the final "Standards Association balloting group" text in the group name; that is supplied by Metanorma.

balloting-group-type

The type of the Standards Association balloting group responsible for the document, individual or entity (default: individual).

Members of the balloting group are to be listed in the Participants clause.

Standardization board

The IEEE Standardization Board at the time of document publication is rendered in the document preface.

Members of the IEEE SA Standardization Board (SASB) are to be listed in the Participants clause.

Personal authors

White papers require personal authors to be specified, as follows:

:surname:, :surname_2:, :surname_{i}:

Surname of personal authors

:givenname:, :givenname_2:, :givenname_{i}:

Given name of personal authors

:contributor-position:, :contributor-position_2:, :contributor-position_{i}:

Job title of personal authors

Sponsors

The sponsoring bodies, if any, are indicated through the :sponsor: and :sponsor-subdivision: attributes.

As with other author values, multiple instances of sponsoring organisations and their subdivisions are indicated as :sponsor_2: and :sponsor-subdivision_2:, :sponsor_3: and :sponsor-subdivision_3:, etc.

The values of :sponsor-subdivision_{i}: can be:

The different hierarchical levels can optionally be prefixed with type and a colon.

On the front cover, if it is a sponsor, "IEEE" is prefixed to the first subdivision, rather than being rendered on a separate line.

The following is an example of how two divisions of the IEEE are indicated as sponsoring the document:

Example 15. IEEE subdivsion sponsors to a document
:sponsor: IEEE
:sponsor-subdivision: "Power & Energy Society", Power System Communications Committee; Communications Society, Standards Committee

rendered as:

Sponsored by the
Power System Communications Committee
of the
IEEE Power & Energy Society
and the
Standards Committee
of the
IEEE Communications Society

Note
 The quotation marks are needed to process the CSV correctly.

Corporate authors

In Industry Affiliate Network documents, an affiliate needs to be nominated, along with its logo. These are indicated through the :corporate-author: attribute, which overrides the default of IEEE to indicate which organisations have been involved in authoring the document [added in https://github.com/metanorma/metanorma-ieee/releases/tag/v1.5.3]. The affiliate should be given as the second :corporate-author: instance, after IEEE. The :corporate-author_logo: attribute should match the :corporate-author: attribute:

:corporate-author: IEEE
:corporate-author_2: Spatial Web Foundation
:corporate-author_logo_2: swf.png

Visual appearance

:hierarchical-object-numbering:

If set, do not number tables and figures consecutively throughout the body of the document, but restart numbering with each clause (hierarchically).

Use in complex documents, with multiple tables or figures, that need to be tracked against clauses for ease of lookup (so Figure 6-3, Figure 6-4, instead of Figure 21, Figure 22.)

:presentation-metadata-coverpage-statement:

In Industry Affiliate Network documents, used to give the coverpage statement of the affiliate organisation’s contribution [added in https://github.com/metanorma/metanorma-ieee/releases/tag/v1.5.3].

:presentation-metadata-page-break-between-sections:

If set to true, page breaks will be added between the document sections in the PDF.

Document processing

:ieee-dtd:

The location of the IEEE XML DTD [added in https://github.com/metanorma/isodoc/releases/tag/v0.1.0]. Used to validate any IEEE XML generated for the document.