Version 8.8 of DoX CMS includes notable changes to the underlying structure of titles and internal links. The table of contents will also reflect these changes. I will list these changes here and also address challenges and opportunities related to them.
I first discuss the changes that we made to the structure of the publication template and the reasons behind them. Afterwards, I address how these changes will affect our users. Whenever the publishing template changes, you must make sure whether such changes require you to adjust your style sheets. In this instance, we know of at least one issue, where we already have a recommended fix for the affected styles. Publications which were approved as part of the workflow will still use the prior template and thus be unaffected by these changes.
Changes to the publication template
As part of the update, we added named sub-sections to each of these parts of a publication. Use these sub-sections to control the visibility, layout, or style of any of these parts. This is a considerable extension to your ability to change how they look.
Each section below shows both the old format of these elements and the newly added structure. This lets you compare them and see the changes. Such comparisons are particularly useful if any part of your styles broke as a result of this update. I will address such potential issues below, as well as the benefits made available by this update.
Table of contents
In the old publication template, there was only an empty space between the number and title for each item in the table of contents. As such, you could not change the spacing between them. Now both have their own frames to which you can apply styles such as a set width.
X is the level of organization for that item in the table of contents. Y is the number of that chapter. Z is the page number for that chapter. Tocdots and tocpagenum are only included in paged publications and do not show as part of a publication’s preview as a result.
<li class="tocline toclineX">
<a class="toclink" href="topic_link_Y">
<span class="tocheading tocheadingX">Y Title</span>
<span class="tocdots" />
<span class="tocpagenum tocpagenumY">Z</span>
</a>
</li>The parts that we added are
- dox-topic-title-number,
- dox-topic-title-space, and
- dox-topic-title-value.
These values are applied around a chapter’s number, the empty space, and its title, respectively. The empty space has its own identifier so that you may control it independently despite us keeping the space to not change what current users’ publications look like.
<li class="tocline toclineX">
<a class="toclink" href="#topic_linkY">
<span class="tocheading tocheadingX">
<span class="dox-topic-title-number">Y</span>
<span class="dox-topic-title-space"> </span>
<span class="dox-topic-title-value">Title</span>
</span>
<span class="tocdots" />
<span class="tocpagenum tocpagenumY">Z</span>
</a>
</li>Titles
The affected titles include both chapter titles and elements’ titles.
Chapter titles
Unlike in the old table of contents, the number in chapter titles themselves has always been something that you could control independently.
X is the level of organization for this chapter. Y is its number.
<hX><span class="titleNumberWrapper">Y </span>Title</hX>The new format for chapter titles includes the same new identifiers and structures as items in the table of contents, shown above.
<hX>
<span class="titleNumberWrapper dox-topic-title-number">Y</span>
<span class="dox-topic-title-space"> </span>
<span class="dox-topic-title-value">Title</span>
</hX>Elements’ titles
Elements have two types of titles: those with a value added in a title field in the editor and those without one. Strictly speaking, a third type would be section elements that have a value written in their title field, because they never have associated numbers. This lack of numbering makes them irrelevant in this context, though.
The value ‘element title settings’ represents the format set in the Settings menu. You can add internal structure to this value in other ways. I have previously discussed methods to add structure to element titles.
<div class="dita-title"><span class="anchor-title">[element title settings] </span>Title</div>
<span class="anchor-title">[element title settings]</span>Here, the new values that we added are
- dox-dita-title-anchor,
- dox-dita-title-space, and
- dox-dita-title-value.
Even though these values differ slightly from those used for chapter titles, they share the same purpose. They make each part something to control independently but we will not remove any part to keep old styles useful.
<div class="dita-title">
<span class="anchor-title dox-dita-title-anchor">[element title settings]</span>
<span class="dox-dita-title-space"> </span>
<span class="dox-dita-title-value">Title</span>
</div>
<span class="anchor-title dox-dita-title-anchor">[element title settings]</span>Links
Similarly to the table of contents, links to a publication’s chapters only allowed you to control the visibility of their components with the kinds of indirect means that I have discussed before. They now allow you to hide parts of the related titles when needed and independently of whether or not the titles themselves show those parts.
We made no such changes to links to elements.
X is the ID value of the topic element. Y is the number for the matching chapter.
<a class="doxInnerReference href="#X"><span class="reference-title">Y Title</span></a>The internal structure of links to chapters is the same as the internal structure of the titles themselves, shown above.
<a class="doxInnerReference" href="#X">
<span class="reference-title">
<span class="dox-topic-title-number">Y</span>
<span class="dox-topic-title-space"> </span>
<span class="dox-topic-title-value">Title</span>
</span>
</a>Challenges
No change to the underlying structure is without risks. As such, you must review your unapproved publications extra carefully immediately after this update. We are already aware of some inevitable challenges. Fortunately, the solutions to those challenges are simple and also already known. I will introduce those solutions below as well.
Copies of an outdated default table of contents style
This is the greatest challenge related to these changes. It is a matter of the layout for the table of contents in style sheets where the rules for it were copied from our old default style sheets before we corrected these issues. At least the fix is both simple and already available in the updated default style sheets. However, we cannot use automation to fix it because we abstain from automated changes to our customers’ style sheets for this, and because copied rules are not controlled through changes to the default style sheets.
The problem is how the old default style sheet had some rules for the table of contents where they were written under the misplaced assumption that those parts would only ever contain the standard set of span elements. As such, the author forgot to specify that those rules should only apply to the span elements directly inside specific parts. These rules in old files based on that one thus target all span elements anywhere inside those parts. This also affects cases like variables inside titles.
This involves the parts shown below that you can search up in your own style sheets.
ul.toccontent a {
display: table;
}
ul.toccontent a span {
display: table-cell;
}
ul.toccontent a span:first-child {
position: relative;
overflow: hidden;
}
html[data-document-type="dox-pdf"] ul.toccontent a span:first-child:after {
position: absolute;
margin-left: 0.3em;
width: 100%;
content:
". . . . . . . . . . . . . . . . . . . . "
". . . . . . . . . . . . . . . . . . . . "
". . . . . . . . . . . . . . . . . . . . "
". . . . . . . . . . . . . . . . . . . . "
". . . . . . . . . . . . . . . . . . . . "
". . . . . . . . . . . . . . . . . . . . "
". . . . . . . . . . . . . . . . . . . . "
". . . . . . . . . . . . . . . . . . . . "
". . . . . . . . . . . . . . . . . . . . "
". . . . . . . . . . . . . . . . . . . . ";
}
ul.toccontent a span + span {
text-align: right;
width: 1%;
vertical-align: bottom;
padding-left: 0.3em;
}We show a fix to this in our user manual. It is just a matter of adding ‘>’ characters to several spots, as shown below, where the targets consist of span elements inside a elements. Do not copy and paste all of this in case your style already involves some changes to the rules involved. Just add the missing characters to the selectors shown below.
ul.toccontent a {
display: table;
}
ul.toccontent a > span {
display: table-cell;
}
ul.toccontent a > span:first-child {
position: relative;
overflow: hidden;
}
html[data-document-type="dox-pdf"] ul.toccontent a > span:first-child:after {
position: absolute;
margin-left: 0.3em;
width: 100%;
content:
". . . . . . . . . . . . . . . . . . . . "
". . . . . . . . . . . . . . . . . . . . "
". . . . . . . . . . . . . . . . . . . . "
". . . . . . . . . . . . . . . . . . . . "
". . . . . . . . . . . . . . . . . . . . "
". . . . . . . . . . . . . . . . . . . . "
". . . . . . . . . . . . . . . . . . . . "
". . . . . . . . . . . . . . . . . . . . "
". . . . . . . . . . . . . . . . . . . . "
". . . . . . . . . . . . . . . . . . . . ";
}
ul.toccontent a > span + span {
text-align: right;
width: 1%;
vertical-align: bottom;
padding-left: 0.3em;
}Effects of the changes to customers’ styles
If you have rules related to otherwise unspecified span elements in positions that match these additions to the publication template, such rules may now target the added parts. The changes may also remove such rules from use from their intended targets, especially if you use counters that target based on ordinal values. When the first span element changes, for instance, the new one becomes the target for a rule like that.
Another noteworthy detail is how empty spaces are now inside their own element which lies next to the one for numbers instead of being inside the element used for numbers. As such, details like standardized indentation for chapter titles, where they rely on a specified width for the numbered part, will not exactly correspond to their original look. The difference is the width of one empty space. You can return the original width if you hide the empty space in those positions with, for example, the following addition to your style sheets:
.titleWrapper .dox-topic-title-space {
display: none;
}Changes to the styles used with approved publications
Publications that were approved before this update will still use the original publication template. The associated saved styles will also remain as they were. However, the system only saves the style designated to be used by that publication when it is approved. Some publications require you to use several styles, and thus, the other styles used like this will include any changes made to account for this update. If some of these changes also target the prior identifiers or rules originally targeted in outdated ways now target the new identifiers, there may be differences when such styles are used with old approved publications.
The best way to avoid such issues would be to maintain separate styles for such old publications, of course. However, this would fill the list of styles with options which are useless for future publications. Another option would be to include the old rules for old publications with the help of selectors which only apply to them. If the number of such publications is large, though, the amount of work involved would be unreasonable.
Fortunately, this issue only applies when multiple styles are needed for one publication, and only when updates tyles are incompatible with the old publication template. Users can control the extent to which the second condition applies. Thus, if you have publications that require the use of multiple styles, be careful when you edit those styles and make sure that any changes do not break old publications when those styles are used like this.
Benefits
The challenges listed above are nothing compared to the benefits that these changes bring. If this was not the case, we would not have made these changes to the publication template. The most important benefits are listed below. To make parts which you could not control independently before into parts that you can removes limitations on what users may target with their style sheets.
Full control over visibility
Have you wanted to hide either the chapter number or chapter title in links to a publication’s chapters? Especially when multiple levels of organization are involved, the number can become rather long together with the full title. In a printed publication, this number is more helpful for finding the related part, though, In an electronic publication which relies more on content searches and links, this value can be completely redundant. Now, you can account for either situation with more targeted styles, because now you can freely either hide or display such details.
The same is true of the table of contents where you can now hide whichever information you want from each listed chapter. As such, online publications such as WebHelp manuals need not show chapter numbers at all, given how they are less important when different parts are not expected to be read in a linear fashion.
Subsequently compiled publications
A big reason behind this change was also how some of our customers expressed their desire to compile publications based on decisions about options that their users made in their portal only moments before. We could in principle achieve this by sending such requests to their environment, but this would require quite a complicated integration involving several providers. As such, we recommended that all that content first gets published from our system as a HTML file that contains each option made available to their users to select from. Our customers can then use these HTML publications as templates from which they can hide parts based on what their own users select before such publications with adjusted styles get compiled into PDF files inside their own server. This option removes the need to work with interfaces between multiple systems, as well as the need for multiple companies to cooperate, and so on. It would not be available without this update, though.
This update was needed to help with this because only hiding different sections would not change the values for the various hard counters used with chapter numbers as well as the numbering of figures and tables in an already compiled publication. This would have the removed portions leave behind gaps in these values.
However, if these values were hidden from the start in that publication and replaced with the same values frm counters tied to a style sheet, these new values would always update to only count whichever parts were shown. This would make the numbering remain continuous for each publication where you change which parts get shown.
Those who plan a similar implementation based on what I said should note how the customer in question had in use an implementation for their documentation which made this require the least possible amount of work. In particular, links to tables and figures make attempts to implement this considerably more complex if you want to use such updated numbering for them.
Other forms of styling
Of course, you can also now manage the styles of these parts in a targeted way in general. The most important ways to do so would likely involve setting standardized indentations between chapter numbers and titles in the table of contents. Previously, there was only an empty space between the two, and they were both part of the same element without any additional structure around either.
Now, you can control this indent by, for example, defining a standardized width for the chapter number, or by adding some padding to the left of the title. Either one of these changes requires you to set these parts to be displayed as ‘inline-block’ to keep them as inline elements, which can still have features meant for block elements such as standardized width or padding. The first of these options standardizes the distance between where the chapter number starts and where the title starts. If this number becomes longer, the title does not move further right. The other option standardizes the distance between where the number ends and where the title starts.
Other alternatives include text effects like bolding being targeted at only the parts which were previously not able to be controlled independently. You can also use colors like this if, for example, you want to make title numbers lighter to keep them visible but to also guide readers’ attention towards the actual titles.
Summary
Version 8.8 of DoX CMS includes changes to the structure of the publication template. You can now control all the parts for chapter titles independently in different places alongside element titles. Even though links to chapters are included in this, links to elements are not. A similar implementation for them would be considerably more complex because only some elements have titles, for example.
No change to publications’ underlying structure is without risk. If old style sheets have rules that are targeted in ways that will affect the new structures, or the new structures move selectors’ targets out of their reach, you must adjust those style sheets to match the new template. Unfortunately, many old style sheets contain an error copied from our old default style sheets, and this error breaks the updated table of contents. Less unfortunately, the fix to that error is small, and we already include instructions for it it in our user manual. Already approved publications still use the old publication template, so such details in their saved styles do not affect the results. However, this also means that later changes in styles can be incompatible with these old publications, if they are designed to be published using multiple different styles.
However, the benefits from this change are worth it. This update makes parts that could not be controlled independently with style sheets available to be controlled independently like this. This allows you to finally set the visibility, layout, and style of parts such as the chapter numbers and titles in the table of contents. The options include standardized indentation greater than one empty space between these two parts, for example. You can also now hide any and all such numbering and add replacements with your style sheet. The benefit of doing this is that such numbers will then update if you hide parts of the publication after it has been published. As such, you will be able to filter out numbered parts if you were to, for example, compile PDF files based on options that your users selected from a HTML publication that has all of them. No extensive system integration would be required for this.
As always, we will answer any questions regarding the ideal ways to fully access the benefits from this update.