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.
= Recommended Practice for Preparing an IEEE Standards Draft (1) :docnumber: 987.6 (2) :docstage: draft (3) :draft: 3 (4)
-
IEEE SA document title.
-
IEEE SA document number. If draft, omit the "P" prefix as it will be automatically added.
-
IEEE SA document stage.
-
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.
:mn-document-class: ieee (1) :mn-output-extensions: xml,html,doc,pdf,rxl (2) :local-cache-only: (3)
-
Metanorma flavor. For IEEE SA, enter
ieee
. -
Metanorma output formats. For IEEE SA, supported formats are
xml
,html
,pdf
,doc
andrxl
. -
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.
:doctype: standard (1)
-
IEEE SA document type.
:doctype: standard :docsubtype: amendment (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:
-
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. -
Draft number increases, e.g.
:draft: 2
, as the working group progresses. -
The draft gets balloted by the working group when ready.
-
Once the balloting group approves the document, it will be represented to the SA standardization board for approval.
-
After approval, the date of approval should be entered as metadata using
:issued-date:
. -
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 .
|
:docstage: draft (1) :draft: 3 (2) :copyright-year: 2021 (3) :issued-date: 2021-01-01 (4)
-
Document stage.
-
Document draft number.
-
Copyright year of document.
-
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
In IEEE SA, a working group operate under one of two modes: "individual mode" or "entity mode".
If the working group operates under individual mode:
-
the participants of the working mode should be entered, as individuals
If the working group operates under entity mode:
-
the representatives of entities that are members of the working group are to be entered;
-
the individual participants of the working mode should be entered, as individuals;
-
the entity members of the working group should be entered.
:society: Computer Society (1) :committee: C/AISC - Artificial Intelligence Standards Committee (2) :working-group: Spatial Web Working Group (3) :wg-chair: Gabriel Rene (4) :wg-vicechair: Michael Wadden (5) :wg-secretary: Christine Perey (6)
-
IEEE Society.
-
IEEE Committee sponsor of the document.
-
IEEE SA working group that produces the document.
-
Working group chair.
-
Working group vice chair.
-
Working group secretary. List of working group members (entity).
:society: Computer Society (1) :committee: Standards Activities Board (2) :working-group: Shared Machine Learning (3) :wg-chair: Jin Peng (4) :wg-vicechair: Cheng Hong (5) :wg-members: Alibaba China Co. Ltd.; Alipay Technology Co., Ltd; ... (6)
-
IEEE Society.
-
IEEE Committee sponsor of the document.
-
IEEE SA working group that produces the document.
-
Working group chair.
-
Working group vice chair.
-
List of working group members (entity), semi-colon delimited.
:balloting-group: Standards Association (1)
:balloting-group-members: 0xSenses Corporation; AAC Technologies; ... (2)
-
Balloting group name.
-
Balloting group members.
:std-board-chair: Gary Hoffman (1)
:std-board-vicechair: Jon Walter Rosdahl (2)
:std-board-pastchair: John D. Kulick (3)
:std-board-secretary: Konstantinos Karachalios (4)
:std-board-members: Edward A. Addy; Doug Edwards; ... (5)
-
IEEE SA Standardization Board Chair.
-
IEEE SA Standardization Board Vice Chair.
-
IEEE SA Standardization Board Past Chair.
-
IEEE SA Standardization Board Secretary.
-
IEEE SA Standardization Board members, semicolon-delimited.
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.
:toc-figures: true (1)
:toc-tables: true (2)
-
Enables the TOC for figures.
-
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.
: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)
-
List of keywords, comma-delimited.
-
ISBN-13 for the PDF version.
-
ISBN-13 for the printed version.
-
STDID for the PDF version.
-
STDID for the printed version.