SUSE Documentation Style Guide

9.1 Remarks #

Use remarks for editorial comments. Remarks can be placed within, before, or after a para but must always be within a section element. When creating output, remarks can be made visible in the output and thus help within the editorial process. When creating the final output, deactivate remarks.

Start remarks with your user name and the current date, then add a colon (:) and finally your actual remark. To comment on someone else's remark, add a new remark directly below it. Delete remarks when the corresponding issue is resolved.

<remark>tux (2013-10-13): could not find the option for foo</remark>
<remark>geeko (2013-11-02): see /usr/share/doc/foo.html</remark>

You can add a role attribute with one of the following values to show the type of the remark:

structure. Use this type of remark to suggest changes to the text or XML structure.
language. Use this type of remark to suggest language improvements.
needinfo. Use this type of remark to mark sections where you need input from others, such as developers.
trans. Use this type of remark to give hints to translators.

9.2 XML comments #

XML comments can be used for temporarily disabling portions of text. Another use of XML comments is to create more permanent internal comments or to mark up changes made for layout reasons. XML comments are never visible in a publication.

<!-- This is an XML comment. -->

For information about formatting XML comments, see Chapter 10, Formatting XML.

9.3 Entities #

Entities are used to expand text. There are several situations in which they can be used:

To represent special characters that cannot easily be displayed, entered or memorized.
To integrate external files using entities representing references to their file names.
To repeat content easily.

When an entity is defined, it can be used in many places. Entities increase consistency, as they only need to be defined once and will automatically be expanded everywhere within the document.

9.3.1 Common types of entities #

Official generic entities are maintained in the Doc Kit repository. They include SUSE product names and other terms that are valid for every repository. In repositories configured with Doc Kit, the file generic-entities.ent therefore must not be changed (any changes will be overwritten by the next Doc Kit run). If there is a need to declare a specific entity that applies to the current repository only, this can be done in the product-entities.ent or entity-decl.ent file in the respective repository.

A generic-entities.ent or entity-decl.ent file contains several categories of entities:

Products: All SUSE product names and other products and applications. This helps when sudden name changes are necessary and avoids misspellings.
Platforms: Use entities for all hardware architectures referenced. This helps when sudden name changes are necessary.
Books: Title entities for all SUSE books. This helps when sudden name changes are necessary.
General Entities: Network IP addresses, host names and user names.

There are several guidelines to consider when working with product entities for SUSE documentation:

Entity selection

Use the entity name &productname; to identify the product for which the documentation is built. Set the value of this entity once per release and have it expand to the name of the current product:

&productname; includes 389-ds.

If you need to reference a specific subproduct or a different product, use a more specific entity:

Tuning &sle; for SAP

Acronyms

In some cases (for example, limited space in table cells or in titles), it is acceptable to use an entity for a product name acronym. Find the approved entities for product name acronyms in the entity declaration files, such as product-entities.ent or generic-entities.ent. For a product name acronym, you can use the generic entity &productnameshort;. If you need acronym entities for specific products, they usually have an appended a at the end, for example, &slsa; for the acronym “SLES.”

Trademarks

Follow the rules under Section 6.21, “Trademarks” and Section 7.17, “Products”.

If an entity is placed at the beginning of a phrase or title, its resolved form is usually lowercase (unless specified in uppercase, for example, for product names). To have it capitalized, use the <phrase role="style:sentencecase"/> element. For example:

<phrase role="style:sentencecase">&ulp;</phrase>

The entity &ulp; expands into “User space live patching”.

Never add this tag to the content within <command/> and <systemitem/> elements. Capitalizing anything inside these elements makes the content ambiguous.

9.3.2 Using entity files #

SUSE uses a set of custom entities. Find these entities in the *.ent files in each documentation repository. One entity file can include other entity files.

Entity files are only used for original, English-language documents. Translated documents contain only the resolved form of entities, that is, plain-text directly in the document.
If you need a new entity to be used generically across all repositories, open a pull request against generic-entities.ent in the Doc Kit repository. After the change is approved by the Doc Kit maintainers, the entity update for generic-entities.ent will be rolled out to all Doc Kit-based repositories with the next Doc Kit run. If you need a custom entity that only applies to a specific repository, define it in product-entities.ent or in entities-decl.ent in this specific repository.
Do not include custom entity definitions directly in the file header, unless the custom definitions are needed to override externally embedded entities.
Use the UTF-8 encoding when editing and saving the entity declaration file or any of the SUSE XML files.

Each header of a SUSE XML file includes the entity declaration file (by means of an entity):

<!ENTITY % entities SYSTEM "generic-entities.ent">
%entities;

Example 9.1: Excerpt from product-entities.ent #

<!ENTITY1product-sp2 "13">
<!ENTITY product-ga  "15">
<!ENTITY productnumber-regurl    "&product-ga;.&product-sp;4">
<!ENTITY productnumber "<phrase xmlns='http://docbook.org/ns/docbook' role='productnumber'>15</phrase">5">

1	Making an entity declaration.
2	Defining the entity name.
3	Setting the value which the processed entity should expand to.
4	Using another entity within the entity value. This entity reference is only valid if the other entity is defined somewhere within the scope of the XML document that is built. However, it does not matter whether the entity is defined before or after the current entity definition.
5	Using a DocBook/GeekoDoc element within the entity value. The attribute `xmlns` must be included to define the correct XML namespace.

9.4 XInclude elements #

XInclude elements are used to create modular source files that are easier to work with and can be reused. When editing a book, create a new source file for every chapter. Later, create a new GeekoDoc file that can serve as the central point. In this file, use XInclude elements to reference all chapters in the correct order:

<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="gfdl.xml"/>

XInclude elements allow adding common sections to multiple books or articles without having to maintain the text in multiple places. Common sections include licenses and information on typographical conventions. XIncludes also simplify co-editing documentation with others in a version control system as they reduce the chance of merge conflicts.

By default, files referenced via XIncludes must be well-formed XML files that are also valid GeekoDoc fragments. This means that they must have a single top-level element and must not contain elements that are not allowed in GeekoDoc. Files that are supposed to be referenced multiple times from within the same set, book or article must not contain any xml:id attributes.

XIncludes also allow embedding plaintext files, for example, as the content in <screen/> elements. To embed a plaintext file, add the attribute parse="text" to the <xi:include/> element.

9 Managing documents #