Jump to content

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.

Publication Date: 01/05/2021

Copyright © 2007–2021 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 https://www.suse.com/company/legal/. 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 http://www.example.com and http://www.example.org 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 192.168.255.0 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 http://en.wikipedia.org/wiki/Private_network.

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 http://en.wikipedia.org/wiki/IPv6_subnetting_reference.

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

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

  1. a preface

  2. chapters, split into sections

  3. (optional) a glossary

  4. (optional) appendixes

For books with many chapters, create parts 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 product manager to define the book title. The book title should not contain the product name and version.

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

  • Documentation version or revision information.  Optionally, use the <releaseinfo/> element to mark up version or revision numbers of the documentation itself.

  • 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
    <legalnotice>
     <para>
      Copyright &copy; [starting year]&ndash;<?dbtimestamp format="Y"?>
      SUSE LLC and contributors. All rights reserved.
     </para>
     <para>
      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
      License</quote>.
     </para>
     <para>
      For &suse; trademarks, see
      <link xlink:href="http://www.suse.com/company/legal/"/>.
      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
      trademarks.
     </para>
     <para>
      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.
     </para>
    </legalnotice>
Abstract

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.

Preface

Include a brief overview of the content of a manual, related manuals, and typographical conventions. The preface can also contain information about its target audience.

Parts

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 are Installation or Network.

Chapters

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.

  • Introduction.  Provide introductory information directly after the highlights. Do not place it 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. Avoid nesting deeper than three levels of sections.

    Start sections with an introductory paragraph outlining the focus of the section. If the section describes a sequential task, add a procedure description, as discussed in Section 5.16, “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.

Glossary

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

3.2 Articles

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

  1. introduction

  2. sections, split into subsections

  3. (optional) a glossary

  4. (optional) appendixes

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 https://www.merriam-webster.com/ (https://www.m-w.com/ for short).

If a product you are documenting is not listed in the terminology table, refer to the SUSE home page, https://www.suse.com. 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

Introduce acronyms by providing the expansion in parentheses after the acronym. Sometimes chapters and parts are used across multiple documents. Therefore, provide the expansion of an acronym at least once per chapter.

However, do not use headlines to introduce an acronym. Headlines or captions must not contain both an acronym and its expansion. If a term 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.

Create plural forms of acronyms by adding a lowercase s,. For example, use CDs and BIOSes. Never add an apostrophe before the s or es.

For clarity, avoid using possessive forms of acronyms. For example, do not use XMLʼs specification.

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 of headings and titles

Sentence-style capitalization is the most common capitalization used in SUSE documentation. When using sentence-style capitalization, only proper names and the first letter of the first word of a phrase are capitalized. Apply sentence-style capitalization to all running text and all types of headings and titles that are part of the document content. An example for sentence-style capitalization is Ceph core components.

For document titles, such as book, article, and set titles, use title-style capitalization. This capitalization 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.

Examples for title-style capitalization are Deployment Guide (book title) or Kernel Module Packages for SUSE-Based Distributions (article title).

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), 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.14, “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

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 5.15, “Outline levels and sectioning”.

4.10 Lists

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

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 and 9.16.

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 who performs 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 SUSE 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.17, “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.20, “User interface items”.

4.21 Quotations

Use quotations to quote from sources, such as books. In other cases, avoid using quotation marks. Do not use irony and do not use quotation marks to mark irony. In the case of computer input, computer output, and user interface elements, use more appropriate markup. See also Section 5.4, “Command line input and command line output” and Section 5.20, “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)
<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
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:

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

5.3 Callouts

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 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>
<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>
Example 7: Example of callouts (output)
color white/blue black/light-gray 1
default 0 2

1

Colors of the boot loader menu.

2

Defines the preselected option.

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

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

https://tdg.docbook.org/tdg/5.1/co.html

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

https://tdg.docbook.org/tdg/5.1/calloutlist.html

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

https://tdg.docbook.org/tdg/5.1/callout.html

5.4 Command line input and command line 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 the user input and/or system output 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.

https://tdg.docbook.org/tdg/5.1/screen.html

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

https://tdg.docbook.org/tdg/5.1/command.html

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

https://tdg.docbook.org/tdg/5.1/option.html

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

https://tdg.docbook.org/tdg/5.1/replaceable.html

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

https://tdg.docbook.org/tdg/5.1/filename.html

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

https://tdg.docbook.org/tdg/5.1/varname.html

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
<command>loffice</command>.

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, whenever possible, try 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. Capitalize placeholder text in all contexts where this is not detrimental to content intelligibility.

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, do not include a host name or a path in them, unless this is vital to understanding. 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 &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>
  • 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 SUSE stylesheets. However, most other 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.

  • Avoid command output that contains dates, version numbers, or other version-specific information that frequently changes.

  • 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 prefix or suffix cross references with text labels such as appendix, chapter, table, or figure. Such labels are generated automatically.

Do not create references to paragraphs (<para/>) or other elements that have no title. An exception to this rule is the element <step/> to which you may create references. If a reference to an element without a title is vital to the document, use the attribute xreflabel to assign a title.

Other types of references to resources are described in Section 5.14, “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>
</sect2>
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 command line 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>
</example>
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.

https://tdg.docbook.org/tdg/5.1/example.html

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

https://tdg.docbook.org/tdg/5.1/screen.html

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>
 <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>
Table 5: Elements related to <figure/>
ElementWeb Link

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

https://tdg.docbook.org/tdg/5.1/figure.html

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

https://tdg.docbook.org/tdg/5.1/informalfigure.html

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

https://tdg.docbook.org/tdg/5.1/mediaobject.html

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

https://tdg.docbook.org/tdg/5.1/imageobject.html

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

https://tdg.docbook.org/tdg/5.1/glossary.html

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

https://tdg.docbook.org/tdg/5.1/textobject.html

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.

  • To ensure readability and consistency, scale screenshots with the width attribute. Choose the appropriate scaling from the following list:

    • Screenshots of the whole desktop should be scaled to 90–99 % page width.

    • Screenshots of individual application windows should be scaled to 75–99 % page width.

    • Small windows such as message boxes should be scaled to 50–60 % page width.

  • 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 (default on Windows and macOS operating systems) creates colored letter edges when zoomed or printed.

  • Where applicable, follow the rules in Section 2, “Names of example items”.

  • Avoid editing screenshots. To anonymize portions of a screenshot, pixelize it. To highlight parts of a screenshot, use rectangles or arrows. Never add callouts, text or freely drawn objects. Always select colors that provide a good contrast with their background.

  • If possible, avoid screenshots with dates, version numbers, or other version-specific information that frequently changes.

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
<glossary>
<title>Glossary</title>
 <glossentry>
  <glossterm xml:id="gt-extensible">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>
  </glossdef>
 </glossentry>
 <glossentry>
  <glossterm>XML</glossterm>
  <glossdef>
   <para>
    See also <xref linkend="gt-extensible"/>.
   </para>
  </glossdef>
 </glossentry>
</glossary>

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 lower-case basic Latin alphabetic and numeric characters and - (hyphen). Do not use _ and . characters, as they may hurt search engine optimization.

  • Identifiers can consist of multiple parts. Join these parts with a - (hyphen).

    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.

    3. Element title label.  Shortened version of name of the title of the element itself.

    Example 13: Examples of identifiers
    xml:id="cha-install"
    xml:id="sec-install-yast"
    xml:id="tab-install-source"
  • 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
ElementPrefix
<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 Lists

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

  • Itemized lists (<itemizedlist/>). Also known as bullet lists or unordered lists.

  • Ordered lists (<orderedlist/>). Also known as numbered lists.

  • Variable lists (<variablelist/>). Also known as definition lists or description lists.

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

Follow these rules when creating or editing lists:

  • 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 few, short, and simple in structure, consider incorporating them in the flowing text instead of creating a list.

  • If all list items are nouns only, do not capitalize their first letter. Use sentence-style capitalization for list items that are full sentences and for terms in descriptive lists.

  • If each item in a list consists of a single sentence only, do not use a period at the end of items.

    If at least one list item consists of two full sentences, end all items in that list with a period.

  • Wherever possible, use parallel phrasing and grammatical construction between list items. This provides a pattern that makes it easier to follow the text.

  • Lists are visually distinct and can break up text flow. Do not overuse them.

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

Table 7: Elements related to lists
ElementWeb Link

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

https://tdg.docbook.org/tdg/5.1/itemizedlist.html

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

https://tdg.docbook.org/tdg/5.1/orderedlist.html

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

https://tdg.docbook.org/tdg/5.1/variablelist.html

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

https://tdg.docbook.org/tdg/5.1/varlistentry.html

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

https://tdg.docbook.org/tdg/5.1/term.html

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

https://tdg.docbook.org/tdg/5.1/listitem.html

5.12.1 Itemized lists

Use itemized lists whenever the order of list items is irrelevant. They are often used to provide an overview of information or to introduce or summarize information.

Example 14: Example of an itemized list (source)
<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>
Example 15: Example of an itemized list (output)

The following operating systems are supported:

  • Linux, Kernel 2.4 and newer

  • FreeBSD 7 and newer

5.12.2 Ordered lists

Use ordered lists when items have a strict order, hierarchy, or importance. Do not use ordered lists to describe sequential user actions (step-by-step instructions). For sequential user actions, use a procedure, as described in Section 5.16, “Procedures”. If order is not relevant, use an itemized list or a variable list.

Example 16: Example of an ordered list (source)
<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>
Example 17: Example of an ordered 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.12.3 Variable lists

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

Use sentence-style capitalization for both the term and 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 18: Example of a variable list (source)
<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>
Example 19: Example of a variable list (output)

This book consists of several parts:

Installation

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

System

Get a basic understanding of the system components.

5.13 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 20: Example of a key
To create a screenshot, press <keycap>Print Screen</keycap>.
Example 21: Example of a keyboard combination
To save a file, press
<keycombo><keycap function="control"/><keycap>S</keycap></keycombo>.
Table 8: Elements related to <keycap/>
ElementWeb Link

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

https://tdg.docbook.org/tdg/5.1/keycombo.html

<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

https://tdg.docbook.org/tdg/5.1/keycap.html

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

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 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 5.5, “Cross references” and Section 5.8, “External links”.

5.15 Outline levels and sectioning

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 on writing headlines, see Section 4.9, “Headings”.

5.16 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 22: 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>
 <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>
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.

https://tdg.docbook.org/tdg/5.1/procedure.html

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

https://tdg.docbook.org/tdg/5.1/step.html

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

https://tdg.docbook.org/tdg/5.1/substeps.html

5.17 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.18 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 23: Example of a questions-and-answers section (source)
<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>

Example of a questions-and-answers section (output)

Q: 1. How can I check if the product was correctly installed?

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

Q: 2. Why does the error Not enough disk space occur during installation?

There are 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.

https://tdg.docbook.org/tdg/5.1/qandaset.html

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

https://tdg.docbook.org/tdg/5.1/qandadiv.html

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

https://tdg.docbook.org/tdg/5.1/qandaentry.html

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

https://tdg.docbook.org/tdg/5.1/question.html

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

https://tdg.docbook.org/tdg/5.1/answer.html

5.19 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 24: Example of a table (source)
<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>
Example 25: 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.

https://tdg.docbook.org/tdg/5.1/table.html

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

https://tdg.docbook.org/tdg/5.1/informaltable.html

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

https://tdg.docbook.org/tdg/5.1/tgroup.html

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

https://tdg.docbook.org/tdg/5.1/colspec.html

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

https://tdg.docbook.org/tdg/5.1/thead.html

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

https://tdg.docbook.org/tdg/5.1/tbody.html

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

https://tdg.docbook.org/tdg/5.1/row.html

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

https://tdg.docbook.org/tdg/5.1/entry.html

5.20 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 26: Example of a single user interface item
To open a file, click <guimenu>Open</guimenu>.
Example 27: Example of nested user interface items
To save a file, use
<menuchoice><guimenu>File</guimenu><guimenu>Save</guimenu></menuchoice>.
Table 12: Elements related to <guimenu/>
ElementWeb Link

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

https://tdg.docbook.org/tdg/5.1/menuchoice.html

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

https://tdg.docbook.org/tdg/5.1/guimenu.html

6 Managing documents

This section provides an overview over 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:

  • To represent special characters that cannot easily be displayed, entered, or memorized.

  • To integrate external files using entities representing references to their file names.

  • To repeat content easily.

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

6.3.1 Using entity files

SUSE uses a set of custom entities. Find these entities in the file xml/entity-decl.ent in each documentation repository.

  • Entity files are only used for original, English-language documents. Translated documents will contain only the resolved form of entities, that is, plain-text directly in the document.

  • If you need to define new custom entities, add their new definitions to the xml/entity-decl.ent file. Do not include custom entity definitions directly in the file header, unless the custom definitions are needed to override externally embedded entities.

  • Use the UTF-8 encoding when editing and saving the entity declaration file or any of the SUSE XML files.

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

<!ENTITY % entities SYSTEM "entity-decl.ent">
%entities;
Example 28: Excerpt from an entity-decl.ent
<!ENTITY1 server2 "sun3">
<!ENTITY domain  "example.org">
<!ENTITY host    "&server;.&domain;4">
<!ENTITY hosttag "<uri xmlns='http://docbook.org/ns/docbook'>&host;</uri>5">

1

Making an entity declaration.

2

Defining the entity name.

3

Setting the value which the processed entity should expand to.

4

Using another entity within the entity value. This entity reference is only valid if the other entity is defined somewhere within the scope of the XML document that is built. However, it does not matter whether the entity is defined before or after the current entity definition.

5

Using a DocBook/GeekoDoc element within the entity value. The attribute xmlns must be included to define the correct XML namespace.

6.3.2 Common types of entities

An entity-decl.ent file contains several categories of entities:

Products

All SUSE product names and other products and applications. This helps in case sudden name changes are necessary and avoids misspellings.

Platforms

Use entities for all hardware architectures referenced. This helps in case sudden name changes are necessary.

Books

Title entities for all SUSE books. This helps in case sudden name changes are necessary.

General Entities

Network IP addresses, host names, and user names.

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

Entity selection

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

<phrase role="productname">&product;</phrase> includes 389-ds.

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

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

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.

Trademarks

Follow the rules under Section 4.19, “Trademarks” and Section 5.17, “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 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.

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:

    <block>
     Content of block, indented by a space.
    </block>

    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:

    <block>
     Content of block <inline>content of inline</inline>.
    <block>
  • 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>
     Block content.
     <!-- An XML comment -->
    </block>

    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.

8 Working With AsciiDoc

This section collects resources on how to use AsciiDoc.

The following things are important when working with AsciiDoc:

  • Only use formatting that is supported by the AsciiDoctor tool. Ignore features that are only documented for the outdated asciidoc (Python) tool. In particular, ignore the documentation at https://powerman.name.

  • Adhere to https://asciidoctor.org/docs/asciidoc-recommended-practices.

  • Most recommendations from https://github.com/SUSE/doc-susemanager/wiki/markup-syntax are applicable generally. Some recommendations, however, are specific to SUSE Manager documentation, in particular:

    • The section Images—images need to be added the same way they are added in other DAPS-based documentation, under the images/src/FORMAT directory of the repo.

    • The section Working with Drafts—there is currently no equivalent standard functionality.

A Terminology and general vocabulary

The following two tables define technical terms and general vocabulary for use in SUSE documentation. See also Section 4, “Language”.

A.1 Terminology

The following table defines the correct spellings and denominations for technical terms in SUSE documentation. Always use the entry listed under Accepted in the table below. All terms are reproduced in sentence-style capitalization.

AcceptedRejected [Reason]Part of Speech; Usage Guideline/Definition
32-bit32 Bit, 32 bit, 32-Bit, 32Bit, 32bitadjective
3D3 D, 3 d, 3.D., 3.d., 3-D, 3-d, 3d, Three-Dadjective
64-bit64 Bit, 64 bit, 64-Bit, 64Bit, 64bitadjective
AArch64ARM64, ARMv8noun; processor architecture
(to) activate sth.(to) block sth., (to) check sth., (to) choose sth., (to) highlight sth., (to) tick sth. verb; when referring to check boxes
adapteradaptornoun
add-onadd on, AddOn, addOn, addonnoun
address bookaddressbooknoun
adviceadvise [misspelling]noun
(to) advise sth.(to) advice sth. [misspelling]verb
AMD64/Intel 64x64, x86_64, x86-64, 64-bit AMD/Intel, AMD/Intel64noun; processor architecture; see also x86
AOOAoo, aoo, OO, oonoun; when referring to versions 3.4 and after; spelling according to project standard; acronym of Apache OpenOffice; see also OOo
Apache OpenOfficeApache Open Office, Apache Openoffice, OpenOffice noun; when referring to versions 3.4 and after; spelling according to project standard; acronym is AOO; see also OpenOffice.org
architecturearchnoun; hardware platform, especially concerning processor platform
appendixesappendicesnoun; plural of appendix
audio CDAudio CD, Audio-CD, CD-Audio, CD Audio, CD audio noun
back-endback end, backendnoun
(to) back sth. up(to) backup sth.verb
backupback-up, back upnoun
BashBASH, bashnoun; spelling as per the GNU Bash manual
BluetoothBlue tooth, blue tooth, Blue-tooth, blue-tooth, bluetooth noun
Bluetooth cardwireless card [card has wires attached to it]noun; card that enables Bluetooth connections.
boot diskboot disc [usually a misspelling], boot-disk, bootdisknoun; disk for starting the system
boot loaderboot-loader, bootloadernoun
(to) boot using PXE or (to) boot via PXE (to) PXE bootverb
BtrfsB.T.R.F.S., Better FS, BetterFS, Butter FS, ButterFS, btrfs noun; not an acronym
cursorpointer [used for pointing device input]noun; on-screen item indicating the position of keyboard input focus; see also pointer
CAC.A., Canoun; acronym for certificate authority
CDC.D., Cdnoun; acronym for compact disc
CD-ROMCD ROM, CD-Rom, CD Romnoun; acronym for compact disc read-only memory
CUPSC.U.P.S., Cups, cupsnoun; spelling as per project standard; acronym for Common Unix Printing System
case-sensitivecase sensitive, casesensitiveadjective
case-insensitivecase insensitive, caseinsensitiveadjective
certificate authoritycertification authority, certificating authority, certified authority noun; acronym is CA
check boxcheck-box, checkbox, checking option, tick boxnoun; avoid, only mention name of option
checklistcheck list, check-list, ticklist noun
check markcheck, check-mark, checkmark, tick, tick marknoun
chipsetchip set, chip-setnoun
(to) click sth.(to) click on sth., (to) click onto sth.verb; using a mouse button, usually to manipulate user interface element; also see press
client/serverclient server, client-server, client–server, client+server noun/noun
(to) close sth.(to) abort sth. [negative], (to) exit sth., (to) kill sth., (to) terminate sth. verb; when referring to closing a window; always use quit when ending an application normally; always use terminate when ending an application forcefully.
Common Unix Printing SystemCommon UNIX Printing System, common Unix printing system noun; spelling as per project standard; acronym is CUPS
command linecommand-line, commandlinenoun
configurationconfignoun; unless when referring to file extension
(to) configure sth.(to) config sth.verb
(to) connect via SSH (to sth.)(to) connect by SSH (to sth.), (to) connect over SSH (to sth.), (to) connect through SSH (to sth.), (to) connect with SSH (to sth.), (to) SSH (to sth.), (to) ssh (to sth.), (to) ssh in (to sth.), (to) ssh into sth. verb
control centerControl Center, Control center, Control-Center, Control-center, control-center, Controlcenter, controlcenter noun; generic term, as in: the YaST control center or the KDE control center
(to) create a hard link (to sth.)(to) hard link (sth.), (to) hardlink (sth.)verb; see also hard link
(to) create a symbolic link (to sth.)(to) soft link (sth.), (to) softlink (sth.), (to) symbolic link (sth.), (to) symlink (sth.) verb; see also hard link
(to) deactivate sth.(to) deblock sth., (to) uncheck sth., (to) untick sth. verb; when referring to check boxes
delta RPMdelta-RPM, deltarpmnoun; RPM package that only includes files that changed between a previous and the current version of the package
(to) deselect sth.(to) de-select sth., (to) remove the selection from sth., (to) un-select sth., (to) unselect sth. verb; when referring to list entries or text; for check boxes, use deactivate
DHCPD.H.C.P., Dhcp, dhcpnoun
dial-updial up, dialuponly as an adjective
dialogdialog box, dialog window, dialogue [British], mask [Germanism], screen noun; a page or window that asks you to make one or more decisions before proceeding
directorydir, foldernoun
DNSD.N.S., DNS name server, Dns, dnsnoun; acronym for dynamic name server
(to) double-click sth.(to) double click sth., (to) double-click on sth., (to) double-click onto sth., (to) doubleclick sth. verb
drop-down boxcombination box, combo box, combobox, dropdown, drop-down, drop-down menu, drop-down list box, popover, pull-down menu noun; GUI element with a list that can opened by clicking on it, whether combined with a text box or not; if list entries start actions, use menu instead
DVDD.V.D., Dvdnoun; acronym for digital versatile disc
dynamic name serverDynamic Name Server, Dynamic name servernoun; acronym is DNS
e-bookE-book, E-book, Ebook, eBook, electronic book, ebooknoun
e-mailE-mail, E-mail, Email, eMail, electronic mail, emailnoun
EPUBE-PUB, e-PUB, e-Pub, EPub, Epub, ePUB, ePubnoun; project logo uses the capitalization ePub, but the vendor standard is EPUB
end userend-usernoun; avoid; where possible, replace with user
(to) enter sth. (into sth.) verb; only when a value needs to be specified and Enter should be pressed afterward; where possible, replace by specify or provide
Ethernetethernetnoun
Ethernet cardwired card [sounds as if wires attached to the card are meant] noun; card that connects to networks via Ethernet.
Ext3EXT3, EXT 3, Ext 3, Ext-3, ext 3, ext-3, ext3noun; use this capitalization for all versions of the Ext file system standard; intentionally inconsistent with project standard to emphasize that this is a proper name
Ext4EXT4, EXT 4, Ext 4, Ext-4, ext 4, ext-4, ext4noun
file namefile-name, filenamenoun
file serverfile-server, fileservernoun
file systemfile-system, filesystemnoun
flavorflavour [British]noun
flash diskflash disc [misspelling], flash drive, USB disk, USB drive, USB stick noun
framebufferframe buffer, frame-buffernoun
front-endfront end, frontendnoun
FTPF.T.P., Ftp, ftpnoun
GIMPG.I.M.P., Gimp, gimpnoun; spelling as per project standard; acronym for GNU Image Manipulation Program; if the occurs directly before GIMP, capitalize it: The
GNOMEG.N.O.M.E., GNU Networked Object Model Environment, Gnome noun; spelling as per project standard; not an acronym.
GRUBG.R.U.B., Grub, grubnoun; acronym for GRand Unified Bootloader
graphical user interfaceGraphical User Interfacenoun; acronym for graphical user interface
GUIG.U.I., GUI interface, GUI user interface, Gui noun; acronym for graphical user interface
hard diskHDD, HD, hard disc [misspelling], hard disk drive, hard drive, hard-disk, hard-drive, harddisk, harddrive, hdd, hd noun
hard linkhard-link, hardlinkonly as a noun; as a verb, use create a hardlink link; directory entry that contains an alternative name for an existing file, in contrast to that, symbolic links are themselves files which link to the name of another file
home pagehome-page, homepagenoun
host namehost-name, hostnamenoun
(to) hotplug sth. (into sth.)(to) hot plug sth. (into sth.), (to) hot-plug sth. (into sth.), (to) hotadd sth., (to) hotswap sth. verb; adding a component or device from a system while the system is running; use remove at runtime where the specific action of removing a component or device is concerned
hotplugginghot plugging, hot-plugging, hotadding, hotswappingnoun
hotpluggablehot pluggable, hot-pluggable, hotaddable, hotswappableadjective
HTML pageHTML document, HTML Web page, HTML web pagenoun; when referring to a local file; see also Web page
HTTPH.T.T.P., Http, httpnoun
HTTPSH.T.T.P.S., Https, httpsnoun
hypervisorhyper visor, hyper-visor, hypervizor noun
indexesindicesnoun; plural of index
infraredinfra red, infra-rednoun or adjective.
init scriptinit-script, initscript, initialization script [incorrect, when referring to script run by init]noun; a script run by init
initializationinit, initialisation [British]noun
(to) initialize sth.(to) init sth., (to) initialise sth. [British]verb
installation mediuminstallation data mediumnoun; often in plural, installation media; where possible, use the more generic term installation source; flash disk-based or disc-based source of installation data for operating systems;
installation sourceinstallation data sourcenoun; source of installation data for operating systems
Internetinternetnoun
intranetIntranetnoun
I/O portI.O. port, I-O port, IO port, Io portnoun
IA64IA-64, ia64, ipf, Itaniumnoun; processor architecture
IPsecIPSEC, Ipsecnoun
IPv4IP v4, IPV4, Ipv4noun; acronym for Internet protocol version four
IPv6IP v6, IPV6, Ipv6noun; acronym for Internet protocol version six
journalingjournalling [British]noun
KIWIKiwi, kiwinoun; project spelling; not an acronym; software for creation of operating system images
K Desktop EnvironmentKool Desktop Environmentnoun; spelling according to project standard; acronym is KDE
KDEKDE Desktop Environment, K.D.E., Kde, kdenoun; spelling according to project standard; acronym for K Desktop Environment
KdumpKDUMP, kdumpnoun; only for application
kdumpKDUMP, Kdumpnoun; only for command
kernel spacekernel-space, kernelspace, kernellandnoun; memory area reserved for the kernel and device drivers; see also user space
key combinationhot key, key accelerator, keyboard accelerator, key combo, keyboard combo, keyboard combination, keyboard shortcut, key shortcut noun
Kprobeskprobesnoun; only for application
kprobesKprobesnoun; only for command
(to) left-click sth.(to) click the left mouse, (to) click the left mouse button, (to) left click sth., (to) left-click on sth., (to) left-click onto sth., (to) leftclick sth. verb
LibreOfficeLibre Office, Libreoffice, LibO, LO, libreofficenoun; spelling according to project standard; do not create acronyms of LibreOffice
licenselicence [British]noun
(to) license sth.(to) licence sth. [British]verb
LinuxLINUX, linuxnoun; spelling according to project standard
list boxlist, list fieldnoun; GUI element that is a list showing multiple elements even before interacting with it
live CDLiveCD, live-CDnoun; CD that allows booting an operating system without installing
live DVDLiveDVD, live-DVDnoun; DVD that allows booting an operating system without installing
live imagelive disk image, LiveImage, live-imagenoun; disk image that can be copied to a medium and then allows booting an operating system without installing
local hostlocal-host, localhostnoun; when describing the concept of hosting locally
localhostlocal host, local-hostnoun; when referring to the default name of a local host
log filelog-file, logfilenoun
loginlog in, log-innoun
logoutlog out, log-outnoun
(to) log in [see below for appropriate preposition](to) log-in, (to) login, (to) log on, (to) log-on, (to) logon, (to) sign in, (to) sign on verb
(to) log in to sth.(to) log in at sth., (to) log into sth.verb; for logging in to a software
(to) log in on sth.(to) log in at sth., (to) log in from sth.verb; for logging in on the console/a host system
(to) log in (to sth.) via SSH(to) log in (to sth.) by SSH, (to) log in (to sth.) over SSH, (to) log in (to sth.) through SSH, (to) log in (to sth.) with SSH, (to) SSH (to sth.), (to) ssh (to sth.), (to) ssh in (to sth.), (to) ssh into sth., verb
(to) log out [see below for appropriate preposition](to) log off, (to) log-out, (to) logout, (to) sign off, (to) sign out verb
(to) log out of sth.(to) log out at sth., (to) log out from sth.verb
loopback deviceloop back device, loop-back devicenoun
lowercaselower case, lower-casenoun
mail servermail-server, mailservernoun
MaildirMail dir, mail dirnoun; specific format for e-mail storage, not a directory for e-mails
mainboardmain board, main-board, mother board, mother-board, motherboard noun
man pageMan page, Man-page, man page, man-page, manpagetwo words
Mboxmboxnoun; specific format for e-mail storage
menudrop-down menunoun; GUI element that is a list whose entries each start an action; see also drop-down box
metadatameta data, meta-data, metadatas [misspelling]noun
(to) middle-click sth.(to) click the middle mouse, (to) click the middle mouse button, (to) middle click sth., (to) middle-click on sth., (to) middle-click onto sth., (to) middleclick sth. verb
mount pointmount-point, mountpointnoun
mouse buttonmouse-button, mousebutton, mouse key, mouse-key, mousekey noun
(to) multitask(to) multi task, (to) multi-taskverb
multitaskingmulti tasking, multi-taskingnoun
multiusermulti user, multi-usernoun
name servername-server, nameservernoun
namespacename space, name-spacenoun
need tohave toverb; see also must
NFSN.F.S., NFS file system, Nfsnoun; often: NFS client, NFS server
NISN.I.S., NIS information service, Nisnoun; often: NIS client, NIS server
OOoOo.o, Ooo, OOoo, OO, oonoun; only when referring to versions prior to 3.4; spelling according to former project standard; acronym of OpenOffice.org; see also AOO
(to) open sth.(to) open up sth.verb
OpenOffice.orgOpen Office Org, OpenOffice, Openoffice.org, openoffice, openoffice.orgnoun; only when referring to versions prior to 3.4; spelling according to former project standard; acronym is OOo; see also Apache OpenOffice
openSUSEOpen SUSE, Open-SUSE, open SUSE, open-SUSEnoun; never capitalize first letter
open sourceOpen Source, Open-Source, open-source, opensourceonly as a noun
operating systemoperation system, operating-systemnoun
paravirtualizedpara-virtualised, paravirtualised [British], para-virtualized adjective
patch levelpatch-level, patchlevelnoun
path namepath-name, pathnamenoun; avoid, check if path can be used instead
(to) plug sth. in(to) plug-in sth., (to) plugin sth.verb
plug-inplug in, pluginnoun|adjective
pointercursor [used for keyboard input], mouse cursornoun; on-screen item echoing the movement of a pointing device, such as a mouse; mouse pointer is also acceptable; see also cursor
pop-uppop up, popupnoun
on portat portpreposition noun
PostScriptPOSTSCRIPT, Postscript, postscriptnoun; spelling as per vendor standard
POWERppc64le, POWER8, Powernoun; processor architecture
(to) preconfigure sth.(to) pre-configure sth.verb
preconfiguredpre-configuredadjective
(to) print sth.(to) print out sth.verb
print queueprinter queue, printing queue noun
print spoolerprinter spooler, printing spooler noun
(to) press sth.(to) depress sth. [negative], (to) hit sth. [colloquial], (to) punch sth. [colloquial], (to) strike sth. [colloquial] verb; when referring to keyboard keys or device buttons, but not mouse buttons; also see click
proxy only as a noun
PXEP.X.E., Pixie, pixie, PXE Environment, Pxe, pxenoun; acronym for Preboot Execution Environment
PXE bootPXE Bootonly as a noun; as a verb, use (to) boot using PXE or (to) boot via PXE instead
(to) quit sth.(to) abort sth., (to) exit sth., (to) kill sth., (to) terminate sth. noun; quitting an application; always use close when referring to windows; always use terminate when ending an application forcefully
RAMR.A.M., RAM memory, Ram, ramnoun; acronym for random access memory
RAM diskRAM disc [misspelling], RAM drive, RAM-disk, RAM-drive, RAMdisk, RAM-drive, Ramdisk, Ramdrive noun; either treating RAM as a hard disk or a type of solid-state storage
READMERead-me, Readme, read-me, readmenoun; use this capitalization for all general references
read-onlyR.O., RO, read only, readonly, roadjective
(to) reconfigure sth.(to) re-configure sth.verb
(to) re-create sth.(to) recreate [different meaning]verb
(to) register [see below for appropriate preposition](to) sign up, (to) sign-up, (to) signupverb; register as a user
(to) register at sth. verb; register at a system
(to) register for sth. verb; register for a service
(to) remove sth. at runtime (from sth.)(to) hotremove sth.verb; removing a component or device to a system while it is running; where sensible, use the more generic term hotplug
(to) right-click sth.(to) click the right mouse, (to) click the right mouse button, (to) right click sth., (to) right-click on sth., (to) right-click onto sth., (to) rightclick sth. verb
RPMR.P.M., Rpm, rpm [different meaning]noun; acronym for RPM Package Manager
runlevelrun level, run-levelnoun
runtimerun time, run-timenoun
SambaSAMBA, sambanoun; project spelling; open-source implementation of the SMB file and print service protocol
(to) save sth.(to) store sth., (to) write sth. outverb; when saving or overwriting a file from a GUI program or via a parameter of a command line program; see also write
(to) save sth. as sth. verb; when either saving a file with a specific name
(to) save sth. in sth. verb; when either saving a file on a specific device or file system
(to) save sth. on sth. verb; when either saving a file on a specific device or file system
(to) save sth. to sth. verb; when either saving a file to a specific folder
saved in sth. verb; when retrieving a file from a specific place
SCSIS.C.S.I., Scsi, scsinoun
screenshotscreen shot, screen-shotnoun
screen saverscreen-saver, screensavernoun
scrollbarscroll-bar, scroll bar, scrollbox, scroller, slidebar noun; GUI element that is used change which portion of a screen area is visible
(to) select sth.(to) block sth., (to) choose sth., (to) highlight sth. verb; when referring to list entries or text; for check boxes, use activate
selectedblocked, chosen, highlightedadjective; selection state of list entries or text; opposite of deselected
(to) set sth. up(to) set-up sth., (to) setup sth.verb
setupset up, set-upadjective|noun
(to) shut sth. down(to) shut-down sth., (to) shutdown sth.verb
shutdownshut down, shut-downadjective|noun
SLES.L.E., SLE Enterprise, SLE Linux, Sle, slenoun; avoid; acronym for SUSE Linux Enterprise
SLEDS.L.E.D., SLE Desktop, SLE Enterprise Desktop, SLE Linux Desktop, Sled, sled noun; avoid; acronym for SUSE Linux Enterprise Desktop
SLESS.L.E.S., SLE Server, SLE Enterprise Server, SLE Linux Server, Sles, sles noun; avoid; acronym for SUSE Linux Enterprise Server
SLES for SAPSLES for SAP Applications, SLE for SAPnoun; acronym for SUSE Linux Enterprise Server for SAP Applications
sliderslide bar, slidebarnoun; GUI element that is used manipulate values that have an upper and a lower bound
solid-state driveSD [misleading], solid state disc [misspelling], solid-state disk drive, solid-state disk, solid state drive, solidstate drive, sd noun; acronym is SSD; a type of mass storage that does not depend on mechanical parts
spec fileSpec file, Spec-file, Specfile, spec-file, specfile noun
SSDS.S.D., SD [misleading], SS-D, sd, ss-dnoun; acronym of solid-state drive; a type of mass storage that does not depend on mechanical parts
stand-alonestand alone, standaloneadjective
(to) start sth. up(to) start-up sth., (to) startup sth.verb
start-upstart up, startupnoun
statusbarstatus bar, status-barnoun
SSHS.S.H., SSH Shell, SSH shell, Ssh, sshnoun
SUSES.U.S.E., Software- und System-Entwicklung, SuSE, SuSe, Suse, suse noun; not an acronym
SUSE Enterprise StorageSUSE Storage, SUSE Linux Enterprise Storagenoun; acronym is SES
SUSE Linux EnterpriseSUSE Linux Entreprise [British], SUSE Linux enterprise, SUSE linux enterprise noun; acronym is SLE
SUSE Linux Enterprise DesktopSUSE Desktop, SUSE Linux Enterprise desktopnoun; acronym is SLED
SUSE Linux Enterprise ServerSUSE Server, SUSE Linux Enterprise servernoun; acronym is SLES
SUSE Linux Enterprise Server for SAP ApplicationsSUSE Linux Enterprise for SAP, SUSE Linux Enterprise Server for SAP, SUSE Server for SAP noun; acronym is SLES for SAP Applications
SUSE ManagerSUSE Linux Managernoun
SUSE OpenStack CloudSUSE Cloud, SUSE Linux Cloudnoun
SUSE StudioSUSE Linux Studionoun
submenusub menu, sub-menunoun; menu that is nested inside another menu
subsystemsub system, sub-systemnoun
systemdSystem D, Systemd, systemD, system d, System 500noun; project spelling; initialization system for Linux
System V initSysVinit, SysV init, system 5 init, system dnoun; spoken: System five init; initialization system for Unix operating systems
symbolic linksoft link, softlink, symlink [jargon]only as a noun; as a verb, use create a symbolic link; a file with a reference to another file or a directory, in contrast to that, a hard link is a directory entry that contains an alternative name for an existing file
synchronizationsync, synch, synchronisation [British]noun; two-way or many-way copying process to ensure data is consistent across two or more locations
(to) synchronize sth. (with sth.)(to) sync sth., (to) synch sth., (to) synchronise sth. [British], (to) synchronize sth. (and sth.)noun; copy data in two or more ways to ensure it is consistent across two or more locations
TAR archiveTAR ball [Unix jargon], tar ball, tar-ball, tarball noun
taskbartask bar, task-barnoun
technology previewtechnical preview, technology-previewnoun; product features that are shipped without support and marked as such
text boxentry area, entry box, entry field, input area, input box, input field, text area, text field noun; GUI element that text can be typed into with one or more lines
(to) terminate sth.(to) abort sth., (to) close sth., (to) exit sth., (to) kill sth., (to) quit sth. noun; ending an application forcefully; always use close when referring to windows; always use quit when ending an application normally
TFTPT.F.T.P., Tftp, tftpnoun
time stamptime-stamp, timestampnoun
titlebartitle bar, title-barnoun
toolbartool bar, tool-barnoun
toolchaintool chain, tool-chainnoun; set of tools (such as build tools) that is used in succession
tooltiptool tip, tool-tipnoun
UEFIUefi, u-EFI, uEFInoun; acronym of Unified Extensible Firmware Interface
Unified Extensible Firmware Interfaceunified extensible firmware interfacenoun; acronym is UEFI; software interface between firmware and operating system; replaces the BIOS interface
UnixUNIX [brand name registered by Open Group], unix noun; use this capitalization for all general references that are not related to brand names
(to) uninstall sth.(to) deinstall sth., (to) un-install sth. verb
unselecteddeselected, un-selectedadjective; selection state of list entries or text; opposite of selected
uppercaseupper case, upper-casenoun
usageutilisation [British], utilizationnoun
use caseuse-case, usecasenoun
(to) use sth.(to) utilise sth. [British], (to) utilize sth.verb
user nameuser-name, usernamenoun
user spaceuser-space, userspace, userlandnoun; memory area used by applications; see also kernel space
video DVDVideo DVD, Video-DVD, DVD videonoun
virtualizationVirtualization, virtualisation [British] noun; referring to software (usually an operating system) running on a virtual computer created by software running on a physical computer or virtual computer created with a software running on a physical computer
(to) virtualize sth.virtualise [British]verb; running software (usually an operating system) on a virtual computer created by software running on a physical computer or creating a virtual computer with a software running on a physical computer
VLANV.L.A.N., Vlan, vlannoun; acronym for Virtualized Local Area Network
WebWEB, World Wide Web, WWW, web, wwwnoun; you may use World Wide Web or WWW in historical contexts
Web camWebcam, Web camera, webcamnoun; camera that can be connected to a computer, mainly for video chats
Web pageHTML Web page, Web-page, Webpagenoun; when referring to page on the Internet; see also HTML page
Web serverWeb-server, Webservernoun
Web siteWeb-site, Website, web site, web-site, websitenoun
WebmasterWeb master, Web-masternoun
Wi-FiWi fi, Wi-fi, Wifi, wireless fidelity, WLANnoun; use the Wi-Fi brand name whenever referring to IEEE 802.11-based networks or access points; use WLAN when referring to non-IEEE 802.11-based wireless LANs.
Wi-Fi cardwireless card [card has wires attached to it]noun; card that connects to Wi-Fi networks.
Wi-Fi/Bluetooth cardwireless card [card has wires attached to it]noun; card that combines a Wi-Fi and a Bluetooth card.
wild cardjoker [Germanism], wild-card, wildcardnoun
WLANWlannoun; avoid; use only when referring to wireless LANs that are not IEEE 802.11-based; use Wi-Fiin all other cases.
(to) write sth.(to) pipe sth. [Unix jargon], (to) write sth. outverb; when saving the command line output of a program as a file using > or >>; see also save
x8632-bit AMD/Intel, i686, i386noun; processor architecture; see also AMD64/Intel 64
X Window SystemX Window, X Windows, X window, X window system, X windows, XWSnoun
XenXEN, xennoun
Xendxendnoun
YaSTYAST, YAST2, Yast, YaST2, yast, yast2noun; spelling according to project standard; acronym for Yet another Setup Tool
IBM Zz Systems, System z, zSeries, z System, zsystems, S390xnoun; processor architecture; see also AMD64/Intel 64
Zypperzyppernoun; only for application
zypperZyppernoun; only for command

A.2 General vocabulary

The following table defines the correct spellings and denominations for general vocabulary in SUSE documentation. Always use the entry listed under Accepted in the table below. All entries are reproduced in sentence-style capitalization.

AcceptedRejected [Reason]Part of Speech; Usage Guideline/Definition
afteronceadverb; only use once in the meaning of one time only
afterwardafterwards [BrE]adverb
althoughwhileconjunction; only use while in the meaning of during the time that
andwhileconjunction; only use while in the meaning of during the time that
backwardbackwards [BrE]adverb
 basically [filler]adverb
because ofdue to, owing topreposition
business casebusiness-case, businesscasenoun
butwhileconjunction; only use while in the meaning of during the time that
cannotcan't [contraction], can notverb
canmayverb; use can to express an ability, only use may to express permissions sought/given.
couldmayverb; use could to express a possibility, only use may to express permissions sought/given.
 easy [filler], easilyadjective, adverb; avoid.
etc. abbreviation; avoid; do not use together with for example and such as; always precede with a comma.
for examplefor instance, for instances [misspelling]adverb
forwardforwards [BrE]adverb
if pronoun; use if an event depends on a condition; also see when and whether
inwardinwards [BrE]adverb
 just [filler]adjective, adverb; avoid
mightmayverb; use might to express a possibility, only use may to express permissions sought/given
musthave toverb; see also need to
need tohave toverb; see also must
 obvious [insulting], obviouslyadjective, adverb
outwardoutwards [BrE]adverb
 pleaseadverb; avoid
 self-evident [insulting], self-evidentlyadjective, adverb
sidewardsidewards [BrE]adverb
 simple [filler], simplyadjective, adverb; avoid
(to) simplify sth.(to) ease sth., (to) facilitate sth.verb; avoid
 stuff [colloquial], stuffsnoun
towardtowards [BrE]adverb
want sth.(to) wish sth., (to) wish for sth., would like sth.verb
whenonceadverb; use once only in the meaning one time only
when pronoun; use if an event is inevitable; also see if
whetherwhether or notpronoun; use to present two alternatives which are not conditions, otherwise use if; see also if
with regard toas regards, in regard to, with regards toconjunction noun preposition
Print this page