Numbering

The topics in this section contain some technical details in case you need to fine-tune the way the numbering works.

Numbering - Built-in CSS

The built-in CSS rules are in:

[PLUGIN_DIR]/css/print/p-numbering-shallow.css
[PLUGIN_DIR]/css/print/p-numbering-deep.css
[PLUGIN_DIR]/css/print/p-numbering-deep-chapter-scope.css
[PLUGIN_DIR]/css/print/p-numbering-deep-chapter-scope-no-page-reset.css

The first CSS (shallow) contains rules that add a "Chapter NN" before the first-level topics from the publication, the second one (deep) contains rules that add a deep structure of counters on all topics referenced from the map (at any level), the third one (chapter-scope) creates a chapter scope-oriented numbering (meaning that the numbering for pages, tables, figures, and links to them are reset for each chapter), and the last one is similar to the third except that page numbers do not reset. For more details, see Numbering Types.

Edit online

Numbering - Input XML Fragments

The numbering affects multiple logical parts of your publication, the table of contents, headers/footers, chapter titles, figures and tables titles:

The Table of Contents

The table of contents is a tree of <topicref> elements.

<map xmlns:ditaarch="http://dita.oasis-open.org/architecture/2005/" ...>
  <oxy:front-page xmlns:oxy="http://www.oxygenxml.com/extensions/author" 
        class=" front-page/front-page ">
        ...
  </oxy:front-page>
  <opentopic:map xmlns:opentopic="http://www.idiominc.com/opentopic" class=" toc/toc ">
    <title class="- topic/title ">Publication Title</title>

    <topicref is-chapter="true" class="- map/topicref " ... >
      <topicmeta class="- map/topicmeta " ... >
        <navtitle href="#unique_1" class="- topic/navtitle ">Overview</navtitle>
            ...
      </topicmeta>
      <topicref class="- map/topicref " ...>
        <topicmeta class="- map/topicmeta " data-topic-id="dcpp_resources">
          <navtitle href="#unique_2" class="- topic/navtitle ">Resources</navtitle>
            ...
        </topicmeta>
      </topicref>
        ...
  </opentopic:map>
...
</map>

Note: The <opentopic:map> element contains the effective table of contents structure.

Note: The TOC items are the elements with the class: - map/topicref.

Note: The ones identified as chapters have the @is-chapter attribute set.

For the DITA Map PDF - based on HTML5 & CSS transformation type, the merged map is further processed resulting in a collection of HTML5 <div> elements. These elements preserve the original DITA @class attribute values and add a new value derived from the DITA element name.

<div class="- map/map map" ...>
  <div 
        class=" front-page/front-page front-page">
        ...
  </div>
  <div class=" toc/toc toc">
    <div class="- topic/title title">Publication Title</title>

    <div is-chapter="true" class="- map/topicref topicref" ... >
      <div class="- map/topicmeta topicmeta" ... >
        <div href="#unique_1" class="- topic/navtitle navtitle">Overview</div>
            ...
      </div>
      <div class="- map/topicref " ...>
        <div class="- map/topicmeta " data-topic-id="dcpp_resources">
          <div href="#unique_2" class="- topic/navtitle ">Resources</div>
            ...
        </div>
      </div>
        ...
  </div>
...
</div>

The Header and Footers

These are based on string sets generated for the titles. The complete set of strings is defined in: [INSTALLATION_DIR]/css/print/p-pages-and-headers.css.

The CSS rules that build the string sets are matching the map title from the front page and the titles from the content.

<oxy:front-page xmlns:oxy="http://www.oxygenxml.com/extensions/author">
        <oxy:front-page-title>
            <title class="- topic/title ">Publication Title</title>
        </oxy:front-page-title>
</oxy:front-page>

For the DITA Map PDF - based on HTML5 & CSS transformations:

<div class=" front-page/front-page front-page">
        <div class=" front-page-title/front-page-title front-page-title">
            <div class="- topic/title title ">Publication Title</div>
        </div>
</div>

The main content is organized as follows:

<map xmlns:ditaarch="http://dita.oasis-open.org/architecture/2005/" ...>
    ...
    <opentopic:map xmlns:opentopic="http://www.idiominc.com/opentopic">
      ...
    </opentopic:map>

    <topic is-chapter="true" oid="dcpp_overview">
        <title class="- topic/title ">Overview</title>
        <body class="- topic/body ">
            ...
        </body>
        <topic class="- topic/topic " id="unique_2" oid="dcpp_resources">
            <title class="- topic/title ">Resources</title>
            ...
        </topic>
        <topic class="- topic/topic " id="unique_2" oid="dcpp_parameters">
            <title class="- topic/title ">Parameters</title>
            ...
        </topic>
    </topic>

For the DITA Map PDF - based on HTML5 & CSS transformations:

<div class=" map/map map" ...>
    ...
   <div class=" toc/toc toc">
      ...
    </div>

    <div is-chapter="true" oid="dcpp_overview" class="- topic/topic topic">
        <div class="- topic/title title">Overview</title>
        <div class="- topic/body body">
            ...
        </div>
        <div class="- topic/topic topic" id="unique_2" oid="dcpp_resources">
            <div class="- topic/title title">Resources</div>
            ...
        </div>
        <div class="- topic/topic topic" id="unique_2" oid="dcpp_parameters">
            <div class="- topic/title title">Parameters</div>
            ...
        </div>
    </div>

Note: The topic content comes after the <opentopic:map> element.

Note: The child topics are the elements that have the class - topic/topic included in the parents.

Note: The ones identified as chapters have the @is-chapter attribute set.

The Titles of Chapters

The titles from the content are children of the topics:

<topic class="- topic/topic " id="unique_2" oid="dcpp_parameters">
        <title class="- topic/title ">Parameters</title>
            ...
</topic>

For the DITA Map PDF - based on HTML5 & CSS transformations:

<div class="- topic/topic topic" id="unique_2" oid="dcpp_parameters">
        <div class="- topic/title title ">Parameters</div>
            ...
</div>

Note: The title elements have the class: - topic/title. The actual element name can be different.

Edit online

Numbering Types

The type of numbering that appears in your publication is controlled by the args.css.param.numbering parameter.

This parameter activates various sets of CSS rules from the built-in CSS. By default, only the first-level topics (the chapters) are numbered (shallow numbering). The following values are accepted:

Table 1. Types of Numbering
Value	Chapters	Sections/ Nested Topics	Figures & Tables	Pages
shallow	numbered	no	counted from the start of the publication	from the start of the publication
deep	numbered	numbered	counted from the start of the publication	from the start of the publication
deep-chapter-scope	numbered	numbered	numbering is restarted at the beginning of each chapter, adds the chapter number in their titles (and in the links to them), and in the list of tables and list of figures sections	restarted at the beginning of each chapter
deep-chapter-scope-no-page-reset	numbered	numbered	numbering is restarted at the beginning of each chapter, adds the chapter number in their titles (and in the links to them), and in the list of tables and list of figures sections	from the start of the publication

Note: When using any of the deep numbering types, no distinction is made between sections and nested topics. For example, if a topic contains two sections, followed by another nested topic, the sections will be numbered with 1 and 2, and the nested topic with 3.

Notice: The deep-chapter-scope and deep-chapter-scope-no-page-reset values are only available for the DITA Map PDF - based on HTML5 & CSS transformation scenario.

Examples

Shallow

Each chapter (or first-level topic) is numbered, but sections/nested topics are not numbered. Figures, tables, and pages are numbered sequentially from the start of the publication and they do not reset.

Chapter 1. First Chapter
    Page 1
      Topic
        Section
          Table 1
          Table 2
      Topic
        Section
    Page 2
        Table 3
Chapter 2. Second Chapter
    Page 3
      Topic
        Table 4
        Table 5
      Topic
    Page 4

It will result in the following content inside the PDF:

Chapter 1. Introduction..............................................................1
Chapter 2. Care and Preparation......................................................2
  Pruning............................................................................2
  Garden Preparation.................................................................3
Chapter 3. Flowers by Season.........................................................4
  Spring Flowers.....................................................................4
    Iris.............................................................................4
    Snowdrop.........................................................................6
  ...

List of Figures
  Figure 1: Iris

List of Tables
  Table 1: Flowers

Deep

All chapters (or first-level topics) and sections/nested topics are numbered (these are also prefixed with the chapter number). Figures, tables, and pages are numbered sequentially from the start of the publication and they do not reset.

1. First Chapter
    Page 1
      Topic 1.1
        Table 1
      Topic 1.2
        Table 2
    Page 2
        Table 3
2. Second Chapter
    Page 3
      Topic 2.1
        Table 4
        Table 5
      Topic 2.2
    Page 4

It will result in the following content inside the PDF:

1. Introduction......................................................................1
2. Care and Preparation..............................................................2
  2.1. Pruning.......................................................................2
  2.2. Garden Preparation............................................................3
3. Flowers by Season.................................................................4
  3.1. Spring Flowers................................................................4
    3.1.1. Iris......................................................................4
    3.1.2. Snowdrop..................................................................6
  ...

List of Figures
  Figure 1: Iris

List of Tables
  Table 1: Flowers

Deep Chapter Scope

Each chapter (or first-level topic) is independent (so it can be read separately, as a separate part of your publication). The sections/nested topics, pages, figures, and table counters (and links to them) restart at each chapter. The general cross reference links also display the chapter number before the page number to clearly specify the target.

1. First Chapter
    Page 1.1
      Topic 1.1
        Table 1-1
        Link to page 2.2
      Topic 1.2
    Page 1.2
        Table 1-2
2. Second Chapter
    Page 2.1
      Topic 2.1
        Table 2-1
        Table 2-2
        Table 2-3
      Topic 2.2
        Table 2-4
    Page 2.2
       Link to page 1.1

It will result in the following content inside the PDF:

1. Introduction......................................................................1
2. Care and Preparation..............................................................1
  2.1. Pruning.......................................................................1
  2.2. Garden Preparation............................................................2
3. Flowers by Season.................................................................1
  3.1. Spring Flowers................................................................1
    3.1.1. Iris......................................................................1
    3.1.2. Snowdrop..................................................................3
  ...

List of Figures
  Figure 3-1: Iris

List of Tables
  Table 2-1: Flowers

Deep Chapter Scope No Page Reset

Each chapter (or first-level topic) is independent (so it can be read separately, as a separate part of your publication). The sections/nested topics, figures, and table counters (and links to them) restart at each chapter, but the page numbers do not reset. The generic cross reference links contain only the page number.

1. First Chapter
    Page 1
      Topic 1.1
        Table 1-1
        Link to page 4
      Topic 1.2
    Page 2
        Table 1-2
2. Second Chapter
    Page 3
      Topic 2.1
        Table 2-1
        Table 2-2
        Table 2-3
      Topic 2.2
        Table 2-4
    Page 4
       Link to page 1

It will result in the following content inside the PDF:

1. Introduction......................................................................1
2. Care and Preparation..............................................................2
  2.1. Pruning.......................................................................2
  2.2. Garden Preparation............................................................3
3. Flowers by Season.................................................................4
  3.1. Spring Flowers................................................................4
    3.1.1. Iris......................................................................4
    3.1.2. Snowdrop..................................................................6
  ...

List of Figures
  Figure 3-1: Iris

List of Tables
  Table 2-1: Flowers

Tip: When using deep numbering, if you want to exclude sections from being numbered, see How to Include Topic Sections in TOC.

Edit online

How to Reset Page Numbering at First Chapter/Part

By default, pages are numbered from the start of the publication, but in some cases, you may need to restart the page numbering at the first chapter of your publication.

Warning: The following sections do not apply for args.css.param.numbering="deep-chapter-scope" because it already define a specific numbering scheme that resets the page number at each chapter.

Reset Page Numbering in Shallow Context

To reset the page counter at the first part/chapter when the args.css.param.numbering="shallow" parameter value is set, use the following rules in your customization CSS:

*[class ~= "map/map"] > *:not([class ~= "topic/topic"][is-chapter]) + *[class ~= "topic/topic"][is-chapter] {
  counter-reset: page 1;
}
*[class ~= "map/map"] > *:not([class ~= "topic/topic"][is-part]) + *[class ~= "topic/topic"][is-part] {
  counter-reset: page 1 chapter;
}

Reset Page Numbering in Deep Context

To reset the page counter at the first part/chapter when the args.css.param.numbering="deep" parameter value is set, use the following rules in your customization CSS:

*[class ~= "map/map"][numbering ^= 'deep'] > *:not([class ~= "topic/topic"][is-chapter]) + *[class ~= "topic/topic"][is-chapter] {
  counter-reset: page 1 section1;
}
*[class ~= "map/map"][numbering ^= 'deep'] > *:not([class ~= "topic/topic"][is-part]) + *[class ~= "topic/topic"][is-part] {
  counter-reset: page 1 chapter chapter-and-sections;
}

Reset Page Numbering in Deep Chapter Scope No Page Reset Context

To reset the page counter at the first part/chapter when the args.css.param.numbering="deep-chapter-scope-no-page-reset" parameter value is set, use the following rules in your customization CSS:

*[class ~= "map/map"][numbering ^= 'deep'] > *:not([class ~= "topic/topic"][is-chapter]) + *[class ~= "topic/topic"][is-chapter] {
  counter-reset: page 1 section1 tablecount figcount !important;
}
*[class ~= "map/map"][numbering ^= 'deep'] > *:not([class ~= "topic/topic"][is-part]) + *[class ~= "topic/topic"][is-part] {
  counter-reset: page 1 chapter chapter-and-sections section1 tablecount figcount !important;
}

Edit online

How to Use Part, Chapter, and Subtopics Numbers in Links

This topic is applicable if you have enabled deep numbering. Suppose you have a link in the third chapter that points to a paragraph in the second subtopic of the first chapter and you need this structural information (1.2) presented to the user, just after the link text. To do this, you can use the target-counters CSS function to extract the entire context of the counters from the target. The chapter-and-sections built-in counter is already updated with both the chapter number and the nested topics:

*[class ~= "topic/xref"]:after {
	content: target-counters(attr(href), chapter-and-sections, ".") !important;	
}

This counter does not include the part number, so be careful when linking between parts (consider adding the target part number explicitly):

*[class ~= "topic/xref"]:after {
	content: "[" target-counter(attr(href), part, upper-roman) "/" target-counters(attr(href), chapter-and-sections, ".") "]" !important;
	color:blue;	
}

Edit online

How to Include Topic Sections in TOC

To include topic sections in the table of contents, set the args.css.param.numbering-sections transformation parameter to yes. In this case, they are numbered according the numbering scheme set by the args.css.param.numbering parameter.

If you want to prevent topic sections from being numbered in your output, set the value of the args.css.param.numbering-sections parameter to no.