SUSE Documentation Style Guide

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

Authors: Rebecca Walter, Martina Dejmek, and Stefan Knorr
Publication Date: 12/08/2016 , Version: 2016-07

Copyright © 2007– 2016 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 http://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

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

Title Page and Imprint

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

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

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

  • Documentation Version or Revision Information.  Use the <releaseinfo/> element to mark up version or revision numbers of the documentation itself. For more information on enabling SVN revision information in your document, see http://svnbook.red-bean.com/en/1.7/svn.advanced.props.special.keywords.html.

  • 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

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

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

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

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

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

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

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

Glossary

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

3.2 Articles

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

4 Language

The following rules are intentionally kept concise. When in doubt about a style rule, see The Chicago Manual of Style, 15th Edition. When in doubt about the spelling or usage of a word, first see Appendix A, Terminology and General Vocabulary. When the usage of a word is not regulated there, use American English spellings as defined on http://www.merriam-webster.com/ (http://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, http://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

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

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

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

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

4.1.2 Latin Abbreviations

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

4.1.3 Units of Measurement

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

4.2 Capitalization and Title Style

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

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

  1. Capitalize the first and the last word.

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

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

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

  5. Write as and to in lowercase.

  6. Capitalize everything that is not mentioned above.

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

4.3 Commas

Use commas between all items in a series of three or more elements. For example, write a, b, and c. Use commas around phrases like for example and that is. Introductory phrases at the beginning of a sentence are normally followed by a comma. For example, Before using YaST Online Update, configure a network connection.

4.4 Contractions

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

4.5 Dashes

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

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

4.6 End of Sentence Punctuation

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

4.7 File and Directory Names

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

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

  • Use forward slashes to separate nested directory or file names.

  • When giving absolute paths, always start with a leading slash to indicate the root of the file system.

  • Do not use a trailing slash to distinguish between a file and a directory. Where differentiation is needed, provide it textually.

Most Linux file systems are case-sensitive. Use capitals exactly as they appear in the file system. For more information on markup aspects, see Section 5.15, “References to Other External Resources” and Section 5.4.2, “File Names”.

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

4.8 Gender Bias

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

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

4.9 Headings

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

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

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

4.10 Numbers and Measurements

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

When the unit of a measurement is abbreviated, always use numerals for the number. In measurements, add a non-breaking space ( &nbsp; ) between the numeral and its corresponding unit abbreviation.

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

4.11 Possessives

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

4.12 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.13 Semicolons

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

4.14 Slashes

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

4.15 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.16 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.17 Tone and Voice

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

Use second person (you) to refer to the reader. Normally, the reader is the user or administrator that does the actions described. Do not overuse you. It is often understood, especially in directions.

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

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

4.18 Trademarks

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

  • Never use trademarks in headings.

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

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

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

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

4.19 User Interface Items

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

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

4.20 Quotations

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

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

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

Example 4: Quote

Suds may froth, the sign reads.

5 Structure and Markup

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

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

5.1 Admonitory and Advisory Paragraphs

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

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

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

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

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

Follow these rules when writing admonitions:

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

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

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

Example 5: An Example of a Warning (Source)
<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. This will not result in a visual change but disables hyphenation:

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

5.3 Callouts

Add the <co/> elements directly after the part of a screen that you want to annotate. Do not try to align them above the part of a screen to annotate. Do not use more than ten callouts per example.

See also Section 5.7, “Examples”.

Example 6: Example of Callouts (Source)
<screen>color white/blue black/light-gray <co xml:id="co.color"/>
default 0 <co xml:id="co.default"/></screen>
<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/>.

http://www.docbook.org/tdg51/en/html/co.html

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

http://www.docbook.org/tdg51/en/html/calloutlist.html

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

http://www.docbook.org/tdg51/en/html/callout.html

5.4 Command Line Input and Output

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

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.

http://www.docbook.org/tdg51/en/html/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.

http://www.docbook.org/tdg51/en/html/command.html

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

http://www.docbook.org/tdg51/en/html/option.html

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

http://www.docbook.org/tdg51/en/html/replaceable.html

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

http://www.docbook.org/tdg51/en/html/filename.html

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

http://www.docbook.org/tdg51/en/html/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 belong to a command, add them after the command markup and a space character using the element <option/>:

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

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

See also Section 5.4.5, “Prompts”.

5.4.2 File Names

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

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

5.4.3 Placeholders

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

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

5.4.4 Literals

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

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

5.4.5 Prompts

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

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

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

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

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

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

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

5.4.6 Screens

Screens are used to present:

  • long commands and commands together with their output

  • system output, such as system messages

  • code or configuration examples

<screen><prompt>tux > </prompt><command>ls /</command>
bin   dev   lib         mnt     proc  sbin     suse  usr
boot  etc   lib64       mounts  root  selinux  sys   var
data  home  lost+found  opt     run   srv      tmp</screen>
  • Use screens only where necessary for understanding the documentation. Present longer screens as examples. For more information, see Section 5.7, “Examples”.

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

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

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

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

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

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

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

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

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

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

5.4.7 Variable Names

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

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

5.5 Cross References

Use the <xref/> element (read: cross ref) when referring to an appendix, chapter, example, figure, part, preface, section, table, or question and answer set. The element referenced needs to have an xml:id attribute. Do not insert text labels such as appendix, chapter, table, or figure. These labels are generated automatically.

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

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

Example 8: Example of a Cross Reference (Source)
<sect2 xml:id="sec.cross_reference">
  <title>Cross References</title>
  <para>Use the <sgmltag class="emptytag">xref</sgmltag> element ...</para>
...
  <para>See <xref linkend="sec.cross_reference"/>.</para>
</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 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 <option>-xa</option></command>

5170 ?        S      0:00 kdeinit: khotkeys
5172 ?        S      0:02 kdeinit: kdesktop
5174 ?        S      0:04 kdeinit: kicker</screen>
Table 4: Elements Related to <example/>
ElementWeb Link

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

http://www.docbook.org/tdg51/en/html/example.html

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

http://www.docbook.org/tdg51/en/html/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/>.

http://www.docbook.org/tdg51/en/html/figure.html

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

http://www.docbook.org/tdg51/en/html/informalfigure.html

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

http://www.docbook.org/tdg51/en/html/mediaobject.html

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

http://www.docbook.org/tdg51/en/html/imageobject.html

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

http://www.docbook.org/tdg51/en/html/glossary.html

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

http://www.docbook.org/tdg51/en/html/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.

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

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

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

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

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

5.10 Glossaries

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

Define infinitive forms of verbs and singular nouns. Use lowercase for the term unless it is a proper noun.

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

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

Example 12: A Typical Example of a Glossary
<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 alphanumeric characters, ., _, and -.

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

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

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

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

    Example 13: Examples of Identifiers
    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.

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
<procedure/> pro
<qandaset/>, <qandadiv/>, <qandaentry/> qa
<sect1/>, <sect2/>, etc. sec
<set/> set
<step/> st
<table/> tab
<variablelist/> vl
<varlistentry/> vle

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

[b] Only add when creating index ranges

5.12 Indexes

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

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

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

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

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

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

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

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

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

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

5.13 Lists

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

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

  • Numbered lists ( <orderedlist/> ).

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

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

Follow these rules when creating or editing lists:

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

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

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

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

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

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

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

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

Table 7: Elements Related to Lists
ElementWeb Link

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

http://www.docbook.org/tdg51/en/html/itemizedlist.html

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

http://www.docbook.org/tdg51/en/html/orderedlist.html

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

http://www.docbook.org/tdg51/en/html/variablelist.html

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

http://www.docbook.org/tdg51/en/html/varlistentry.html

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

http://www.docbook.org/tdg51/en/html/term.html

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

http://www.docbook.org/tdg51/en/html/listitem.html

5.13.1 Unordered Lists

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

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

The following operating systems are supported:

  • Linux, Kernel 2.4 and newer

  • FreeBSD 7 and newer

5.13.2 Numbered Lists

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

Example 19: Example of a Numbered List (Source)
<para>Before installing, make sure of the following:</para>
<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 20: Example of a Numbered List (Output)

Before installing, make sure of the following:

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

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

5.13.3 Descriptive Lists

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

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

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

Example 21: Example of a Descriptive List (Source)
<para>This book consists of several parts:</para>
<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 22: Example of a Descriptive 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.14 Keys and Key Combinations

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

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

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

For more information on creating cross references, see Section 5.5, “Cross References”.

Example 23: Example of a Key
To create a screenshot, press <keycap>Print Screen</keycap>.
Example 24: Example of a Keyboard Combination
To save a file, press
<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.

http://www.docbook.org/tdg51/en/html/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

http://www.docbook.org/tdg51/en/html/keycap.html

5.15 References to Other External Resources

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

Reference man pages and info pages in this format:

  • the man page of command

  • the info page of command

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

To learn more about subcommands, see the man page of
<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 as a fall-back. For books, provide the title of the translated version along with the original title if such a translation exists.

Other types of references to resources are described in Section 5.5, “Cross References” and Section 5.8, “External Links”.

5.16 Outline Levels

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

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

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

5.17 Procedures

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

  • An xml:id attribute.

  • A title.

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

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

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

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

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

Example 25: Example of a Procedure (Source)
<procedure xml:id="pro.procedure">
  <title>Example of a Procedure</title>
    <para>To add a new user to the system, perform the following steps:
    </para>
    <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.

http://www.docbook.org/tdg51/en/html/procedure.html

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

http://www.docbook.org/tdg51/en/html/step.html

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

http://www.docbook.org/tdg51/en/html/substeps.html

5.18 Products

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

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

5.19 Questions and Answers

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

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

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

Example 26: Example of a Questions-and-Answers Section (Source)
<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 is less than 4 GB of space available on the selected
        partition.
      </para>
    </answer>
  </qandaentry>
</qandaset>

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

How can I check if the product was correctly installed?

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

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

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

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

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

http://www.docbook.org/tdg51/en/html/qandaset.html

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

http://www.docbook.org/tdg51/en/html/qandadiv.html

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

http://www.docbook.org/tdg51/en/html/qandaentry.html

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

http://www.docbook.org/tdg51/en/html/question.html

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

http://www.docbook.org/tdg51/en/html/answer.html

5.20 Tables

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

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

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

Example 27: Example of a Table (Source)
<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 28: Example of a Table (Output)
File SystemMaximum File Size
Ext2 (1 kB block size)16 GB
Ext2 (2 kB block size)256 GB
Table 11: Elements Related to <table/>
ElementWeb Link

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

http://www.docbook.org/tdg51/en/html/table.html

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

http://www.docbook.org/tdg51/en/html/informaltable.html

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

http://www.docbook.org/tdg51/en/html/tgroup.html

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

http://www.docbook.org/tdg51/en/html/colspec.html

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

http://www.docbook.org/tdg51/en/html/thead.html

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

http://www.docbook.org/tdg51/en/html/tbody.html

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

http://www.docbook.org/tdg51/en/html/row.html

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

http://www.docbook.org/tdg51/en/html/entry.html

5.21 User Interface Items

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

For more information on language aspects, see Section 4.19, “User Interface Items”.

Example 29: Example of a Single User Interface Item
To open a file, click <guimenu>Open</guimenu>.
Example 30: Example of Nested User Interface Items
To save a file, use
  <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.

http://www.docbook.org/tdg51/en/html/menuchoice.html

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

http://www.docbook.org/tdg51/en/html/guimenu.html

6 Managing Documents

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

6.1 Remarks

Use remarks for editorial comments. Remarks can be placed within, before, or after a para but must always be within a section element. When creating output, remarks can be made visible in the output and thus help within the editorial process. When creating the final output, deactivate remarks.

Start remarks with your user name and the current date, then add a colon (:) and finally your actual remark. To comment on someone else's remark, add a new remark directly below it. Delete remarks when the corresponding issue is resolved.

<remark>tux (2013-10-13): could not find the option for foo</remark>
<remark>geeko (2013-11-02): see /usr/share/doc/foo.html</remark>

You can add a role attribute with one of the following values to show the type of the remark:

  • structure Use this type of remark to suggest changes to the text or XML structure.

  • language Use this type of remark to suggest language improvements.

  • needinfo Use this type of remark to mark sections where you need input from others, such as developers.

  • trans Use this type of remark to give hints to translators.

6.2 XML Comments

XML comments can be used for temporarily disabling portions of text. Another use of XML comments is to create more permanent internal comments or to mark up changes made for layout reasons. XML comments are never visible in a publication.

<-- This is an XML comment. --!>
Tip
Tip: Creating Valid Comments

Do not use -- in comments. -- is the first part of end-of-comment string --> and thus causes validation to fail.

6.3 Entities

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

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

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

  • Text expansion for repeating content.

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

6.3.1 Using Entity Files

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

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

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

1

The kind of declaration to be made.

2

Defines the entity name.

3

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

4

Nests an entity in the value.

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

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

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

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

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

6.3.2 Common Types of Entities

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

General Entities

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

Books

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

Platforms

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

Products

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

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

Entity Selection

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

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

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

The Ext4 file system has been included in the <literal>&suse;</literal>
Kernel since <literal>&suselinux;</literal> XYZ.
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 5.18, “Products”.

6.4 XInclude Elements

XInclude elements are used to create modular source files that are easier to work with and can be re-used. When editing a book, create a new source file for every chapter. Later, create a new Novdoc file that can serve as the central point. In this file, use XInclude elements to reference all chapters in the correct order:

<xi:include xmlns:xi="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.

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

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, electronic book, ebooknoun
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 combinationkey 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
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
paravirtualizedpara-virtualised, paravirtualised [British], para-virtualized adjective
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
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
usageutilisation [British], utilizationnoun
(to) use sth.(to) utilise sth. [British], (to) utilize sth.verb
uppercaseupper case, upper-casenoun
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
z SystemsSystem 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
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