Authoring ITU documents using Metanorma

Document attributes

Note

Document attributes listed below are unique to the processing of ITU 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 ITU.

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

Document Information

doctype

Document type. Choices:

  • recommendation (default): This document is an ITU Recommendation.

  • recommendation-supplement: This document is a Supplement of an ITU Recommendation.

  • recommendation-amendment: This document is an Amendment of an ITU Recommendation.

  • recommendation-corrigendum: This document is a Corrigendum of an ITU Recommendation.

  • recommendation-errata: This document is an Errata of an ITU Recommendation.

  • recommendation-annex: This document is an Annex of an ITU Recommendation.

  • focus-group: This document is the output of a Focus Group.

  • implementers-guide: This document is an ITU Implementers Guide.

  • technical-paper: This document is a ITU Technical Paper.

  • technical-report: This document is a ITU Technical Report.

  • joint-itu-iso-iec: This document is a “Common Text” Recommendation between ITU and ISO/IEC JTC 1.

:status:

Document status. Synonym: :docstage:. Choices:

  • in-force: This document is In-force.

  • in-force-prepublished: This document is In-force but the text is not final.

  • superseded: This document has been superseded.

  • withdrawn: This document has been withdrawn.

Note
If the document is a draft, use the general :draft: document attribute instead of :status: to indicate so (see Document attributes reference).

In general, the document stages are:

  • Draft Recommendation (the text of the Recommendation is being developed and may be quite mature, but it has not yet been approved)

  • Once the text is mature, the SG may decide to “Consent it” (APP) or “Determine it” (TAP). The draft Recommendation is then in “Consented” (AAP) or “Determined” (TAP) state.

  • As soon as it has been approved, the Recommendation is no longer a draft Recommendation, but an in-force Recommendation.

  • TSB then prepublishes the Recommendation. Prepublished Recommendations are in-force texts that are not yet in their final form. Because they are not final, they are made available only to the Membership.

  • TSB copy-edits and publishes the Recommendation. This final in-force version is made available to all for free download.

  • If the Recommendation is revised, it will be superseded by the revision as soon as the revision is approved.

  • Recommendations are seldom withdrawn, but it may happen when the SG decides to do so.

Please refer to the Traditional Approval Process (TAP) (WTSA Resolution 1) and the Alternative Approval Process (AAP) (Recommendation A.8) for further details.

:series:

Series that the recommendation belongs to. Use full title, for example: “H: Audiovisual and Multimedia Systems”

:series1:

First level subseries, for example: “IPTV multimedia services and applications for IPTV” (= “H.700–H.789”)

:series2:

Second level subseries, for example: “Digital Signage” (= “H.780–H.789”)

:language:

The language of the document (only en for now; will eventually support ar, zh, en, fr, ru, es) (default: en)

:provisional-name:

A provisional identifier allocated to the document if the proper document identifier (:docnumber:) is not yet known.

:ip-notice-received:

ITU has received a notice of intellectual property, protected by patents, which may be required to implement this Recommendation. (default: false)

:title-(en, fr, es, ar, ru, zh):

The title to use, in each of the official languages of the ITU.

:annexid:

The ID to use for the annex, if this document is an annex.

:annextitle:

The title to use for the annex, if this document is an annex.

:annextitle-(en, fr, es, ar, ru, zh):

The title to use for the annex, if this document is an annex,

in each of the official languages of the ITU.

Author Information

:bureau_{i}:

Mandatory. Bureau that the document belongs to. Choices:

  • T (Telecommunication Standardization Bureau, ITU-T) (default)

  • R (Radiocommunication Bureau, ITU-R)

  • D (Development Bureau, ITU-D)

bureau, group, subgroup, and workgroup together form a project group, and there may be multiple project groups associated with a document; each group after the first is indicated by a trailing number, e.g. bureau_2, group_2.

:group_{i}:

Mandatory. Project group that the document belongs to.

:grouptype_{i}:

Type of Project group that the document belongs to. Permitted values: tsag, study-group, work-group

:groupacronym_{i}:

Acronym of Project group that the document belongs to.

:groupyearstart_{i}:

Year that Project group study period started.

:groupyearend_{i}:

Year that Project group study period ended.

:subgroup_{i}:

Project subgroup that the document belongs to.

:subgrouptype_{i}:

Type of Project subgroup that the document belongs to. Permitted values:

  • tsag: TSAG

  • study-group: Study Group

  • work-group: Working Group of a Study Group

:subgroupacronym_{i}:

Acronym of Project subgroup that the document belongs to.

:subgroupyearstart_{i}:

Year that Project subgroup study period started.

:subgroupyearend_{i}:

Year that Project subgroup study period ended.

:workgroup_{i}:

Project workgroup that the document belongs to.

:workgrouptype_{i}:

Type of Project workgroup that the document belongs to. Permitted values:

  • tsag: TSAG

  • study-group: Study Group

  • work-group: Working Group of a Study Group

:workgroupacronym_{i}:

Acronym of Project workgroup that the document belongs to.

:workgroupyearstart_{i}:

Year that Project workgroup study period started.

:workgroupyearend_{i}:

Year that Project workgroup study period ended.

Recommendation Status

:recommendation-from:

Date from which recommendation status applies

:recommendation-to:

Date to which recommendation status applies

:approval-process:

Approval Process for recommendation status. Legal values are:

:approval-status:

Approval status code for recommendation status. Legal values are:

  • If :approval-process: is set to tap: (refer to WTSA Resolution 1, Figure 9.1 “Approval of new and revised Recommendations using TAP — Sequence of events”)

    • determined: Determined

    • in-force: In-force

  • If :approval-process: is set to aap: (refer to Recommendation A.8, Figure 1 “Sequence of Events”)

    • a: Approved

    • ac: Approved with Substantial Changes

    • aj: Additional Review Judgement

    • ar: Additional Review

    • at: Approved with Typographical Corrections

    • lc: Last Call

    • c: Consented

    • lj: Last Call Judgment (includes Last Call Comment resolution)

    • na: Not Approved

    • ri: Re-Initiate Last Call

    • sg: Referred to Study Group Approval

    • tap: Moved to TAP (ITU-T A.8 / §5.2)

Visual appearance

:smartquotes:

In the rest of Metanorma, if this attribute is not supplied, quotes and apostrophes default to smart. In ITU, quotes and apostrophes default to straight.

Markup

Summaries

The summary sections of recommendations are marked up with the style attribute [abstract].

Lists

The ITU Author’s guide specifies that ordered lists by default should follow the following numbering scheme (which is also default to Metanorma):

  • a), b), c),

  • then 1), 2), 3),

  • then i), ii), iii),

  • then A), B), C),

  • then I), II), III).

If an ordered list is intended to describe “steps” within a process, it should start with Arabic numbers and should be encoded with the class steps:

  • 1), 2), 3),

  • then a), b), c),.

Encoding an ordered list as steps:

[class=steps]
. First Step
. Second Step
. Third Step

Formulae

By default, formulae are labelled “Equation” with a formula sequence number, such as “Equation 18”.

[stem]
++++
A = B + 100
++++

Inequalities are indicated through the option attribute %inequality. They will be shown with a label such as “Inequality 19”.

[stem%inequality]
++++
A < B
++++

Corrigenda

Text to be marked as added or deleted in corrigenda is indicated through the macros add:[…​] and del:[…​]:

del:[The use of echo cancellers on the VBD channel, as per Rec. ITU-T G.168.]

... or other forms of redundancy add:[(e.g. per <<rfc2198>>)]

Annexes

Appendixes are annexes marked as informative instead of normative, which is the default.

Appendixes are numbered with roman numerals rather than letters, as a separate sequence from normative Annexes.

[appendix,obligation=normative]
== First Annex

[appendix,obligation=informative]
== First Appendix

renders as

Annex A

First Annex

(This annex forms an integral part of this Recommendation)

Appendix I

First Appendix

(This appendix does not form an integral part of this Recommendation)

References & Bibliography

There is one references section in ITU documents, which is titled “References”. All documents have the same references boilerplate inserted at the start of the section, which overwrites any text already supplied before the individual references.

Definitions

Boilerplate

If no text appears at the start of the clauses and subclauses in the Definitions section, standard boilerplate is provided automatically:

  • If there is a terms subclause “Terms defined elsewhere”, we must inject the text “This Recommendation uses the following terms defined elsewhere:” or “None”, depending on whether any terms are present.

  • If there is a terms subclause “Terms defined in this Recommendation”, we must inject the text “This Recommendation defines the following terms:” or “None”, depending on whether any terms are present.

  • If neither subclause appears (as is the case in ITU G.650.1 but not in the documents first sighted), we must inject at the top clause the text “This Recommendation defines the following terms:”.

Tables

The ITU editorial rules specifies the following formatting rules for authors:

  1. table header row content must be center-aligned;

  2. “text” in tables should be left-aligned;

  3. “values” in tables should be center-aligned.

In Metanorma, this is conveyed by setting the horizontal alignment on the corresponding columns and ensuring that the header cells are centered; e.g.

[cols="<,^,^,<", options="header"]
|===
^| Text ^| Value ^| Value ^| Text

| Table | 121 | 0.1 | Other table
|===
Note
This editorial rule is mandated by the ITU Editorial Team, but is not described in the ITU-T Author’s Guide.