Most users never participate in setting up covers. The rest must just add the occasional new conditional value to them.
These circumstances make it all the more important to discuss how covers are made. This way, such practices won’t be a mystery. Current implementations can also be improved by understanding them better.
Such information will help understand your current implementation when problems occur or you must update it. Use this information to help plan the details when you implement or commission an update to your covers. Despite how you receive your initial covers as part of setting up DoX CMS, the observations here help relate to the process of putting them together. They tell you, for example, what kinds of information must you provide to us for the best results.
Implementations
Covers have no one true implementation. Different publication formats can involve different covers, and the available implementations for them are surprisingly varied. These are the implementations that I have witnessed or introduced myself.
The throughline between all of them is that they involve templates written in the text editor. The involved topics have been designated to be used as covers. This lets you select them them as covers in publication templates’ settings.
Use cases
Covers with different use cases require slightly different implementations. It can prove surprising, though, just how freely you can adapt the same original files for them.
Front and back covers
The clearest distinction between use cases for covers is between front and back covers. The system only distinguishes between them when you select these covers for a publication. Any topic designated as a cover can be selected for either type of cover page.
As you browse through style sheets, note how selectors for these two types of covers use completely different identifiers. The front cover is designated with ‘coverPageWrapper’ and the back cover with ‘backCoverPageWrapper’. There are no shared identifiers with which to add rules that apply to both.
Often, back covers are actually left completely empty which means that there are no rules to be found for them. An occasional exception are rules about page groups in style sheets used with DocRaptor. They specify, for example, that those pages have no headers or footers.
These two parts also work best with slightly different rules for positioning content because they are at either vertical end of a publication. If, for example, they have absolute positions, pieces of content in the front cover are usually positioned relative to the top of the publication and content in the back cover relative to its bottom. Doing so is not strictly necessary because absolute positions exist relative to the next highest positioned element in the content hierarchy. As such, adding rules that position the frames around these parts would let you position their parts relative to those frames’ top and bottom borders regardless of their type.
In practice, then, when you write or inspect covers, you must account for how these two types of covers require entirely unrelated selectors and often also different rules in style sheets. Even empty back covers must be added to publications and there must be topics dedicated to them. Unless, of course, you just add the same cover topic twice and then tell the compiler to hide all its content in the back cover.
Publishing Formats
Online publications can also have cover pages. In practice, they act as welcome pages when content is presented in separate page entries. Likewise, both paged publishing formats, PDF and DOCX, actually have quite different requirements.
It would be intuitive for the covers for each publishing format just to use different topics altogether. It would prevent the use of shared publication templates, though, and thus limit the benefits of structured authoring. After all, one of its key benefits is the separation of content and style. That separation allows for the same content to be published with different styles and in different formats. To use different topics is thus not only unnecessary but also a hindrance. If your implementation relies on them, check if even your circumstances require their use.
In DoX CMS, you can specify the rules in a style separately for each publishing format. The attribute used for this is data-document-type. Thus, the parts related to this read as ‘[data-document-type= dox-html=””]’, for example.
The parts designated like this can be used to control different sections’ visibility, too. The rule ‘display: none;’ hides the designated content in the publishing format specified in its selector. Do note that this does not remove that content from the publication, though. In online publications, for example, users can retrieve it with help from the developer view of their browser. As a result, never leave any content that they must be unable to access in there.
Rules specified in this way can change the layout in other ways, too, such as by using different rules to position content in DOCX publications. Covers are particularly problematic for them because this publishing format does not allow the use of the most commonly applied rules for covers like repositioning and background images.
Another, slightly more awkward method to achieve the same result involves the use of sufficiently differentiated sections per style sheet and putting together separate styles from multiple style sheets each. The parts that define each publishing format’s covers separately can thus use different style sheets instead of the identifiers discussed above. You can also do this as part of separating the overall styles for different publishing formats into different style sheets. The difference in practical terms is that you must then select the correct style for each publishing format when you publish content in it.
Selectors
Selectors designate the affected parts for sets of rules that add styles to content. Covers involve more options for them because they involve rules applied to individual elements rather than general sets of rules. Below are the three implementations with which I am familiar.
Counting elements
Selectors can target elements based on their order. For example, you can target the third paragraph within the specified type of element wrapped around them. The selectors used for this involve the pseudo-class ‘:nth-child(x)’ where x is the ordinal value of that type of element inside another element.
This is the most commonly used solution but it is my least favorite as the primary implementation. There are two reasons for this.
Firstly, this is a principle which is completely obscured from users. If they do not know how the style functions, they can accidentally break the layout of their covers by making changes to their contents. Just adding a new element or removing an old one is enough. Each action shifts which section a given set of rules in the style sheet affects. I have met my share of users confused by this.
Secondly, these style sheets are a pain to read. They do not directly inform whoever is editing them which part is involved with each set of rules. You must also update the values for each section below the affected part whenever you change the number of elements. This makes these implementations feel disposable because they fail to account for the eventual need for updates.
On the other hand, such implementations do not require any additional classifications. This makes me consider it a suitable option as part of a wider implementation. You can, for example, use such counters for paragraphs inside sections which have been marked in other ways.
Element classes
My first attempt to resolve the issues with visibility to users used element classes to distinguish the different parts of a cover. This makes the text editor show that each part has been designated a role. It is also easier to make new covers when you just need to add the correct classes to each part. Users need not know the correct order and number of these parts in advance.
When the layout uses absolute positions, these parts need not be set into their final order for them to have the correct layout once published. This was a minor secondary benefit that I hoped would help users when they needed to add new covers.
The problem is how these element classes are effectively single use. Usually, one set of covers is enough. They dilute the list of element classes and this makes them an obstacle when you need to use other element classes.
In principle, you could just directly edit those parts to have these values as part of the raw content. These element classes would then not need to actually be added to the system. From the perspective of style sheets, it makes no difference. For users, though, this arrangement would be no less confusing than parts without identifiers. Most of them are unlikely to know that you can freely add values to element classes as part of the raw content.
ID values
In general, references to ID values in style sheets are not recommended. In this case, they are the only identifier for these elements that users can control directly, though. The problem is how each ID value can only ever be used once per publication. For covers, that only becomes an issue when the same publication includes multiples of the same covers. As such, only multilanguage publications are affected.
This achieves the benefits of element classes without their issues. You can also set these values up in ways which let you classify them in style sheets. Shared values at the start or other included keywords allow you to specify rules for each section that matches such criteria simultaneously. For more information on how to use attributes in style sheets, see here.
I personally mainly use ID values with section elements and then counters for the paragraphs inside them. This combines the best aspects of both methods. Each part has a clearly expressed role but every single one does not require its own identifier.
Content structure
For the used topics, the other difference between implementations involves how those topics are structured. The default option for most is just a DITA topic with each part as its own paragraph.
You must include all these topics in at least one translation project for each language. Such translations are needed even when the topics contain nothing to be translated. Translation files for publications already include their covers, of course, unless those revisions have not already been translated to said languages.
Sections
Section elements function as frames for sets of other elements. They allow you to position several successive parts at once, for example. You can also connect pagination rules to them. And in the case of DocRaptor, you can use them for distinct page groups for the content before the table of contents.
I really recommend that you include these sections in your covers when the time to update them comes.
Style sheets refer to these sections with the class ‘dita-section’.
Hidden tables
Tables with invisible frames are a classic method for adding aligned columns. They are particularly common in headers and footers. Covers can also benefit from them when different parts of the content must be aligned onto rows with defined indentation for each.
Please note that these tables are problematic for users of screen readers. Those read the content of each cell separately and not always in an intuitive order.
Phrase elements
At times, seemingly redundant phrase elements are required for content layouts. They allow for more levels of organization which may be required by rules defined relative to the preceding level of organization. You can also define their widths, for example. You can adjust where content on the same row starts horizontally in a way similar to hidden tables.
Also note how variables always include a phrase element as their outer frame.
A tagged phrase element in a cover can also add a warning that this is not the final version which you can only show in drafts. For now, controlling visibility like this requires its own tag category and you must remember to remove that tag from use at the end of the review process.
Publications are compiled from HTML templates and thus, references to phrase elements must refer to them as span elements. Not all span elements correspond to them, though, because they are also used elsewhere in the template.
HTML topics
You can also use HTML topics in DoX CMS. Seeing them in use for covers is decently commonplace because covers are often left unchanged for years. The system used to be based on HTML before we adopted DITA.
HTML topics may also have been selected later because the text editor for them shows paragraphs with borders. This would make counting elements at least a little clearer.
HTML topics can also have horizontal lines. Despite DITA not having them as a distinct type of element, you can still add them with the help of bottom borders of elements, for example.
Variables
Variables are an essential parts of covers because they allow for one cover to be adapted for any publication. You can also make content in the actual cover conditional but it is often easier and safer to only edit variables instead of the covers themselves. Many of these variables are also often needed as part of content outside covers.
Types of variables
Different details require the use of the correct types of variables which show the correct information with minimal effort. Here is a list of the different types of variables and suggestions for how to use each of them.
Simple variables
Simple variables are just single-sourced pieces of inline content that you cannot translate. Their uses are surprisingly varied, though. You can also adjust their values when needed with tag filters or by embedding other types of variables.
The most obvious use case for simple variables are model numbers or other untranslated identifiers. These should still use filters much of the time. They can also be used outside covers, of course.
Simple variables are also a good option for adding images. To be sure, cover images are rarely used elsewhere. The use of variables for them allows you to keep covers closed to direct edits, though, and to use the same images for more than one set of covers if need be.
You can also combine the values from several other types of variables.
Complex variables
Complex variables are identical to simple variables with the exception that their values differ between languages. This also means that they have no values unless they have been included in translation projects to the used language at least once. They are included by default in the first translation project to that language after they have been added, though. However, this remains an unnecessary source of potential issues if the values in question need not be different across languages.
In covers, complex variables should be used for defining the type of manual, for example. Device types are also often something that needs to be translated. If its model number is included alongside its type, you can combine these two data points using two variables. This way, translations need not include any model numbers that must remain constant.
Publishing variables
The values of publishing variables are written separately for each publication. They are thus the correct option for delivery-specific serial numbers, for example, or adding values related to special orders. Remember that you can divide parts of these values between multiple variables and then combine those values. For example, language codes are available directly as a system variable.
Unfortunately, custom date formats currently also require that you write the dates yourself. The system variable for dates uses the date format mm/dd/yyyy without adding zero before single digit values. You can have the date format that you want by having separate publishing variables for each of these values and then organizing them inside a simple variable in the format that you prefer. Developing system variables to account for such variation is a high development priority, though.
Because you must write the values of publishing variables, you cannot use them for images that vary between publications, for example. However, there are other means to control images separately for each publication.
System variables
DoX CMS includes various system variables that let you fetch values from the system’s database to use in publications.
This way, the cover or other values inside it can include details such as
- the language identifier for the publication,
- the different parts of the publication’s revision number,
- the publication template’s name, or
- the username who published the content to be used in drafts.
Our manual contains a full list of system variables.
Embedded variables
You can use variables inside other variables despite the text editor for variables not showing a list of other variables. To do so, you just write their names inside two pairs of curly parentheses as part of the content of another variable.
I have mentioned several ways to use such embedded variables already. Some examples include
- adding special characters such as ™ or ® after the value of the embedded variable,
- date formats compiled from publishing variables,
- values that combine values that are also used independently such as the type and model of a product together, and
- identifiers compiled from several pieces.
Identifiers compiled from several pieces are woefully under-utilized. I mainly see people just use publishing variables which you need to write in full for each publication. They depend on you both remembering the correct value and not mistyping any part of it. Even though these values often include a unique portion which can still be included as a publishing variable, the other parts can be covered by variables with conditional content. You can then pull all these values together by embedding them all in sequence inside one variable. This adds the correct values when you just select the tags that correspond to them. Oftentimes, filtering the content properly would already require the use of those tags.
For example, the raw content for such a variable could be ‘{{ProductID}}{{VersionID}}{{DeliveryID}}/{{Language}}’, where ProductID and VersionID are simple variables with conditional content, and DeliveryID is a publishing variable. You can also add reminders such as how many numbers each of them includes as part of their names. The published result could be a code such as ‘671025567/EN’ which consists of those components but does not show distinct values for them in the final result, unless you know the principle behind the value.
Style rules
Besides their structure and other used content, covers obviously consist of the parts in style sheets which define their layouts. For covers, the most important rules relate to positioning content and image details. Other details such as typefaces and font sizes are a part of these implementations. However, you need not consider them past your own brand style guide.
Layout
Different parts have carefully specified positions, and you must place them there with various positioning rules.
Do note how using the same styles for online publications as well means that you need to be prudent about which units you use. Absolute units such as millimeters are acceptable in paged publications. Online publications, though, also need to account for differences between viewport sizes. You can also use styles that vary based on the used device.
Position
If the cover layout does not just consist of normal text rows, the most common means of adjusting positions is absolute position relative to higher level content. The content in question must use the rule ‘position: absolute;’ as well as coordinates along the horizontal and vertical axes. You specify these relative to the right or left side, and the top or bottom end. Each value specifies where that element starts. Reading from left to right, this means the top-left corner of the element.
Absolute positions remove that content from the normal flow of content but this only applies after space has been reserved for that content. This entails that it can leave behind empty pages if the content positioned like takes up more than one page. As a result, do not stuff your covers. If there is not enough space otherwise, you can also consider extending content horizontally rather than vertically with the help of invisible tables, for example.
Absolute positions do not work in DOCX publications, for example, because the compiler that we use does not allow moving content. An alternative in situations like this is to use the margin values of different parts, instead.
More specifically, people usually use padding values for this because margins can collapse to only leave the larger value behind. This makes implementations based on paddings more predictable. In this case, remember to remove any margins from these parts to avoid them messing with calculations.
The limitation of such implementations is how all content must remain in its initial order. The number of rows that any given part uses also cannot change because this would affect the positions of all content below that part. Having multiple pieces of content on the same horizontal line requires either invisible tables or phrase elements with specified widths.
Dimensions
You can also specify the dimensions of various parts. This lets you define the allowed line width, for example, when it is preferable to have the content split on multiple rows rather than overlap with the product image, for example.
By default, not all types of elements let you determine their dimensions. Any such element can be forced to accept specified dimensions, though. This simply requires that you change their display mode to something compatible with specified dimensions. Thus, phrase elements, for example, can be primed with rules such as ‘display: inline-block;’ or ‘display: block;’ to allow you to control their dimensions. These two are not the only options.
Besides the actual width and height values, pieces of content can also have minimum dimensions (min-width and min-height) as well as maximum dimensions (max-width and max-height). In the case of specified maximum values, content past them is subject to overflow rules. You can use these values to limit how images in particular settle without specifying exact values which may also distort the aspect ratio. For example, upper limits make sure that scaling stops before the image can overlap with other content along either axis.
Partitioning
Often, cover files include more than just the outside covers. The used topic must contain all parts which precede the table of contents. (Technically, you can bypass this limitation in some publications. But the methods for that are not worth the hassle.)
I recommend that you add a page break before the contents of the inner cover and preferably before each such section. This way, the layout of each can be determined independently without needing to worry about preceding parts. Section elements are ideal as a means to differentiate these parts. As a result, you can add page breaks to these sections based on their count or identifiers.
Besides the outer covers, such sections include legal text, such as copyright statements, and revision tables.
If the legal disclaimer must be repeated across multiple cover files, you can use content references (conref) or just a variable with the whole disclaimer. This keeps it consistent across all publications even with different covers. The parts that differ can still filtered with tags. I recommend that you use margins to place them vertically and possibly also set width limits for the text.
Revision tables are specific to each publication. As such, you must make them conditional properly. Depending on the needs for the implementation, I would use a variety of elements for this:
- Full table: Each table has its own title.
- Tablebody (tbody): Shared title but distinct tables. Add these inside full tables as the default elements inside that frame.
- Simple table: There are no titles.
Shared values for the header rows of these tables are kept consistent easily with the help of complex variables. This also updates them in each table simultaneously if you must change them.
You can link to the parts that were changed here and if you use DocRaptor to compile publications, these links can show the page numbers for the pages where those parts start. There is an example implementation below.
#Cover_Revision_History a[href^="#"]:empty::before {content: target-counter(attr(href), page);}
#Cover_Revision_History a[href^="#"]:empty:not(:last-of-type)::after {content: ", ";}This would make links inside the element designated with the ID value ‘Cover_Revision_History’ (section or table) fetch their target’s page number when those links target other parts thanks to the target value that starts with # and when they are left empty. When it is not the final value like that, the page number is automatically followed by a comma.
Simpler solutions for this would be possible but I wanted to be maximally unambiguous. The requirement that the link element be kept empty makes sure that other internal links in the same section are not subjected to these additions. In part, I am abusing a tiny bug here. The way in which covers are compiled entails that internal links inside covers cannot automatically add the numbers or titles with which they usually identify their targets. For the same reason, numbered elements inside covers do not count for the numbering of the rest of those elements in the publication.
You can also hide some of these parts in some publication formats when you apply the rule ‘display: none;’ to them in those formats. This only hides that content and does not remove it. The distinction matters because users can retrieve the content in online publications.
Images
Cover images require some additional consideration besides just their position. The required rules relate both to how you add the images and then adjusting how they get displayed.
Background images
It can feel like he obvious correct choice to use background images for cover images. This is especially true for any background graphics which remain constant across products.
The big issue with background images is how they can only continue for the length of the element that they were applied to. At times, this leads to unpredictable behavior. Even if you define the height of that element, the background image might only show for the portion which corresponds to its actual content.
Additionally, our default PDF compiler does not provide an bleed zone for cover images set up as background images. DocRaptor has one for printed publications where you use a larger sheet for covers before cutting them from it. Without a bleed zone, the smallest part that creeps past the page break will show on the next page. In such cases, you must set up at least background images filled with colour with pixel precision. I cannot thus recommend this option with them, at least.
In fact, I do not generally recommend the use of background images for cover images at all. You can add the images inside the topic and then place them relative to other content with absolute position rules. Moving them like this does not function in DOCX publications. But then again, neither do background images. That publication format practically requires that you design covers with its limitations in mind from the start if you want them to look viable.
Depth layer
Some users of absolute positions may initially face the challenge of images covering text. You can change this by reordering that content. It is a clumsy solution, though, and the operating logic may not be clear to later users.
Instead, you can also use a separate rule that determines the depth layers used by content. This lets you push images behind all text. The rules used for this is z-index, and the parts with higher values for it settle on top of parts with smaller values. The easiest method here is to just add the rule ‘z-index: -1;’ to all cover images used as backgrounds. This pushes them behind other content by default.
Transparency
You can fade images by making them partially transparent — especially when the page behind them has a solid color. The rule used for this is ‘opacity’ which has values between 0 and 1. Smaller decimal values entail more transparent images.
You can obviously achieve this with edits to the images in advance. The presented option lets you bypass that stage whenever you must add more such images to the covers or when the same images are also used elsewhere in the publication.
Summary
For many, covers are just a means to satisfy the conditions in the style guide when their environment is set up. We help set up environments by also writing the styles for covers. All too often, the used solutions become a mystery to the users. A better understanding of these implementations allows you to discuss the best options during this setup, understand existing implementations, and replace them with better ones when needed.
Both front and back covers use topics which have been designated as cover pages. In the actual publication, though, they use different identifiers, and they need to use slightly different rules for vertical absolute positions, for example.
Different publishing formats can use different files for their covers but this would require you to separate them to use different publication templates, too. This is not your only option because style rules can also be specified separately for different publishing formats, and you can even hide parts of content in some of them. Hiding that content does not fully remove it, though. You thus cannot do this with content where that information must not be allowed to leak.
As part of the actual implementation, you can target rules at different parts based on their order or identifiers added to each of them. Such idenfiers include element classes and ID values. You can combine different methods, and my recommendation is to use ID values and then counters inside those parts. The use of nothing but counters is invisible to basic users which makes them easy to break with edits. By comparison, the use of element classes suffers from them remaining on the list of all element classes. ID values, on the other hand, only target one set of covers correctly in a multilanguage publication.
As part of the structure for covers’ content, you can use section elements, hidden tables, or phrase elements. You can also use HTML rather than DITA topics for them if you must add horizontal lines or the editor must have clear distinctions between paragraphs to help an implementation based on their order.
Variables are essential for adapting covers for different publications. Different details require different types of variables. Simple variables are suitable for content that must not be translated and for combining the values of other variables. Complex variables are required for values that are uniform within a language but must be translated. You can use tags to make parts of either conditional. Publishing variables are required for values that are unique to each publications such as delivery-specific identifiers. Such values can be split between multiple variables, though, if they also contain standardized portions. System variables are used to retrieve details such as revision numbers or the publication’s language code from the system.
The styles for covers require you to place their contents. You can use absolute positions or large margins for this. You may also have to define elements’ sizes to define their line length, for example. Adding images also involves some unique considerations. Background images may occasionally be cut off. Thus, I mostly recommend the use of absolute positions and specified depth layers.