Next: , Previous: , Up: Reference for Common Language Elements   [Contents]


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.

ex63_cshex63

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)34. 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.

You can use the numbering.increment chart option to set an automatic increment other than 1. Using negative numbers will number the arrows backwards.

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, respectively35. 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’.

ex64_cshex64

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

(34)

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

(35)

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


Next: Specifying Colors, Previous: Links, Up: Reference for Common Language Elements   [Contents]