The other fields in the text editor: shortdesc, prolog, and sections

A topic in DoX CMS contains parts other than just its title and the content field. In this piece, I will discuss how to use the other fields. They are

1. shortdesc for an introduction,
2. prolog for metadata, and
3. sections.

Shortdesc

This field lies immediately below the title field. You can only inclide inline elements inside it. They are

• text effects,
• images,
• phrases (ph), and
• links.

This field is mainly intended for summaries. You can define styling rules only targeted at such summaries in a style sheet in relation to the identifier .dita-shortdesc. However, you can also use this field in other ways which I detail below.

Section links

If you have a system where each topic (at a specific level of organization) always has elements that you can target with links such as figures, full tables or the section elements discussed below, you can add links to them in their introduction. In longer topics in particular, this lets users move to the correct parts of the document directly. If the document is printed and each such topic starts from a new page, users can more easily browse for parts such as specific tables, which were mentioned elsewhere, with the help of such sections with normalized positions.

In an online publication, you can keep this part visible even when users scroll through content. One example of this kind of implementation in another context are Wikipedia articles which show the links to their sub-sections in the upper left corner of each article. This lets users move freely between these sub-sections while they remain on that page. Such an implementation is particularly helpful when the content is organized according to Mark Baker’s Every Page is Page One principle. This involves the content being divided into self-sufficient and comprehensive topic-specific sections which you navigate with links.

You make this part move with the position rule’s values fixed or sticky. You must also specify the position of the section on the screen with directional commands (left, right, top, bottom) and related distances. A fixed position always shows the content in the specified part of the screen. A sticky position shows the content as part of the normal content flow until the user scrolls past it. This element only moves while you scroll when the wrapper around it still shows on screen.

Icons

Alternatively, you can use this field to show picture which tell users about the subject matter of each topic. For examole, such icons can signify which parts

• are suitable for different levels of expertise,
• contain specific kinds of instructions or specifications,
• relate to specific risks or require specific precautions, or
• relate to specific components of a device or user interface.

A simple example of this is a magnifying glass for instructions related to finding the reasons for errors.

Such icons are more immediately recognizable than text when users browse through the document. You can associate them with details that register more quickly such as colour coding or frame shapes. You can also move these icons to the outer page margin, for example, which lets users locate them without browsing the text itself.

Prolog

This field for other information is only usable by data elements that contain metadata related to the topic. The only publications that contain this information are those published in the DITA format. You can also use it to find related content within the system itself, though.

To use data elements for the prolog field in the text editor requires you to fill in their DITA attributes. This menu has two fields: name and value. The name field determines the type of metadata in question and the value field the associated value. You can also write inside these elements or include other data elements inside them. Use embedded data elements to categorize metadata. For example, publishing details can be a category that includes both the year of publication and the author.

To filter content and search for values in the prolog field, you must write corresponding values from the source view in the Find in Content field. If they do not recur elsewhere in your documentation, you can write the values themselves there. If you must specify that the value relates to metadata, you can also write the names of these attributes, such as ‘name=”author”‘. Remember that this search function treats empty spaces as differentiation between mutually required phrases to find in content.

Sections

The most versatile of these additional fields is the sections field which contains all the section elements in a given topic. You can use section elements to, for example,

• add sub-headers,
• form multiple elements into wholes that you condition with tags,
• form multiple elements into wholes that prevent page breaks inside them.
• add frames to wholes formed from multiple elements,
• apply content references (conref) to wholes formed from multiple elements,
• apply content references (conref) to block elements which so not otherwise support them, or
• add tags to condition a wrapper around the target elements of content references (conref).

Topics which include sections elements should not have other content in the content field. You can also use section elements for portions that do not require them. When you leave their title fields empty, the results look the same as when you write it in the content field, unless the style sheet has different specifications. However, if you add content to both the content field and the sections field, publications will show the contents of the sections field after the contents of the content field.

You can add more section elements inside the sections field by adding them as the default elements directly inside it. Move the cursor over the gap between section elements and click on the red button with an arrow which shows to the right of the red dotted line.

Sub-headers

Section elements have title fields which you can use to add sub-headers between them. This is the best method with which you can add sub-headers between parts of a topic. Unlike paragraphs that you style to look like headers with an element class, for example, these are dedicated title elements.

The best method to target these titles with a style sheet is to specify selectors which target elements’ titles directly inside section elements. Otherwise, the associated rules can also apply to the titles of full tables and figures inside section elements. At its simplest, such a selector looks like this:

.dita-section > .dita-title {}

Conditioning

You can use tags to condition section elements. As a result, you can condition either wholes formed from multiple elements with one set of tags or condition the target elements of content references (conrefs) with them.

Normally, you must condition the source element to apply conditioning to content references (conref). The reason is how that feature fully replaces the target elements. As such, the tags used to condition them are also replaced with those of the source element.

However, the section elements around the target element are unaffected by this replacement. As such, you can use one to control whether the target element is included in that part of a document. The result is that you can use target elements based on the same source element differently between publications related to different tags.

Sivunvaihdot

Because you can target section elements with style sheets, you can also add rules that control page breaks in relation to them. You can do this to ensure that lists and their explanations stay on the same page, for example. You can specify such rules in more detail for different use cases. The simplest solution, though, is an element class which prevents page breaks inside the element that has it. This is a better method than it would be to prevent page breaks inside all section elements, unless you know in advance that their use will be compatible with that alternative.

Such a solution looks like this with an element class named ‘NoPageBreakInside’:

[doxelementclass~="NoPageBreakInside"] {break-inside: avoid-page;}

You can also use the rule ‘page-break-inside: avoid’.

Framing

Sometimes, it is best to add frames around wholes that include multiple elements. You can also add a number to order such sections if they relate to steps in a task, for example. Section elements are the best available option for this. You can add other content inside them freely and they have no innate functionality such as being counted. You can still link to them, though.

Once again, it is best to connect such rules to element classes that you can add to section elements as needed. I will not include a specific implementation because they all mostly include details which determine a look. However, you can add frames with the border rule and then control their details with other rules such as rounded corners with the border-radius rule.

Adding numbers to section elements, on the other hand, requires a new counter. You can add one with appropriately targeted counter-reset and counter-increment rules to (re)start the counter and to increase its value. To show the values of this counter, you must then add it to specified elements with the ::before selector and the content-rule with a value that includes the value counter(). You must include the name of your counter inside the parentheses of the counter() value.

Content references

The DITA attributes for section elements include the ID field and Conref field that the use of content references requires. You can thus target them with content references. You can use section elements like this to control recurring wholes that consist of multiple elements from one place. You can also use them to do this to individual block elements that are themselves not compatible with content references.

For such individual elements, have them be the only contents inside the section elements even if you have no other use for the section elements around them. Make sure that the use of a section element has no unwanted consequences because of their specifications in your style sheets. When the topics where they are used have all their content divided between section elements, you can place the target section element for the content references between them. This method lets you, for example, include the same figure element in several locations inside a publication or between publications.

Summary

A topic can hold more than just a title and a singular content field. They also have fields for introductions and metadata. You can also divide content itself into sections which considerably increase its functionality. You do this with the shortdesc, prolog, and sections fields in the text editor.

The introduction in the shortdesc can include text, images, or links. You can thus also use it to link sub-sections or to identify types of content with different icons. You can move this field to page margins, for example, with rules targeted at it in the style sheet.

The prolog field consists of parallel and embedded data elements. These elements’ DITA attributes include a name field and a value field that you must use to specify the type of metadata and the associated value. You can also write inside the data elements. However, these values only currently apply to content searches in DoX CMS and DITA publications.

The section elements of the Sections field, on the other hand, let you further divide content into distinct parts. Even if you do not use these sections to add sub-headers, you can still target them with style sheets, condition them with tags, or use their DITA attributes for content references (conrefs). This lets you split a topic according to your needs. You can also add tags to the targets of content references and content references for block elements which are not themselves compatible with them.