Applies to 2025-05

9 Managing documents #

This section provides an overview over specific features to manage documents.

9.1 Entities #

Entities (or attributes) 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.1.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-attributes.adoc 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 or file in the respective repository.

A generic-attributes.adoc 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 specific 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 or generic-attributes.adoc. 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 7.22, “Trademarks”.

9.1.2 Using entity files #

SUSE uses a set of custom entities. Find these entities in the *-attributes.adoc 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-attributes.adoc in the Doc Kit repository. After the change is approved by the Doc Kit maintainers, the entity update for generic-attributes.adoc 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-attributes.adoc 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 AsciiDoc files.

Entity files are usually included from the book or article main file:

include::generic-attributes.adoc[]

Example 9.1: Excerpt from product-entities.ent #

:product-sp:1 12
:product-ga:  15
:productnumber-regurl:    {product-ga;.}{product-sp}3

1	Defining the entity name.
2	Setting the value which the processed entity should expand to.
3	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.

9.2 Include elements #

Include 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 file that can serve as the central point. In this file, include elements to reference all chapters in the correct order:

[appendix]
include::common_license_gfdl1.2.adoc[]

Include 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. Includes also simplify co-editing documentation with others in a version control system as they reduce the chance of merge conflicts.