feat: update numbering section

author/ref/document-attributes.adoc

@@ -89,7 +89,8 @@ Read more about
 link:/author/topics/blocks/math/[mathematical expressions].
 
 `:number-presentation:`::
-Sets the formatting options for the `number:[]` command in the document [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.8.12].
+Sets the formatting options for the `number:[]` command in the document [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.8.12]. Please refer to the dedicated section at
+link:/author/topics/inline_markup/semantic-elements#numbers[numbers] for usage.
 +
 .Using the `:number-presentation:` attribute
 [example]
@@ -101,14 +102,13 @@ Sets the formatting options for the `number:[]` command in the document [added i
 number:341[]
 ----
 ====
-+
-Please refer to the dedicated section at
-link:/author/topics/inline_markup/semantic-elements#numbers[numbers].
 
 
 `:number-presentation-profile-{NAME}:`::
 Sets the formatting options for the `number:[]` command in the document
 as profile `{NAME}` [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.8.12].
+Please refer to the dedicated section at
+link:/author/topics/inline_markup/semantic-elements#numbers[numbers] for usage.
 +
 .Using the `:number-presentation-profile-{NAME}:` attribute
 [example]
@@ -121,12 +121,10 @@ as profile `{NAME}` [added in https://github.com/metanorma/metanorma-standoc/rel
 number:342[profile=3]
 ----
 ====
-+
-Please refer to the dedicated section at
-link:/author/topics/inline_markup/semantic-elements#numbers[numbers].
+
 
 `:number-presentation-formula:`::
-Sets the formating options for numbers contained in formulas [added in https://github.com/metanorma/metanorma-standoc/releases/tag/2.9.6].
+Sets the formatting options for numbers contained in formulas [added in https://github.com/metanorma/metanorma-standoc/releases/tag/2.9.6].
 Please refer to the dedicated section at
 link:/author/topics/inline_markup/semantic-elements#formula-numbers[numbers in formulas].
 

author/topics/inline_markup/semantic-elements.adoc

@@ -518,15 +518,22 @@ and it removes `exponent_sign`, resulting in
 
 === Encoding numbers as formulas
 
-Numbers can be formatted within `stem` blocks. By default, numbers in `stem` blocks
-are not formatted at all: number formatting is reserved for the  `number` macro.
-So if a formula contains the string _1221_, that will usually not be formatted
-into _1,221_, but left alone.
+Numbers can be formatted within `stem` blocks.
+
+By default, numbers in `stem` blocks are not formatted at all: number formatting
+is reserved for the  `number` macro.
+
+[example]
+If a formula contains the string _1221_, it will usually not be formatted into
+_1,221_, but left alone.
 
 In order to make a block formula format its numbers, use the argument
 `number-format` on `[stem]`: it has the same format as the foregoing number formatting
-expressions:
+expressions.
 
+.Using the `number-format` argument on a `stem` block
+[example]
+====
 [source,adoc]
 ----
 [stem]
@@ -535,7 +542,7 @@ expressions:
 ++++
 
 [stem,number-format="precision=2"]
-++++  
+++++
 1 + x
 ++++
 ----
@@ -548,57 +555,82 @@ ____
 
 1.00 + x
 ____
+====
+
 
-Default numeric processing is applied to a formula by specifying `number-format=default`:
+Default numeric processing is applied to a formula by specifying
+`number-format=default`.
 
+.Using the `number-format` argument with `default` on a `stem` block
+[example]
+====
 [source,adoc]
 ----
 [stem,number-format="default"]
-++++  
+++++
 1221 + x
 ++++
 ----
 
-in an English-language document applies default English locale formatting on the formula's number,
-to render as:
+in an English-language document applies default English locale formatting on the
+formula's number, to render as:
 
 ____
 
 1,221 + x
 ____
+====
 
-Number formatting profiles can also be used on formulas:
 
+Number formatting profiles can also be used on formulas.
+
+.Using a number formatting profile on a `stem` block
+[example]
+====
 [source,adoc]
 ----
 :number-presentation-profile-foo: notation=scientific,exponent_sign=nil,decimal=","
 
 [stem,number-format="profile=foo"]
-++++  
+++++
 1221 + x
 ++++
 ----
+====
+
+It is possible to specify that by default, all formulas have their numbers
+formatted, through the `number-presentation-formula` document attribute.
+
+The document attribute can take the value `number-presentation`, in which case
+it has the same value as the `:number-presentation:` document attribute; or
+`default`, in which case default number formatting is applied
+(`notation='basic'`).
+
+Syntax:
+
+[source,adoc]
+----
+:number-presentation-formula: {OPTIONS}
+----
 
-It is possible to specify that by default, all formulas have their numbers formatted,
-through the `number-presentation-formula` document attribute. The document attribute
-can take the value `number-presentation`, in which case it has the same value as
-the `:number-presentation:` document attribute; or `default`, in which case default
-number formatting is applied (`notation='basic'`).
 
 If `number-presentation-formula` is set, a formula can ignore number formatting
 by setting `number-format: nil`.
 
+.Using the `number-presentation-formula` document attribute
+[example]
+====
 [source,adoc]
 ----
-:number-presentation-formula: notation=scientific"
+:number-presentation-formula: notation=scientific
 
 [stem]
-++++  
+++++
 1221 + x
 ++++
 
 [stem,number-format=nil]
-++++  
+++++
 1221 + x
 ++++
 ----
@@ -610,6 +642,8 @@ ____
 
 1221 + x
 ____
+====
+
 
 The `number` command however provides granular configuration options, and
 is the recommended method for encoding numbers for consistency reasons.
@@ -627,8 +661,7 @@ NOTE: Inline stem macros (`stem:[]`) do not support attributes, so specifying
 number formatting on inline stem macros is no currently supported, other than
 through the universal application of `:number-presentation-formula:`.
 
-
-NOTE: The number in the `\stem:[]` or `\number:[]` expression must be specified according to the
+NOTE: The number in the `\stem:[]` or `number:[]` expression must be specified according to the
 en-US locale; `30000.54` is recognised as a decimal number, `30 000,54` is not.
 However, if the document is in French, `stem:[30000.54]` will in fact be
 rendered consistent with French practice, as _30 000,54_.