Metanorma markup for ITU

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.

Initial untitled clauses in Resolutions may be marked with a blank title and as [%unnumbered] [added in https://github.com/metanorma/metanorma-itu/releases/tag/v1.2.11]:

[%unnumbered]
== {blank}
The World Telecommunication Standardization Assembly (Hammamet, 2016),

_considering_
...

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
++++

Numbers

Numbers should be marked up with stem:[…​] to have them formatted as required by the ITU Editing Guidelines. This way the numbers will be shown with single quote as a thousands separator.

EXAMPLE: stem:[1234567890] is rendered as 1'234'567'890.

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 predefined text 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 details 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

Title

The internal terms section is recognised with the heading “Terms defined in this Recommendation”.

The external terms section are recognised with the heading “Terms defined elsewhere”.

Setting the heading attribute of a title will also allow the internal and external terms section to be recognised [added in https://github.com/metanorma/isodoc/releases/tag/v1.2.0]:

[heading="terms defined in this recommendation"]
=== Terminoj difinitaj en ĉi tiu rekomendaĵo

Predefined text

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

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

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

  • If neither subclause appears (as is the case in ITU G.650.1), the text “This Recommendation defines the following terms:” is provided.

Abbreviations and acronyms

“Abbreviations and acronyms” sections are recognized as such when:

  • A section titled “Abbreviations and acronyms” is given as a top-level section;

  • A section attribute of [heading=Abbreviations and acronyms] is explicitly given.

Otherwise they are treated as normal sections [added in https://github.com/metanorma/isodoc/releases/tag/v1.2.1].

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 for ITU.

Cross-references

Cross-references to clauses are rendered 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 get it wrong.

To override such capitalisation, you can use the the flags capital% or lowercase% as the content of the cross-reference, 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%>>.