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

:docnumber:

The identifier for the document, including the series, the document number, and any suffix, but excluding the bureau. For instance, H.781, G.108.2, G.709/Y.1331.

: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-{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.

:subtitle-{en, fr, es, ar, ru, zh}:

The subtitle to use, in each of the official languages of the ITU; appears only at the start of the document body, not in the front cover [added in https://github.com/metanorma/metanorma-itu/releases/tag/v1.0.16].

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.

:legacy-do-not-insert-missing-sections:

If set, do not insert the sections Scope, References, Definitions, Abbreviations and acronyms, Conventions if missing [added in https://github.com/metanorma/metanorma-itu/releases/tag/v1.0.11]. Use this if you have a legacy recommendation document with clauses with names preceding this requirement (e.g. "Prerequisites", "Process", "General"), and you do not want the compulsory new sections to be added in at the start of the document.

:hierarchical-object-numbering:

If set, do not numbering objects (tables, figures etc.) consecutively throughout the body of the document, but restart numbering with each clause (hierarchically) [added in https://github.com/metanorma/metanorma-itu/releases/tag/v1.0.11]. Use in complex documents, with multiple tables or figures, that need to be tracked against clauses for ease of lookup (so Figure 6-3, 6-4, instead of Figure 21, 22.) Note that equations in ITU are always numbered hierarchically.

Markup

Prefatory

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

The prefatory sections Summary, History, [added in https://github.com/metanorma/metanorma-itu/releases/tag/v1.0.16] Source, and the Keywords appear in the Word frontispiece.

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)

ITU Annexes skip numbering of “Annex I” in order to avoid ambiguity, due to the identical “I” in “letter I” and “Roman numeral one”. (e.g. is “Figure I.3” part of the first Appendix, or the ninth Annex?). Therefore the Annexes skip from “Annex H” directly to “Annex J”.

References & bibliography

The normative references section in ITU documents 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.

Any references given in the bibliography section are expected to have user-supplied identifiers prefixed with b-:

* [[[b-CMake,b-CMake]]], Kitware (2018), _CMake_. https://cmake.org/.
* [[[ISO20483,(b-ISO 20483)ISO 20483]]], _ISO 20483:2013 Cereals and cereal products -- Determination of moisture content -- Reference method_

ITU Supplements must be cited with the exact same abbreviation they appear as on the ITU web site, so that their reference deatils can be looked up online. That abbreviation can vary from the abbreviation used in documents: e.g. ITU-T G Suppl. 41, not (as in the Editing Guidelines) ITU-T G-Sup.41.

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.

Index

Indexes are not currently supported in Metanorma.

Cross-references

Cross-references to clauses are in lowercase: “see clause 4.1”. Metanorma will attempt to impose correct capitalisation for instances at the start of blocks and sentences, but it may well get it wrong; to override such capitalisation, you can use the the flags capital% or lowercase% as the content of the crossreference, to force that casing on the cross-reference [added in https://github.com/metanorma/isodoc/releases/tag/v1.0.28]:

[[cl3]]
== Clause 3

== Clause 4

See e.g. <<cl3,lowercase%>> +
<<cl3,capital%>>.