Because the contents from structured authoring are to be used in multiple publications, individual pieces of content ought not be given document-specific identifiers such as ‘table 1’. The same table can be in a completely different positio as part of another publication and thus require a corresponding different (number) identifier. This entails that there could be no direct references to such parts as part of the text, either, except by making such references conditioned content.
Fortunately, the systems for structured authoring are able to fill in such details during publishing instead. This article is about how such systems operate in practice and how this results in practices that differ from direct text editing. At the same time, it will describe how some content is added using the stylesheet and provide a reminder on how referenced content operates. The differences that references introduce to the workspace were already discussed in the first installment of this series.
Internal Links
Since the (number) identifiers for sections and elements are determined by their context, they cannot be used as such when such contents are mentioned. The solution here is to use internal links to reference such contents. At least DoX CMS will complete any such references with the correct identifiers for the document being published during the publishing process. How exactly such identifiers are filled in is discussed in more detail below.
Internal links can either be applied to your choice of expression or be left empty in this respect. In the case of the latter, DoX CMS will fill in the text that implements the link itself: links to topics will include their number identifier and title and links to elements their number identifier, including the type of the element where applicable. The details for elements are determined by their settings in your company’s copy of DoX CMS (see below).
Because the values are calculated automatically, there is no risk associated with errors related to updating them. If, for example, a new table is added before table 3, the numbering on all the tables will immediately reflect this which makes table 3 to table 4 instead. Internal links track these changes and they will always show the appropriate value for the publication in question.
These changes in the values of other parts of a document make the use of internal links necessary for structured authoring. Examples of the kinds of content that require internal links are discussed below.
Numbering of Sections
Documents that involve structured authoring are assembled from content modules that determine the number identifiers of each of their sections. Such contents can be arranged into hierarchies that then affect their number identifiers. The standard format that DoX CMS also applies adds a new cardinal number at the end of the number identifier for each involved level of organization, separated from the preceding parts with a period. As such, an example number identifier for a section on the third level of organization would be of the form ‘2.1.3’.
The order and hierarchy applied to a publication are determined with the help of pre-specified organizational trees. DoX CMS uses so-called topic trees for this purpose, and they let you reorganize the content as needed. This involves dragging and dropping content for the topic tree before a publication is assembled. The correct topic tree is then selected for the publication, at which point you may still filter out any conditioned sections and other content that do not belong in said publication.
Because each section will be a part of the publication as a title at the very least, it is best to add some content in each of them. Otherwise, the publication will include multiple titles in immediate sequence or pages with nothing but a title in the case of web-based publications, and this tends to be a sign of weak layout.
Together with the internal links filled in by the system, such automatic numbering of sections allows the same content to be reused in different publications without adjusting it. Users need not concern themselves with coordinating the used identifiers at all.
Named Elements
Individual elements may also have a title and a number identifier. The most relevant among them are tables and figures with embedded images. There are two types of tables in DoX CMS: full tables that always have titles and more properties and untitled simple tables. You can add titles and descriptions to images by using separate figure elements to house them. Titles may also be added to other kinds of elements such as paragraphs through the use of internal links. However, we recommend against doing this.
Unlike sections, the numbering of named elements follows more than one possible format. In the case of DoX CMS, they all follow the same format for now but you may freely set this format in the system’s settings. This makes use of variables that are connected to values such as how many elements of a given type precede each such element as part of the contents under the same topic on the first level of organization. Variables are a type of externally controlled referenced content that the first installment discusses in more detail.
The number identifiers of named elements may for example be of the form ‘Table 1.5’ where the first part tells the type of the element and the numbered part tells which first level of organization the section belongs to as well as the ordinal value for said element within it, relative to the all the elements of the same type. The listed table would be the fifth (full) table belonging to the contents under the first main section of said document. The identifier values for elements can also consist of nothing but the type of the element and its ordinal value as a member of that type within the whole document, such as ‘Image 12’ for the twelfth figure in the whole document. The names for element types use variables which allow them to be translated to always correspond to the language of the publication.
When an internal link is used on a thus named element in DoX CMS and the link in question is not already connected to a specific phrase, the system will fill in the number identifier of the element in the link’s position.
Additions from Stylesheets
It is possible to specify additions besides those made by the system already with the help of a stylesheet that is applied during the publishing process. Especially the symbols and names associated with different kinds of notes are best implemented in this manner. This allows a label like ‘Danger’ and the related warning sign to be added to notes with the proper identifier.
One must be especially careful when it comes to additioned derived from stylesheets. The presence of such things must be recognized before writing starts. Otherwise, details such as the ‘Danger’ label mentioned above may be repeated both as part of text and as an addition from the stylesheet. Because of the limitations that stylesheets possess, it can sometimes be necessary to write such labels as part of the text itself with the help of variables, for exmaple. As such, these forms of complements cannot be taken for granted.
The stylesheets used in DoX CMS are largely based on CSS (Cascading Style Sheets). At this time, CSS only enables each element to have one element before it and another after it, and the formatting of such added elements is more limited than for the rest of a document in relation to controlling page breaks, for example. Additionally, images can be set as the backgrounds for elements but each possible solution has its limitations and challenges. For example, background images must not have a greater height than the element to which it is applied with the lowest height. Unless this is done, the elements with the lowest heights will crop their background images accordingly.
Even though we at DoX Systems provide initial stylesheets and additional consulting related to them, it remains important for users to also understand what their stylesheets do. The associated changes will show in document previes and published drafts but such things do not directly convey the limitations involved with said implementation. All possible implementations involve some limitations that users must be able to accommodate during the writing process. Additionally, managing the translations for any content derived from stylesheets generally happens through the stylesheets themselves.
As long as users remain conscious of what stylesheets do and accommodate their limitations as part of organizing content, they remain a powerful tool for controlling layouts. The additions that stylesheets enable remove the need for users to format such content as part of the writing process.
Referenced Content
As was discussed in the first installment, structured authoring also includes forms of content that are retrieved from elsewhere during the publishing process. Strictly speaking, such contents are not added in the same sense as the examples discussed above. Said material precedes this phase and it is merely used as part of what is being published. The difference between base material and the final publication still involves material that is not directly a part of thr former, though. Hence referened content is also mentioned in brief here.
Summary
Because the contents from structured authoring must be reusable in dfferent publications, writing them cannot make use of set number identifiers. Thus, all content is numbered only during the publishing phase and references to numbered content are coordinated with the help of internal links. Such links utilize the generated identifiers of the referenced content as part of the text.
Additionally, content that is not part of the base material can be added to a publication either through its stylesheet or through references in the content itself. The exact implementation may differ in relation to stylesheets in particular because different requirements entail the use of different solutions. Users must thus know what the stylesheet will add in their stead and how such additions must be accommodated as part of organizing content.
Ultimately, all this relates to a very simple feature of structured authoring. However, this fact emphasizes how using such systems requires a different mindset from direct text editors. Structured authoring involves drawing relationships that adapt to each application between parts of content. Contents are also branded with different identifiers that entail changes which mist be understood during writing even when the differences that they make may not be immediately present in the workspace.
This achieves both the adaptability that is a condition for reusability and the uniformity of complex elements such as warnings. As long as these forms of implementation are kept in mind during writing, they will only benefit the results.