Use http://www.example.com and http://www.example.org as example domains. Both domains were registered for use in documentation.

Use objects of the solar system: For the most important system, use sun. For other systems, use the names of planets such as earth or mars.

Use addresses from the class C subnet 192.168.255.0 for examples. That is, replace the final 0 with any integer between 0 and 255. To create examples using a larger setup, use addresses from the private network ranges. For more information, see http://en.wikipedia.org/wiki/Private_network.

Use addresses from the subnet 2001:0db8::/32 for examples. That is, after the 2001:0db8: prefix, add six four-digit numbers, each separated by a colon on both sides. Each of the hexadecimal digits may have a value between 0 and f. A valid example URL is 2001:0db8:0123:4567:89ab:cdef:1234:5678. For more information, see http://en.wikipedia.org/wiki/IPv6_subnetting_reference.

For example users, use free-software mascots, such as Tux (Linux Kernel), Wilber (The GIMP), Geeko (SUSE), Foxkeh (Firefox), Konqi (KDE), or Duke (Java).

For books, use a document structure that includes the following elements, in that order:

For books with many chapters, create parts at the outline level above chapters.

For articles, use a document structure that includes the following elements, in that order:

The most important thing to do with your Web copy is to help users get answers to their questions as soon as possible. To achieve this, we recommend the modular approach of topic-based authoring where documentation is created and maintained in chunks, subsequently referred to as topics.

Topics have the sole purpose of supporting users in their tasks. Each topic focuses on one specific subject and has one distinct purpose. We write topics in a way that they can stand alone as well as in context with other topics. They should also be reusable in different contexts.

Recommendations:

SEO, or Search Engine Optimization, is the strategy to attract organic (unpaid) traffic that originates from online search and refers to visitors landing on the Web site. When it comes to SEO, content is key. Here are some insights to help you create and design the content that will rank high in search engines.

Remember that every document is a potential candidate for localization (translation). Make sure the document’s original English content is correct and clear. Simplicity, clarity and direct prose are essential.

Recommendations:

Avoid using abbreviations, especially unusual ones. Avoid creating plurals of abbreviations, unless the abbreviation is an acronym or initialism.

Do not artificially limit your audience by excluding or offending members of it.

Avoid indicating gender in your documentation. If possible, use plural to allow use of “they” as the pronoun. Otherwise, use “he or she.”

SUSE supports the Inclusive Naming Initiative which aims to help avoid harmful language. When making language choices for documentation, check the initiative's Evaluation Framework and its “Word lists.”

For more information about avoiding gender bias, see The Chicago Manual of Style, 5.43. For information about names of example items, see Section 3, “Names of example items”.

Use commas to separate elements in a series of three or more elements, but do not put a comma before the conjunction in most simple series. For example, “Find basic information about how to register your system, modules and extensions.” Use commas around phrases like for example and that is. Introductory phrases at the beginning of a sentence are normally followed by a comma. For example, “Before using YaST Online Update, configure a network connection.”

Do not use contractions (such as “don't”), unless you are purposefully writing a casual document.

Use en dashes (–) between numbers in a range in tables and figures.

For punctuation, use em dashes (—). Do not surround em dashes with spaces. Use em dashes sparingly.

End sentences in a period. Avoid using exclamation marks. Restrict question marks to question and answer sections.

Under Linux, objects like directories, printers, or flash disks are all considered files. Therefore, the naming and markup conventions are the same for “drives” (for example, hard disks, CD-ROM drives), directories, or files.

The layout for file names and directory names is the same. See the following example:

Most Linux file systems are case-sensitive. Use capitals exactly as they appear in the file system. For more information about markup aspects, see Section 7.19, “References to other external resources” and Section 7.4.2, “File names”.

When it is necessary to refer to file extensions, such as in compound words like “PDF file,” always capitalize the extension.

When writing a descriptive section, use a noun-based heading title, for example, “Concepts of Software.” When writing a task-orientated section, use a verb in gerund, for example, “Installing Software.”

Keep headings short and simple. Do not use both an acronym and the expanded form in a heading. Make sure that headlines in a chapter follow the same pattern.

For advice on how to nest sections, refer to Section 7.15, “Outline levels and sectioning”.

Generally, hyphens are used as joiners for two or more words that form a single concept and function together as a compound modifier before the noun. If the noun comes first, the hyphen is not added. For example, “the list in the upper-left corner” but “place the list in the corner in the upper left.”

There are technical guidelines to help you choose whether to use or not to use a hyphen.

Add the hyphen when:

Do not use the hyphen when:

Many combinations that are hyphenated before a noun are not hyphenated when they occur after a noun. For example: “This is the up-to-date version” and “The calendar is up to date.”

For information about creating lists, see Section 7.13, “Lists”.

Write the integers zero through nine as words. Use numerals for all other numbers.

When the unit of a measurement is abbreviated, always use numerals for the number. In measurements, add a non-breaking space ( ) between the numeral and its corresponding unit abbreviation. Use the % sign when paired with a number, with no space.

For more information, see The Chicago Manual of Style 9.6 and 9.16.

Do not use possessives of acronyms and trademarked terms. Avoid possessives of inanimate objects.

Add a hyphen after the prefix to prefixed words only if you foresee misunderstandings. For example, there is a difference in meaning between “recreate” and “re-create.”

For more information about using hyphens, see Section 6.10, “Hyphens”.

Use quotations to quote from sources, such as books. In all other cases, do not use quotation marks:

To create quotations, use the <quote/> element. This element is easier to localize than hardcoded quotation marks. During processing, localized quotation marks are added automatically. Avoid using single quotation marks.

The period and the comma always go within the quotation marks, as illustrated in Example 3, “Quote”. The dash, the semicolon, the colon, the question mark and the exclamation mark go within the quotation marks when they apply to the quoted matter only. They go outside when they apply to the whole sentence.

Avoid using semicolons to join sentences. You may use semicolons in place of commas in very complicated series.

Form clear and direct sentences with 20 words or less. Avoid complicated clauses. Make sure that the relationship between subject, verb, and object is clear. Avoid joining sentences with semicolons. Avoid ending sentences with prepositions.

Avoid using parentheses. Where they are necessary, move them to the end of the sentence. Never nest parentheses.

Always let the reader know the objective of an action before describing the action itself. As an example, write: “To save the settings, click OK.”

Do not use slashes except when they are part of a standard technical term, such as TCP/IP or client/server.

Use the simple present tense. Apply the simple present tense even to sentences with “if” or “when” clauses and to prerequisites of an action. For example, “If this happens, go there.” or “Glibc is installed.”

Maintain a professional tone. Do not use contractions, except in casual documents. Do not use humor. Be honest and avoid absolutes and exaggerations, but focus on positive aspects.

Use the second person (“you”) to refer to the reader. Normally, the reader is the user or administrator who performs the actions described. For example, “To install all officially released patches that apply to your system, run zypper patch.” Do not overuse “you” and “your.” It is often implied who you are addressing in the instructions. For example, instead of “Install package on your system,” just say “Install package on the system.”

Where possible, use active voice. If there is no emphasis on the object of the verb or if the performer of the action is unknown, use passive voice. “A Samba server must be configured in the network” is an example of the proper use of passive voice. The emphasis is on the server, not on the person configuring it.

When giving a recommendation, start with “We recommend.” Do not use passive phrasings like “It is recommended.”

To refer to other parts of the document, start with “For more information (about), see.”

Most products referenced in the documentation are trademarked. Follow these rules when dealing with these terms:

For more information about markup aspects, see Section 7.17, “Products”.

When referring to labels of user interface items, do not include ending punctuation such as … or :. Whenever possible, refer to user interface items without identifying them as any special type of element. For example, use “click OK” rather than “click the OK button.” However, complex dialogs may require more specific wording.

When referring to UI labels, capitalize them exactly as in the UI itself. Software created at SUSE (such as YaST or Uyuni) should use sentence-style capitalization. If it does not, you can make aware the developers of that software. For more information about sentence-style capitalization, see Section 6.3.1, “Most titles: sentence-style capitalization” and the SUSE Product Brand guide.

For more information about markup for UI labels, see Section 7.21, “User interface items”.

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 list the contents of a directory, execute
<command>ls <replaceable>DIRECTORY</replaceable></command>.

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

<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.19, “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>

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.19, “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. 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 12, “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 13, “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 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.

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 Section 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>.

With GeekoDoc 2, it is possible to use the Internationalization Tag Set (ITS) tags to explicitly indicate that a tag should be translated or not.

For this, you need to have the ITS namespace enabled in the XML file. Make sure the following line is added to the root element: xmlns:its="http://www.w3.org/2005/11/its".

For example: You have used the tag <guimenu> which is usually translated but in this particular case it should not be translated.

To mark the tag correctly, use the ITS tag as shown here:

Click <guimenu its:translate="no">Save</guimenu>.

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:

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 Section 10, “Formatting XML”.

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

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.

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

<!ENTITY1 server2 "sun3">
<!ENTITY domain  "example.org">
<!ENTITY host    "&server;.&domain;4">
<!ENTITY hosttag "<uri xmlns='http://docbook.org/ns/docbook'>&host;</uri>5">

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

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.

Assembly files use ITS tags and attributes which flag whether the content of the tag should be translated or not. In the following example, the ITS attribute indicates that the content of the tag should not be translated:

<meta name="maintainer" content="Smart Doc author" its:translate="no"/>

If the its:translate attribute is set to yes, translation is needed.

<meta name="bugtracker" its:translate="no">

<phrase role="url">https://bugzilla.suse.com/enter_bug.cgi</phrase>

<phrase role="component">Non-product-specific documentation</phrase>

<phrase role="product">Smart Docs</phrase>

<phrase role="assignee">assignee@suse.com</phrase>

<meta name="translation" its:translate="no"/>

<phrase role="trans">yes</phrase>

<phrase role="language">de-de,cs-cz</phrase>

<meta name="architecture" content="x86;power"
its:translate="no"/>

<meta name="productname" its:translate="no"/>

<productname version="15-SP5">SLES</productname>

<meta name="title" its:translate="yes">
short title for SEO and social media, max. 55 chars</meta>

<meta name="description" its:translate="yes">
short description, max. 150 chars</meta>

<meta name="social-descr" its:translate="yes">
ultrashort description for social media, max. 55 chars</meta>

<dm:docmanager xmlns:dm="urn:x-suse:ns:docmanager">
  <dm:bugtracker>
    <dm:url>https://bugzilla.suse.com/enter_bug.cgi</dm:url>
    <dm:component>Smart Docs</dm:component>
    <dm:product>Documentation</dm:product>
    <dm:assignee>maintainer@suse.com</dm:assignee>
  </dm:bugtracker>
  <dm:editurl>https://github.com/SUSE/doc-modular/tree/</dm:editurl>
  <dm:translation>no</dm:translation>
</dm:docmanager>

<resource xml:id="_glue-example" href="../glues/glue.xml">
  <description>Glue example</description>
</resource>

<merge>
  <title>Your title, limit to 55 characters, if possible</title>
  <subtitle>Subtitle if necessary</subtitle>
  <revhistory xml:id="rh-USE_ROOTID">
    <revision>
      <date>2024-11-11</date>
      <revdescription>
        <para>
          Describe the purpose of this revision
        </para>
      </revdescription>
    </revision>
    <revision>
      <date>2024-10-10</date>
      <revdescription>
        <para>
         Describe the purpose of this revision
        </para>
      </revdescription>
    </revision>
  </revhistory>
  <module resourceref="_concept-example" renderas="section"/>
</merge>
<title>You are a very special concept now!</title>

A revision history lists all the high-level changes about the document itself. It gives the reader an overview of important changes made over time.

Update revision history regularly, mentioning most important changes to your document when you amend or rework it. The data you enter as revision history is used as meta data. The “Revision History” text is available as a link before the abstract and opens up in its individual page. Keep in mind the following rules:

<revhistory xml:id="rh-USE-ROOTID">  
  <revision><date>2024-11-13</date>
    <revdescription>  
      <itemizedlist>
        <listitem><para>Added sections:</para>
          <itemizedlist>
            <listitem><para>New section on <quote>foo</quote> to resolve issue <uri>bsc#12345</uri></para></listitem>
            <listitem><para>New section on <quote>foo bar</quote></para></listitem>
          </itemizedlist>
        </listitem>
        <listitem><para>Removed sections:</para>
          <itemizedlist>
            <listitem><para>Removed section on <quote>foo1</quote> to resolve issue <uri>bsc#12346</uri></para></listitem>
            <listitem><para>Removed section on <quote>foo1 bar</quote></para></listitem>
          </itemizedlist>
        </listitem>
        <listitem><para>Changed sections:</para>
          <itemizedlist>
            <listitem><para>Changed section on <quote>foo2</quote> to resolve issue <uri>bsc#12347</uri></para></listitem>
            <listitem><para>Changed section on <quote>foo2 bar</quote></para></listitem>
          </itemizedlist>
        </listitem>
      </itemizedlist>
    </revdescription>
  </revision>
</revhistory>