### 8.4 Numbering ¶

Signalling chart arrows, boxes and dividers (any element with a label, except entities) and block diagram blocks can be auto-numbered. It is a useful feature that allows easier reference to certain steps or blocks from explanatory text. At present numbering is not implemented for graphs. To auto assign a number to an element, simply set its `number` attribute to `yes`. You can also assign a specific number, in that case the element will get that number and subsequent elements will be numbered (if they have `number` set to `yes`) from that number upwards.

Notes and comments (signalling charts) will not increase numbering, instead they carry the number of the element they are referring to. If the target element had no number comments will have none, even if numbering is turned on for them.

Styles can also control numbering. If a style has its `number` attribute set to `yes` or `no`, any element that you assign the style to will have its attribute set likewise. See Styles for more.

In order to minimize typing, the `numbering` chart option can be used. It can be set to `yes` or `no` and serves as the default for freshly defined elements. You can set the value of `numbering` at any time and impact elements defined thereafter. You can use scoping to enable or disable numberig for only blocks of the chart, see Scoping.

Most of the time you just declare `numbering=yes` at the beginning of the chart and be done with it. However, if you want to control that only some parts of the elements (e.g., only concrete messages and not boxes, for example) got a number, you may need the other alternatives.

If numbering is turned on for a label, the number is inserted at the beginning of the label and is followed by a semicolon and a space by default. More precisely, the number is inserted after any initial text formatting sequences, so that it has the same formatting as the label itself (see Text Formatting)38. The above default can be changed by inserting the `\N` escape sequence into a label. This causes the number appear where the `\N` is inserted, as opposed to the beginning of the label. In this case, the colon and the space is omitted, only the number itself is inserted.

The colon and space can be changed to some other value by setting the `numbering.post` chart option to the string you want to append to the number. Similar, any string the `numbering.pre` option is set to will be prepended to the number (empty by default). Both options are ignored when using the `\N` escape sequence to set the label position.

Note that for the last two arrows formatting escapes were added to the `numbering.pre` option. These are reversed by the ‘`\s()`’ escape in the `numbering.post` option. See Text Formatting for more details.

The format of the number can be set with the `numbering.format` chart option. You can specify any of ‘`123`’, ‘`iii`’, ‘`III`’, ‘`abc`’, or ‘`ABC`’ for arabic, lowercase and uppercase roman numbers or lowercase and uppercase letters, respectively39. You can also prepend or append any text before or after the above strings, those will be prepended or appended to the number (and will be included also when the number is inserted via the ‘`\N`’ escape).

If you want to specify an increment other than one, use the `numbering.increment` option with a nonzero integer. You can even count backwards using a negative increment. In case of multi-level numbering (see below) this applies to the last level,

Note that the value of the `numbering` options is subject to scoping, that is any change lasts only up to the next closing brace.

Note also, that when using roman numbers or letters, you can use such numbers as the value of the `number` attribute, as shown below for ‘`7c`’.

It is also possible to have multi-level numbering (such as 1.1). To achieve this, use the `numbering.append` chart option and specify the format of the second level including any separator. Use the same format as for `numbering.format` above.

It is possible to change the format of a multi-level label via the `numbering.format` option. Simply use multiple of the number format strings (such as ‘`123`’ or ‘`roman`’) as in the ‘`Exotic format`’ line of the example above. If you use less number format strings than the current number of levels (as in the ‘`Only the last number`’ line of the example), Msc-generator displays only the end of the number, omitting levels from the top. Those levels, however, are still maintained, just are not displayed.

The `numbering.append` option can only be used to add levels. There is no explicit way to decrease the number of levels, you have to use scoping to achieve that. On the example above, the second level appended in the scope of ‘`Alternative #1`’ is cancelled at the end of the scope, so we need to append a second level also in ‘`Alternative #2`’, which then restarts from ‘`a`’.

Finally, if an element is named, you can reference the number of that element in another label using the `\r(name)` escape sequence. Signalling chart elements can be named using the `refname` attribute, while block diagram blocks can simply have their name at their definition. Note that the value of the `numbering.pre` and `numbering.post` options are ignored when inserting the number of a referenced element, similar to how the `\N` escape inserts numbers. Specifying an empty `\r()` escape inserts the number of the current element and is thus equivalent to `\N`.

#### Footnotes

##### (38)

You can use the `\|` formatting escape to insert a non-visible break into a stream of formatting escapes. The number will be inserted there.

##### (39)

Using ‘`arabic`’, ‘`letters`’ or ‘`roman`’ is also valid (both uppercase or lowercase).