SUSE Documentation Style Guide

This guide provides answers to writing, style, and layout questions commonly arising when editing SUSE documentation. The GeekoDoc/DocBook markup reference at the end of this guide will help you choose the right XML element for your purpose. Following this guide will make your documentation more understandable and easier to translate.

Authors: Rebecca Walter, Martina Dejmek, and Stefan Knorr
Publication Date: 11/05/2018 , Version: 2016-07

Copyright © 2007– 2018 SUSE LLC and contributors. All rights reserved.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or (at your option) version 1.3; with the Invariant Section being this copyright notice and license. A copy of the license version 1.2 is included in the section entitled GNU Free Documentation License.

For SUSE trademarks, see All other third party trademarks are the property of their respective owners. Trademark symbols (®, ™ etc.) denote trademarks of &suse; and its affiliates. Asterisks (*) denote third-party trademarks.

All information found in this book has been compiled with utmost attention to detail. However, this does not guarantee complete accuracy. Neither SUSE LLC, its affiliates, the authors nor the translators shall be held liable for possible errors or the consequences thereof.

1 Audience

Before starting to write, define the target audience of your documentation. Adjust tone, style, and technicality of the text based on the intended audience. Keep in mind that not all facts that seem obvious to you will be obvious to your readers. If you move parts of documents into other documents, make sure to adapt the parts you move to the new document.

For later reference, document the defined target audience in the main file of every book and article. Place an XML comment directly before the relevant <book/> or <article/> element, such as this:

<!-- Target audience: institutional desktop users. -->

For more information using XML comments, see Section 6.2, “XML Comments”.

Generally, there is no need to add information about the target audience to the book or article content itself.

2 Names of Example Items

This section summarizes conventions for creating generic names for objects in documentation. At least some of the following names should be provided through entities. See also Section 6.3, “Entities”.

2.1 Domains

Use and as example domains. Both domains were registered for use in documentation.

2.2 Host Names

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.

2.3 IPv4 Addresses

Use addresses from the class C subnet for examples. That is, replace the final 0 by any integer between 0 and 255. To create examples using a larger setup, use addresses from the private network ranges. For more information, see

2.4 IPv6 Addresses

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

2.5 Users

For example users, use free-software mascots, such as Tux (Linux Kernel), Wilber (The GIMP), Geeko (SUSE), Foxkeh (Firefox), Konqi (KDE), or Duke (Java). In prompts, use the lowercase version of these names.

3 Outline of a Manual

Maintain a consistent structure within your documents. The structure can vary between different books, articles or projects, but the most common parts of the document structure are documented here.

3.1 Books

Always use a document structure that includes the following elements, in that order: a preface, and chapters which are split in sections. Optionally, add appendixes, a glossary, and an index. In some cases, parts can be created at the outline level above chapters.

Title Page and Imprint

Both title page and imprint are created automatically, but depend on information being present in the book.

  • Title.  Work with the marketing department to define the correct book title. The book title should not contain the product name and version.

  • Product Name and Product Version.  Work with the marketing department to find the correct product name and version number. Mark this information up with <productname/> and <productnumber/>, respectively.

  • Documentation Version or Revision Information.  Use the <releaseinfo/> element to mark up version or revision numbers of the documentation itself. For more information on enabling SVN revision information in your document, see

  • Authorship Information.  Create a separate file authors.xml and add an <authorgroup/> listing all authors and contributors inside it. Include this file with an XInclude.

  • Copyright Notice.  Use the standard copyright notice reproduced below. Change the starting year of the copyright protection to the current year.

    Example 1: Standard Copyright Notice
      Copyright &copy; [starting year]&ndash;<?dbtimestamp format="Y"?>
      SUSE LLC and contributors. All rights reserved.
      Permission is granted to copy, distribute and/or modify this document
      under the terms of the GNU Free Documentation License, Version 1.2 or
      (at your option) version 1.3; with the Invariant Section being this
      copyright notice and license. A copy of the license version 1.2 is
      included in the section entitled <quote>GNU Free Documentation
      For &suse; trademarks, see
      <link xlink:href=""/>.
      All other third-party trademarks are the property of their respective
      owners. Trademark symbols (&reg;, &trade; etc.) denote trademarks
      of &suse; and its affiliates. Asterisks (*) denote third-party
      All information found in this book has been compiled with utmost
      attention to detail. However, this does not guarantee complete
      accuracy. Neither SUSE LLC, its affiliates, the authors nor the
      translators shall be held liable for possible errors or the
      consequences thereof.

Use an abstract to summarize the information provided in a book, article, or set in five or fewer sentences. Summarize the topic instead of summarizing the outline.

Example 2: An Abstract

SUSE Linux Enterprise ships with several file systems, including Btrfs, Ext3, Ext4. Each file system has advantages and disadvantages that make it more or less suitable for a scenario. Professional high-performance setups can require a different choice of file system than a home user setup. This guide will help you choose the right one.

Table of Contents

The table of contents is generated automatically.


The preface of a book contains a brief overview of the content of a manual, related manuals, and typographical conventions. It may also contain information about its target audience.


If you are writing a book with many chapters, create parts at the outline level above chapters. Parts should contain at least three chapters. Keep part titles clear and concise. Often a single noun is enough. Typical part titles include Installation or Network.


Chapters typically consist of the following elements (appendixes should be regarded an exception):

  • Highlights.  Use a highlights section to summarize the information provided in a chapter in four or fewer bullet points. Summarize the topic instead of summarizing the outline.

    Example 3: A Highlights Section

    This chapter will:

    • Give you an overview over the file systems available in SUSE Linux Enterprise, such as Ext3, Ext4, and Btrfs.

    • Inform you about their distinctive advantages and disadvantages.

    • Help you choose the right one for your purpose.

  • Introductions.  Any introductory information follows directly after the highlights section and should not be placed in a separate section.

  • Sections.  Structure the detailed information, so readers can skim the text. Create sections for every major task, such as installing, configuring, monitoring, and administering. If helpful, split sections into subsections, but avoid going above three levels of sections.

    Sections start with an introductory paragraph outlining the focus of the section. If the section describes a sequential task, follow the introduction with a procedure description, as discussed in Section 5.17, “Procedures”. Steps of a procedure can contain a cross reference to subsections where topical background is provided and an action is explained in detail. See also Section 5.5, “Cross References”.

  • Troubleshooting.  In this section, collect common mistakes and problems. The section should always be named Troubleshooting. Use the DocBook element <qandaset/> (a Question and Answer section) to mark up Troubleshooting problems. In case you want to describe solutions to more than ten problems, add topical subsections ( <qandadiv/> elements) below the Troubleshooting section.

  • For More Information.  In this section, collect Web links to all sources of information that might prove helpful in a given context. Follow the general referencing guidelines in Section 5.5, “Cross References” when creating such sections.


The optional glossary contains important terms in alphabetical order and provides a brief explanation.

3.2 Articles

For articles, use a structure similar to that of books. However, note that there is no equivalent of parts in articles. Additionally, in articles, the function of chapters is filled by first-level sections (<sect1/>).

4 Language

The following rules are intentionally kept concise. When in doubt about a style rule, see The Chicago Manual of Style, 15th Edition. When in doubt about the spelling or usage of a word, first see Appendix A, Terminology and General Vocabulary. When the usage of a word is not regulated there, use American English spellings as defined on ( for short).

If a product you are documenting is not listed in the terminology table, refer to the SUSE home page, If the product is not mentioned on the SUSE home page, refer to the Marketing department.

4.1 Abbreviations

Where possible, avoid using abbreviations. Especially avoid unusual abbreviations. You may create plurals of acronyms. In all other cases, avoid creating plurals of abbreviations.

4.1.1 Acronyms

Headlines or captions must not contain both an acronym and its expansion. When dealing with a term that is commonly written as an acronym, use the acronym in the title. When mentioning the term for the first time in the following text, use its expanded form. All following occurrences of the term in this chapter should then use the acronym.

Sometimes chapters and parts are used across multiple documents, therefore provide the expansion of an acronym at least once per chapter. Provide the expansion by adding it in parentheses after the acronym.

Create plural forms of acronyms by adding a lowercase s, for example, use CDs and BIOSs. Never add an apostrophe before the s.

Avoid using possessive forms of acronyms (a negative example would be XMLʼs specification) for reasons of clarity.

4.1.2 Latin Abbreviations

Do not use Latin abbreviations. Use the full English form: for example, use that is instead of i.e.. As an exception to this rule, the abbreviation etc. is allowed.

4.1.3 Units of Measurement

You may use abbreviations of common units of measurement. For more information on units of measurement, see Section 4.11, “Numbers and Measurements”.

4.2 Capitalization and Title Style

In all running text, use sentence-style capitalization. That is, only capitalize the first word of a sentence and proper names.

Use title-style capitalization for all types of headings and titles, including figure and table titles. This style is explained in The Chicago Manual of Style 8.167. A simplified version of these rules is below:

  1. Capitalize the first and the last word.

  2. Write articles in lowercase. Articles are: the, a, and an.

  3. Write prepositions in lowercase unless they are used with a verb (Logging In) or in a noun (The On Button). Prepositions are for example: up, in, of, through, and between.

  4. Write certain conjunctions in lowercase: and, but, for, nor, and or.

  5. Write as and to in lowercase.

  6. Capitalize everything that is not mentioned above.

In variable lists, capitalize the term in title style unless it is a complete sentence. In all list items, use sentence-style capitalization (capitalize the first letter and proper nouns only). Use title style for row and column labels in tables.

4.3 Commas

Use commas between all items in a series of three or more elements. For example, write a, b, and c. 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.

4.4 Contractions

Do not use contractions, unless you are purposefully writing a casual document.

4.5 Dashes

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.

4.6 End of Sentence Punctuation

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

4.7 File and Directory Names

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, or flash disks), directories, or files.

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

  • In general, use forward slashes (/) to separate nested directory or file names. If you are describing actions performed on Windows* systems and within a Windows-native file system, use backward slashes (\) instead.

  • In general, when giving absolute paths, always start with a leading slash to indicate the root of the file system. If you are describing actions performed on Windows systems and within a Windows-native file system, do not add a leading slash to absolute paths.

  • Use a trailing slash to distinguish between a file and a directory. If the distinction is important in the current context, in addition comment on it in the accompanying or surrounding running text.

Most Linux file systems are case-sensitive. Use capitals exactly as they appear in the file system. For more information on markup aspects, see Section 5.15, “References to Other External Resources” and Section 5.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.

4.8 Gender Bias

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

For naming of example items, refer to Section 2, “Names of Example Items”. For more information on how to avoid gender bias, refer to The Chicago Manual of Style 5.43.

4.9 Headings

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

Provide at least some introductory information between a heading and its subheadings.

For advice on how to nest sections, refer to Section 5.16, “Outline Levels”.

4.10 Lists

The following rules apply to both ordered and unordered lists:

  • Each list entry starts with a capital letter if it is a complete sentence

  • If a list entry consists of a single sentence, do not use period

  • Use periods if a list entry contains two or more sentences

4.11 Numbers and Measurements

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 ( &nbsp; ) between the numeral and its corresponding unit abbreviation.

For more information, refer to The Chicago Manual of Style 9.6.

4.12 Possessives

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

4.13 Prefixes

Add a hyphen after the prefix to prefixed words only if:

  • The last letter of the prefix and the first letter of the word are the same.

  • You foresee misunderstandings. For example, there is a difference in meaning between recreate and re-create.

4.14 Semicolons

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

4.15 Slashes

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

4.16 Sentence Structure

Form clear and direct sentences with 20 words or less. Avoid complicated clauses. Make sure that the relationship between subject, verb, and object are 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 restore world peace, click Shake Hands.

4.17 Tense

Use the simple present tense. Apply the simple present tense even to sentences with if or when clauses: If this happens, go there.

Prerequisites of an action should be expressed in the present tense as well: Glibc is installed. In some cases, no verb is necessary before the prerequisite of an action: a 1 GHz processor or better.

4.18 Tone and Voice

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 second person (you) to refer to the reader. Normally, the reader is the user or administrator that does the actions described. Do not overuse you. It is often understood, especially in directions.

Where possible, use active voice. In active voice, the subject of the sentence performs the verb. For example, The root user performs administrative tasks is active voice. Administrative tasks are performed by the root user is passive voice.

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

4.19 Trademarks

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

  • Never use trademarks in headings.

  • Only use the marked version on the first occurrence of the product name in a chapter.

  • Only use the ®, ™, or ℠ marks for Micro Focus products.

  • Use an * (asterisk) for all service marks or trademarks of third-party companies. This acknowledges the service mark or trademark of the other company. It also protects SUSE if the protection of the brand changes in any way.

For more information on markup aspects, see Section 5.18, “Products”.

4.20 User Interface Items

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.

For instructions concerning markup, refer to Section 5.21, “User Interface Items”.

4.21 Quotations

Use quotations to quote from sources, such as books. In most other cases, you should not use quotation marks. For example, avoid ironic usage of words entirely. In the case of computer input and output or user interface elements, use more appropriate markup. See also Section 5.4, “Command Line Input and Output” and Section 5.21, “User Interface Items”.

To create quotations, use the <quote/> element, as it is easier to localize than hardcoded quotation marks and always provides typographic quotes.

Punctuation directly following the quoted text should be included within the quotation marks, as illustrated in Example 4, “Quote”.

Example 4: Quote

Suds may froth, the sign reads.

5 Structure and Markup

Structure your documentation by tasks relevant to the user instead of providing reference documentation by describing each part of the user interface individually. Often, it is unnecessary to describe every minor functionality of a product. Describe what a product can do rather than its limitations.

SUSE uses the GeekoDoc Relax NG schema which is compatible with DocBook 5.1. Thus, for more detailed descriptions of the elements of a book, see the DocBook 5.1: The Definitive Guide sections listed in Table 1, “Important Elements”.

5.1 Admonitory and Advisory Paragraphs

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.

  • <warning/> Use these elements to warn of security issues, potential loss of data, damage to hardware, or physical hazards. Warnings must always precede the action to which they apply.

  • <important/> Use these elements to give vital information.

  • <tip/> Use these elements to introduce guidelines or give tips.

  • <note/> Use these elements to highlight software version differences.

Follow these rules when writing admonitions:

  • Add a <title/> to admonitions. In the title, state the subject of the admonition and, in the case of a <warning/>, also the source of danger.

  • <warning/> or <important/>: In the first paragraph, clearly state possible consequences of ignoring the danger.

  • <warning/> or <important/>: In the second paragraph, explain how to avoid the danger. If there are multiple ways to avoid a danger, use an unordered list. If fewer than five consecutive steps need to be taken to avoid a danger, use an ordered list. If more than five consecutive steps need to be taken, use a cross reference to another part of the documentation.

Example 5: An Example of a Warning (Source)
  <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>Always wait until formatting has finished.</para>
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.

5.2 Application Names

When referring to an application, 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.

5.3 Callouts

Add the <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 5.7, “Examples”.

Example 6: Example of Callouts (Source)
<screen>color white/blue black/light-gray <co xml:id="co.color"/>
default 0 <co xml:id="co.default"/></screen>
  <callout arearefs="co.color">
    <para>Colors of the boot loader menu.</para>
  <callout arearefs="co.default">
    <para>Defines the preselected option.</para>
Example 7: Example of Callouts (Output)
color white/blue black/light-gray 1
default 0 2


Colors of the boot loader menu.


Defines the preselected option.

Table 2: Elements Related to <callout/>
ElementWeb Link

<co/> Inline element to mark an area within a <screen/>.

<calloutlist/> Block element containing a list of descriptions for each of the marked areas.

<callout/> Block element containing a description of a single area marked with <co/>.

5.4 Command Line Input and Output

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 it in a <screen/> element. See also Section 5.7, “Examples”.

When using <command/> elements standalone, that is outside of a <screen/>, do not use <prompt/> elements before or within them. For more information about <prompt/>, see Section 5.4.5, “Prompts”.

Table 3: Elements Related to Command Line Input and Output
ElementWeb Link

<screen/> Block element in which all characters are reproduced exactly as they are in the source of the document. See also Section 5.7, “Examples”. Can contain any of the inline elements listed in this table.

<command/> Inline element that contains the name of an executable program or the command that a user types to execute a program. Can contain <replaceable/> elements.

<option/> Inline element that contains an argument to a command or instruction. Can contain <replaceable/> elements.

<replaceable/> Inline element that contains content that can or must be replaced by the user.

<filename/> Inline element that contains the name of a directory or file. Can contain <replaceable/> elements.

<varname/> Inline element that contains the name of a variable. Can contain <replaceable/> elements.

5.4.1 Commands

Commands can be embedded in running text or presented as part of a screen environment. In running text, use <command/> when referring to an actual command you would use on a command line:

To start LibreOffice from the command line, use

Where options or subcommands belong with a command, include them within the element <command/> itself:

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

If options or subcommands stand for themselves in a text, wrap them in the element <option/>.

Use markup for commands even inside <screen/> environments. To avoid spelling or capitalization errors, where possible, run commands before adding them to the documentation.

See also Section 5.4.5, “Prompts”.

5.4.2 File Names

A file name is the name of a file on a local or network disk. Can contain a simple name or could include a path or other elements specific to the operating system. See also Section 4.7, “File and Directory Names”.

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

5.4.3 Placeholders

To mark up text that readers need to replace, use the <replaceable/> element.

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

5.4.4 Literals

Use <literal/> to mark up data taken literally from a computer system.

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

5.4.5 Prompts

When documenting commands entered into Bash with a <screen/> element, always prefix them with a prompt marked up this way:

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

To avoid making prompts longer than necessary, never include a host name or a path. The first restricted user should always be named tux. For more information on names of restricted users, see Section 2, “Names of Example Items”.

Avoid using root prompts in your documentation by using the sudo command where applicable. If you do need a root prompt, always mark it up as following:

<prompt>root # </prompt><command>yast</command>

When documenting prompts other than the one of Bash, use a custom prompt that is as generic as possible.

For consistency, it is helpful to create entities for the prompts used in your documentation. For more information, see Section 6.3, “Entities”.

5.4.6 Screens

Screens are used to present:

  • long commands and commands together with their output

  • system output, such as system messages

  • code or configuration examples

<screen><prompt>tux > </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>
  • Use screens only where necessary for understanding the documentation. Present longer screens as examples. For more information, see Section 5.7, “Examples”.

  • Do not add empty lines at the beginning or end of screens. They can be cut away by the suse2013 stylesheets, however, most stylesheets do not have such functionality.

  • Text in screens should not follow the indentation level of the XML around them: All indentation will be reproduced verbatim.

  • Lines in a screen should be at most 80 characters long. If you are working in a structure with less available space, such as within a list or within a table, work with appropriate shorter line lengths.

  • To make long shell commands less unwieldy, split them into multiple lines at appropriate positions, such as after the end of an option. At the end of each line but the last, append a \. The character \ informs the shell that the command invocation will continue after the end of the line. Splitting commands into lines can also be helpful for aligning callouts with the right option.

  • To work with long output, especially tabular output, use either of the following strategies:

    • Remove or replace items that are irrelevant to your goal. For example, replace long file names by shorter ones or remove a table column and replace it with [...].

    • Use a processing instruction at the beginning of the screen to decrease font size:

      <?dbsuse-fo font-size="SIZEem"?>

      Replace SIZE by a suitable value, such 0.7. Choose a value between 0.55 and 1. Values outside that range will lead to either unreadably small or unsuitably large text.

See also Section 5.7, “Examples”, Section 5.4.1, “Commands”, Section 5.4.5, “Prompts”, and Section 5.3, “Callouts”.

5.4.7 Variable Names

To reference to names of variables, use the <varname/> element:

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

5.5 Cross References

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. Do not insert text labels such as appendix, chapter, table, or figure. These labels are generated automatically.

To be able reference an otherwise untitled element, add the attribute xreflabel to the element with a useful title as its value. Never create references to single paragraphs ( <para/> ).

Other types of references to resources are described in Section 5.15, “References to Other External Resources” and Section 5.8, “External Links”. Create identifiers to reference from cross references using the rules under Section 5.11, “Identifiers”.

Example 8: Example of a Cross Reference (Source)
<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>
Example 9: Example of a Cross Reference (Output)

5.6 Emphasis

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>

5.7 Examples

Use examples to illustrate complex processes. The rules established in Section 5.9.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 on screen environments, see Section 5.4.6, “Screens”. For more information on displaying computer input and output, see Section 5.4, “Command Line Input and Output”. To annotate examples, use callouts. Callouts are described in Section 5.3, “Callouts”.

Example 10: Example of an Example
<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>
Table 4: Elements Related to <example/>
ElementWeb Link

<example/> Formal block element containing a <title/> and a <screen/> or other elements such as lists or paragraphs.

<screen/> Verbatim block element for displaying text that readers might see on a computer terminal or in a text file.

5.9 Figures

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 5.5, “Cross References”.

All referenced image files must have a lowercase alphanumeric file name. Provide an appropriate image width using the width attribute. Always add a <textobject role="description"/> as in Example 11, “Example of a Figure” to provide an alternative text for the HTML output.

Example 11: Example of a Figure
<figure xml:id="fig.picture">
  <title>An Interesting Picture</title>
    <imageobject role="fo">
      <imagedata fileref="picture.eps" width="80%" format="EPS"/>
    <imageobject role="html">
      <imagedata fileref="picture.png" width="80%" format="PNG"/>
    <textobject role="description">
      <phrase>Cat chasing Geeko</phrase>
Table 5: Elements Related to <figure/>
ElementWeb Link

<figure/> Formal block element containing a <title/> and a <mediaobject/>.

<informalfigure/> Informal block element containing a <mediaobject/>.

<mediaobject/> Block element containing one or more <imageobject/> elements. Place additional textual descriptions inside <textobject/> elements.

<imageobject/> Element containing <imagedata/> and meta information about the image.

<imagedata/> Element that points to an external image file.

<textobject/> Element containing textual description of a media object as a fallback option.

5.9.1 Graphics

Keep graphics as simple as possible. Use as little text as possible. To allow for translation, reserve twice as much space for runs of text as the English version of it consumes.

5.9.2 Screenshots

Use screenshots to illustrate complex situations in which the user cannot easily follow the instructions otherwise.

  • Be selective. Only illustrate steps in which meaningful user interactions are necessary. Do not create screenshots of progress bars or confirmation windows. Usually, it is unnecessary to create a screenshot of every step of an instruction.

  • Always create screenshots illustrating the situation right before an action has been taken.

  • Insert screenshots directly after the textual description of the action.

  • Make sure screenshots focus on what they are supposed to illustrate. When documenting application windows, create a screenshot of the window only. When documenting Web applications, only reproduce the contents of the tab instead of the entire browser window.

  • Do not scale screenshots using graphics software. Embed screenshots at their original resolution and use DocBook attributes to scale them appropriately.

  • Avoid creating screenshots of windows higher or wider than 800 pixels at 96 pixels per inch. When creating screenshots of applications scaled for a higher pixel-per-inch count, apply a proportionally larger maximum window size.

  • Create screenshots that are recognizable to readers. For example, create screenshots of KDE applications on a KDE desktop with the default KDE theme and disable toolbar modifications you have made.

  • Use grayscale font antialiasing (default on SUSE operating systems). Subpixel font antialiasing creates colored letter edges when zoomed or printed.

  • Where applicable, follow the rules in Section 2, “Names of Example Items”.

  • Avoid editing screenshots. If you need to edit a screenshot, use the Shutter application. To anonymize portions of a screenshot, use the Pixelize tool. To highlight parts of a screenshot, use the Rectangle tool or the Arrow tool. Never add callouts, text or freely drawn objects. Always select colors that provide a good contrast with their background.

5.10 Glossaries

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. Use lowercase for the term unless it is a proper noun.

Use cross-references to link acronyms with their written out forms. Define the written out form. Use a See reference for the acronym form to link it to the defined written out form.

The markup for a glossary entry is shown in Example 12, “A Typical Example of a Glossary”.

Example 12: A Typical Example of a Glossary
    <glossterm xml:id="gt.extensible">Extensible Markup Language</glossterm>
      <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>See also <xref linkend="gt.extensible"/>.</para>

5.11 Identifiers

  • Always use an xml:id attribute in parts, chapters, appendixes, sections, figures, and examples. Identifiers can be used in other elements as well, such as tables and procedures.

  • In identifiers, only use alphanumeric characters, ., _, and -.

  • Identifiers consist of up to three parts. Join these parts with a ..

    1. Prefix.  Signifies the type of XML element. Use in accordance with Table 6, “Abbreviations for Different Elements in an xml:id Attribute”.

    2. Chapter Title Label.  Shortened version of the title of the parent chapter or parent chapter-level element (preface, appendix, etc.). Do not add a chapter title label to chapters and chapter-level elements themselves. Do not add chapter title identifiers within articles. Do not use . within the chapter title label.

    3. Element Title Label.  Shortened version of name of the title of the element itself. Do not use . within the element title label.

    Example 13: Examples of Identifiers
  • Use short, memorable, English terms or phrases as title labels. Favor longer terms over non-obvious abbreviations. Always use the singular of nouns and the infinitive of verbs. For example, a section about installing with YaST could be called sec.install.yast.

  • Keep in mind that section and chapter identifiers are used in the online documentation URLs. Choosing understandable keywords helps readers to understand what the page is about and also improves the search engine ranking.

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

Table 6: Abbreviations for Different Elements in an xml:id Attribute
<appendix/> app
<book/> book
<co/> co
<chapter/> cha
<example/> ex
<figure/> fig
<glossary/>, <glossterm/> gl
<itemizedlist/> il [a]
<listitem/> li
<indexterm/> idx [b]
<orderedlist/> ol[a]
<part/> part
<preface/> pre
<procedure/> pro
<qandaset/>, <qandadiv/>, <qandaentry/> qa
<sect1/>, <sect2/>, etc. sec
<set/> set
<step/> st
<table/> tab
<variablelist/> vl
<varlistentry/> vle

[a] Only add an xml:id attribute when the list has a title element

[b] Only add when creating index ranges

5.12 Indexes

Insert index terms as close to the relevant text as possible. When more than five paragraphs belong to a topic, use a page range. Nest index terms up to two levels deep.

Index information users are likely to be looking for. Consider that users might not have in mind the same terms you do. This is especially often the case when it comes to highly technical words or brands.

Adapt breadth and depth of index terms included of a topic to the weight the topic has within the manual. Do not index For More Information sections, abstracts, or passing mentions of items.

Be consistent in the terms you index. Write nouns in the plural. Write verbs in the gerund (-ing form). Use sentence-style capitalization.

If an entry has six or more page references, create more specific subentries. If an entry only has a single subentry, delete the subentry.

Check for spelling errors and inconsistencies that result in multiple items in the index. Check all see and see also references for consistency. Do not create index entries that have both a page and a see reference. Avoid creating index entries that have both a page references and a see also reference.

<indexterm/> elements mark text passages that should be referenced in an <index/>. Simple <indexterm/> elements are placed in the flow of the document at the exact point which the Index page should refer to.

Example 14: Example of a Simple Index Entry
To configure DNS
</indexterm>, use the DNS configuration utility.

An index range consists of two separate <indexterm/> elements, the first one signifying the start, the second the end of the indexed range.

Example 15: Example of an Index Range
<indexterm class="startofrange" xml:id="idx.install">
<indexterm class="endofrange" startref="idx.install"/>
Example 16: Example of a See Index Entry
  <secondary>boot loaders</secondary>

5.13 Lists

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

  • Unordered lists ( <itemizedlist/> ). Also known as bullet lists.

  • Numbered lists ( <orderedlist/> ).

  • Descriptive lists ( <variablelist/> ). Also known as definition lists or variable lists.

  • Procedures ( <procedure/> ). Also known as step-by-step instruction lists. Described in Section 5.17, “Procedures”.

Follow these rules when creating or editing lists:

  • List environments should be used with caution. Their markup is quite distinct and overusing them might disrupt the text flow.

  • Always introduce a list in the text. If needed for reference or better coordination with the related text, add a title and an xml:id attribute.

  • A list must contain at least two items. If items are short and simple in structure, consider incorporating them in the flowing text instead of creating a list environment.

  • Use sentence-style capitalization for list items. Use title-style capitalization for terms in descriptive lists.

  • When using multiple sentences as a list item, end all items in that list with a period.

  • Make sure that the items are grammatically parallel constructions providing a pattern that makes it easier to follow the text.

Never nest more than three lists within each other. In such cases, 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 5.5, “Cross References”.

Table 7: Elements Related to Lists
ElementWeb Link

<itemizedlist/> Block element for an unordered list. Contains multiple <listitem/> elements.

<orderedlist/> Block element for a numbered list. Contains multiple <listitem/> elements.

<variablelist/> Block element for a descriptive list. Contains multiple <varlistentry/> elements.

<varlistentry/> Element within a <variablelist/> that associates a <term/> and a <listitem/>.

<term/> Element whose content serves as the title of an element of a <variablelist/>.

<listitem/> A single list element. To add text to this item, first add a <para/> element.

5.13.1 Unordered Lists

Unordered lists are often used to provide an overview of information or to introduce or summarize information. They should be used when the order of list items is irrelevant.

Example 17: Example of an Unordered List (Source)
<para>The following operating systems are supported:</para>
    <para>Linux, Kernel 2.4 and newer</para>
    <para>FreeBSD 7 and newer</para>
Example 18: Example of an Unordered List (Output)

The following operating systems are supported:

  • Linux, Kernel 2.4 and newer

  • FreeBSD 7 and newer

5.13.2 Numbered Lists

Use numbered lists when items have a strict order, hierarchy, or importance. If order is not relevant, use an unordered list or a descriptive list. Do not use numbered lists to describe procedures. Complex sequential actions are better described by means of the procedure environment. For more information, see Section 5.17, “Procedures”.

Example 19: Example of a Numbered List (Source)
<para>Before installing, make sure of the following:</para>
    <para>The network connection of the computer is configured
    <para>The latest security updates are installed. If you are in
      doubt, run an online update.
Example 20: Example of a Numbered List (Output)

Before installing, make sure of the following:

  1. The network connection of the computer is configured properly.

  2. The latest security updates are installed. If you are in doubt, run an online update.

5.13.3 Descriptive Lists

Use descriptive lists when defining terms or describing options. Each item of a descriptive list contains a short term that is then further explained by means of an explanatory paragraph.

Use title-style capitalization for the term. Use sentence-style for the list item.

To reference the list, assign it a xml:id attribute and add a title. Individual list items may be referenced by assigning an xml:id. The entry is then identified by the value of xml:id and referenced by the term.

Example 21: Example of a Descriptive List (Source)
<para>This book consists of several parts:</para>
      <para>Learn about the installation and initial configuration
        of a Linux system.
      <para>Get a basic understanding of the system components.</para>
Example 22: Example of a Descriptive List (Output)

This book consists of several parts:


Learn about the installation and initial configuration of a Linux system.


Get a basic understanding of the system components.

5.14 Keys and Key Combinations

Capitalize all keys as printed on a standard keyboard. Capitalize all letter keys. To refer to a capitalized character, use ShiftZ, 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 on creating cross references, see Section 5.5, “Cross References”.

Example 23: Example of a Key
To create a screenshot, press <keycap>Print Screen</keycap>.
Example 24: Example of a Keyboard Combination
To save a file, press
  <keycap function="control"/>
Table 8: Elements Related to <keycap/>
ElementWeb Link

<keycombo/> Inline element containing multiple <keycap/> elements that together make up a key combination.

<keycap/> Inline element to mark up a single key. Contains either the key labels text inside it or is self-closing and has a function attribute with one of the following values:

  • alt

  • backspace

  • command

  • control

  • delete

  • down

  • end

  • enter

  • escape

  • home

  • insert

  • left

  • meta (also known as Win, Windows, or Super)

  • option (macOS only)

  • pagedown

  • pageup

  • right

  • shift

  • space

  • tab

  • up

5.15 References to Other External Resources

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 5.4.2, “File Names”.

Reference man pages and info pages in this format:

  • the man page of command

  • the info page of command

In a situation where the category of the page is needed, append the category in parentheses. Use, for example (man 9 command).

To learn more about subcommands, see the man page of

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.

As an author, where possible, provide language-specific references to translators in XML comments (see also Section 6.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 as a fall-back. 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 5.5, “Cross References” and Section 5.8, “External Links”.

5.16 Outline Levels

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

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

For more information on creating headline titles, see Section 4.9, “Headings”.

5.17 Procedures

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

  • An xml:id attribute.

  • A title.

  • An introductory phrase establishing the purpose of the procedure. If the procedure is otherwise the only element in its section, place the introductory phrase before the procedure.

  • If there are preconditions or prerequisites, add them as a second paragraph after the introduction.

  • Short, simple steps and, if necessary, substeps describing the actions to be performed. See also Section 4.16, “Sentence Structure”.

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.

Example 25: Example of a Procedure (Source)
<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>In the <phrase role="productname">YaST</phrase> window,
        click <guimenu>User and Group Management</guimenu>.
      <para>To open the <guimenu>Add a New User</guimenu> dialog, click
      <para>Type in the user name and click <guimenu>Create</guimenu>.
Procedure 1: Example of a Procedure (Output)

To add a new user to the system, perform the following steps:

  1. In the YaST window, click User and Group Management.

  2. To open the Add a New User dialog, click Add.

  3. Type in the user name and click Create.

Table 9: Elements Related to <procedure/>
ElementWeb Link

<procedure/> Block element containing a <title/> (optional) and multiple <step/> elements.

<step/> Element signifying a single unit of action. Usually contains a <para/> element, but can also house a <substeps/> element.

<substeps/> Element containing multiple, subordinate <step/> elements.

5.18 Products

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.

5.19 Questions and Answers

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, “Audience”.

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

Example 26: Example of a Questions-and-Answers Section (Source)
  <title>Example of a Questions-and-Answers Section</title>
      <para>How can I check if the product was correctly installed?</para>
      <para>Open the log file. Look for entries starting with
      <para>Why does the error
        <literal>Not enough disk space</literal> occur
        during installation?
      <para>There is less than 4 GB of space available on the selected

Example of a Questions-and-Answers Section (Output)

How can I check if the product was correctly installed?

Open the log file. Look for entries starting with Failed.

Why does the error Not enough disk space occur during installation?

There is less than 4 GB of space available on the selected partition.

Table 10: Elements Related to <qandaset/>
ElementWeb Link

<qandaset/> Block element containing a <title/> (optional) and multiple <qandaentry/> or <qandadiv/> elements.

<qandadiv/> Block element containing a <title/> and multiple <qandaentry/> elements. Used to structure a <qandaset/> into smaller topical subsections.

<qandaentry/> Block element used to associate a <question/> with an <answer/>.

<question/> Block element containing the question. Use a single <para/> element inside.

<answer/> Block element containing the answer. Use <para/> elements inside.

5.20 Tables

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.

Value and description pairs are better handled by means of a descriptive list.

Example 27: Example of a Table (Source)
  <tgroup cols="2">
        <entry>File System</entry>
        <entry>Maximum File Size</entry>
        <entry>Ext2 (1 kB block size)</entry>
        <entry>16 GB</entry>
        <entry>Ext2 (2 kB block size)</entry>
        <entry>256 GB</entry>
Example 28: Example of a Table (Output)
File SystemMaximum File Size
Ext2 (1 kB block size)16 GB
Ext2 (2 kB block size)256 GB
Table 11: Elements Related to <table/>
ElementWeb Link

<table/> Formal block element that contains a <title/> and a <tgroup/> element.

<informaltable/> Informal block element that contains a <tgroup/> element.

<tgroup/> Wrapper for the content of a table. Can contain one or more <colspec/> and one <thead/>. Contains a <tbody/>

<colspec/> Element to define common properties for a column.

<thead/> Element to mark up a table head. Contains a <row/> element.

<tbody/> Element to mark up the table body. Contains multiple <row/> elements.

<row/> Element to mark up a table row. Contains multiple <entry/> elements.

<entry/> Element to mark up a table cell.

5.21 User Interface Items

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 on language aspects, see Section 4.20, “User Interface Items”.

Example 29: Example of a Single User Interface Item
To open a file, click <guimenu>Open</guimenu>.
Example 30: Example of Nested User Interface Items
To save a file, use
Table 12: Elements Related to <guimenu/>
ElementWeb Link

<menuchoice/> Inline element containing multiple <guimenu/> elements that together form a nested menu structure.

<guimenu/> Inline element to mark up a single user interface item.

6 Managing Documents

This section provides an overview over some features of XML you can use to manage documents.

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

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

6.3 Entities

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

  • Representation of special characters that cannot easily be displayed, entered or memorized.

  • Integration of external files by entities representing references to their file names.

  • Text expansion for repeating content.

When an entity is defined, it can be used in many places. Entities reduce the risk of translation errors and increase consistency because they are translated once and automatically expanded elsewhere.

6.3.1 Using Entity Files

SUSE uses a small set of custom entities. This set is localized for each supported language. Find the SUSE set of entities in the file entity-decl.ent under each documentation project and each language. When the set has been modified for a new product release, this file must be updated in the supported languages as well.

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

<!ENTITY % entities SYSTEM "../entity-decl.ent">
Example 31: Excerpt from a SUSE entity-decl.ent
<!ENTITY1 exampleserver2   "sun3">
<!ENTITY exampleserverip    "&exampledomainip;.20">
<!ENTITY exampleserverfq    "&exampleserver;.&exampledomain;"4>


The kind of declaration to be made.


Defines the entity name.


Sets the value to which the processed entity should be expanded.


Nests an entity in the value.

A few hints for working with entities in SUSE documentation projects:

  • If there should be any need for defining special entities (for example, for localization purposes), add the new definitions to the appropriate entity-decl.ent file. Never include these definitions in the file header.

  • When translating entities, translate the value, but never change the entity name. See also Example 31, “Excerpt from a SUSE entity-decl.ent”.

  • Always use the exact notation of the entities when translating files to avoid processing errors.

  • Make sure that you use proper UTF-8 encoding when editing and saving the entity declaration file or any of the SUSE XML files.

6.3.2 Common Types of Entities

The following provides some background on the most important entities used in creating documentation for SUSE products. To be able to adjust product names of platform branding even past any deadlines, a set of entities must represent the frequently-changing product names. The same applies to book titles. An entity-decl.ent file contains several categories of entities. These are:

General Entities

These feature mostly network IP addresses, host names, and user names.


Title entities should be defined for all SUSE books in case sudden name changes are necessary.


To avoid changing the documentation itself if a vendor rebrands products, use entities for all hardware architectures referenced in the books.


We maintain a list of entities of all SUSE-based product names and some other products and applications for which we write documentation.

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

Entity Selection

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

<phrase role="productname">&product;</phrase> includes openLDAP.

If you need to reference a particular product, use a more specific entity.

The Ext4 file system has been included in the <literal>&suse;</literal>
Kernel since <literal>&suselinux;</literal> XYZ.

Avoid using acronyms of product names where they are not the preferred form of the name. If you do define an additional acronym version of a longer product name, append an a to the end of the entity name. For example, use &slesa; the acronym SLES.


Follow the rules under Section 5.18, “Products”.

6.4 XInclude Elements

XInclude elements are used to create modular source files that are easier to work with and can be re-used. When editing a book, create a new source file for every chapter. Later, create a new Novdoc 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="" 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.

Files referenced via XIncludes must be well-formed XML files but do not need to be valid DocBook files. This means that they must have a single top-level element. Files that are supposed to be referenced multiple times from within the same set, book or article must not contain any xml:id attributes.

7 Formatting XML

This section provides information on formatting XML sources.

  • Line Ends:  Lines should end with a Unix line end character (also called line feed, LF, newline, or \n).

  • Line Length:  Lines should be at most 80 characters long, unless one of the following exceptions applies:

    • Some computer output, computer input, or URIs may run longer and cannot be broken.

    • Some elements become much harder to read if broken. For example, that can be the case for long <menuchoice/> elements.

    • Aim to minimize the size of diffs in version control, to make reading diffs more efficient and version control storage more efficient. For example, if a typo fix introduces a line with 82 characters, consider keeping the line at that length. Also, avoid reflowing entire paragraphs of text, as that will also lead to hard-to-read diffs.

  • Indentation:  Indent using a single space character per indentation level. Make sure your editor does not replace some spaces with tabs. Documents should not contain any tab characters.

  • Trailing Whitespace:  Avoid introducing trailing whitespace characters such as spaces, protected spaces, or tabs. Many editors have an option to view such characters. git diff will show newly introduced trailing whitespace characters in red.

  • Formatting of Block Elements:  Block elements are all DocBook elements that create a rectangular visual block in the layout, such as <para/>, <table/>, or <figure/>. Format block elements with new lines before and after each tag and make sure they follow the indentation of the document:

     Content of block, indented by a space.

    For information about the usage of <screen/>, see Section 5.4.6, “Screens”.

  • Formatting of Inline Elements:  Block elements are all DocBook elements that can be reflowed freely within a block element, such as <emphasis/>, <keycap/>, or <guimenu/>. Format inline elements along with other inline content without adding newlines or extra indentation:

     Content of block <inline>content of inline</inline>.
  • Formatting of Title Elements:  The title elements <title/> and <term/> are block elements. However, they provoke a stylesheet quirk and should be treated differently. This avoids superfluous whitespace when used in the context of a cross-reference. Format title elements with new lines before the opening tag and after the closing tag and make sure they follow the indentation of the document:

    <title>Content of Title</block>
  • Formatting of Computer Output/Computer Input Blocks:  The Computer Output/Computer Input Block Element <screen/> should be treated like a block element but multi-line <screen/> elements should not be indented to aid source reading flow and avoid the trap of adding extraneous leading space to their content. (Single-line <screen/> can be indented).

  • XML Comments.  XML comments should follow the indentation of the document. Where feasible, put XML comments on new lines to make reading diffs and later removal of the comment easier:

     Block content.
     <!-- An XML comment -->

    XML comments must not contain the characters --. To preserve such character combinations within comments, replace them with -/-.

    For information about the usage of XML comments, see Section 6.2, “XML Comments”.

  • Reflowing Entire Files:  Before reflowing entire files to a different XML formatting style, weigh the cost of keeping the document in its current state against the cost of reflowing. Reflowing often makes it easier to work with the document. However, if the document has a rich editing history already, reflowing makes it harder to use properly use tools like git blame.

To easily convert documents to this style after importing them, use the commands daps xmlformat (for an entire document) and daps-xmlformat (for a single file). Note that while these tools are very good otherwise, they do not reflow XML comments properly.

Print this page