Documents

Handling and managing documents

Number Config

Background

Paragraph and heading numbers are a long-standing challenge for publishing technology and while the PageSeeder numbering model is not the same as conventional solutions, the hypertext architecture and structured content provide a robust foundation for complex numbering schemes.

Issues that arise with PageSeeder that don't occur with conventional documents include the following:

  • multiple references documents linking or transcluding the same component into different positions in their numbering scheme.
  • adjusting the heading levels due to component document being embedded at different levels in the references document. (when published, an <h1> in the component document can become <h3> if it is embedded +2)

Opportunities for improved number handling are created by the robust PageSeeder cross reference model, these include: 

  • numbering is abstracted away from the editing process, meaning users can work with more semantically meaningful link titles (for example, 'Warranty' instead of '17.2').
  • there are different processing layers built into the PSML document lifecycle, these create flexibility for where to resolve numbering.

What is Number Config?

It is a configuration file on the Publish Engine that controls options listed below. Multiple number config files can exist on a server. They can be referenced through a process taskor an Ant script.

  • strip-zeros — if enabled, '0' are stripped from a label for example if a heading had hierarchy '1.0.2.', it would be converted to '1.2.'.
    Allowed values are 'true' or 'false', default is 'true'.
  • prefix-para — if enabled, numbered paragraph will inherit numbering from the preceding heading. For example, if paragraph a.i. follows heading 2.1, the paragraph will be displayed as 2.1.a.i.
  • numbering restarts — determines which counters restart after each numbered heading. Allowed values are 'true' or 'false', default is 'false'.

Numbering Patterns

In the example below, each 'pattern' describes how to express each 'level' for every 'step' in the document hierarchy. For a step to inherit values from previous levels in the hierarchy, the pattern must be re-expressed at each step.

A pattern is expressed using the following syntax:

Pattern Syntax

[*(letter)(level)*]
  • '[' and ']' represent the pattern delimiters
  • '*' – represents the 'decoration' before or after the incrementing value

'letter' Values

The letter specifies how PageSeeder should express the incrementing value. The options are the following:

  • 1 – digits (1, 2, 3, ...)
  • a – lowercase letters (a, b, c, ...)
  • A – uppercase letters (A, B, C, ...)
  • i – lowercase roman numerals (i, ii, iii, ...)
  • I – uppercase roman numerals (I, II, III, ...)

'level' Values

A level is a single 'step' down the hierarchy of the document. Currently levels 1 to 6 are supported by PageSeeder.

Examples of Usage

Following are examples of schemes and their output.

canonical value  scheme  strip-zerosresulting label  
1.1.3.1.  [11.][12.][13.][14.]  true 1.1.3.1. 
1.1.3.1.  [11.][13.][14.]  true 1.3.1.  
1.2.1.3.  [a1-][A2-][I3-][14.]  truea-B-I-3.
2.4  [11.][(i2).]  true2.(iv). 
1.0.3  [11.][(i2).][a3]  true1.c.  
1.0.3  [11.][(i2).][a3]  false1.(0).c. 

 

 Example

<numbering>
<strip-zeros>true</strip-zeros>
<prefix-para>false</prefix-para>
<para-schemes>
<scheme level="1">[11.]</scheme>
<scheme level="2">[11.][12.]</scheme>
<scheme level="3">[11.][12.][13.]</scheme>
<scheme level="4">[11.][12.][13.][14.]</scheme>
<scheme level="5">[11.][12.][13.][14.][15.]</scheme>
<scheme level="6">[11.][12.][13.][14.][15.][16.]</scheme>
</para-schemes>
<heading-schemes>
<scheme level="1">[11.]</scheme>
<scheme level="2">[11.][12.]</scheme>
<scheme level="3">[11.][12.][13.]</scheme>
<scheme level="4">[11.][12.][13.][14.]</scheme>
<scheme level="5">[11.][12.][13.][14.][15.]</scheme>
<scheme level="6">[11.][12.][13.][14.][15.][16.]</scheme>
</heading-schemes>
</numbering>

Created on , last edited on