This is the final installment for the foreseeable future in this series on the differences between direct text editing and structured authoring. There have been multiple references to stylesheets in prior installments. They are central to the differences compared to direct text editing since all the details of content layout and styling are controlled through them. As such, stylesheets also deserve their own installment which only focuses on related details.
This installment will reiterate on how the CSS language used for stylesheets functions. It also clarifies the demands that apply to how you can implement different parts such as cover pages or page headers and footers. The piece will then finish by discussing ways to account for differences between different versions of publications. Such versions include both translations and different publishing formats.
Links to the four prior installments in this series are provided below. They discuss the main differences that writers will experience during the content creation process such as how publications diverge from the base material used to compile them.
Writing Stylesheets
The fourth installment in this series also provided a very bried introduction to how CSS functions. This installment will discuss in more depth the kinds of solutions which the selectors and associated rules that the language involves enable.
CSS functions by rules always being linked to various selectors that detrmine which elements said rules affect. The first things discussed below are how selectors function and associated ways to control content layout through them. Then, the focus shifts to the different rules that CSS supports. Their limitations are also touched upon in brief.
Selectors
In this context, ‘selector’ refers to the part of a command in CSS that determines where the set of rules provided inside curly brackets is applied. This part specifies which types of elements and in which contexts are subject to a given set of rules.
Selectors designate types of elements, associated identifiers and totals that can be specified elsewhere on the stylesheet. PrinceXML, for example, has its own rules that let you designate the pages that contain a specified type of element as their own section. DoX CMS allows such rules to be used in PDF publications that are compiled with DocRaptor. This lets you determine details such as which parts of a document are treated as its cover pages. DoX CMS also has a system-specific means of distinguishing cover pages, the table of contents, and the body of the publication.
A selectors lets you define special contexts based on the relationships between the elements designated by different identifiers such as being embedded or in sequence. Each such relation between identifiers is expressed by a different symbol between them. For example, the plus sign (+) expresses being in the same sequence as part of content. It is also possible to add further specifications separated from them by colons (:) to identifiers. The specification ‘:hover’, for example, activates the associated rules when the cursor is moved over the associated kinds of elements in a publication that supports the feature. This allows for options such as making links change color when they can be clicked.
The level of specificity of the used identifiers and the order of used selectors determine which rules apply. More specific identifiers override more generic identifiers. Later equally specific identifiers override preceding ones. There are three levels of specificity, starting with the most generic: 1. element types such as ‘img’, 2. element classes such as ‘.dita-title’, and 3. the unique identifiers of elements such as ‘#main-title’. Other available identifiers also use this three level hierarchy as is shown here.
This makes it important to always write generic identifiers first and those for more specific contexts below them. For example, a specification based on ordinal values such as ‘:last-of-type’, which designates the final element of the specified type embedded in another element, and the aforementioned specification ‘:hover’ interact differently based on their order. If the rules tied to ordinal values are provided first, the affected elements will change in style when the cursor is moved above them. Should the rules tied to ordinal values be provided afterwards, the sections affected by them will not respond to the cursor.
Rules
Each selector is associated with a set of rules inside a pair of curly brackets and separated from each other with a semicolon (;). Each rule consists of the title for the rule and the associated value(s) separated from this title with a colon (:). For example, the rule ‘margin: 0 0 0 0;’ removes all marginals on the elements designated by its selector. Each of the four values corresponds to the marginals in a single direction dependent on its position.
These rules control all changes to the layour and styling of the base material when it is published, save for any changes derived from the system being used.
Rules are responsible for both direct changes to content and any restrictions on the possible results. Using the latter kind of rules is also important as it ensures that the results can be anticipated. Using percentage values to set maximum values for image dimensions, for example, ensures that they will fit wherever they are used, such as inside table cells. The available units are discussed in more detail below.
Stylesheets also allow you to apply other files such as images to the base material. Fonts besides default options are also made available like this. Either action requires specifying an address to which the system that applies the stylesheet has access and that contains the file in question. It is possible to add the background image for the front cover in this way, for example.
This section will not address all possible forms of changes that CSS supports. The example below shows how to add the string ‘Il faut faire avec’ below the title of each section in a publication made with DoX CMS.
.titleWrapper::after {
content: "Il faut faire avec';
font-size: 11pt;
margin-top: 6px;
color: #dbdbdb;
}It is important to note how there can be system-specific rules in addition to the available basic rules. PrinceXML, for example, lets you designate parts of content and reposition them. This feature can be used for details such as showing the titles of active main sections as part of page headers or footers.
Units
Stylesheets allow you to use either absolute or relative units. It is crucial to recognize their differences and to know when to use either and how it will affect the reusability of the stylesheet for different contexts. A list of the available units can be found here.
Absolute units always have the same length per unit. They include pixels, millimeters, and points, for example. In terms of pixel values, one must note how they have been standardized for a pixel density of 96ddpi and as such, each pixel equals 1/96 of an inch. As such, images with higher pixel densities, or devices with greater resolutions do not affect the lengths of pixel-based values.
Absolute units should be used when the dimensions related to a publishing format are known in advance. The most obvious example are PDF publications with known page sizes. Absolute units are rigid and intuitive to apply. Using them ensures the same result each time.
Relative units, on the other hand, are dependent on the dimensions associated with some other factor. The most common relative unit are percentages which express size in relation to the element in which the affected element is embedded such as table cells or sections of content. Besides this option, such measurements can be tied to various font-based dimensions or the size of a monitor.
Relative units are needed when context affects the available dimensions. This includes both embedded elements, such as parts of tables, and mobile publications such as web contents. In such contexts, absolute units would risk breaking the document because the affected elements would not adapt to their various contexts of use.
Implementation
Various sections may need to be implemented in one of several ways based on the system being used or users’ needs. CSS always supports more than one possible implementation and they each have their merits and restrictions. In some instances, said restrictions may force compromising on which parts may be done automatically and which require either budging on demands or alternative implementations. Common incidents like this are discussed below.
Cover Pages
The implementation of cover pages include determining layouts for the cover image and other content. The most options for controlling details is afforded by preparing the cover page in an image editor. This makes it possible to define the cover page directly as a PDF file, for example. Alternatively, the image for the cover page and all text on it can be controlled separately. This allows the parts with text to be adapted for different publications.
If all content that uses the same stylesheet include the same image on their covers, this image can be placed through the stylesheet. If the cover image must be different for each model, for example, it can be included as part of the content module used for the cover page. The stylesheet can then include rules for images in the cover page to define a proper layout for said image.
The layout and styling for the contents of cover pages can be based on either the ordering of that content or the use of identifiers. In the case of this layout being based on the order of these elements, the stylesheet will contain an invisible template that the content module used as a cover page must obey. Since users cannot see this template while writing, we do not recommend this solution. Connecting a set of identifiers to rules that determine the absolute position of content, for example, allows users to apply the proper identifiers themselves to control the layout of content. This lets users know the principles controlling content layout as part of their user experience.
Headers and Footers
How headers and footes are implemented depends on the commands allowed by the PDF compiler being used. The most common method used to add them in DoX CMS involves separate HTML files associated with a style. However, PrinceXML also supports special commands which let you designate content elsewhere to be added to page headers and footers.
Even though variables cannot be added through a stylesheet because of the order of operations, they can be used inside such HTML files. This allows you to add details such as the publication’s title and other publication-specific information with the appropriate variables. DoX CMS also includes variables unique to headers and footers such as one for page numbers.
The additional commands in PrinceXML let you either copy or cut the content designated by a selector and to set them in new positions such as inside the header or footer. You can use selectors based on positions on the page margins, which are supported by said compiler. More information on them is available in the linked user manual.
Notes
The majority of the styling related to types of notes is best done through a stylesheet. This includes both the associated icons and related textual identifiers such as ‘Danger!’. Because these elements often have several parts, their implementation must be considered carefully. Compared to implementing them with direct text editing, the limitations of CSS can force you to compromise.
The rules for different types of notes are applied with selectors that refer to types specified in their DITA properties such as ‘caution’. This lets you use different rules for each.
The icons for notes can be added either as backgrounds or as their own elements before or after the notes. The positions of the latter can be specified in various ways. When you add them as backgrounds, the text can be moved off the image using its left padding. This is the recommended solution but it does not allow the icon to be set deeper inside the page margin than other content. The problem with elements that are added through the stylesheet is that only one can be used before an element and another after it. Relative position is also based on the initial position which makes an image added in this way impossible to center vertically. Said element can also be separated from the note itself by a page break if its position in the layout has not been anticipated properly.
If the textual clarification of a note’s type is not part of its icon, it must be added before (or after) it in the aforementioned manner. Because this cannot be done with more than one element, to do so with images may require that the clarification is made a part of the base material with the help of variables, for example. Text inside images can be made language-specific, though. DoX CMS supports language-specific images or you can add language-specific images through stylesheets. Any written additions must already be translated in this manner. Because these parts are not included in translation projects otherwise, it is a good idea to write a content module with them to be sent to translators.
Differences Between Versions
As has been mentioned on occasion above, a stylesheet may require rules that only affect some of the publications that use it. For example, any strings of text added through it must be specified separately for each language to translate them. In the same vein, different publishing formats may require separate stylesheets to account for differences in their demands. Should content have publication-specific additions to its layout such as forced page breaks, they must also be taken into consideration to ensure reusability.
Translations
Language-specific rules can be specified by adding being embedded in an element with the language identifier as a condition in the selector. When you do this, the associated rules only affect publications in that language. Each language may then have its own set of rules. Doing this with any strings of text added through the stylesheet is especially important. An example on how to implement warnings in both English and Finnish is displayed below. Such rules can be copied for each language. You only need to update the language identifier and the added content when you do this.
[lang="en"] [data-ditaattribute-type="warning"]::before {
content: "Warning:";
font-weight: bold;
}
[lang="fi"] [data-ditaattribute-type="warning"]::before {
content: "Varoitus:";
font-weight: bold;
}Besides translated strings, different languages may require the use of special fonts that correspond to their alphabets, for example. Each alphabet has its default font but it is better to control the font yourself to ensure proper results. Implementing them requires you to first link the file for the font to the stylesheet. Once the font has been given a title within the stylesheet in this manner, it can be used with a language by conditioning the rules related to used fonts with language identifiers in the manner shown above.
Additionally, the proper language-specific implementation of some rules may require further external resources. For example, the hyphenation rule ‘hyphens: auto;’ adds hyphens between syllables in words that continue between rows based on such available resources. The required resources can be added for each language with the rule ‘hyphenate-resource’, which must be used together with language identifiers in the manner shown above.
Publishing Formats
One should heed how different publishing formats may require adjusting the rules being used, especially in terms of units. There are good reasons to use absolute units but they are very much tied to specific publishing formats. As such, using them with web publications that are intended for multiple types of devices, for example, is not a great idea. Although the adjustments can be included in a single stylesheet, it is generally best to write separate stylesheets for them. Besides them, there are rules that only affect specific publishing formats even when they are part of the same stylesheet.
Rules related to page breaks naturally only function with publishing formats which use traditional, continuous pagination. The most commonly used publishing format like this is PDF. Such rules include forced page breaks and requirements for minimum content per page around a page break. There is already an article on the ways to do this in DoX CMS.
Web-based publications, on the other hand, support more interactivity. They allow you to add rules based on the position of the cursor or using it to activate elements, for example. A very common application of this is changing the color of hyperlinks whenever the cursor is above them. Available options also include alternatives such as stretching an image to full size when it is clicked. Because templates such as WebHelp have a set of default elements, overriding rules for these elements can be used to style such templates anew. To do this, you may need to inspect said elements with a brpowser and to use the qualifier ‘!important’ to override the rules in the default stylesheet.
Reusing Content
We do not recommend adding styling that is specific to any one publication. Such additions can be required on occasion such as when a table’s cells are tall enough to break the usual rules related to them. Not all methods to retain reusability in terms of layout directly involve the stylesheet. Such methods are still discussed here, though, because they relate in part to the limitations of automating layouts with stylesheets.
When edits to content help with the layout of individual publications, it is best to replivate the related elements and to condition the two instances in different ways. This makes the publication-specific changes only appear in the publications that require them. Otherwise, the content might be positioned differently and a forced page break, for example, could well break any publication where the content was being reused. Forced page breaks in DoX CMS require you to give an element an element class associated with a rule that adds a forced page break either before or after the element. More details are available here.
Stylesheets can help with reusability by also adding forced page breaks alongside specific kinds of sections – or types of elements. Starting from a new page ensures that the layout on the following pages can be fully anticipated wherever the same content is used. This option should not be abused. However, it can help with otherwise troubling elements such as tables, large images, or a sequence of notes.
Summary
The stylesheets used for structured authoring are based on the language that is also used for web interfaces, CSS, which uses sets of selectors with associated sets of rules. Selectors are used to designate parts of documents based on types of elements or various identifiers. They can also be made for more specific contexts based on relationships between the designated groups of elements. Each selector comes with a set of rules that are used to determine the values used for related details such as text color. There are both absolute and relative units for values that require measurement units. Values in absolute units always have the same results whereas values in relative units change based on where they are used.
There are multiple ways to implement parts of documents. It is important to recognize the merits and limitations of different methods before you select one to match your needs. For example, the styling for the different parts of cover pages can be written directly in the stylesheet based on their order or it can be based on rules associated with identifiers for each of them. The latter option is better for communicating to users what they must do to make the cover layout work properly. If elements require multiple additions around them, as is the case with notes, you must consider which method to add content through the stylesheet should be used with each. Different implementations for this each have their own limitations that must be accounted for in terms of expectations.
The same set of rules or even the same stylesheet will not always function properly in different publications based on the same base material. When this happens, it can prove necessary to either make rules conditional to target specific publications or to write rules that work with different publishing formats. The additions to publications in different languages can be made language-specific with language identifiers and languages with different alphabets can be given appropriate fonts. Publishing formats with pages require rules for page layouts. Web-based publications, on the other hand, allow for rules that let you fully utilize the features that they support and that improve the usability of such publications. Should some publications require changes such as forced page breaks, you must also make sure that such changes do not break other publications. The best ways to do so are conditioning said parts and standardizing the layout by starting sections from new pages.
This ends this series on the differences between direct text editing and structured authoring for now. Should we receive queries on some unaddressed topic(s), new installments can be written to cover related issues.