We provide new customers with a stylesheet that is written to match their needs when they implement DoX CMS. This piece will discuss the details that must be accounted for in the related instructions. These observations may also benefit others that must design stylesheets.
The demands for stylesheets are divided into three sections here: 1. the primary publishing format (PDF or HTML), 2. the details related to text, and 3. specifications for different types of elements.
Primary Publishing Format
Different publishing formats have their own special features and requirements. As such, it is is best to separate the stylesheets for each. The two main formats for structured authoring are HTML for web content and PDF for books. Writing stylesheets requires you to know with which type of file it is to be used and how the unique features for that file format should be taken into consideration.
HTML Publications
HTML publications are used online and also often in different kinds of virtual environments, for instance. Once DoX VAD is implemented, HTML publications will be the most compatible option to use with it. When it comes to HTML publications, it is important to know the identifiers from any template being used to edit its details and whether the active elements that this format supports will be used.
Templates
HTML content is often used in an environment which adds a frame around it. Such environments have their own stylesheets but the different stylesheets are generally combined for compling a site. Even if you lack direct access to said stylesheet, the stylesheet for the publication can include rules for this frame’s elements which become overriding with the use of the !important qualifier.
If this template must be adapted using the stylesheet for the published content, this requires knowing the identifiers for the elements of the frame. This allows using these identifiers for the selectors in the stylesheet.
It is also important to know whether the stylesheet for the frame has rules for different types of elements. For example, the font size for the titles of different levels of content is often standardized. These exact details should also be included in the stylesheet being written to keep it usable in other contexts without changing the results. It is also important to know which units, colors and fonts this complementary stylesheet uses. The new stylesheet can then also be written to be consistent with these details.
Active Elements
HTML supports different real time changes to content such as animations and interactability. If these features are to be used, their implementation must be planned first.
Animations should be connected to specific interactions and they let you control the transition between colors when the pointer is moved above a link, for example. However, one should note that details such as the transition between image sizes cannot be animated directly. There are possible implementations but they require you to also consider the size of the used images, for example.
The most important means of interaction are moving the cursor over an element (:hover) and selecting an element (:active or :focus). They allow you to control details such as image size, the color of rows in tables, text size, text effects such as bolding, and link color.
PDF Publications
The most important parts of stylesheets that PDF publications require concern page breaks and page headers and footers. It is also a good idea to consider details related to the layout of the table of contents.
Page Breaks
Controlling page breaks includes starting from a new page for contents of a specified level of organization and setting conditions for minimum content per page. An earlier piece on the subject is available here. When it comes to tables, it is also important to know how they will be used. These rules do not automatically register whether the table has so few rows that it will always be moved to the next page, or the height of individual rows. Different situations may require different sets of rules that can be implemented with element classes.
Page Headers and Footers
Page headers and footers belong in PDF publications. You must thus decide whether they will be symmetrical or asymmetrical and what information they must contain. Any images that these parts contain must of course be delivered in the appropriate format.
In DoX CMS, you can use variables inside page headers and footers and their contents can be conditioned in turn. This allows you to express whether a publication is just a draft, for example. You must also specify how page numbering is to be done, such as whether the total page count is shown, and which (if any) levels of organization show their titles inside these parts of the document.
Table of Contents
Managing the table of contents mostly requires deciding on the indentation length for the titles in each level of organization. It is also possible to determine whether titles are separated from page numbers by symbols such as periods, and whether some titles use a smaller font size. You must also known whether page numbers and page headers and footers are included in the table of contents or only in the main text.
Text Format
The fact that documents mainly consist of text makes the rules for formatting text likely the most important part of a stylesheet. This includes both the text body and all titles. Some elements such as tables may also include rules for details such as the text size used inside them. This section discusses color codes, fonts, details related to size, and both vertical and horizontal margins.
Color Codes
Companies often have their official palettes that are specified in their internal marketing style guides. On occasion, there are are several palettes for different implementations and outsiders will not know which to use where. Some such guides do not even include the specific color codes and instead opt for color samples alone. Here, ‘color code’ refers either to color-specific hex codes such as #0ff1ce or RGB(A) values such as (15, 241, 206). For the latter, a fourth available value corresponds to opacity which ranges between 0 (fully transparent) to 1 (fully opaque).
Writing a stylesheet requires access to the exact color codes that will be used for colored portions of text or backgrounds. You must also tell the writer which portions will be colored and with which color. This includes the titles for different levels of organization if they use different colors such as varying shades of gray.
Fonts
If non-standard fonts are to be used, the files for them must be provided. Whenever more than one font is used, it must be speficied which is used for a given type of element. If it is known in advance that content will be translated to languages that use different alphabets, the fonts that are used for said alphabets should also be provided. They can then be implemented for the appropriate languages.
These font-related requirements also apply to cover pages and their titles if they are done within the system and not with a separate graphics program. Further information about the options for table layouts are available here.
Font Size
MS Word uses points (pt) for font sizes but elsewhere, better options may include different units such as pixels (px). Furthermore, HTML publications in particular benefit from the use of relative units such as multipliers for the font size of the parent element (em) or percents of the parent element’s dimensions (%). A list of all the available units is available here.
Margins
Besides formatting the text itself, you must also determine its layout. A major part of text layout consists of its margins and padding values, both vertically and horizontally.
Should some content such as the icons for notes be included inside page margins, both the requirements and restrictions of implementing this must be considered carefully. If this is done by using the icon as the background for the element, for example, the element must have a minimum height which prevents the background from being cut off.
Tables may also require adjustments in this respect. We recommend using the same indentation length in each column. It is possible to maintain differences between columns but they always involve risks in terms of the values for split cells. The problems that they can incur may require further actions such as using element classes to fix individual cells.
Specifications for Different Elements
Different types of elements have their own requirements that must be met. Those discussed here include 1. numbering format, 2. tables, 3. images, 4. notes, 5. cover pages, and 6. exceptions to general rules.
Numbering Format
Elements with titles such as figures and complex tables require you to specify the format for their numerical identifiers. In DoX CMS, this is done in the Settings menu and for the time being, all elements will be numbered based on the same format.
The most important decision in this respect is whether the numbering will extend across the whole document or whether it is related to different sections. It is easier to just count how many elements of that type precede an element in the whole document. On the other hand, showing details such as the active main sections as part of the numbering makes it easier to locate the correct positions if they are referred to elsewhere in the document. If multiple elements of one type are commonly included in a single topic, it can also be sensible to count this value.
Tables
Tables are the most complex type of element, and their implementation involves multiple decisions. It is commonplace that you will need several types of tables based on different sets of rules. They can be differentiated with the use of identifiers such as element classes.
Quite possibly, the most important decision here is whether column widths are based on their contents or fixed portions. Acommodating content width is prone to breaking. When this happens, the causes must often be located without seeing directly where they lie. It can also result in columns of inconsistent widths between different languages and successive, otherwise similar tables. Fixed proportions involve dividing the available width equally between each column without prior specifications. This option emphasizes the importance of setting the width values for columns manually. This allows for content to spread past column boundaries if it is too wide but such parts can be tracked and fixed in a targeted manner.
The specifications for tables also include whether they will include background colors, such as on every other row, and whether some columns have different padding values. However, such adjustments will often not function properly when you also split cells. As such, using them requires either not splitting cells or the use of element classes that adjust the results.
Images
Images require you to specify the limits to their size in different contexts. It is mostly not prudent to force original image sizes to match their intended applications. Controlling their dimensions can be done through a stylesheet by setting minimum and maximum dimensions to images, preferably for when they are included inside other elements such as figured or tables. Doing this makes the layout of large images easier to anticipate in relation to their intended positions, for example.
Images also allow you to add details such as frames around them. Electing to use such frames, in turn, requires you to specify their style, width, and color. Any such details can also be specified separately for different contexts.
Notes
As is mentioned here, the styling of notes requires special attention. They generally include more than one part which is added using a stylesheet and different solutions each have their own restrictions. The nost relevant parts like this are the icons and titles for different types of notes.
Unlike images used as part of the content, the images added through a stylesheet should ideally match their final size in advance much of the time. You simply have less control over content which is added like this than over images as part of content proper. Attempting to embed them in the page margins requires either specifying the margins for all other elements separately or using added elements for the images themselves. If an image set as a background is moved inside page margins specified elsewhere with the use of a negative value for magins, it will be hidden as a result.
The titles for notes are simpler to control but there are several methods for managing their translations. Such content can either be specified separately for each language in the stylesheet or they can be retrieved from a topic which includes an appropriate complex variable. In the latter instance, possible means to retrieve the content include the option to hide the originals.
Adding such titles through the stylesheets requires the use of a ::before selector. Each element may only have a single piece of content added like this. If this slot is used to move the icon inside the page margin, the title of the note cannot be added in this usual manner. Under these circumstances, the best compromise is to write titles as part of content with the help of variables, for example.
Cover Pages
If cover pages are not made with external software to be used as PDF topics, for example, they require considerable styling. It is generally necessary to recognize all the kinds of information that may be added to a cover. This allows specifying the rules for each with the help of element classes, for example. Whether separate publications will use different covers must also be known in advance. If this is the case, they basically require separate stylesheets if the backgrounds for covers are specified in the stylesheet.
The style-related details of a cover page can be done using a template written as part of the stylesheet. In this case, the order of the elements inside the topic used as a cover page determines their layout and style. The same effect can be achieved by using a different element class for each part, which would allow users to control the layout of covers as part of content creation.
Exceptions
A stylesheet provides both general and conditional rules. Conditioning requires context-specific identifiers such as a publication’s language. Most such identifiers are innate and correspond to basic requirements. Should you have a need for specific exceptions, DoX CMS allows element classes to be used as the required identifiers.
Element classes allow the use of different types of tables and templates for tables, for example. They also let you add details such as colors or colored background boxes to pieces of text. Any such demand should be recognized in advance if you will not manage your stylesheet yourselves, since the effects of element classes must still be specified in a stylesheet.
Summary
Stylesheets must anticipate all the requirements associated with related documents. As such, these requirements must be recognized when the stylesheet is being written. If the stylesheet is being done by an external actor such as ourselves, related demands must be communicated clearly while also recognizing the possibility of related restrictions. Each solution used in a stylesheet also affects how writing itself is to be done.
It is especially important to recognize the demands related to different publishing formats and exceptions to general rules. It is also not guaranteed that an easily available solution for replicating the functions of alternatives such as MS Word, including active management of the details of table cells. It is well within the realm of possibility that a solution included in the stylesheet requires a compromise to be accommodated during content creation.