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.
- 1 Audience
- 2 Names of example items
- 3 Outline of a manual
- 4 Language
- 5 Structure and markup
- 6 Managing documents
- 7 Formatting XML
- 8 Working With AsciiDoc
- A Terminology and general vocabulary
- B GNU Free Documentation License
- B.1 PREAMBLE
- B.2 APPLICABILITY AND DEFINITIONS
- B.3 VERBATIM COPYING
- B.4 COPYING IN QUANTITY
- B.5 MODIFICATIONS
- B.6 COMBINING DOCUMENTS
- B.7 COLLECTIONS OF DOCUMENTS
- B.8 AGGREGATION WITH INDEPENDENT WORKS
- B.9 TRANSLATION
- B.10 TERMINATION
- B.11 FUTURE REVISIONS OF THIS LICENSE
- B.12 ADDENDUM: How to use this License for your documents
Copyright © 2007–2021 SUSE LLC and contributors. All rights reserved.
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or (at your option) version 1.3; with the Invariant Section being this copyright notice and license. A copy of the license version 1.2 is included in the section entitled “GNU Free Documentation License”.
For SUSE trademarks, see https://www.suse.com/company/legal/. All other third party trademarks are the property of their respective owners. Trademark symbols (®, ™ etc.) denote trademarks of &suse; and its affiliates. Asterisks (*) denote third-party trademarks.
All information found in this book has been compiled with utmost attention to detail. However, this does not guarantee complete accuracy. Neither SUSE LLC, its affiliates, the authors nor the translators shall be held liable for possible errors or the consequences thereof.
1 Audience #
Before starting to write, define the target audience of your documentation. Adjust tone, style, and technicality of the text based on the intended audience. Keep in mind that not all facts that seem obvious to you will be obvious to your readers. If you move parts of documents into other documents, make sure to adapt the parts you move to the new document.
For later reference, document the defined target audience in the main file
of every book and article. Place an XML comment directly before the
relevant
<book/>
or
<article/>
element, such as this:
<!-- Target audience: institutional desktop users. -->
For more information using XML comments, see Section 6.2, “XML comments”.
Generally, there is no need to add information about the target audience to the book or article content itself.
2 Names of example items #
This section summarizes conventions for creating generic names for objects in documentation. At least some of the following names should be provided through entities. See also Section 6.3, “Entities”.
2.1 Domains #
Use http://www.example.com and http://www.example.org as example domains. Both domains were registered for use in documentation.
2.2 Host names #
Use objects of the solar system: For the most important system, use
sun
. For other systems, use the names of
planets such as earth
or
mars
.
2.3 IPv4 addresses #
Use addresses from the class C subnet 192.168.255.0
for examples. That is, replace the final 0
by any
integer between 0
and 255
. To
create examples using a larger setup, use addresses from the private
network ranges. For more information, see
http://en.wikipedia.org/wiki/Private_network.
2.4 IPv6 addresses #
Use addresses from the subnet 2001:0db8::/32
for
examples. That is, after the 2001:0db8:
prefix, add
six four-digit numbers, each separated by a colon on both sides. Each of
the hexadecimal digits may have a value between 0
and
f
. A valid example URL is
2001:0db8:0123:4567:89ab:cdef:1234:5678
.
For more information, see
http://en.wikipedia.org/wiki/IPv6_subnetting_reference.
2.5 Users #
For example users, use free-software mascots, such as Tux (Linux Kernel), Wilber (The GIMP), Geeko (SUSE), Foxkeh (Firefox), Konqi (KDE), or Duke (Java). In prompts, use the lowercase version of these names.
3 Outline of a manual #
Maintain a consistent structure within your documents. The structure can vary between different books, articles or projects, but the most common parts of the document structure are documented here.
3.1 Books #
For books, use a document structure that includes the following elements, in that order:
a preface
chapters, split into sections
(optional) a glossary
(optional) appendixes
For books with many chapters, create parts at the outline level above chapters.
- Title page and imprint
Both title page and imprint are created automatically, but depend on information being present in the book.
Title. Work with the product manager to define the book title. The book title should not contain the product name and version.
Product name and product version. Work with the product manager to find the correct product name and version number. Mark this information up with
<productname/>
and<productnumber/>
, respectively.Documentation version or revision information. Optionally, use the
<releaseinfo/>
element to mark up version or revision numbers of the documentation itself.Authorship information. Create a separate file
authors.xml
and add an<authorgroup/>
listing all authors and contributors inside it. Include this file with an XInclude.Copyright notice. Use the standard copyright notice reproduced below. Change the starting year of the copyright protection to the current year.
Example 1: Standard copyright notice #
<legalnotice> <para> Copyright © [starting year]–<?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 (®, ™ etc.) denote trademarks of &suse; and its affiliates. Asterisks (*) denote third-party trademarks. </para> <para> All information found in this book has been compiled with utmost attention to detail. However, this does not guarantee complete accuracy. Neither SUSE LLC, its affiliates, the authors nor the translators shall be held liable for possible errors or the consequences thereof. </para> </legalnotice>
- Abstract
Use an abstract to summarize the information provided in a book, article, or set in five or fewer sentences. Summarize the topic instead of summarizing the outline.
Example 2: An abstract #
SUSE Linux Enterprise ships with several file systems, including Btrfs, Ext3, Ext4. Each file system has advantages and disadvantages that make it more or less suitable for a scenario. Professional high-performance setups can require a different choice of file system than a home user setup. This guide will help you choose the right one.
- Table of Contents
The table of contents is generated automatically.
- Preface
Include a brief overview of the content of a manual, related manuals, and typographical conventions. The preface can also contain information about its target audience.
- Parts
If you are writing a book with many chapters, create parts at the outline level above chapters. Parts should contain at least three chapters. Keep part titles clear and concise. Often a single noun is enough. Typical part titles are Installation or Network.
- Chapters
Chapters typically consist of the following elements (appendixes should be regarded an exception):
Highlights. Use a highlights section to summarize the information provided in a chapter in four or fewer bullet points. Summarize the topic instead of summarizing the outline.
Example 3: A highlights section #
This chapter will:
Give you an overview over the file systems available in SUSE Linux Enterprise, such as Ext3, Ext4, and Btrfs.
Inform you about their distinctive advantages and disadvantages.
Help you choose the right one for your purpose.
Introduction. Provide introductory information directly after the highlights. Do not place it in a separate section.
Sections. Structure the detailed information, so readers can skim the text. Create sections for every major task, such as installing, configuring, monitoring, and administering. If helpful, split sections into subsections. Avoid nesting deeper than three levels of sections.
Start sections with an introductory paragraph outlining the focus of the section. If the section describes a sequential task, add a procedure description, as discussed in Section 5.16, “Procedures”. Steps of a procedure can contain a cross reference to subsections where topical background is provided and an action is explained in detail. See also Section 5.5, “Cross references”.
Troubleshooting. In this section, collect common mistakes and problems. The section should always be named Troubleshooting. Use the DocBook element
<qandaset/>
(a Question and Answer section) to mark up Troubleshooting problems. In case you want to describe solutions to more than ten problems, add topical subsections (<qandadiv/>
elements) below the Troubleshooting section.For more information. In this section, collect Web links to all sources of information that might prove helpful in a given context. Follow the general referencing guidelines in Section 5.5, “Cross references” when creating such sections.
- Glossary
The optional glossary contains important terms in alphabetical order and provides a brief explanation for each.
3.2 Articles #
For articles, use a document structure that includes the following elements, in that order:
introduction
sections, split into subsections
(optional) a glossary
(optional) appendixes
4 Language #
The following rules are intentionally kept concise. When in doubt about a style rule, see The Chicago Manual of Style, 15th Edition. When in doubt about the spelling or usage of a word, first see Appendix A, Terminology and general vocabulary. When the usage of a word is not regulated there, use American English spellings as defined on https://www.merriam-webster.com/ (https://www.m-w.com/ for short).
If a product you are documenting is not listed in the terminology table, refer to the SUSE home page, https://www.suse.com. If the product is not mentioned on the SUSE home page, refer to the Marketing department.
4.1 Abbreviations #
Where possible, avoid using abbreviations. Especially avoid unusual abbreviations. You may create plurals of acronyms. In all other cases, avoid creating plurals of abbreviations.
4.1.1 Acronyms #
Introduce acronyms by providing the expansion in parentheses after the acronym. Sometimes chapters and parts are used across multiple documents. Therefore, provide the expansion of an acronym at least once per chapter.
However, do not use headlines to introduce an acronym. Headlines or captions must not contain both an acronym and its expansion. If a term is commonly written as an acronym, use the acronym in the title. When mentioning the term for the first time in the following text, use its expanded form. All following occurrences of the term in this chapter should then use the acronym.
Create plural forms of acronyms by adding a lowercase “s,”. For example, use “CDs” and “BIOSes.” Never add an apostrophe before the “s” or “es.”
For clarity, avoid using possessive forms of acronyms. For example, do not use “XMLʼs specification”.
4.1.2 Latin abbreviations #
Do not use Latin abbreviations. Use the full English form: for example, use “that is” instead of “i.e.”. As an exception to this rule, the abbreviation etc. is allowed.
4.1.3 Units of measurement #
You may use abbreviations of common units of measurement. For more information on units of measurement, see Section 4.11, “Numbers and measurements”.
4.2 Capitalization of headings and titles #
Sentence-style capitalization is the most common capitalization used in SUSE documentation. When using sentence-style capitalization, only proper names and the first letter of the first word of a phrase are capitalized. Apply sentence-style capitalization to all running text and all types of headings and titles that are part of the document content. An example for sentence-style capitalization is “Ceph core components”.
For document titles, such as book, article, and set titles, use title-style capitalization. This capitalization style is explained in The Chicago Manual of Style, 8.167. A simplified version of these rules is below:
Capitalize the first and the last word.
Write articles in lowercase. Articles are: the, a, and an.
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.
Write certain conjunctions in lowercase: and, but, for, nor, and or.
Write as and to in lowercase.
Capitalize everything that is not mentioned above.
Examples for title-style capitalization are “Deployment Guide” (book title) or “Kernel Module Packages for SUSE-Based Distributions” (article title).
4.3 Commas #
Use commas between all items in a series of three or more elements. For example, write “a, b, and c.” Use commas around phrases like for example and that is. Introductory phrases at the beginning of a sentence are normally followed by a comma. For example, “Before using YaST Online Update, configure a network connection.”
4.4 Contractions #
Do not use contractions, unless you are purposefully writing a casual document.
4.5 Dashes #
Use en dashes (–) between numbers in a range in tables and figures.
For punctuation, use em dashes (—). Do not surround em dashes with spaces. Use em dashes sparingly.
4.6 End of sentence punctuation #
End sentences in a period. Avoid using exclamation marks. Restrict question marks to question and answer sections.
4.7 File and directory names #
Under Linux, objects like directories, printers, or flash disks are all considered files. Therefore, the naming and markup conventions are the same for “drives” (for example, hard disks, CD-ROM drives), directories, or files.
The layout for file names and directory names is the same. See the following example:
In general, use forward slashes (
/
) to separate nested directory or file names. If you are describing actions performed on Windows* systems and within a Windows-native file system, use backward slashes (\
) instead.In general, when giving absolute paths, always start with a leading slash to indicate the root of the file system. If you are describing actions performed on Windows systems and within a Windows-native file system, do not add a leading slash to absolute paths.
Use a trailing slash to distinguish between a file and a directory. If the distinction is important in the current context, in addition comment on it in the accompanying or surrounding running text.
Most Linux file systems are case-sensitive. Use capitals exactly as they appear in the file system. For more information on markup aspects, see Section 5.14, “References to other external resources” and Section 5.4.2, “File names”.
When it is necessary to refer to file extensions, such as in compound words like “PDF file”, always capitalize the extension.
4.8 Gender bias #
Avoid indicating gender in your documentation. If possible, use plural to allow use of “they” as the pronoun. Otherwise, use “he or she.”
For naming of example items, refer to Section 2, “Names of example items”. For more information on how to avoid gender bias, refer to The Chicago Manual of Style, 5.43.
4.9 Headings #
When writing a descriptive section, use a noun-based heading title, for example, “Concepts of Software”. When writing a task-orientated section, use a verb in gerund, for example, “Installing Software”.
Keep headings short and simple. Do not use both an acronym and the expanded form in a heading. Make sure that headlines in a chapter follow the same pattern.
For advice on how to nest sections, refer to Section 5.15, “Outline levels and sectioning”.
4.10 Lists #
For information about creating lists, see Section 5.12, “Lists”.
4.11 Numbers and measurements #
Write the integers zero through nine as words. Use numerals for all other numbers.
When the unit of a measurement is abbreviated, always use numerals for
the number. In measurements, add a non-breaking space (
) between the numeral and its corresponding unit abbreviation.
For more information, refer to The Chicago Manual of Style 9.6 and 9.16.
4.12 Possessives #
Do not use possessives of acronyms and trademarked terms. Avoid possessives of inanimate objects.
4.13 Prefixes #
Add a hyphen after the prefix to prefixed words only if:
The last letter of the prefix and the first letter of the word are the same.
You foresee misunderstandings. For example, there is a difference in meaning between “recreate” and “re-create”.
4.14 Semicolons #
Avoid using semicolons to join sentences. You may use semicolons in place of commas in very complicated series.
4.15 Slashes #
Do not use slashes except when they are part of a standard technical term, such as TCP/IP or client/server.
4.16 Sentence structure #
Form clear and direct sentences with 20 words or less. Avoid complicated clauses. Make sure that the relationship between subject, verb, and object are clear. Avoid joining sentences with semicolons. Avoid ending sentences with prepositions.
Avoid using parentheses. Where they are necessary, move them to the end of the sentence. Never nest parentheses.
Always let the reader know the objective of an action before describing the action itself. As an example, write: “To restore world peace, click ” .
4.17 Tense #
Use the simple present tense. Apply the simple present tense even to sentences with “if” or “when” clauses: “If this happens, go there.”
Prerequisites of an action should be expressed in the present tense as well: “Glibc is installed.” In some cases, no verb is necessary before the prerequisite of an action: “a 1 GHz processor or better.”
4.18 Tone and voice #
Maintain a professional tone. Do not use contractions, except in casual documents. Do not use humor. Be honest and avoid absolutes and exaggerations, but focus on positive aspects.
Use second person (“you”) to refer to the reader. Normally, the reader is the user or administrator who performs the actions described. Do not overuse “you.” It is often understood, especially in directions.
Where possible, use active voice. In active voice, the subject of the sentence performs the verb. For example, “The root user performs administrative tasks” is active voice. “Administrative tasks are performed by the root user” is passive voice.
Use passive voice if there is no emphasis on the object of the verb or if the performer of the action is unknown. “A Samba server must be configured in the network” is an example of proper use of passive voice. The emphasis is on the server, not on the person configuring it.
4.19 Trademarks #
Most products referenced in the documentation are trademarked. Follow these rules when dealing with these terms:
Never use trademarks in headings.
Only use the marked version on the first occurrence of the product name in a chapter.
Only use the ®, ™, or ℠ marks for SUSE products.
Use an * (asterisk) for all service marks or trademarks of third-party companies. This acknowledges the service mark or trademark of the other company. It also protects SUSE if the protection of the brand changes in any way.
For more information on markup aspects, see Section 5.17, “Products”.
4.20 User interface items #
When referring to labels of user interface items, do not include ending
punctuation such as …
or :
.
Whenever possible, refer to user interface items without identifying them
as any special type of element. For example, use “click
” rather than “click the
” button. However, complex dialogs may
require more specific wording.
For instructions concerning markup, refer to Section 5.20, “User interface items”.
4.21 Quotations #
Use quotations to quote from sources, such as books. In other cases, avoid using quotation marks. Do not use irony and do not use quotation marks to mark irony. In the case of computer input, computer output, and user interface elements, use more appropriate markup. See also Section 5.4, “Command line input and command line output” and Section 5.20, “User interface items”.
To create quotations, use the
<quote/>
element, as it is easier to localize than hardcoded quotation marks and
always provides typographic quotes.
Punctuation directly following the quoted text should be included within the quotation marks, as illustrated in Example 4, “Quote”.
Example 4: Quote #
“Suds may froth,” the sign reads.
5 Structure and markup #
Structure your documentation by tasks relevant to the user instead of providing reference documentation by describing each part of the user interface individually. Often, it is unnecessary to describe every minor functionality of a product. Describe what a product can do rather than its limitations.
SUSE uses the GeekoDoc Relax NG schema which is compatible with DocBook 5.1. Thus, for more detailed descriptions of the elements of a book, see the DocBook 5.1: The Definitive Guide sections listed in Table 1, “Important elements”.
Table 1: Important elements #
Element | Web Link |
---|---|
<appendix/>
| https://tdg.docbook.org/tdg/5.1/appendix.html |
<book/>
| https://tdg.docbook.org/tdg/5.1/book.html |
<chapter/>
| https://tdg.docbook.org/tdg/5.1/chapter.html |
<glossary/>
| https://tdg.docbook.org/tdg/5.1/glossary.html |
<part/>
| https://tdg.docbook.org/tdg/5.1/part.html |
<preface/>
| https://tdg.docbook.org/tdg/5.1/preface.html |
<sect1/>
| https://tdg.docbook.org/tdg/5.1/sect1.html |
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: Do not interrupt creation of file systems
Creating a file system can take multiple hours. Interrupting this process will result in a corrupt file system and an unusable installation.
Always wait until formatting has finished.
5.2 Application names #
When referring to an application, add a
<phrase role="productname"/>
element around it:
<phrase role="productname">LibreOffice</phrase> is an office suite.
This will not result in a visual change but disables hyphenation in browsers. This markup sidesteps hyphenation issues of CamelCased names.
5.3 Callouts #
Callouts allow annotating examples, such as configuration files or commands
with many options.
Add <co/>
elements directly after the part of a screen that you want to annotate.
Do not try to align them above the part of a screen to annotate. Do not
use more than ten callouts per example.
See also Section 5.7, “Examples”.
Example 6: Example of callouts (source) #
<screen>color white/blue black/light-gray <co xml:id="co-color"/> default 0 <co xml:id="co-default"/></screen> <calloutlist> <callout arearefs="co-color"> <para> Colors of the boot loader menu. </para> </callout> <callout arearefs="co-default"> <para> Defines the preselected option. </para> </callout> </calloutlist>
Example 7: Example of callouts (output) #
Table 2: Elements related to
<callout/>
#
Element | Web Link |
---|---|
| https://tdg.docbook.org/tdg/5.1/co.html |
| https://tdg.docbook.org/tdg/5.1/calloutlist.html |
| https://tdg.docbook.org/tdg/5.1/callout.html |
5.4 Command line input and command line output #
When dealing with user input and system output shorter than 30
characters, format it with an inline element, such as
<command/>
or
<filename/>
. In all other cases, close the current
paragraph and enclose the user input and/or system output in a
<screen/>
element. See also Section 5.7, “Examples”.
When using <command/>
elements standalone, that
is outside of a <screen/>
, do not use
<prompt/>
elements before or within them. For
more information about <prompt/>
, see
Section 5.4.5, “Prompts”.
Table 3: Elements related to command line input and output #
Element | Web Link |
---|---|
| https://tdg.docbook.org/tdg/5.1/screen.html |
| https://tdg.docbook.org/tdg/5.1/command.html |
| https://tdg.docbook.org/tdg/5.1/option.html |
| https://tdg.docbook.org/tdg/5.1/replaceable.html |
| https://tdg.docbook.org/tdg/5.1/filename.html |
| https://tdg.docbook.org/tdg/5.1/varname.html |
5.4.1 Commands #
Commands can be embedded in running text or presented as part of a
screen environment. In running text, use
<command/>
when referring to an actual command you would use on a command line:
To start LibreOffice from the command line, use <command>loffice</command>.
Where options or subcommands belong with a command, include
them within the element <command/>
itself:
To start LibreOffice Writer from the command line, use <command>loffice --writer</command>.
If options or subcommands stand for themselves in a text, wrap them in the
element <option/>
.
Use markup for commands even inside
<screen/>
environments. To avoid spelling or capitalization errors, whenever
possible, try commands before adding them to the documentation.
See also Section 5.4.5, “Prompts”.
5.4.2 File names #
A file name is the name of a file on a local or network disk. Can contain a simple name or could include a path or other elements specific to the operating system. See also Section 4.7, “File and directory names”.
Find the log file <filename>configuration.xml</filename> in the directory <filename>/etc/sysconfig</filename>.
5.4.3 Placeholders #
To mark up text that readers need to replace, use the
<replaceable/>
element. Capitalize placeholder text in all contexts where this is not
detrimental to content intelligibility.
To list the contents of a directory, execute <command>ls <replaceable>DIRECTORY</replaceable></command>.
5.4.4 Literals #
Use
<literal/>
to mark up data taken literally from a computer system.
To create a comment, insert <literal>#</literal> characters.
5.4.5 Prompts #
When documenting commands entered into Bash with a
<screen/>
element, always prefix them with a prompt marked up this way:
<prompt>tux > </prompt><command>ls</command>
To avoid making prompts longer than necessary, do not include a host name or a path in them, unless this is vital to understanding. The first restricted user should always be named tux. For more information on names of restricted users, see Section 2, “Names of example items”.
Avoid using root prompts in your documentation by using the
sudo
command where applicable. If you do need a root
prompt, always mark it up as following:
<prompt>root # </prompt><command>yast</command>
When documenting prompts other than the one of Bash, use a custom prompt that is as generic as possible.
For consistency, it is helpful to create entities for the prompts used in your documentation. For more information, see Section 6.3, “Entities”.
5.4.6 Screens #
Screens are used to present:
long commands and commands together with their output
system output, such as system messages
code or configuration examples
<screen><prompt>tux > </prompt><command>ls /</command> bin dev lib mnt proc sbin suse usr boot etc lib64 mounts root selinux sys var data home lost+found opt run srv tmp</screen>
Use screens only where necessary for understanding the documentation. Present longer screens as examples. For more information, see Section 5.7, “Examples”.
Do not add empty lines at the beginning or end of screens. They can be cut away by the SUSE stylesheets. However, most other stylesheets do not have such functionality.
Text in screens should not follow the indentation level of the XML around them: All indentation will be reproduced verbatim.
Lines in a screen should be at most 80 characters long. If you are working in a structure with less available space, such as within a list or within a table, work with appropriate shorter line lengths.
Avoid command output that contains dates, version numbers, or other version-specific information that frequently changes.
To make long shell commands less unwieldy, split them into multiple lines at appropriate positions, such as after the end of an option. At the end of each line but the last, append a
\
. The character\
informs the shell that the command invocation will continue after the end of the line. Splitting commands into lines can also be helpful for aligning callouts with the right option.To work with long output, especially tabular output, use either of the following strategies:
Remove or replace items that are irrelevant to your goal. For example, replace long file names by shorter ones or remove a table column and replace it with
[...]
.Use a processing instruction at the beginning of the screen to decrease font size:
<?dbsuse-fo font-size="SIZEem"?>
Replace SIZE by a suitable value, such
0.7
. Choose a value between0.55
and1
. Values outside that range will lead to either unreadably small or unsuitably large text.
See also Section 5.7, “Examples”, Section 5.4.1, “Commands”, Section 5.4.5, “Prompts”, and Section 5.3, “Callouts”.
5.4.7 Variable names #
To reference to names of variables, use the
<varname/>
element:
To select another display manager, start the YaST system configuration editor and change the value of <varname>DISPLAYMANAGER</varname>.
5.5 Cross references #
Use the
<xref/>
element (read: “cross ref”) when referring to an appendix,
chapter, example, figure, part, preface, section, table, or question and
answer set. The element referenced needs to have an
xml:id
attribute. Do not prefix or suffix cross references with text labels such
as “appendix,”
“chapter,” “table,” or “figure.”
Such labels are generated automatically.
Do not create references to paragraphs (<para/>
) or
other elements that have no title.
An exception to this rule is the element <step/>
to which you may create references.
If a reference to an element without a title is vital to the document, use
the attribute xreflabel
to assign a title.
Other types of references to resources are described in Section 5.14, “References to other external resources” and Section 5.8, “External links”. Create identifiers to reference from cross references using the rules under Section 5.11, “Identifiers”.
Example 8: Example of a cross reference (source) #
<sect2 xml:id="sec-cross-reference">
<title>Cross references</title>
<para>
Use the <sgmltag class="emptytag">xref</sgmltag> element ...
</para>
...
<para>
See <xref linkend="sec-cross-reference"/>.
</para>
</sect2>
Example 9: Example of a cross reference (output) #
5.6 Emphasis #
Where possible, indicate stress with language only. If that is not
possible, use the
<emphasis/>
element to indicate stress.
Where added emphasis is needed, use the
role="bold"
attribute.
This will be displayed in <emphasis>italics</emphasis>. This will be displayed in <emphasis role="bold">bold</emphasis>
5.7 Examples #
Use examples to illustrate complex processes. The rules established in Section 5.9.1, “Graphics” also apply to examples.
Examples usually contain <screen/>
elements.
Additionally, there can be callouts and explanatory text.
Always give examples a title and an identifier.
For more information on screen environments, see Section 5.4.6, “Screens”. For more information on displaying computer input and output, see Section 5.4, “Command line input and command line output”. To annotate examples, use callouts. Callouts are described in Section 5.3, “Callouts”.
Example 10: Example of an example #
<example xml:id="ex-example"> <title>Example of an example</title> <screen><prompt>tux > </prompt><command>ps -xa</command> 5170 ? S 0:00 kdeinit: khotkeys 5172 ? S 0:02 kdeinit: kdesktop 5174 ? S 0:04 kdeinit: kicker</screen> </example>
Table 4: Elements related to
<example/>
#
Element | Web Link |
---|---|
| https://tdg.docbook.org/tdg/5.1/example.html |
| https://tdg.docbook.org/tdg/5.1/screen.html |
5.8 External links #
Use the
<link/>
element to mark up URLs that can be opened with a Web browser, such as
https://www.example.org/. Always add the correct
protocol prefix (for example, https://
), otherwise
links will not work. Never use
filename
for a link, as that would both disable the link checker and make the link
unclickable. Avoid entering a text label between
<link/>
start and end tags. Instead, use a self-closing tag:
<link xlink:href="https://www.example.org/"/>
Make URLs as short as possible before adding them to documentation. Many
long URLs can be shortened by leaving away non-essential pieces,
such as the _utm
parameters used for marketing purposes.
If a Web site provides a built-in URL shortener, use it.
Do not use third-party URL shorteners, such as bit.ly. Third-party URL shorteners have the following disadvantages:
They obscure the destination a link points to.
They introduce an extra element of uncertainty, as the shortening service may disappear or become unreliable in the future.
The providers of these services usually run Web analytics that may introduce privacy issues.
Do not use
<link/>
to link to SUSE documentation outside of the current document set.
Instead, use the appropriate entity for the book title. Always reference
the book itself, as chapter names can change.
Where possible, collect links in a “For More Information” section at the end of the chapter. This helps readers focus on your documentation instead of leading them immediately to other resources.
To mark up multiple links, create an
<itemizedlist/>
around them. Do not use a list environment for a single link. If you need
to present many links, group them by topic and create a separate list
environment for each group. Provide a comprehensive title for each of the
groups or an introductory sentence. For more information on creating lists,
see Section 5.12.1, “Itemized lists”.
Where possible, provide translators with localized versions of links in the comments of the source file.
Other types of references to resources are described in Section 5.5, “Cross references” and Section 5.14, “References to other external resources”.
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/>
#
Element | Web Link |
---|---|
| https://tdg.docbook.org/tdg/5.1/figure.html |
| https://tdg.docbook.org/tdg/5.1/informalfigure.html |
| https://tdg.docbook.org/tdg/5.1/mediaobject.html |
| https://tdg.docbook.org/tdg/5.1/imageobject.html |
| https://tdg.docbook.org/tdg/5.1/glossary.html |
| https://tdg.docbook.org/tdg/5.1/textobject.html |
5.9.1 Graphics #
Keep graphics as simple as possible. Use as little text as possible. To allow for translation, reserve twice as much space for runs of text as the English version of it consumes.
5.9.2 Screenshots #
Use screenshots to illustrate complex situations in which the user cannot easily follow the instructions otherwise.
Be selective. Only illustrate steps in which meaningful user interactions are necessary. Do not create screenshots of progress bars or confirmation windows. Usually, it is unnecessary to create a screenshot of every step of an instruction.
Always create screenshots illustrating the situation right before an action has been taken.
Insert screenshots directly after the textual description of the action.
Make sure screenshots focus on what they are supposed to illustrate. When documenting application windows, create a screenshot of the window only. When documenting Web applications, only reproduce the contents of the tab instead of the entire browser window.
Do not scale screenshots using graphics software. Embed screenshots at their original resolution and use DocBook attributes to scale them appropriately.
Avoid creating screenshots of windows higher or wider than 800 pixels at 96 pixels per inch. When creating screenshots of applications scaled for a higher pixel-per-inch count, apply a proportionally larger maximum window size.
To ensure readability and consistency, scale screenshots with the
width
attribute. Choose the appropriate scaling from the following list:Screenshots of the whole desktop should be scaled to 90–99 % page width.
Screenshots of individual application windows should be scaled to 75–99 % page width.
Small windows such as message boxes should be scaled to 50–60 % page width.
Create screenshots that are recognizable to readers. For example, create screenshots of KDE applications on a KDE desktop with the default KDE theme and disable toolbar modifications you have made.
Use grayscale font antialiasing (default on SUSE operating systems). Subpixel font antialiasing (default on Windows and macOS operating systems) creates colored letter edges when zoomed or printed.
Where applicable, follow the rules in Section 2, “Names of example items”.
Avoid editing screenshots. To anonymize portions of a screenshot, pixelize it. To highlight parts of a screenshot, use rectangles or arrows. Never add callouts, text or freely drawn objects. Always select colors that provide a good contrast with their background.
If possible, avoid screenshots with dates, version numbers, or other version-specific information that frequently changes.
5.10 Glossaries #
An optional glossary contains terms and their definitions. Make sure that the glossary entries are appropriate to the intended audience. Define unfamiliar terms and special jargon.
Define infinitive forms of verbs and singular nouns. Use lowercase for the term unless it is a proper noun.
Use cross-references to link acronyms with their written out forms. Define the written out form. Use a See reference for the acronym form to link it to the defined written out form.
The markup for a glossary entry is shown in Example 12, “A typical example of a glossary”.
Example 12: A typical example of a glossary #
<glossary> <title>Glossary</title> <glossentry> <glossterm xml:id="gt-extensible">Extensible Markup Language</glossterm> <glossdef> <para> A markup language that defines a set of rules for encoding documents in a format that is both human-readable and machine-readable. </para> </glossdef> </glossentry> <glossentry> <glossterm>XML</glossterm> <glossdef> <para> See also <xref linkend="gt-extensible"/>. </para> </glossdef> </glossentry> </glossary>
5.11 Identifiers #
Always use an
xml:id
attribute in parts, chapters, appendixes, sections, figures, and examples. Identifiers can be used in other elements as well, such as tables and procedures.In identifiers, only use lower-case basic Latin alphabetic and numeric characters and
-
(hyphen). Do not use_
and.
characters, as they may hurt search engine optimization.Identifiers can consist of multiple parts. Join these parts with a
-
(hyphen).Prefix. Signifies the type of XML element. Use in accordance with Table 6, “Abbreviations for different elements in an
xml:id
attribute”.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.
Element title label. Shortened version of name of the title of the element itself.
Example 13: Examples of identifiers #
xml:id="cha-install" xml:id="sec-install-yast" xml:id="tab-install-source"
Use short, memorable, English terms or phrases as title labels. Favor longer terms over non-obvious abbreviations. Always use the singular of nouns and the infinitive of verbs. For example, a section about installing with YaST could be called
sec-install-yast
.Keep in mind that section and chapter identifiers are used in the online documentation URLs. Choosing understandable keywords helps readers to understand what the page is about and also improves the search engine ranking.
Do not rework identifiers in existing documentation, instead apply these rules to newly created documentation only.
Table 6: Abbreviations for different elements in an
xml:id
attribute #
Element | Prefix |
---|---|
<appendix/>
|
app
|
<book/>
|
book
|
<co/>
|
co
|
<chapter/>
|
cha
|
<example/>
|
ex
|
<figure/>
|
fig
|
<glossary/> ,
<glossterm/>
|
gl
|
<itemizedlist/>
|
il
[a]
|
<listitem/>
|
li
|
<indexterm/>
|
idx
[b]
|
<orderedlist/>
|
ol [a]
|
<part/>
|
part
|
<preface/>
|
pre
|
<procedure/>
|
pro
|
<qandaset/> ,
<qandadiv/> ,
<qandaentry/>
|
qa
|
<sect1/> ,
<sect2/> , etc. |
sec
|
<set/>
|
set
|
<step/>
|
st
|
<table/>
|
tab
|
<variablelist/>
|
vl
|
<varlistentry/>
|
vle
|
[a]
Only add an
[b] Only add when creating index ranges |
5.12 Lists #
SUSE documentation uses the following types of lists (the respective XML elements are given in parentheses):
Itemized lists (
<itemizedlist/>
). Also known as bullet lists or unordered lists.Ordered lists (
<orderedlist/>
). Also known as numbered lists.Variable lists (
<variablelist/>
). Also known as definition lists or description lists.Procedures (
<procedure/>
). Also known as step-by-step instructions or step lists. Described in Section 5.16, “Procedures”.
Follow these rules when creating or editing lists:
Always introduce a list in the text. If needed for reference or better coordination with the related text, add a title and an
xml:id
attribute.A list must contain at least two items. If items are few, short, and simple in structure, consider incorporating them in the flowing text instead of creating a list.
If all list items are nouns only, do not capitalize their first letter. Use sentence-style capitalization for list items that are full sentences and for terms in descriptive lists.
If each item in a list consists of a single sentence only, do not use a period at the end of items.
If at least one list item consists of two full sentences, end all items in that list with a period.
Wherever possible, use parallel phrasing and grammatical construction between list items. This provides a pattern that makes it easier to follow the text.
Lists are visually distinct and can break up text flow. Do not overuse them.
Never nest more than three lists within each other. Instead, restructure the information using a combination of lists and running texts.
To be able to reference untitled lists, use the
xreflabel
attribute. For more information, see Section 5.5, “Cross references”.
Table 7: Elements related to lists #
Element | Web Link |
---|---|
| https://tdg.docbook.org/tdg/5.1/itemizedlist.html |
| https://tdg.docbook.org/tdg/5.1/orderedlist.html |
| https://tdg.docbook.org/tdg/5.1/variablelist.html |
| https://tdg.docbook.org/tdg/5.1/varlistentry.html |
| https://tdg.docbook.org/tdg/5.1/term.html |
| https://tdg.docbook.org/tdg/5.1/listitem.html |
5.12.1 Itemized lists #
Use itemized lists whenever the order of list items is irrelevant. They are often used to provide an overview of information or to introduce or summarize information.
Example 14: Example of an itemized list (source) #
<para> The following operating systems are supported: </para> <itemizedlist> <listitem> <para> Linux, Kernel 2.4 and newer </para> </listitem> <listitem> <para> FreeBSD 7 and newer </para> </listitem> </itemizedlist>
Example 15: Example of an itemized list (output) #
The following operating systems are supported:
Linux, Kernel 2.4 and newer
FreeBSD 7 and newer
5.12.2 Ordered lists #
Use ordered lists when items have a strict order, hierarchy, or importance. Do not use ordered lists to describe sequential user actions (step-by-step instructions). For sequential user actions, use a procedure, as described in Section 5.16, “Procedures”. If order is not relevant, use an itemized list or a variable list.
Example 16: Example of an ordered list (source) #
<para> Before installing, make sure of the following: </para> <orderedlist> <listitem> <para> The network connection of the computer is configured properly. </para> </listitem> <listitem> <para> The latest security updates are installed. If you are in doubt, run an online update. </para> </listitem> </orderedlist>
Example 17: Example of an ordered list (output) #
Before installing, make sure of the following:
The network connection of the computer is configured properly.
The latest security updates are installed. If you are in doubt, run an online update.
5.12.3 Variable lists #
Use variable lists when defining terms or describing options. Each item of a variable list contains a short term that is then further explained by means of an explanatory paragraph.
Use sentence-style capitalization for both the term and the list item.
To reference the list, assign it a xml:id
attribute and add a title.
Individual list items may be referenced by assigning an
xml:id
. The entry is then identified by the value
of
xml:id
and referenced by the term.
Example 18: Example of a variable list (source) #
<para> This book consists of several parts: </para> <variablelist> <varlistentry> <term>Installation</term> <listitem> <para> Learn about the installation and initial configuration of a Linux system. </para> </listitem> </varlistentry> <varlistentry> <term>System</term> <listitem> <para> Get a basic understanding of the system components. </para> </listitem> </varlistentry> </variablelist>
Example 19: Example of a variable list (output) #
This book consists of several parts:
- Installation
Learn about the installation and initial configuration of a Linux system.
- System
Get a basic understanding of the system components.
5.13 Keys and key combinations #
Capitalize all keys as printed on a standard keyboard. Capitalize all letter keys. To refer to a capitalized character, use Shift–Z, for example. Introduce this convention by means of the “Typographical Conventions” section of the introduction.
To mark up key combinations, use
<keycombo/>
as a wrapper for multiple
<keycap/>
elements. Separators between
<keycap/>
elements are then created automatically.
If a key is listed in Table 8, “Elements related to
<keycap/>
”, use the
function
attribute with the appropriate value. When using the
function
attribute, make the tag self-closing—DocBook's language files
will insert key names automatically. This simplifies both your work and
the work of translators.
For more information on creating cross references, see Section 5.5, “Cross references”.
Example 20: Example of a key #
To create a screenshot, press <keycap>Print Screen</keycap>.
Example 21: Example of a keyboard combination #
To save a file, press <keycombo><keycap function="control"/><keycap>S</keycap></keycombo>.
Table 8: Elements related to
<keycap/>
#
Element | Web Link |
---|---|
| https://tdg.docbook.org/tdg/5.1/keycombo.html |
| https://tdg.docbook.org/tdg/5.1/keycap.html |
5.14 References to other external resources #
To reference file names, use the
<filename/>
element. To reference e-mail addresses, use the
<email/>
element. In either case, do not include a protocol prefix, that is
file://
or mailto:
, respectively.
See also Section 5.4.2, “File names”.
Reference man pages and info pages in this format:
“the man page of
command
”“the info page of
command
”
In a situation where the category of the page is needed, append the
category in parentheses. Use, for example “(man 9
command
)”.
To learn more about subcommands, see the man page of <command>command</command>.
Insert references to external (non-SUSE) physical books in the format
“Title by Author (ISBN #00000000).” Inclusion of the ISBN is
optional. Place the title in a
<citetitle/>
element. For example:
<citetitle>Lorem Ipsum</citetitle> by Dolores S. Amet (ISBN 0-246-52044-7) is a useful guide.
As an author, where possible, provide language-specific references to translators in XML comments (see also Section 6.2, “XML comments”). As a translator, look for corresponding language-specific resources where none have been provided. For URLs, provide only the language-specific version of a site. Use the English version as a fallback. For books, provide the title of the translated version along with the original title if such a translation exists.
Other types of references to resources are described in Section 5.5, “Cross references” and Section 5.8, “External links”.
5.15 Outline levels and sectioning #
Create sections using the
<sect1/>
, <sect2/>
, and
<sect3/>
elements.
Avoid outlines that require <sect4/>
and <sect5/>
elements.
Instead, create a flatter structure in which more elements are
visible at a glance.
Provide at least one paragraph of introductory information directly within each section.
Do not create lone subsections. A lone subsection is a section that is the only subsection of its parent section.
For more information on writing headlines, see Section 4.9, “Headings”.
5.16 Procedures #
Use procedures to describe sequential tasks. A procedure consists of the following elements and attributes:
An
xml:id
attribute.A title.
An introductory phrase establishing the purpose of the procedure. If the procedure is otherwise the only element in its section, place the introductory phrase before the procedure.
If there are preconditions or prerequisites, add them as a second paragraph after the introduction.
Short, simple steps and, if necessary, substeps describing the actions to be performed. See also Section 4.16, “Sentence structure”.
To link alternative actions inside the same substep element, use
“or.” Apply a
performance=optional
attribute to optional steps.
Steps may contain a link to an explanatory subsection providing further details on the step.
Example 22: Example of a procedure (source) #
<procedure xml:id="pro-procedure"> <title>Example of a procedure</title> <para> To add a new user to the system, perform the following steps: </para> <step> <para> In the <phrase role="productname">YaST</phrase> window, click <guimenu>User and Group Management</guimenu>. </para> </step> <step> <para> To open the <guimenu>Add a New User</guimenu> dialog, click <guimenu>Add</guimenu>. </para> </step> <step> <para> Type in the user name and click <guimenu>Create</guimenu>. </para> </step> </procedure>
Procedure 1: Example of a procedure (output) #
To add a new user to the system, perform the following steps:
In the YaST window, click .
To open the
dialog, click .Type in the user name and click
.
Table 9: Elements related to
<procedure/>
#
Element | Web Link |
---|---|
| https://tdg.docbook.org/tdg/5.1/procedure.html |
| https://tdg.docbook.org/tdg/5.1/step.html |
| https://tdg.docbook.org/tdg/5.1/substeps.html |
5.17 Products #
Always use the preferred product name instead of, for example, an
acronym. When referring to a product, add a
<phrase role="productname"/>
element around it. This will not result in a visual change but disables
hyphenation:
<phrase role="productname">LibreOffice</phrase> is an office suite.
5.18 Questions and answers #
Use questions-and-answers sections to present information about troubleshooting or commonly asked questions about a product. Never use questions-and-answers sections to explain trivia, such as how a product got its name. Keep your audience in mind. See also Section 1, “Audience”.
Questions must always end in a ?
. Where explanations
longer than three paragraphs are necessary for an answer, add a cross
reference to an explanation outside of the questions-and-answers section.
See also Section 5.5, “Cross references”.
When a questions-and-answers section contains over 10 questions and there
are clear topical divisions, add
<qandadiv/>
elements to further structure the section.
Example 23: Example of a questions-and-answers section (source) #
<qandaset> <title>Example of a questions-and-answers section</title> <qandaentry> <question> <para> How can I check if the product was correctly installed? </para> </question> <answer> <para> Open the log file. Look for entries starting with <literal>Failed</literal>. </para> </answer> </qandaentry> <qandaentry> <question> <para> Why does the error <literal>Not enough disk space</literal> occur during installation? </para> </question> <answer> <para> There are less than 4 GB of space available on the selected partition. </para> </answer> </qandaentry> </qandaset>
Example of a questions-and-answers section (output)
- Q: 1. How can I check if the product was correctly installed?
Open the log file. Look for entries starting with
Failed
.
- Q: 2.
Why does the error
Not enough disk space
occur during installation? There are less than 4 GB of space available on the selected partition.
Table 10: Elements related to
<qandaset/>
#
Element | Web Link |
---|---|
| https://tdg.docbook.org/tdg/5.1/qandaset.html |
| https://tdg.docbook.org/tdg/5.1/qandadiv.html |
| https://tdg.docbook.org/tdg/5.1/qandaentry.html |
| https://tdg.docbook.org/tdg/5.1/question.html |
| https://tdg.docbook.org/tdg/5.1/answer.html |
5.19 Tables #
Use tables to present many similar facts. Tables are easy to scan and compare. Always keep tables simple enough to not require long explanations even for readers unfamiliar with the topic.
A table always has a title and should have an
xml:id
attribute.
Value and description pairs are better handled by means of a descriptive list.
Example 24: Example of a table (source) #
<informaltable> <tgroup cols="2"> <thead> <row> <entry>File System</entry> <entry>Maximum File Size</entry> </row> </thead> <tbody> <row> <entry>Ext2 (1 kB block size)</entry> <entry>16 GB</entry> </row> <row> <entry>Ext2 (2 kB block size)</entry> <entry>256 GB</entry> </row> </tbody> </tgroup> </informaltable>
Example 25: Example of a table (output) #
File System | Maximum File Size |
---|---|
Ext2 (1 kB block size) | 16 GB |
Ext2 (2 kB block size) | 256 GB |
Table 11: Elements related to
<table/>
#
Element | Web Link |
---|---|
| https://tdg.docbook.org/tdg/5.1/table.html |
| https://tdg.docbook.org/tdg/5.1/informaltable.html |
| https://tdg.docbook.org/tdg/5.1/tgroup.html |
| https://tdg.docbook.org/tdg/5.1/colspec.html |
| https://tdg.docbook.org/tdg/5.1/thead.html |
| https://tdg.docbook.org/tdg/5.1/tbody.html |
| https://tdg.docbook.org/tdg/5.1/row.html |
| https://tdg.docbook.org/tdg/5.1/entry.html |
5.20 User interface items #
To mark up single user interface items, use
<guimenu/>
. To mark up nested menu structures, use
<menuchoice/>
as a wrapper for multiple
<guimenu/>
elements. Separators between
<guimenu/>
elements are then created automatically.
For more information on language aspects, see Section 4.20, “User interface items”.
Example 26: Example of a single user interface item #
To open a file, click <guimenu>Open</guimenu>.
Example 27: Example of nested user interface items #
To save a file, use <menuchoice><guimenu>File</guimenu><guimenu>Save</guimenu></menuchoice>.
6 Managing documents #
This section provides an overview over features of XML you can use to manage documents.
6.1 Remarks #
Use remarks for editorial comments. Remarks can be placed within, before, or after a para but must always be within a section element. When creating output, remarks can be made visible in the output and thus help within the editorial process. When creating the final output, deactivate remarks.
Start remarks with your user name and the current date, then add a colon
(:
) and finally your actual remark. To comment on
someone else's remark, add a new remark directly below it. Delete remarks
when the corresponding issue is resolved.
<remark>tux (2013-10-13): could not find the option for foo</remark> <remark>geeko (2013-11-02): see /usr/share/doc/foo.html</remark>
You can add a
role
attribute with one of the following values to show the type of the
remark:
structure
. Use this type of remark to suggest changes to the text or XML structure.language
. Use this type of remark to suggest language improvements.needinfo
. Use this type of remark to mark sections where you need input from others, such as developers.trans
. Use this type of remark to give hints to translators.
6.2 XML comments #
XML comments can be used for temporarily disabling portions of text. Another use of XML comments is to create more permanent internal comments or to mark up changes made for layout reasons. XML comments are never visible in a publication.
<!-- This is an XML comment. -->
For information about formatting XML comments, see Section 7, “Formatting XML”.
6.3 Entities #
Entities are used to expand text. There are several situations in which they can be used:
To represent special characters that cannot easily be displayed, entered, or memorized.
To integrate external files using entities representing references to their file names.
To repeat content easily.
When an entity is defined, it can be used in many places. Entities increase consistency, as they only need to be defined once and will automatically be expanded everywhere within the document.
6.3.1 Using entity files #
SUSE uses a set of custom entities.
Find these entities in the file
xml/entity-decl.ent
in each documentation repository.
Entity files are only used for original, English-language documents. Translated documents will contain only the resolved form of entities, that is, plain-text directly in the document.
If you need to define new custom entities, add their new definitions to the
xml/entity-decl.ent
file. Do not include custom entity definitions directly in the file header, unless the custom definitions are needed to override externally embedded entities.Use the UTF-8 encoding when editing and saving the entity declaration file or any of the SUSE XML files.
Each header of a SUSE XML file includes the entity declaration file (by means of an entity):
<!ENTITY % entities SYSTEM "entity-decl.ent"> %entities;
Example 28: Excerpt from an entity-decl.ent
#
<!ENTITY1 server2 "sun3"> <!ENTITY domain "example.org"> <!ENTITY host "&server;.&domain;4"> <!ENTITY hosttag "<uri xmlns='http://docbook.org/ns/docbook'>&host;</uri>5">
Making an entity declaration. | |
Defining the entity name. | |
Setting the value which the processed entity should expand to. | |
Using another entity within the entity value. This entity reference is only valid if the other entity is defined somewhere within the scope of the XML document that is built. However, it does not matter whether the entity is defined before or after the current entity definition. | |
Using a DocBook/GeekoDoc element within the entity value.
The attribute |
6.3.2 Common types of entities #
An entity-decl.ent
file contains several categories of
entities:
- Products
All SUSE product names and other products and applications. This helps in case sudden name changes are necessary and avoids misspellings.
- Platforms
Use entities for all hardware architectures referenced. This helps in case sudden name changes are necessary.
- Books
Title entities for all SUSE books. This helps in case sudden name changes are necessary.
- General Entities
Network IP addresses, host names, and user names.
There are several guidelines to consider when working with product entities for SUSE documentation:
- Entity selection
Use the entity name
&product;
to identify the product for which the documentation is built. Set the value of this entity once per release and have it expand to the name of the current product:<phrase role="productname">&product;</phrase> includes 389-ds.
If you need to reference a specific subproduct or a different product, use a more specific entity:
The Ext4 file system has been included in the <literal>&suse;</literal> Kernel since <literal>&sle;</literal> XYZ.
- Acronyms
Avoid using acronyms of product names where they are not the preferred form of the name. If you do define an additional acronym version of a longer product name, append an
a
to the end of the entity name. For example, use&slesa;
the acronym “SLES”.- Trademarks
Follow the rules under Section 4.19, “Trademarks” and Section 5.17, “Products”.
6.4 XInclude elements #
XInclude elements are used to create modular source files that are easier to work with and can be re-used. When editing a book, create a new source file for every chapter. Later, create a new GeekoDoc file that can serve as the central point. In this file, use XInclude elements to reference all chapters in the correct order:
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="gfdl.xml"/>
XInclude elements allow adding common sections to multiple books or articles without having to maintain the text in multiple places. Common sections include licenses and information on typographical conventions. XIncludes also simplify co-editing documentation with others in a version control system as they reduce the chance of merge conflicts.
By default, files referenced via XIncludes must be well-formed XML files that
are also valid GeekoDoc fragments.
This means that they must have a single top-level element and must not
contain elements that are not allowed in GeekoDoc.
Files that are supposed to be referenced multiple times from within the same
set, book, or article must not contain any xml:id
attributes.
XIncludes also allow embedding plaintext files, for example, as the
content in <screen/>
elements.
To embed a plaintext file, add the attribute
parse="text"
to the
<xi:include/>
element.
7 Formatting XML #
This section provides information on formatting XML sources.
Line ends: Lines should end with a Unix line end character (also called line feed, LF, newline, or
\n
).Line length: Lines should be at most 80 characters long, unless one of the following exceptions applies:
Some computer output, computer input, or URIs may run longer and cannot be broken.
Some elements become much harder to read if broken. For example, that can be the case for long
<menuchoice/>
elements.Aim to minimize the size of diffs in version control, to make reading diffs more efficient and version control storage more efficient. For example, if a typo fix introduces a line with 82 characters, consider keeping the line at that length. Also, avoid reflowing entire paragraphs of text, as that will also lead to hard-to-read diffs.
Indentation: Indent using a single space character per indentation level. Make sure your editor does not replace some spaces with tabs. Documents should not contain any tab characters.
Trailing whitespace: Avoid introducing trailing whitespace characters such as spaces, protected spaces, or tabs. Many editors have an option to view such characters.
git diff
will show newly introduced trailing whitespace characters in red.Formatting of block elements: Block elements are all DocBook elements that create a rectangular visual block in the layout, such as
<para/>
,<table/>
, or<figure/>
. Format block elements with new lines before and after each tag and make sure they follow the indentation of the document:<block> Content of block, indented by a space. </block>
For information about the usage of
<screen/>
, see Section 5.4.6, “Screens”.Formatting of inline elements: Block elements are all DocBook elements that can be reflowed freely within a block element, such as
<emphasis/>
,<keycap/>
, or<guimenu/>
. Format inline elements along with other inline content without adding newlines or extra indentation:<block> Content of block <inline>content of inline</inline>. <block>
Formatting of title elements: The title elements
<title/>
and<term/>
are block elements. However, they provoke a stylesheet quirk and should be treated differently. This avoids superfluous whitespace when used in the context of a cross-reference. Format title elements with new lines before the opening tag and after the closing tag and make sure they follow the indentation of the document:<title>Content of Title</block>
Formatting of computer output/computer input blocks: The Computer Output/Computer Input Block Element
<screen/>
should be treated like a block element but multi-line<screen/>
elements should not be indented to aid source reading flow and avoid the trap of adding extraneous leading space to their content. (Single-line<screen/>
can be indented).XML comments. XML comments should follow the indentation of the document. Where feasible, put XML comments on new lines to make reading diffs and later removal of the comment easier:
<block> Block content. <!-- An XML comment --> </block>
XML comments must not contain the characters
--
. To preserve such character combinations within comments, replace them with-/-
.For information about the usage of XML comments, see Section 6.2, “XML comments”.
Reflowing entire files: Before reflowing entire files to a different XML formatting style, weigh the cost of keeping the document in its current state against the cost of reflowing. Reflowing often makes it easier to work with the document. However, if the document has a rich editing history already, reflowing makes it harder to use properly use tools like
git blame
.
To easily convert documents to this style after importing them, use the
commands daps xmlformat
(for an entire document) and
daps-xmlformat
(for a single file). Note that while these
tools are very good otherwise, they do not reflow XML comments properly.
8 Working With AsciiDoc #
This section collects resources on how to use AsciiDoc.
The following things are important when working with AsciiDoc:
Only use formatting that is supported by the AsciiDoctor tool. Ignore features that are only documented for the outdated
asciidoc
(Python) tool. In particular, ignore the documentation athttps://powerman.name
.Adhere to https://asciidoctor.org/docs/asciidoc-recommended-practices.
Most recommendations from https://github.com/SUSE/doc-susemanager/wiki/markup-syntax are applicable generally. Some recommendations, however, are specific to SUSE Manager documentation, in particular:
The section Images—images need to be added the same way they are added in other DAPS-based documentation, under the
images/src/FORMAT
directory of the repo.The section Working with Drafts—there is currently no equivalent standard functionality.
A Terminology and general vocabulary #
The following two tables define technical terms and general vocabulary for use in SUSE documentation. See also Section 4, “Language”.
A.1 Terminology #
The following table defines the correct spellings and denominations for technical terms in SUSE documentation. Always use the entry listed under “Accepted” in the table below. All terms are reproduced in sentence-style capitalization.
Accepted | Rejected [Reason] | Part of Speech; Usage Guideline/Definition |
---|---|---|
32-bit | 32 Bit, 32 bit, 32-Bit, 32Bit, 32bit | adjective |
3D | 3 D, 3 d, 3.D., 3.d., 3-D, 3-d, 3d, Three-D | adjective |
64-bit | 64 Bit, 64 bit, 64-Bit, 64Bit, 64bit | adjective |
AArch64 | ARM64, ARMv8 | noun; 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 |
adapter | adaptor | noun |
add-on | add on, AddOn, addOn, addon | noun |
address book | addressbook | noun |
advice | advise [misspelling] | noun |
(to) advise sth. | (to) advice sth. [misspelling] | verb |
AMD64/Intel 64 | x64, x86_64, x86-64, 64-bit AMD/Intel, AMD/Intel64 | noun; processor architecture; see also x86 |
AOO | Aoo, aoo, OO, oo | noun; when referring to versions 3.4 and after; spelling according to project standard; acronym of Apache OpenOffice; see also OOo |
Apache OpenOffice | Apache 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 |
architecture | arch | noun; hardware platform, especially concerning processor platform |
appendixes | appendices | noun; plural of appendix |
audio CD | Audio CD, Audio-CD, CD-Audio, CD Audio, CD audio | noun |
back-end | back end, backend | noun |
(to) back sth. up | (to) backup sth. | verb |
backup | back-up, back up | noun |
Bash | BASH, bash | noun; spelling as per the GNU Bash manual |
Bluetooth | Blue tooth, blue tooth, Blue-tooth, blue-tooth, bluetooth | noun |
Bluetooth card | wireless card [card has wires attached to it] | noun; card that enables Bluetooth connections. |
boot disk | boot disc [usually a misspelling], boot-disk, bootdisk | noun; disk for starting the system |
boot loader | boot-loader, bootloader | noun |
(to) boot using PXE or (to) boot via PXE | (to) PXE boot | verb |
Btrfs | B.T.R.F.S., Better FS, BetterFS, Butter FS, ButterFS, btrfs | noun; not an acronym |
cursor | pointer [used for pointing device input] | noun; on-screen item indicating the position of keyboard input focus; see also pointer |
CA | C.A., Ca | noun; acronym for certificate authority |
CD | C.D., Cd | noun; acronym for compact disc |
CD-ROM | CD ROM, CD-Rom, CD Rom | noun; acronym for compact disc read-only memory |
CUPS | C.U.P.S., Cups, cups | noun; spelling as per project standard; acronym for Common Unix Printing System |
case-sensitive | case sensitive, casesensitive | adjective |
case-insensitive | case insensitive, caseinsensitive | adjective |
certificate authority | certification authority, certificating authority, certified authority | noun; acronym is CA |
check box | check-box, checkbox, checking option, tick box | noun; avoid, only mention name of option |
checklist | check list, check-list, ticklist | noun |
check mark | check, check-mark, checkmark, tick, tick mark | noun |
chipset | chip set, chip-set | noun |
(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/server | client 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 System | Common UNIX Printing System, common Unix printing system | noun; spelling as per project standard; acronym is CUPS |
command line | command-line, commandline | noun |
configuration | config | noun; 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 center | Control 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 RPM | delta-RPM, deltarpm | noun; 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 |
DHCP | D.H.C.P., Dhcp, dhcp | noun |
dial-up | dial up, dialup | only as an adjective |
dialog | dialog box, dialog window, dialogue [British], mask [Germanism], screen | noun; a page or window that asks you to make one or more decisions before proceeding |
directory | dir, folder | noun |
DNS | D.N.S., DNS name server, Dns, dns | noun; 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 box | combination 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 |
DVD | D.V.D., Dvd | noun; acronym for digital versatile disc |
dynamic name server | Dynamic Name Server, Dynamic name server | noun; acronym is DNS |
e-book | E-book, E-book, Ebook, eBook, electronic book, ebook | noun |
E-mail, E-mail, Email, eMail, electronic mail, email | noun | |
EPUB | E-PUB, e-PUB, e-Pub, EPub, Epub, ePUB, ePub | noun; project logo uses the capitalization “ePub”, but the vendor standard is “EPUB” |
end user | end-user | noun; 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 | |
Ethernet | ethernet | noun |
Ethernet card | wired card [sounds as if wires attached to the card are meant] | noun; card that connects to networks via Ethernet. |
Ext3 | EXT3, EXT 3, Ext 3, Ext-3, ext 3, ext-3, ext3 | noun; 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 |
Ext4 | EXT4, EXT 4, Ext 4, Ext-4, ext 4, ext-4, ext4 | noun |
file name | file-name, filename | noun |
file server | file-server, fileserver | noun |
file system | file-system, filesystem | noun |
flavor | flavour [British] | noun |
flash disk | flash disc [misspelling], flash drive, USB disk, USB drive, USB stick | noun |
framebuffer | frame buffer, frame-buffer | noun |
front-end | front end, frontend | noun |
FTP | F.T.P., Ftp, ftp | noun |
GIMP | G.I.M.P., Gimp, gimp | noun; spelling as per project standard; acronym for GNU Image Manipulation Program; if “the” occurs directly before GIMP, capitalize it: “The” |
GNOME | G.N.O.M.E., GNU Networked Object Model Environment, Gnome | noun; spelling as per project standard; not an acronym. |
GRUB | G.R.U.B., Grub, grub | noun; acronym for GRand Unified Bootloader |
graphical user interface | Graphical User Interface | noun; acronym for graphical user interface |
GUI | G.U.I., GUI interface, GUI user interface, Gui | noun; acronym for graphical user interface |
hard disk | HDD, HD, hard disc [misspelling], hard disk drive, hard drive, hard-disk, hard-drive, harddisk, harddrive, hdd, hd | noun |
hard link | hard-link, hardlink | only 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 page | home-page, homepage | noun |
host name | host-name, hostname | noun |
(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 |
hotplugging | hot plugging, hot-plugging, hotadding, hotswapping | noun |
hotpluggable | hot pluggable, hot-pluggable, hotaddable, hotswappable | adjective |
HTML page | HTML document, HTML Web page, HTML web page | noun; when referring to a local file; see also Web page |
HTTP | H.T.T.P., Http, http | noun |
HTTPS | H.T.T.P.S., Https, https | noun |
hypervisor | hyper visor, hyper-visor, hypervizor | noun |
indexes | indices | noun; plural of index |
infrared | infra red, infra-red | noun or adjective. |
init script | init-script, initscript, initialization script [incorrect,
when referring to script run by init ] | noun; a script run by init
|
initialization | init, initialisation [British] | noun |
(to) initialize sth. | (to) init sth., (to) initialise sth. [British] | verb |
installation medium | installation data medium | noun; 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 source | installation data source | noun; source of installation data for operating systems |
Internet | internet | noun |
intranet | Intranet | noun |
I/O port | I.O. port, I-O port, IO port, Io port | noun |
IA64 | IA-64, ia64, ipf, Itanium | noun; processor architecture |
IPsec | IPSEC, Ipsec | noun |
IPv4 | IP v4, IPV4, Ipv4 | noun; acronym for Internet protocol version four |
IPv6 | IP v6, IPV6, Ipv6 | noun; acronym for Internet protocol version six |
journaling | journalling [British] | noun |
KIWI | Kiwi, kiwi | noun; project spelling; not an acronym; software for creation of operating system images |
K Desktop Environment | Kool Desktop Environment | noun; spelling according to project standard; acronym is KDE |
KDE | KDE Desktop Environment, K.D.E., Kde, kde | noun; spelling according to project standard; acronym for K Desktop Environment |
Kdump | KDUMP, kdump | noun; only for application |
kdump | KDUMP, Kdump | noun; only for command |
kernel space | kernel-space, kernelspace, kernelland | noun; memory area reserved for the kernel and device drivers; see also user space |
key combination | hot key, key accelerator, keyboard accelerator, key combo, keyboard combo, keyboard combination, keyboard shortcut, key shortcut | noun |
Kprobes | kprobes | noun; only for application |
kprobes | Kprobes | noun; 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 |
LibreOffice | Libre Office, Libreoffice, LibO, LO, libreoffice | noun; spelling according to project standard; do not create acronyms of LibreOffice |
license | licence [British] | noun |
(to) license sth. | (to) licence sth. [British] | verb |
Linux | LINUX, linux | noun; spelling according to project standard |
list box | list, list field | noun; GUI element that is a list showing multiple elements even before interacting with it |
live CD | LiveCD, live-CD | noun; CD that allows booting an operating system without installing |
live DVD | LiveDVD, live-DVD | noun; DVD that allows booting an operating system without installing |
live image | live disk image, LiveImage, live-image | noun; disk image that can be copied to a medium and then allows booting an operating system without installing |
local host | local-host, localhost | noun; when describing the concept of hosting locally |
localhost | local host, local-host | noun; when referring to the default name of a local host |
log file | log-file, logfile | noun |
login | log in, log-in | noun |
logout | log out, log-out | noun |
(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 device | loop back device, loop-back device | noun |
lowercase | lower case, lower-case | noun |
mail server | mail-server, mailserver | noun |
Maildir | Mail dir, mail dir | noun; specific format for e-mail storage, not a directory for e-mails |
mainboard | main board, main-board, mother board, mother-board, motherboard | noun |
man page | Man page, Man-page, man page, man-page, manpage | two words |
Mbox | mbox | noun; specific format for e-mail storage |
menu | drop-down menu | noun; GUI element that is a list whose entries each start an action; see also drop-down box |
metadata | meta 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 point | mount-point, mountpoint | noun |
mouse button | mouse-button, mousebutton, mouse key, mouse-key, mousekey | noun |
(to) multitask | (to) multi task, (to) multi-task | verb |
multitasking | multi tasking, multi-tasking | noun |
multiuser | multi user, multi-user | noun |
name server | name-server, nameserver | noun |
namespace | name space, name-space | noun |
need to | have to | verb; see also must |
NFS | N.F.S., NFS file system, Nfs | noun; often: “NFS client”, “NFS server” |
NIS | N.I.S., NIS information service, Nis | noun; often: “NIS client”, “NIS server” |
OOo | Oo.o, Ooo, OOoo, OO, oo | noun; 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.org | Open Office Org, OpenOffice, Openoffice.org, openoffice, openoffice.org | noun; only when referring to versions prior to 3.4; spelling according to former project standard; acronym is OOo; see also Apache OpenOffice |
openSUSE | Open SUSE, Open-SUSE, open SUSE, open-SUSE | noun; never capitalize first letter |
open source | Open Source, Open-Source, open-source, opensource | only as a noun |
operating system | operation system, operating-system | noun |
paravirtualized | para-virtualised, paravirtualised [British], para-virtualized | adjective |
patch level | patch-level, patchlevel | noun |
path name | path-name, pathname | noun; avoid, check if path can be used instead |
(to) plug sth. in | (to) plug-in sth., (to) plugin sth. | verb |
plug-in | plug in, plugin | noun|adjective |
pointer | cursor [used for keyboard input], mouse cursor | noun; on-screen item echoing the movement of a pointing device, such as a mouse; mouse pointer is also acceptable; see also cursor |
pop-up | pop up, popup | noun |
on port | at port | preposition noun |
PostScript | POSTSCRIPT, Postscript, postscript | noun; spelling as per vendor standard |
POWER | ppc64le, POWER8, Power | noun; processor architecture |
(to) preconfigure sth. | (to) pre-configure sth. | verb |
preconfigured | pre-configured | adjective |
(to) print sth. | (to) print out sth. | verb |
print queue | printer queue, printing queue | noun |
print spooler | printer 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 | |
PXE | P.X.E., Pixie, pixie, PXE Environment, Pxe, pxe | noun; acronym for “Preboot Execution Environment” |
PXE boot | PXE Boot | only 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 |
RAM | R.A.M., RAM memory, Ram, ram | noun; acronym for random access memory |
RAM disk | RAM 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 |
README | Read-me, Readme, read-me, readme | noun; use this capitalization for all general references |
read-only | R.O., RO, read only, readonly, ro | adjective |
(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) signup | verb; 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 |
RPM | R.P.M., Rpm, rpm [different meaning] | noun; acronym for RPM Package Manager |
runlevel | run level, run-level | noun |
runtime | run time, run-time | noun |
Samba | SAMBA, samba | noun; project spelling; open-source implementation of the SMB file and print service protocol |
(to) save sth. | (to) store sth., (to) write sth. out | verb; 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 | |
SCSI | S.C.S.I., Scsi, scsi | noun |
screenshot | screen shot, screen-shot | noun |
screen saver | screen-saver, screensaver | noun |
scrollbar | scroll-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 |
selected | blocked, chosen, highlighted | adjective; selection state of list entries or text; opposite of deselected |
(to) set sth. up | (to) set-up sth., (to) setup sth. | verb |
setup | set up, set-up | adjective|noun |
(to) shut sth. down | (to) shut-down sth., (to) shutdown sth. | verb |
shutdown | shut down, shut-down | adjective|noun |
SLE | S.L.E., SLE Enterprise, SLE Linux, Sle, sle | noun; avoid; acronym for SUSE Linux Enterprise |
SLED | S.L.E.D., SLE Desktop, SLE Enterprise Desktop, SLE Linux Desktop, Sled, sled | noun; avoid; acronym for SUSE Linux Enterprise Desktop |
SLES | S.L.E.S., SLE Server, SLE Enterprise Server, SLE Linux Server, Sles, sles | noun; avoid; acronym for SUSE Linux Enterprise Server |
SLES for SAP | SLES for SAP Applications, SLE for SAP | noun; acronym for SUSE Linux Enterprise Server for SAP Applications |
slider | slide bar, slidebar | noun; GUI element that is used manipulate values that have an upper and a lower bound |
solid-state drive | SD [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 file | Spec file, Spec-file, Specfile, spec-file, specfile | noun |
SSD | S.S.D., SD [misleading], SS-D, sd, ss-d | noun; acronym of solid-state drive; a type of mass storage that does not depend on mechanical parts |
stand-alone | stand alone, standalone | adjective |
(to) start sth. up | (to) start-up sth., (to) startup sth. | verb |
start-up | start up, startup | noun |
statusbar | status bar, status-bar | noun |
SSH | S.S.H., SSH Shell, SSH shell, Ssh, ssh | noun |
SUSE | S.U.S.E., Software- und System-Entwicklung, SuSE, SuSe, Suse, suse | noun; not an acronym |
SUSE Enterprise Storage | SUSE Storage, SUSE Linux Enterprise Storage | noun; acronym is SES |
SUSE Linux Enterprise | SUSE Linux Entreprise [British], SUSE Linux enterprise, SUSE linux enterprise | noun; acronym is SLE |
SUSE Linux Enterprise Desktop | SUSE Desktop, SUSE Linux Enterprise desktop | noun; acronym is SLED |
SUSE Linux Enterprise Server | SUSE Server, SUSE Linux Enterprise server | noun; acronym is SLES |
SUSE Linux Enterprise Server for SAP Applications | SUSE Linux Enterprise for SAP, SUSE Linux Enterprise Server for SAP, SUSE Server for SAP | noun; acronym is SLES for SAP Applications |
SUSE Manager | SUSE Linux Manager | noun |
SUSE OpenStack Cloud | SUSE Cloud, SUSE Linux Cloud | noun |
SUSE Studio | SUSE Linux Studio | noun |
submenu | sub menu, sub-menu | noun; menu that is nested inside another menu |
subsystem | sub system, sub-system | noun |
systemd | System D, Systemd, systemD, system d, System 500 | noun; project spelling; initialization system for Linux |
System V init | SysVinit, SysV init, system 5 init, system d | noun; spoken: “System five init”; initialization system for Unix operating systems |
symbolic link | soft 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 |
synchronization | sync, 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 archive | TAR ball [Unix jargon], tar ball, tar-ball, tarball | noun |
taskbar | task bar, task-bar | noun |
technology preview | technical preview, technology-preview | noun; product features that are shipped without support and marked as such |
text box | entry 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 |
TFTP | T.F.T.P., Tftp, tftp | noun |
time stamp | time-stamp, timestamp | noun |
titlebar | title bar, title-bar | noun |
toolbar | tool bar, tool-bar | noun |
toolchain | tool chain, tool-chain | noun; set of tools (such as build tools) that is used in succession |
tooltip | tool tip, tool-tip | noun |
UEFI | Uefi, u-EFI, uEFI | noun; acronym of Unified Extensible Firmware Interface |
Unified Extensible Firmware Interface | unified extensible firmware interface | noun; acronym is UEFI; software interface between firmware and operating system; replaces the BIOS interface |
Unix | UNIX [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 |
unselected | deselected, un-selected | adjective; selection state of list entries or text; opposite of selected |
uppercase | upper case, upper-case | noun |
usage | utilisation [British], utilization | noun |
use case | use-case, usecase | noun |
(to) use sth. | (to) utilise sth. [British], (to) utilize sth. | verb |
user name | user-name, username | noun |
user space | user-space, userspace, userland | noun; memory area used by applications; see also kernel space |
video DVD | Video DVD, Video-DVD, DVD video | noun |
virtualization | Virtualization, 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 |
VLAN | V.L.A.N., Vlan, vlan | noun; acronym for Virtualized Local Area Network |
Web | WEB, World Wide Web, WWW, web, www | noun; you may use World Wide Web or WWW in historical contexts |
Web cam | Webcam, Web camera, webcam | noun; camera that can be connected to a computer, mainly for video chats |
Web page | HTML Web page, Web-page, Webpage | noun; when referring to page on the Internet; see also HTML page |
Web server | Web-server, Webserver | noun |
Web site | Web-site, Website, web site, web-site, website | noun |
Webmaster | Web master, Web-master | noun |
Wi-Fi | Wi fi, Wi-fi, Wifi, wireless fidelity, WLAN | noun; 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 card | wireless card [card has wires attached to it] | noun; card that connects to Wi-Fi networks. |
Wi-Fi/Bluetooth card | wireless card [card has wires attached to it] | noun; card that combines a Wi-Fi and a Bluetooth card. |
wild card | joker [Germanism], wild-card, wildcard | noun |
WLAN | Wlan | noun; 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. out | verb; when saving the command line output of a program as a
file using > or >> ;
see also save
|
x86 | 32-bit AMD/Intel, i686, i386 | noun; processor architecture; see also AMD64/Intel 64 |
X Window System | X Window, X Windows, X window, X window system, X windows, XWS | noun |
Xen | XEN, xen | noun |
Xend | xend | noun |
YaST | YAST, YAST2, Yast, YaST2, yast, yast2 | noun; spelling according to project standard; acronym for Yet another Setup Tool |
IBM Z | z Systems, System z, zSeries, z System, zsystems, S390x | noun; processor architecture; see also AMD64/Intel 64 |
Zypper | zypper | noun; only for application |
zypper | Zypper | noun; 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.
Accepted | Rejected [Reason] | Part of Speech; Usage Guideline/Definition |
---|---|---|
after | once | adverb; only use once in the meaning of “one time only” |
afterward | afterwards [BrE] | adverb |
although | while | conjunction; only use while in the meaning of “during the time that” |
and | while | conjunction; only use while in the meaning of “during the time that” |
backward | backwards [BrE] | adverb |
basically [filler] | adverb | |
because of | due to, owing to | preposition |
business case | business-case, businesscase | noun |
but | while | conjunction; only use while in the meaning of “during the time that” |
cannot | can't [contraction], can not | verb |
can | may | verb; use can to express an ability, only use may to express permissions sought/given. |
could | may | verb; use could to express a possibility, only use may to express permissions sought/given. |
easy [filler], easily | adjective, adverb; avoid. | |
etc. | abbreviation; avoid; do not use together with “for example” and “such as”; always precede with a comma. | |
for example | for instance, for instances [misspelling] | adverb |
forward | forwards [BrE] | adverb |
if | pronoun; use if an event depends on a condition; also see when and whether | |
inward | inwards [BrE] | adverb |
just [filler] | adjective, adverb; avoid | |
might | may | verb; use might to express a possibility, only use may to express permissions sought/given |
must | have to | verb; see also need to |
need to | have to | verb; see also must |
obvious [insulting], obviously | adjective, adverb | |
outward | outwards [BrE] | adverb |
please | adverb; avoid | |
self-evident [insulting], self-evidently | adjective, adverb | |
sideward | sidewards [BrE] | adverb |
simple [filler], simply | adjective, adverb; avoid | |
(to) simplify sth. | (to) ease sth., (to) facilitate sth. | verb; avoid |
stuff [colloquial], stuffs | noun | |
toward | towards [BrE] | adverb |
want sth. | (to) wish sth., (to) wish for sth., would like sth. | verb |
when | once | adverb; use once only in the meaning “one time only” |
when | pronoun; use if an event is inevitable; also see if | |
whether | whether or not | pronoun; use to present two alternatives which are not conditions, otherwise use if; see also if |
with regard to | as regards, in regard to, with regards to | conjunction noun preposition |
B GNU Free Documentation License #
Version 1.2, November 2002
Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
PREAMBLE #
The purpose of this License is to make a manual, textbook, or other functional and useful document “free” in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.
This License is a kind of “copyleft”, which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.
We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.
APPLICABILITY AND DEFINITIONS #
This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The “Document”, below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as “you”. You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law.
A “Modified Version” of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.
A “Secondary Section” is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document’s overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.
The “Invariant Sections” are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none.
The “Cover Texts” are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words.
A “Transparent” copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not “Transparent” is called “Opaque”.
Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only.
The “Title Page” means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, “Title Page” means the text near the most prominent appearance of the work’s title, preceding the beginning of the body of the text.
A section “Entitled XYZ” means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as “Acknowledgements”, “Dedications”, “Endorsements”, or “History”.) To “Preserve the Title” of such a section when you modify the Document means that it remains a section “Entitled XYZ” according to this definition.
The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License.
VERBATIM COPYING #
You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.
You may also lend copies, under the same conditions stated above, and you may publicly display copies.
COPYING IN QUANTITY #
If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document’s license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.
If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.
If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.
It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.
MODIFICATIONS #
You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:
A. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.
B. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has fewer than five), unless they release you from this requirement.
C. State on the Title page the name of the publisher of the Modified Version, as the publisher.
D. Preserve all the copyright notices of the Document.
E. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.
F. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.
G. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document’s license notice.
H. Include an unaltered copy of this License.
I. Preserve the section Entitled “History”, Preserve its Title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section Entitled “History” in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.
J. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the “History” section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.
K. For any section Entitled “Acknowledgements” or “Dedications”, Preserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein.
L. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.
M. Delete any section Entitled “Endorsements”. Such a section may not be included in the Modified Version.
N. Do not retitle any existing section to be Entitled “Endorsements” or to conflict in title with any Invariant Section.
O. Preserve any Warranty Disclaimers.
If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version’s license notice. These titles must be distinct from any other section titles.
You may add a section Entitled “Endorsements”, provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.
You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.
The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.
COMBINING DOCUMENTS #
You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers.
The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.
In the combination, you must combine any sections Entitled “History” in the various original documents, forming one section Entitled “History”; likewise combine any sections Entitled “Acknowledgements”, and any sections Entitled “Dedications”. You must delete all sections Entitled “Endorsements”.
COLLECTIONS OF DOCUMENTS #
You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.
You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.
AGGREGATION WITH INDEPENDENT WORKS #
A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an “aggregate” if the copyright resulting from the compilation is not used to limit the legal rights of the compilation’s users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document’s Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate.
TRANSLATION #
Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail.
If a section in the Document is Entitled “Acknowledgements”, “Dedications”, or “History”, the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title.
TERMINATION #
You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.
FUTURE REVISIONS OF THIS LICENSE #
The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.
Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License “or any later version” applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation.
ADDENDUM: How to use this License for your documents #
To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:
Copyright (c) YEAR YOUR NAME. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled “GNU Free Documentation License”.
If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the “with...Texts.” line with this:
with the Invariant Sections being LIST THEIR TITLES, with the Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation.
If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.