chore: clean ups

author/bipm/topics/markup.adoc

@@ -12,11 +12,14 @@ receive section numbering, and are cross-referenced by their title.
 
 === Quoted titles
 
-In the SI Brochure, the subtitles in Annex 1 with a black square bullet, indicating the subject of the cited
-CIPM recommendations and CGPM resolutions, are treated as variant titles, of type `quoted`,
-since they are treated as part of the cited recommendations 
-and resolutions [added in https://github.com/metanorma/metanorma-bipm/releases/tag/v1.1.10]. They are marked up
-as follows:
+In the SI Brochure, subtitles in Annex 1 are presented with black square bullets.
+
+This indicates that the subject of the cited CIPM recommendations and CGPM
+resolutions are treated as variant titles, of type `quoted`, since they are
+treated as part of the cited recommendations and
+resolutions [added in https://github.com/metanorma/metanorma-bipm/releases/tag/v1.1.10].
+
+Quoted titles are encoded as follows:
 
 [source,asciidoc]
 ----

author/concepts/metanorma_workflow.adoc

@@ -48,44 +48,77 @@ end::editing[]
 
 == Validation
 
-Before you can generate any outputs, the AsciiDoc document needs to be checked against the document model to ensure it follows the rules of your SDO. Since the document model is defined in an XML schema, the compiler converts the AsciiDoc document into an XML file. The XML file is then checked against the SDO's XML schema. Metanorma will log all deviations from the SDO's structure or formatting on the terminal and into an error file.
-
-* ❌ Invalid XML: The XML file does not comply with the XML schema, or with the formatting rules defined by the SDO.
-All errors are logged to the terminal and are saved to an Error file (.`err.html`). Often the document will render successful despite errors, but the error messages point out potential issues with the document structure.
-
-* ✅ Valid XML: The XML file complies with the XML schema and the compiler can proceed to generate an output.
+Before you can generate any output, the Metanorma document needs to be checked
+against the document model to ensure it follows the rules of your SDO.
+
+Since the document model is defined in an XML schema, the compiler converts the
+Metanorma document into a Metanorma XML file. This XML file is then checked
+against the SDO's XML schema. Metanorma will log all deviations from the SDO's
+structure or formatting on the terminal and into an error file.
+
+❌ Invalid XML::
+The XML file does not comply with the XML schema, or with the formatting rules
+defined by the SDO.
++
+All errors are logged to the terminal and are saved to an error file
+(.`err.html`). Often the document will render successful despite errors, but the
+error messages point out potential issues with the document structure.
+
+✅ Valid XML::
+The XML file complies with the XML schema and the compiler can proceed to
+generate an output.
 
 == Output generation
 
+=== General
+
 The Metanorma toolchain compiles documents in the following formats:
 
 * Metanorma XML
 * HTML
 * PDF
 * Microsoft Word
 
-*Metanorma XML*
+=== Metanorma XML
 
-Metanorma always generates an XML output first because it is the intermediate format used to drive the other formats. The Metanorma XML file marks up the semantic content of the standards document and is therefore used during the validation stage. Metanorma then generates a presentation version of the XML (`.presentation.xml`), which resolves cross-references, captions, and internationalisation, and is used as the basis of all other formats.
+Metanorma always generates an XML output first because it is the intermediate
+format used to drive the other formats. The Metanorma XML file marks up the
+semantic content of the standards document and is therefore used during the
+validation stage. Metanorma then generates a presentation version of the XML
+(`.presentation.xml`), which resolves cross-references, captions, and
+internationalisation, and is used as the basis of all other formats.
 
-*HTML*
+=== HTML
 
-The HTML output is in HTML 5. All HTML output has a sidebar with a Javascript-generated table of contents, which is two section levels deep. Audio and video files are not supported.
+The HTML output is in HTML 5. All HTML output has a sidebar with a
+Javascript-generated table of contents, which is two section levels deep. Audio
+and video files are not supported.
 
-*PDF*
+=== PDF
 
-Metanorma generates PDF output from XML. The styling comes from an https://www.xml.com/articles/2017/01/01/what-is-xsl-fo/[XSL-FO] stylesheet. A processing engine (Apache FOP) interprets the stylesheet and generates the PDF.
+Metanorma generates PDF output from XML. The styling comes from an
+https://www.xml.com/articles/2017/01/01/what-is-xsl-fo/[XSL-FO] stylesheet. A
+processing engine (Apache FOP) interprets the stylesheet and generates the PDF.
 
-*Microsoft Word*
+=== Microsoft Word
 
-Metanorma can also generate a `.doc` Word output. Metanorma does not output `.docx` because it is easier to support all of the formatting requirements in a `.doc` file.
+Metanorma can also generate a `.doc` Word output. Metanorma does not output
+`.docx` because it is easier to support all of the formatting requirements in a
+`.doc` file.
 
 == Review
 
-Standards documents require collaboration and every SDO has its own process for reviews. Metanorma does support authors and reviewers by providing metadata that indicate in which phase the document is in and who reviewed it. You can add your remarks to a document with comments or create a to-do if you want someone to act.
+Standards documents require collaboration and every SDO has its own process for
+reviews. Metanorma does support authors and reviewers by providing metadata that
+indicate in which phase the document is in and who reviewed it. You can add your
+remarks to a document with comments or create a to-do if you want someone to
+act.
 
 == Publication
-Once you and your reviewers agree that the standard is ready for publishing, you send it to your standard developing organization (SDO). The SDO will publish your document in their preferred channels, such as online or print.
+
+Once you and your reviewers agree that the standard is ready for publishing, you
+send it to your standard developing organization (SDO). The SDO will publish
+your document in their preferred channels, such as online or print.
 
 end::tutorial[]
 

author/ref/document-attributes.adoc

@@ -42,28 +42,38 @@ If set, use the `relaton` and `iev` gem functionality to look up
 ISO and IEV references online, but do not use the cache of `relaton` and `iev` searches.
 
 `:local-cache:`::
-Use the local relaton and iev search caches to override the global `relaton` and `iev` search
+Use the local Relaton and iev search caches to override the global `relaton` and `iev` search
 caches. If a directory name is given for the attribute, that name overrides `relaton` as the
 cache name.
 
 `:local-cache-only:`::
-Use the local relaton and iev search caches to the exclusion of the global
+Use the local Relaton and iev search caches to the exclusion of the global
 `relaton` and `iev` search caches.
 If a directory name is given for the attribute, that name overrides `relaton` as the cache name.
 
 `:flush-caches:`::
-If set, delete and reinitialise the cache of `https://www.relaton.org/[relaton]` searches.
+If set, delete and reinitialise the cache of https://www.relaton.org/[Relaton] searches.
 
-`:relaton-data-source`:: Allows specification of an external bibliographic file to be 
+`:relaton-data-source`::
+Allows specification of an external bibliographic file to be
 imported [added in https://github.com/metanorma/metanorma-standoc/releases/tag/2.2.9].
-The value of the field is the file name; if the format also needs to be specified, this is done
-as `file=PATH/TO/FILE,format=FORMAT`. Currently, only "bibtex" is supported as a format,
-and any other formats will raise an error.
+The value of the field is the file name. If the format also needs to be
+specified, this is done as `file=PATH/TO/FILE,format=FORMAT`. Valid formats are
+follows.
 
-`:relaton-data-source-{id}`:: Allows specification of multiple external bibliographic files to be
+`bibtex`::: The BibTeX format. Currently, only
+this is supported as a format, all other formats will raise an error.
+
+`:relaton-data-source-{id}`::
+Allows specification of multiple external bibliographic files to be
 imported [added in https://github.com/metanorma/metanorma-standoc/releases/tag/2.2.9].
-The different bibliographic sources are differentiated through the value of the `{id}` identifier,
-e.g. `:relaton-data-source-bib1: PATH/TO/FIRST/FILE`, `:relaton-data-source-bib2: PATH/TO/SECOND/FILE`.
+The different bibliographic sources are differentiated through the value of the `{id}` identifier.
++
+[example]
+----
+:relaton-data-source-bib1: PATH/TO/FIRST/FILE
+:relaton-data-source-bib2: PATH/TO/SECOND/FILE
+----
 
 
 == Math

author/ref/section_block_attributes.adoc

@@ -40,18 +40,23 @@ to "informative" as a section attribute if needed. For example:
 
 === Type
 
-Clauses can have types; in Metanorma these are normally set internally (e.g. all clauses
-with the title "Scope" or `heading=` attribute "scope" are of type "scope"). However the
-type of a clause can also be set by the user [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.7.4],
-through the `type` attribute. This is useful particularly for any semantic processing of the
-document downstream.
+Clauses can have types. In Metanorma, clause types are normally set internally
+(e.g. all clauses with the title "Scope" or `heading=` attribute "scope" are of
+type "scope").
+
+The type of a clause can also be explicitly set by the user through the `type`
+attribute [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.7.4].
+
+This is useful particularly for any semantic processing of the document
+downstream.
 
 [source,asciidoc]
 --
 [type=reagents]
 == Reagents
 --
 
+
 == Numbering
 
 As with link:/author/topics/document-format/text#numbering-override[block element numbering],

author/topics/inline_markup/changes.adoc

@@ -52,7 +52,7 @@ If the `change` attribute has the value `modify`, the replacement text needs to
 represented as a final blockquote within the change clause.
 
 [source,asciidoc]
-----
+--
 [change=modify,locality="page=14,clause=4.3.1",title="Array based unstructured mesh",path="./source"]
 ==== {blank}
 
@@ -62,21 +62,27 @@ Remove the EXPRESS definition of this entity and replace with:_
 ____
 [%unnumbered]
 [source,html]
------
+----
 *)
 ENTITY array_based_unstructured_mesh
 ...
 (*
------
-____
 ----
+____
+--
 
 The replacement text may contain assets that need to be numbered on rendering, in order to reflect
-how they should look in the target document. Replacement text cannot rely on auto-numbering, and its
-content is by default skipped in auto-numbering; but the starting point for any auto-numbering can
-be defined for an asset with the macro `autonumber:asset_class[value]`, giving the starting value
-for auto-numbering an asset class within the change clause; for example `autonumber:table[2]` means
-start numbering any tables in the replacement text from 2.
+how they should look in the target document.
+
+Replacement text cannot rely on auto-numbering, and its content is by default
+skipped in auto-numbering. However, the starting point for any auto-numbering
+can be defined for an asset with the macro `autonumber:asset_class[value]`,
+giving the starting value for auto-numbering an asset class within the change
+clause.
+
+[example]
+`autonumber:table[2]` means start numbering any tables in the replacement text
+from 2.
 
 [source,asciidoc]
 ----
@@ -102,15 +108,14 @@ ____
 |===
 
 NOTE: This is not generalised further.
-
 ____
-
 ----
 
+
 If the starting value is empty, the asset is treated as unnumbered:
 
 [source,asciidoc]
-----
+--
 [change=replace,locality="clause=4.2.2,note=1"]
 == 4.2.2
 autonumber:note[]
@@ -120,7 +125,7 @@ ____
 [NOTE]
 The calendar year used in the week calendar...
 ____
-----
+--
 
 [[corrigenda]]
 == Corrigenda
@@ -135,4 +140,5 @@ 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>>)]
 --
 
-For more complicated corrigenda involving changes, you may use link:/author/topics/document-format/annotation#reviewer[reviewer notes].
+For more complicated corrigenda involving changes, you may
+use link:/author/topics/document-format/annotation#reviewer[reviewer notes].