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.
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>
<opentopic:map>
element contains the effective table of
contents structure.- map/topicref
.@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.
<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>
<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>
<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>
<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>
<opentopic:map>
element.- topic/topic
included in the parents.@is-chapter
attribute
set.The Titles of Chapters
<topic class="- topic/topic " id="unique_2" oid="dcpp_parameters">
<title class="- topic/title ">Parameters</title>
...
</topic>
<div class="- topic/topic topic" id="unique_2" oid="dcpp_parameters">
<div class="- topic/title title ">Parameters</div>
...
</div>
- topic/title
. The actual element
name can be different.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:
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 |
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
- 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
- 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
- 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
How to Reset Page Numbering at First Chapter/Part
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;
}
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;
}
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.