7 Structure and markup #

To make readers aware of potential problems and recent changes, or to give them tips, use an admonition element. Avoid using more than one admonition per page of PDF output.

Follow these rules when writing admonitions:

<warning>
 <title>Do not interrupt creation of file systems</title>
 <para>
  Creating a file system can take multiple hours.
  Interrupting this process will result in a corrupt file system and an
  unusable installation.
 </para>
 <para>
  Always wait until formatting has finished.
 </para>
</warning>

Warning: Do not interrupt creation of file systems

Creating a file system can take multiple hours. Interrupting this process will result in a corrupt file system and an unusable installation.

Always wait until formatting has finished.

When referring to an application, add a <phrase role="productname"/> element around it:

<phrase role="productname">LibreOffice</phrase> is an office suite.

This will not result in a visual change but disables hyphenation in browsers. This markup sidesteps hyphenation issues of CamelCased names.

Callouts allow annotating examples, such as configuration files or commands with many options. Add <co/> elements directly after the part of a screen that you want to annotate. Do not try to align them above the part of a screen to annotate. Do not use more than ten callouts per example.

See also Section 7.7, “Examples”.

<screen>color white/blue black/light-gray <co xml:id="co-color"/>
default 0 <co xml:id="co-default"/></screen>
<calloutlist>
 <callout arearefs="co-color">
  <para>
   Colors of the boot loader menu.
  </para>
 </callout>
 <callout arearefs="co-default">
  <para>
   Defines the preselected option.
  </para>
 </callout>
</calloutlist>

color white/blue black/light-gray 1
default 0 2

You can group different callouts to point to the same annotation. This helps to avoid repeating the same annotation. To do this, complete the following steps:

d1 = dict() <co xml:id="co-dict"/>
  d2 = {} <xref linkend="co-dict"/>
  l1 = list() <co xml:id="co-list"/>
  l2 = [] <xref xml:id="co-list"/>
    <calloutlist>
    <callout arearefs="co-dict">
      <para>A dictionary.</para>
    </callout>
    <callout arearefs="co-list">
      <para>A list.</para>
    </callout>
  </calloutlist>

d1 = dict() 1
      d2 = {} 1
      l1 = list() 2
      l2 = [] 2

When dealing with user input and system output shorter than 30 characters, format it with an inline element, such as <command/> or <filename/>. In all other cases, close the current paragraph and enclose the user input and/or system output in a <screen/> element. See also Section 7.7, “Examples”.

When using stand-alone <command/> elements that are outside of a <screen/>, do not use <prompt/> elements before or within them. For more information about <prompt/>, see Section 7.4.5, “Prompts”.

To start LibreOffice from the command line, use
<command>loffice</command>.

To start LibreOffice Writer from the command line, use
<command>loffice --writer</command>.

Find the log file <filename>configuration.xml</filename>
in the directory <filename>/etc/sysconfig</filename>.

To create a comment, insert <literal>#</literal> characters.

To list the contents of a directory, execute
 <command>ls <replaceable>DIRECTORY</replaceable></command>.

<prompt>&gt;&nbsp;</prompt><command>ls</command>

<prompt role="root">#&nbsp;</prompt><command>yast</command>

<screen><prompt>tux &gt; </prompt><command>ls /</command>
bin   dev   lib         mnt     proc  sbin     suse  usr
boot  etc   lib64       mounts  root  selinux  sys   var
data  home  lost+found  opt     run   srv      tmp</screen>

To select another display manager, start the YaST system configuration editor
and change the value of <varname>DISPLAYMANAGER</varname>.

Use the <xref/> element (read: “cross ref”) when referring to an appendix, chapter, example, figure, part, preface, section, table or question and answer set. The element referenced needs to have an xml:id attribute, an identifier. Create identifiers to reference from cross-references using the rules under Section 7.12, “Identifiers”. Note that the <xref/> element only works when it links to documentation within the same set, for example, the same book or set of books.

Other types of references to resources are described in Section 7.20, “References to other external resources” and Section 7.8, “External links”.

<sect2 xml:id="sec-cross-reference">
  <title>Cross-references</title>
  <para>
   Use the <sgmltag class="emptytag">xref</sgmltag> element ...
  </para>
 ...
  <para>
   See <xref linkend="sec-cross-reference"/>.
  </para>
 </sect2>

This example shows the default display of a cross-reference. To change it, use the xrefstyle attribute, either with select: or template:. Do not use custom “named” xrefstyle attributes that require support from the style sheets. For more info, refer to DocBook XSL: The Complete Guide: Customizing cross-references.

Keep in mind the following cases where listing cross-references is discouraged and must be avoided:

Do not prefix or suffix cross-references with text labels such as “appendix,” “chapter,” “table,” or “figure.” Such labels are generated automatically.

Where possible, indicate stress with language only. If that is not possible, use the <emphasis/> element to indicate stress.

Where added emphasis is needed, use the role="bold" attribute.

This will be displayed in <emphasis>italics</emphasis>. This
will be displayed in <emphasis role="bold">bold</emphasis>

Use examples to illustrate complex processes. The rules established in Section 7.10.1, “Graphics” also apply to examples.

Examples usually contain <screen/> elements. Additionally, there can be callouts and explanatory text.

Always give examples a title and an identifier.

For more information about screen environments, see Section 7.4.6, “Screens”. For more information about displaying computer input and output, see Section 7.4, “Command-line input and command-line output”. To annotate examples, use callouts. Callouts are described in Section 7.3, “Callouts”.

<example xml:id="ex-example">
 <title>Example of an example</title>
 <screen><prompt>tux &gt; </prompt><command>ps -xa</command>

5170 ?        S      0:00 kdeinit: khotkeys
5172 ?        S      0:02 kdeinit: kdesktop
5174 ?        S      0:04 kdeinit: kicker</screen>
</example>

Information that is relevant within SUSE documentation is often available from other Web sites already. In such cases, choose between linking to these sites or including their content in edited form. Adhere to the following guidelines when selecting sites to link to:

In some cases, product managers will request avoiding all or selected external links to avoid issues for customers impacted by restrictive firewall rules.

Use the <link/> element to mark up URLs that can be opened with a Web browser, such as https://www.example.org/. Always add the correct protocol prefix (for example, https://), otherwise links will not work. If possible, use the secure protocol prefix (https://).

Never use filename for a link, as that would both disable the link checker and make the link unclickable. Avoid entering a text label between <link/> start and end tags. Instead, use a self-closing tag:

<link xlink:href="https://www.example.org/"/>

Make URLs as short as possible before adding them to documentation. Many long URLs can be shortened by leaving away non-essential pieces, such as the _utm parameters used for marketing purposes. If a Web site provides a built-in URL shortener, use it.

Do not use third-party URL shorteners, such as bit.ly. Third-party URL shorteners have the following disadvantages:

Do not use <link/> to link to SUSE documentation outside of the current document set. Instead, use the appropriate entity for the book title. Always reference the book itself, as chapter names can change.

For consistency, do not use the article in front of the name of the referenced book or chapter. For example, “The general concept of Podman is described in Containers and Podman.”

Where possible, collect links in a “More information” section at the end of the chapter. This helps readers focus on your documentation instead of leading them immediately to other resources. This is described in Section 4.1, “Books”.

To mark up multiple links, create an <itemizedlist/> around them. Do not use a list environment for a single link. If you need to present many links, group them by topic and create a separate list environment for each group. Provide a comprehensive title for each of the groups or an introductory sentence. For more information about creating lists, see Section 7.13.1, “Itemized lists”.

Where possible, provide translators with localized versions of links in the comments of the source file.

Other types of references to resources are described in Section 7.5, “Cross-references” and Section 7.20, “References to other external resources”.

The SUSE documentation is hosted under documentation.suse.com. This is the URL that must be provided in all documents. The abbreviated URLs such as doc.suse.com and docs.suse.com also work but must be avoided for SEO reasons.

Make sure to use complete URLs instead of entities for an easy copy and paste.

Most links in our documentation that goes to documentation.suse.com refer to a specific product and release. However, sometimes it makes sense to not include the SP or even the major release. These are so-called SP-independent links.

The following reasons give you an idea when to use them:

Make sure to follow this syntax:

documentation.suse.com/<PRODUCT>[/<MAJOR_RELEASE>]/<DEEP_LINK>

The placeholders mean the following:

Make sure you use html and not single-html. This is needed for SEO reasons.

For example, the link https://documentation.suse.com/sle-ha/15-SP3/html/SLE-HA-all/article-installation.html#sec-ha-inst-quick-req/ points to the “System requirements” for SUSE Linux Enterprise Server High Availability Extension. To turn this link into an SP-independent link, you need to identify the different components first:

With the above parts, the redirection rules on our server allow expressing SP-independent links in several ways:

Note

If IDs have been changed between releases or SPs, this is what happens:

• If the hash part (everything after #) is not found, the browser will jump to the beginning of the file.

• If the file cannot be found (in our example, article-installation.html), the server will respond with a 404 error (file not found).

For figures within lists or procedures, use the <informalfigure/> element. In all other cases, use the <figure/> element. Always assign an xml:id attribute to <figure/> elements. Reference figures from the text by means of a cross-reference. For more information, see Section 7.5, “Cross-references”.

All referenced image files must have a lowercase alphanumeric file name. When specifying figure names, follow the naming conventions at https://github.com/SUSE/doc-modular/blob/main/templates/README.md.

Provide an appropriate image width using the width attribute. For both figure types, formal and informal, always add a <textobject role="description"/> as in Example 7.9, “Example of a figure” to provide an alternative text for the HTML output.

<figure xml:id="fig-picture">
 <title>An interesting picture</title>
 <mediaobject>
  <imageobject role="fo">
   <imagedata fileref="picture.eps" width="80%" format="EPS"/>
  </imageobject>
  <imageobject role="html">
   <imagedata fileref="picture.png" width="80%" format="PNG"/>
  </imageobject>
  <textobject role="description">
   <phrase>Cat chasing Geeko</phrase>
  </textobject>
 </mediaobject>
</figure>

An optional glossary contains terms and their definitions. Make sure that the glossary entries are appropriate to the intended audience. Define unfamiliar terms and special jargon.

Define infinitive forms of verbs and singular nouns. Do not start the definition with the term itself. Use lowercase for the term unless it is a proper noun.

Where applicable, group your terms with the <glossdiv/> tag for higher ordering.

To support automatic alphabetical ordering in localized versions, use <glosslist/> so that glossary items are sorted in alphabetical order by default.

Use cross-references in the following cases:

The markup for a glossary entry is shown in Example 7.10, “A typical example of a glossary”.

<glossary xmlns="http://docbook.org/ns/docbook" version="5.2">
  <title>Glossary</title>

  <glossentry xml:id="gt-docbook">
      <glossterm>DocBook</glossterm>
      <glossdef><para>...</para></glossdef>
  </glossentry>

  <glossentry xml:id="gt-svg">
      <glossterm>SVG</glossterm>
      <glossdef><para>...</para></glossdef>
  </glossentry>

  <glossentry xml:id="gt-extensible-markup-language">
      <glossterm>Extensible Markup Language</glossterm>
      <glossdef>
          <para> A markup language that defines a set of rules for encoding
              documents in a format that is both human-readable and
              machine-readable. </para>
          <glossseealso linkend="gt-docbook"/>
          <glossseealso linkend="gt-svg">SVG (Scalable Vector Graphics)</glossseealso>
      </glossdef>
  </glossentry>

  <glossentry xml:id="gt-xml">
      <glossterm>XML</glossterm>
      <glosssee linkend="gt-extensible-markup-language" />
  </glossentry>

</glossary>

Do not rework identifiers in existing documentation, instead apply these rules to newly created documentation only.

SUSE documentation uses the following types of lists (the respective XML elements are given in parentheses):

Follow these rules when creating or editing lists:

Never nest more than three lists within each other. Instead, restructure the information using a combination of lists and running texts.

To be able to reference untitled lists, use the xreflabel attribute. For more information, see Section 7.5, “Cross-references”.

<para>
 The following operating systems are supported:
</para>
<itemizedlist>
 <listitem>
  <para>
   Linux, Kernel 2.4 and newer
  </para>
 </listitem>
 <listitem>
  <para>
   FreeBSD 7 and newer
  </para>
 </listitem>
</itemizedlist>

<para>
 Before installing, make sure of the following:
</para>
<orderedlist>
 <listitem>
  <para>
   The network connection of the computer is configured properly.
  </para>
 </listitem>
 <listitem>
  <para>
   The latest security updates are installed.
   If you are in doubt, run an online update.
  </para>
 </listitem>
</orderedlist>

<para>
 This book consists of several parts:
</para>
<variablelist>
 <varlistentry>
  <term>Installation</term>
  <listitem>
   <para>
    Learn about the installation and initial configuration of a Linux system.
   </para>
  </listitem>
 </varlistentry>
 <varlistentry>
  <term>System</term>
  <listitem>
   <para>
    Get a basic understanding of the system components.
   </para>
  </listitem>
 </varlistentry>
</variablelist>

Capitalize all keys as printed on a standard keyboard. Capitalize all letter keys. To refer to a capitalized character, use Shift–Z, for example. Introduce this convention by means of the “Typographical Conventions” section of the introduction.

To mark up key combinations, use <keycombo/> as a wrapper for multiple <keycap/> elements. Separators between <keycap/> elements are then created automatically.

If a key is listed in Table 7.8, “Elements related to <keycap/>”, use the function attribute with the appropriate value. When using the function attribute, make the tag self-closing—DocBook's language files will insert key names automatically. This simplifies both your work and the work of translators.

For more information about creating cross-references, see Section 7.5, “Cross-references”.

To create a screenshot, press <keycap>Print Screen</keycap>.

To save a file, press
<keycombo><keycap function="control"/><keycap>S</keycap></keycombo>.

Create sections using the <sect1/>, <sect2/> and <sect3/> elements. Avoid outlines that require <sect4/> and <sect5/> elements. Instead, create a flatter structure in which more elements are visible at a glance.

Provide at least one paragraph of introductory information directly within each section.

Do not create lone subsections. A lone subsection is a section that is the only subsection of its parent section.

For more information about writing headlines, see Section 6.9, “Headings”.

Use procedures to describe sequential tasks. A procedure consists of the following elements and attributes:

To link alternative actions inside the same substep element, use “or.” Apply a performance=optional attribute to optional steps.

Steps may contain a link to an explanatory subsection providing further details on the step.

<procedure xml:id="pro-procedure">
 <title>Example of a procedure</title>
 <para>
  To add a new user to the system, perform the following steps:
 </para>
 <step>
  <para>
   In the <phrase role="productname">YaST</phrase> window,
   click <guimenu>User and group management</guimenu>.
  </para>
 </step>
 <step>
  <para>
   To open the <guimenu>Add a new user</guimenu> dialog, click
   <guimenu>Add</guimenu>.
  </para>
 </step>
 <step>
  <para>
   Type in the user name and click <guimenu>Create</guimenu>.
  </para>
 </step>
</procedure>

Always use the preferred product name instead of, for example, an acronym. When referring to a product, add a <phrase role="productname"/> element around it. This will not result in a visual change but disables hyphenation:

<phrase role="productname">LibreOffice</phrase> is an office suite.

Profiling is convenient for the creation of consistent documentation across different products or product lines. This is especially beneficial when similar products share a considerable amount of features, with only a few differences. Instead of maintaining separate documentation for each product, you can share most of the XML source code and only vary text snippets where necessary. In DocBook XML files, you can mark some elements as conditional by using profiling attributes. Specify which conditions apply to the output when processing the files to generate output. The style sheets will then include or exclude the marked text, according to the conditions.

Profiling allows you to keep both common and product-specific content in one XML file and select at production time which information to include in the output.

If you need to use profiling in your writing, adhere to the following guidelines:

<?xml version="1.0" encoding="UTF-8"?>
[...]
<phrase os="sles;sled">Note that the official update repository is only
available after registering your SUSE Linux Enterprise Server installation.</phrase>

MAIN="MAIN.SLEDS.xml"
ROOTID=book-administration
    
## Profiling
PROFOS="sles"
...

<?xml version="1.0" encoding="UTF-8"?>
[...]
Entire hard disks are listed as devices without numbers, such as
<filename>/dev/sda</filename><phrase arch="zseries;aarch64" os="sles;sled;slemicro"></phrase>.

Use questions-and-answers sections to present information about troubleshooting or commonly asked questions about a product. Never use questions-and-answers sections to explain trivia, such as how a product got its name. Keep your audience in mind. See also Chapter 1, Writing technical documentation.

Questions must always end in a ?. Where explanations longer than three paragraphs are necessary for an answer, add a cross-reference to an explanation outside of the questions-and-answers section. See also Section 7.5, “Cross-references”.

When a questions-and-answers section contains over 10 questions and there are clear topical divisions, add <qandadiv/> elements to further structure the section.

<qandaset>
 <title>Example of a questions-and-answers section</title>
 <qandaentry>
  <question>
   <para>
    How can I check if the product was correctly installed?
   </para>
  </question>
  <answer>
   <para>
    Open the log file.
    Look for entries starting with <literal>Failed</literal>.
   </para>
  </answer>
 </qandaentry>
 <qandaentry>
  <question>
   <para>
    Why does the error <literal>Not enough disk space</literal> occur
    during installation?
   </para>
  </question>
  <answer>
   <para>
    There are less than 4 GB of space available on the selected partition.
   </para>
  </answer>
 </qandaentry>
</qandaset>

To reference file names, use the <filename/> element. To reference e-mail addresses, use the <email/> element. In either case, do not include a protocol prefix, that is file:// or mailto:, respectively. See also Section 7.4.2, “File names”.

Reference man pages and info pages in this format:

In a situation where the category of the page is needed, append the category in parentheses. For example, use “(man 9 command).”

To learn more about subcommands, see the man page of
<command>command</command>.

Insert references to external (non-SUSE) physical books in the format “Title by Author (ISBN #00000000).” Inclusion of the ISBN is optional. Place the title in a <citetitle/> element. For example:

<citetitle>Lorem Ipsum</citetitle> by Dolores S. Amet
(ISBN 0-246-52044-7) is a useful guide.

Note that <citetitle/> is not translated.

As an author, where possible, provide language-specific references to translators in XML comments (see also Section 9.2, “XML comments”). As a translator, look for corresponding language-specific resources where none have been provided. For URLs, provide only the language-specific version of a site. Use the English version as a fallback. For books, provide the title of the translated version along with the original title if such a translation exists.

Other types of references to resources are described in Section 7.5, “Cross-references” and Section 7.8, “External links”.

Use tables to present many similar facts. Tables are easy to scan and compare. Always keep tables simple enough to not require long explanations even for readers unfamiliar with the topic.

A table always has a title and should have an xml:id attribute.

Typical use cases of tables include:

As there are use cases for tables, there are cases when not to use tables:

Some general style tips for tables:

<informaltable>
 <tgroup cols="2">
  <thead>
   <row>
    <entry>File System</entry>
    <entry>Maximum File Size</entry>
   </row>
  </thead>
  <tbody>
   <row>
    <entry>Ext2 (1 kB block size)</entry>
    <entry>16 GB</entry>
   </row>
   <row>
    <entry>Ext2 (2 kB block size)</entry>
    <entry>256 GB</entry>
   </row>
  </tbody>
 </tgroup>
</informaltable>

To mark up single user interface items, use <guimenu/>. To mark up nested menu structures, use <menuchoice/> as a wrapper for multiple <guimenu/> elements. Separators between <guimenu/> elements are then created automatically.

For more information about language aspects, see Section 6.22, “User interface items”.

To open a file, click <guimenu>Open</guimenu>.

To save a file, use
<menuchoice><guimenu>File</guimenu><guimenu>Save</guimenu></menuchoice>.