Lists and numbered paragraphs

PSML provides two similar mechanisms to represent a numbered list of items, but they are quite different in their intentions.

Both lists and paragraphs can have prefixes and indents, letting you create nested lists.

Numbered lists

Numbered lists are designed to represent lists of items using a basic numbering scheme with decimals, roman numerals, or letters.

While they are convenient for basic lists, they are also relatively limited. The prefix before each item is only determined by the position in the list, as it isn’t aware of its position with the document or publication.

For example, the first item of any list is prefixed ‘1.’, ‘a.’, ‘i.’, ’A.’, or ‘I.’ depending on which style of list is used. Authors are free to choose the numbering style.

You can create a nested list by adding a list under an item in a list. Items in a nested list are numbered the same way regardless of which item they are attached to or how deep they are nested.

Numbered paragraphs

Numbered paragraphs provide more control over the numbering and are part of the document structure. You can create the equivalent of a “nested list” by adding a numbered paragraph of a level higher than the preceding numbered paragraph.

Paragraphs with a manual prefix let you control exactly the prefix to use for each item. This might be useful when the prefix is fixed, such as in legislation.

Paragraphs which are auto-numbered are structure-aware, in other words, they are aware of their position within the document or publication. This has two important consequences.

First, the numbering scheme can be configured so that their position within the structure is reflected in the prefix. For example, the first numbered paragraph of level 2 following the second paragraph of level 1, might be prefixed ‘a)’, ‘2.1’, ‘II-a’, ‘B (i)’, etc. depending on your numbering configuration. When wrapped by a block label they can be used as auto-numbered table or image captions.

Second, numbered paragraphs are part of the overall structure and can be configured to appear in the table of contents.