-
-
- Admonitory and advisory paragraphs
+ Structure and markup
- 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.
+ This chapter contains instructions on using the correct DocBook markup to
+ create consistent and legible documents, and structuring the content in the
+ way that it effectively helps readers find answers to their queries.
-
-
-
- <tag class="emptytag">warning</tag>
-
- 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.
-
-
-
-
-
- <tag class="emptytag">important</tag>
-
- Use these elements to give vital information.
-
-
-
-
-
- <tag class="emptytag">tip</tag>
-
- Use these elements to introduce guidelines or give tips.
-
-
-
-
-
- <tag class="emptytag">note</tag>
-
- Use these elements to highlight software version differences.
-
-
-
-
- Follow these rules when writing admonitions:
+ In the Doc Kit repository, you can see examples of how
+ books
+ and
+ articles
+ are rendered in our documentation.
-
-
-
- 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 must 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.
-
-
-
-
- An example of a warning (source)
+
+ &suse; uses the GeekoDoc Relax NG schema which is compatible with DocBook
+ 5.2. For more information about the XML elements described here, see the
+ DocBook 5.2: The Definitive Guide sections listed in
+ .
+
+
+ Important elements
+
+
+
+ Element
+ Web link
+
+
+
+
+ appendix
+
+
+
+
+
+ book
+
+
+
+
+
+ chapter
+
+
+
+
+
+ glossary
+
+
+
+
+
+ part
+
+
+
+
+
+ preface
+
+
+
+
+
+ sect1
+
+
+
+
+
+
+
+
+ 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.
+
+
+
+
+ <tag class="emptytag">warning</tag>
+
+ 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.
+
+
+
+
+
+ <tag class="emptytag">important</tag>
+
+ Use these elements to give vital information.
+
+
+
+
+
+ <tag class="emptytag">tip</tag>
+
+ Use these elements to introduce guidelines or give tips.
+
+
+
+
+
+ <tag class="emptytag">note</tag>
+
+ 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 must 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.
+
+
+
+
+ An example of a warning (source)<warning>
<title>Do not interrupt creation of file systems</title>
<para>
@@ -176,49 +166,45 @@
Always wait until formatting has finished.
</para>
</warning>
-
-
- Do not interrupt creation of file systems
-
- Creating a file system can take multiple hours. Interrupting this
- process will result in a corrupt file system and an unusable
- installation.
-
-
- Always wait until formatting has finished.
-
-
-
-
-
- Application names
-
- When referring to an application, add a
- phrase role="productname"
- element around it:
-
+
+
+ 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.
+
+
+
+
+ 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.
-
-
-
-
- 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 .
-
-
- Example of callouts (source)
+
+ This will not result in a visual change but disables hyphenation in
+ browsers. This markup sidesteps hyphenation issues of CamelCased names.
+
+
+
+ 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 .
+
+
+ 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>
@@ -233,99 +219,99 @@ default 0 <co xml:id="co-default"/></screen>
</para>
</callout>
</calloutlist>
-
-
- Example of callouts (output)
+
+
+ Example of callouts (output)color white/blue black/light-gray
default 0
-
-
-
- Colors of the boot loader menu.
-
-
-
-
- Defines the preselected option.
-
-
-
-
-
- Elements related to
- <tag class="emptytag">callout</tag>
-
-
-
- Element
- Web link
-
-
-
-
-
-
- <tag class="emptytag">co</tag>
-
- Inline element to mark an area within a
- screen.
-
-
-
-
-
-
-
-
-
- <tag class="emptytag">calloutlist</tag>
-
- Block element containing a list of descriptions for each of the
- marked areas.
-
-
-
-
-
-
-
-
-
- <tag class="emptytag">callout</tag>
-
- Block element containing a description of a single area marked with
- co.
-
-
-
-
-
-
-
-
-
-
- You can group different callouts to point to the same annotation.
- This helps to avoid repeating the same annotation.
- To do this, complete the following steps:
-
-
-
- Create the co element with the
- xml:id attribute to comment on the first line.
-
-
-
-
- On another line, use the xref element
- to point to the ID from the previous step.
-
-
-
-
-
- Example of a callout group (source)
- d1 = dict() <co xml:id="co-dict"/>
+
+
+
+ Colors of the boot loader menu.
+
+
+
+
+ Defines the preselected option.
+
+
+
+
+
+ Elements related to <tag class="emptytag">callout</tag>
+
+
+
+ Element
+ Web link
+
+
+
+
+
+
+ <tag class="emptytag">co</tag>
+
+ Inline element to mark an area within a
+ screen.
+
+
+
+
+
+
+
+
+
+ <tag class="emptytag">calloutlist</tag>
+
+ Block element containing a list of descriptions for each of
+ the marked areas.
+
+
+
+
+
+
+
+
+
+ <tag class="emptytag">callout</tag>
+
+ Block element containing a description of a single area
+ marked with co.
+
+
+
+
+
+
+
+
+
+
+ You can group different callouts to point to the same annotation. This
+ helps to avoid repeating the same annotation. To do this, complete the
+ following steps:
+
+
+
+
+ Create the co element with the
+ xml:id attribute to comment on the first
+ line.
+
+
+
+
+ On another line, use the xref element to
+ point to the ID from the previous step.
+
+
+
+
+ Example of a callout group (source)
+d1 = dict() <co xml:id="co-dict"/>
d2 = {} <xref linkend="co-dict"/>
l1 = list() <co xml:id="co-list"/>
l2 = [] <xref xml:id="co-list"/>
@@ -337,428 +323,437 @@ default 0
<para>A list.</para>
</callout>
</calloutlist>
-
-
- Example of a callout group (output)
- d1 = dict()
+
+
+ Example of a callout group (output)
+d1 = dict()
d2 = {}
l1 = list()
l2 = []
-
+
- A dictionary.
+
+ A dictionary.
+
- A list.
+
+ A list.
+
-
-
-
-
-
- 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 .
-
-
- When using stand-alone command elements that
- are outside of a screen, do not use
- prompt elements before or within them. For
- more information about prompt, see
- .
-
-
- Elements related to command-line input and output
-
-
-
- Element
- Web link
-
-
-
-
-
-
- <tag class="emptytag">screen</tag>
-
- Block element in which all characters are reproduced exactly as
- they are in the source of the document. See also
- . Can contain any of the inline
- elements listed in this table.
-
-
-
-
-
-
-
-
-
- <tag class="emptytag">command</tag>
-
- Inline element that contains the name of an executable program or
- the command that a user types to execute a program. Can contain
- replaceable elements.
-
-
-
-
-
-
-
-
-
- <tag class="emptytag">option</tag>
-
- Inline element that contains an argument to a command or
- instruction. Can contain
- replaceable
- elements.
-
-
-
-
-
-
-
-
-
- <tag class="emptytag">replaceable</tag>
-
- Inline element that contains content that can or must be replaced
- by the user.
-
-
-
-
-
-
-
-
-
- <tag class="emptytag">filename</tag>
-
- Inline element that contains the name of a directory or file. Can
- contain
- replaceable
- elements.
-
-
-
-
-
-
-
-
-
- <tag class="emptytag">varname</tag>
-
- Inline element that contains the name of a variable. Can contain
- replaceable
- elements.
-
-
-
-
-
-
-
-
-
-
- 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:
-
+
+
+
+ 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
+ .
+
+
+ When using stand-alone command elements that
+ are outside of a screen, do not use
+ prompt elements before or within them. For
+ more information about prompt, see
+ .
+
+
+ Elements related to command-line input and output
+
+
+
+ Element
+ Web link
+
+
+
+
+
+
+ <tag class="emptytag">screen</tag>
+
+ Block element in which all characters are reproduced exactly
+ as they are in the source of the document. See also
+ . Can contain any of the inline
+ elements listed in this table.
+
+
+
+
+
+
+
+
+
+ <tag class="emptytag">command</tag>
+
+ Inline element that contains the name of an executable
+ program or the command that a user types to execute a
+ program. Can contain replaceable
+ elements.
+
+
+
+
+
+
+
+
+
+ <tag class="emptytag">option</tag>
+
+ Inline element that contains an argument to a command or
+ instruction. Can contain
+ replaceable elements.
+
+
+
+
+
+
+
+
+
+ <tag class="emptytag">replaceable</tag>
+
+ Inline element that contains content that can or must be
+ replaced by the user.
+
+
+
+
+
+
+
+
+
+ <tag class="emptytag">filename</tag>
+
+ Inline element that contains the name of a directory or file.
+ Can contain replaceable elements.
+
+
+
+
+
+
+
+
+
+ <tag class="emptytag">varname</tag>
+
+ Inline element that contains the name of a variable. Can
+ contain replaceable elements.
+
+
+
+
+
+
+
+
+
+
+ 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:
-
+
+ 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 .
-
-
-
- File names
-
- A file name is the name of a file on a local or network disk. Can
- contain a simple name or include a path or other elements specific
- to the operating system. See also .
-
+
+ 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 .
+
+
+
+ File names
+
+ A file name is the name of a file on a local or network disk. Can
+ contain a simple name or include a path or other elements specific to
+ the operating system. See also .
+ Find the log file <filename>configuration.xml</filename>
in the directory <filename>/etc/sysconfig</filename>.
-
- To assign standard names to files and images in DocBook and AsciiDoc,
- follow the naming conventions at
- .
-
-
-
- Literals
-
- Use
- literal
- to mark up data taken literally from a computer system.
-
+
+ To assign standard names to files and images in DocBook and AsciiDoc,
+ follow the naming conventions at
+ .
+
+
+
+ Literals
+
+ Use literal to mark up data taken literally
+ from a computer system.
+ To create a comment, insert <literal>#</literal> characters.
-
-
- 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.
- Do not use spaces within placeholders. Instead, use underscores
- (_).
-
- To list the contents of a directory, execute
+
+
+ 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. Do not use spaces within placeholders. Instead, use
+ underscores (_).
+
+To list the contents of a directory, execute
<command>ls <replaceable>DIRECTORY</replaceable></command>.
-
-
- Prompts
-
- When documenting commands entered into Bash with a
- screen
- element, always prefix them with a prompt marked up this way:
-
+
+
+ Prompts
+
+ When documenting commands entered into Bash with a
+ screen element, always prefix them with a
+ prompt marked up this way:
+ <prompt>> </prompt><command>ls</command>
-
- To avoid making prompts longer than necessary, do not include paths, user
- or host names, unless this is vital to understanding.
- The first restricted user must always be named
- tux. For more information about names of restricted
- users, see .
-
-
- Whenever you provide commands in a screen,
- make it clear if the user needs regular or elevated privileges.
- 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 follows:
-
+
+ To avoid making prompts longer than necessary, do not include paths,
+ user or host names, unless this is vital to understanding. The first
+ restricted user must always be named tux. For more
+ information about names of restricted users, see
+ .
+
+
+ Whenever you provide commands in a screen,
+ make it clear if the user needs regular or elevated privileges. 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 follows:
+ <prompt role="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. Doc Kit repository contains entities for
- user, root and sudo prompts.
- For more information, see .
-
-
-
- Screens
-
- Screens are used to present:
-
-
-
-
- long commands and commands together with their output
-
-
-
-
- system output, such as system messages
-
-
-
-
- code or configuration examples
-
-
-
+
+ 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. Doc Kit repository contains entities for
+ user, root and
+ sudo prompts. For more information, see
+ .
+
+
+
+ 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
- .
-
-
-
-
- Do not add empty lines at the beginning or end of screens. They can
- be cut away by the &suse; style sheets. However, most other
- style sheets do not have such functionality.
-
-
-
-
- Text in screens must not follow the indentation level of the XML around
- them: All indentation will be reproduced verbatim.
-
-
-
-
- Lines in a screen must 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.
-
-
-
-
- You can combine multiple commands within a
+
+
+ Use screens only where necessary for understanding the
+ documentation. Present longer screens as examples. For more
+ information, see .
+
+
+
+
+ Do not add empty lines at the beginning or end of screens. They can
+ be cut away by the &suse; style sheets. However, most other style
+ sheets do not have such functionality.
+
+
+
+
+ Text in screens must not follow the indentation level of the XML
+ around them: All indentation will be reproduced verbatim.
+
+
+
+
+ Lines in a screen must 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.
+
+
+
+
+ You can combine multiple commands within a
+ screen element, if:
-
-
-
-
- all commands are explained unambiguously before the
+
+
+
+ all commands are explained unambiguously before the
+ screen element and
-
-
-
-
- all commands are strictly consecutive and none is optional.
-
-
-
-
- In all other cases, do not combine multiple commands within one
- screen element. Instead, use multiple
- screen elements. For example,
- as part of a multi-step procedure.
-
-
- If you show multiple commands within a single
- screen, use prompts before each command and
- command elements around commands. This
- effectively separates commands from each other and their output.
-
-
-
-
- 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 with 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 with a suitable value, such
- 0.7. Choose a value between 0.55
- and 1. Values outside that range will lead to either
- unreadably small or unsuitably large text.
-
-
-
-
-
- To enable automatic syntax highlighting for programming languages or
- formats, add a language
- attribute for the respective language format. Valid language formats:
- apache, bash,
- c++, css,
- diff, html,
- xml, http,
- ini, json,
- java, javascript,
- makefile, nginx,
- php, perl,
- python, ruby,
- sql, crmsh,
- dockerfile, lisp,
- and yaml.
- Note that syntax highlighting may not be supported in all
- target formats.
-
-
-
- See also , ,
- , and .
-
-
-
- Variable names
-
- To reference to names of variables, use the
- varname
- element:
-
+
+
+
+
+ all commands are strictly consecutive and none is optional.
+
+
+
+
+ In all other cases, do not combine multiple commands within one
+ screen element. Instead, use multiple
+ screen elements. For example, as part
+ of a multi-step procedure.
+
+
+ If you show multiple commands within a single
+ screen, use prompts before each command
+ and command elements around commands.
+ This effectively separates commands from each other and their
+ output.
+
+
+
+
+ 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 with 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 with a suitable value,
+ such 0.7. Choose a value between
+ 0.55 and 1. Values
+ outside that range will lead to either unreadably small or
+ unsuitably large text.
+
+
+
+
+
+
+ To enable automatic syntax highlighting for programming languages
+ or formats, add a language attribute
+ for the respective language format. Valid language formats:
+ apache,
+ bash, c++,
+ css, diff,
+ html, xml,
+ http, ini,
+ json, java,
+ javascript,
+ makefile,
+ nginx, php,
+ perl,
+ python,
+ ruby, sql,
+ crmsh,
+ dockerfile,
+ lisp, and
+ yaml.
+
+
+ Note that syntax highlighting may not be supported in all target
+ formats.
+
+
+
+
+ See also , ,
+ , and .
+
+
+
+ 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>.
+
-
-
-
- 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, an identifier. Create
- identifiers to reference from cross-references using the rules
- under . Note that the xref
- element only works when it links to documentation within the same set,
- for example, the same book or set of books.
-
- Other types of references to resources are described in
- and .
-
- Example of a cross-reference (source)
- <sect2 xml:id="sec-cross-reference">
+
+ 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, an identifier. Create identifiers to reference from
+ cross-references using the rules under . Note
+ that the xref element only works when it
+ links to documentation within the same set, for example, the same book or
+ set of books.
+
+
+ Other types of references to resources are described in
+ and .
+
+
+ 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 ...
@@ -768,88 +763,92 @@ and change the value of <varname>DISPLAYMANAGER</varname>.
See <xref linkend="sec-cross-reference"/>.
</para>
</sect2>
-
-
- Example of a cross-reference (output)
-
- See .
-
-
-
- This example shows the default display of a cross-reference. To change it, use the
- xrefstyle attribute, either with
- select: or template:. Do not use custom
- namedxrefstyle attributes that require support
- from the style sheets. For more info, refer to DocBook XSL: The Complete
- Guide: Customizing cross-references.
-
-
- Keep in mind the following cases where listing cross-references is discouraged and must be
- avoided:
-
+
+
+ Example of a cross-reference (output)
+
+ See .
+
+
+
+ This example shows the default display of a cross-reference. To change
+ it, use the xrefstyle attribute, either with
+ select: or
+ template:. Do not use custom
+ namedxrefstyle attributes
+ that require support from the style sheets. For more info, refer to
+ DocBook
+ XSL: The Complete Guide: Customizing cross-references.
+
+
+ Keep in mind the following cases where listing cross-references is
+ discouraged and must be avoided:
+
-
- Do not insert cross-references (xref linkend="...")
- into a title element.
- The title must not be clickable, and a cross-reference in a title can create
- issues when linking to such a title in a different paragraph.
+
+ Do not insert cross-references (xref
+ linkend="...") into a title
+ element. The title must not be clickable, and a cross-reference in a
+ title can create issues when linking to such a title in a different
+ paragraph.
+
- 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.
-
+ 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.
+
+
- Do not prefix or suffix cross-references with text labels such
- as appendix,chapter,table,
- or figure. Such labels are generated automatically.
+
+ Do not prefix or suffix cross-references with text labels such as
+ appendix,chapter,table, or
+ figure. Such labels are generated automatically.
+
-
-
- 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.
-
+
+ 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>
-
-
-
- Examples
-
- Use examples to illustrate complex processes. The rules established in
- also apply to examples.
-
-
- Examples usually contain screen elements.
- Additionally, there can be callouts and explanatory text.
-
-
- Always give examples a title and an identifier.
-
-
- For more information about screen environments, see
- .
- For more information about displaying computer input and output, see
- . To annotate examples, use callouts.
- Callouts are described in .
-
-
- Example of an example
+
+
+ Examples
+
+ Use examples to illustrate complex processes. The rules established in
+ also apply to examples.
+
+
+ Examples usually contain screen elements.
+ Additionally, there can be callouts and explanatory text.
+
+
+ Always give examples a title and an identifier.
+
+
+ For more information about screen environments, see
+ . For more information about displaying
+ computer input and output, see . To
+ annotate examples, use callouts. Callouts are described in
+ .
+
+
+ Example of an example<example xml:id="ex-example">
<title>Example of an example</title>
<screen><prompt>tux > </prompt><command>ps -xa</command>
@@ -858,336 +857,338 @@ will be displayed in <emphasis role="bold">bold</emphasis>
5172 ? S 0:02 kdeinit: kdesktop
5174 ? S 0:04 kdeinit: kicker</screen>
</example>
-
-
- Elements related to
- <tag class="emptytag">example</tag>
-
-
-
- Element
- Web link
-
-
-
-
-
-
- <tag class="emptytag">example</tag>
-
- Formal block element containing a
- title
- and a
- screen
- or other elements such as lists or paragraphs.
-
-
-
-
-
-
-
-
-
- <tag class="emptytag">screen</tag>
-
- Verbatim block element for displaying text that readers might see
- on a computer terminal or in a text file.
-
-
-
-
-
-
-
-
-
-
-
-
- External links
-
- Information that is relevant within &suse; documentation is often
- available from other Web sites already.
- In such cases, choose between linking to these sites or including their
- content in edited form.
- Adhere to the following guidelines when selecting sites to link to:
-
-
-
+
+
+ Elements related to <tag class="emptytag">example</tag>
+
+
+
+ Element
+ Web link
+
+
+
+
+
+
+ <tag class="emptytag">example</tag>
+
+ Formal block element containing a
+ title and a
+ screen or other elements such as
+ lists or paragraphs.
+
+
+
+
+
+
+
+
+
+ <tag class="emptytag">screen</tag>
+
+ Verbatim block element for displaying text that readers might
+ see on a computer terminal or in a text file.
+
+
+
+
+
+
+
+
+
+
+
+ External links
- Link to credible sources, such as suse.com, upstream projects or
- developer sites.
- Avoid linking to direct competitors of &suse;.
- Do not link to obvious clickbait sites.
+ Information that is relevant within &suse; documentation is often
+ available from other Web sites already. In such cases, choose between
+ linking to these sites or including their content in edited form. Adhere
+ to the following guidelines when selecting sites to link to:
-
-
+
+
+
+ Link to credible sources, such as suse.com, upstream projects or
+ developer sites. Avoid linking to direct competitors of &suse;. Do
+ not link to obvious clickbait sites.
+
+
+
+
+ Prefer larger, well-kept sites over blogs that may vanish overnight.
+ If you need to link to smaller blogs, save an archive version of the
+ site at .
+
+
+
+
+ Avoid linking to sites that feature controversial or political
+ content.
+
+
+
- Prefer larger, well-kept sites over blogs that may vanish overnight.
- If you need to link to smaller blogs, save an archive version of the
- site at .
+ In some cases, product managers will request avoiding all or selected
+ external links to avoid issues for customers impacted by restrictive
+ firewall rules.
-
-
- Avoid linking to sites that feature controversial or political content.
+ Use the link element to mark up URLs that can
+ be opened with a Web browser, such as
+ . Always add the correct
+ protocol prefix (for example, https://), otherwise
+ links will not work. If possible, use the secure protocol prefix
+ (https://).
-
-
-
- In some cases, product managers will request avoiding all or selected
- external links to avoid issues for customers impacted by restrictive
- firewall rules.
-
-
- Use the
- link
- element to mark up URLs that can be opened with a Web browser, such as
- . Always add the correct
- protocol prefix (for example, https://), otherwise
- links will not work. If possible, use the secure protocol prefix
- (https://).
-
-
- Never use filename
- for a link, as that would both disable the link checker and make the link
- unclickable. Avoid entering a text label between
- link
- start and end tags. Instead, use a self-closing tag:
-
-<link xlink:href="https://www.example.org/"/>
-
- Make URLs as short as possible before adding them to documentation. Many
- long URLs can be shortened by leaving away non-essential pieces,
- such as the _utm parameters used for marketing purposes.
- If a Web site provides a built-in URL shortener, use it.
-
-
- Do not use third-party URL shorteners, such as bit.ly.
- Third-party URL shorteners have the following disadvantages:
-
-
-
- They obscure the destination a link points to.
+ 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/"/>
- They introduce an extra element of uncertainty, as the shortening
- service may disappear or become unreliable in the future.
+ 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.
-
-
- The providers of these services usually run Web analytics that may
- introduce privacy issues.
+ Do not use third-party URL shorteners, such as bit.ly. Third-party URL
+ shorteners have the following disadvantages:
-
-
-
- Do not use
- link
- to link to &suse; documentation outside of the current document set.
- Instead, use the appropriate entity for the book title. Always reference
- the book itself, as chapter names can change.
-
-
- For consistency, do not use the article in front of the name of the
- referenced book or chapter. For example, The general concept of Podman is
- described in Containers and Podman.
-
-
- Where possible, collect links in a More information section
- at the end of the chapter.
- This helps readers focus on your
- documentation instead of leading them immediately to other resources.
- This is described in .
-
-
- To mark up multiple links, create an
- itemizedlist
- around them. Do not use a list environment for a single link. If you need
- to present many links, group them by topic and create a separate list
- environment for each group. Provide a comprehensive title for each of the
- groups or an introductory sentence. For more information about creating lists,
- see .
-
-
- 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
- and
- .
-
-
-
-
- External links to &suse; documentation
-
- The &suse; documentation is hosted under documentation.suse.com.
- This is the URL that must be provided in all documents. The abbreviated URLs such
- as doc.suse.com and docs.suse.com also work but must
- be avoided for SEO reasons.
-
-
- Make sure to use complete URLs instead of entities for an easy copy and paste.
-
-
- Most links in our documentation that goes to documentation.suse.com
- refer to a specific product and release. However, sometimes it makes sense to
- not include the SP or even the major release.
- These are so-called SP-independent links.
-
-
- The following reasons give you an idea when to use them:
-
-
-
+
+
+
+ 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.
+
+
+
- Your linked information is independent from any SP
+ 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.
-
-
- You cannot or do not need to pick a specific SP
+ For consistency, do not use the article in front of the name of the
+ referenced book or chapter. For example, The general concept of
+ Podman is described in Containers and
+ Podman.
-
-
- You want to link to the most recent SP without checking which one it is
+ Where possible, collect links in a More information
+ section at the end of the chapter. This helps readers focus on your
+ documentation instead of leading them immediately to other resources.
+ This is described in .
-
-
-
- You want to support SEO where the most prominent SP is more important
- than previous, older SPs
+
+ To mark up multiple links, create an
+ itemizedlist around them. Do not use a list
+ environment for a single link. If you need to present many links, group
+ them by topic and create a separate list environment for each group.
+ Provide a comprehensive title for each of the groups or an introductory
+ sentence. For more information about creating lists, see
+ .
-
-
-
- Make sure to follow this syntax:
-
- documentation.suse.com/<PRODUCT>[/<MAJOR_RELEASE>]/<DEEP_LINK>
-
- The placeholders mean the following:
-
-
-
- PRODUCT: the abbreviation of the product, like sle for &sle;,
- sle-ha for &sle; Server High Availability Extension, etc.
+ Where possible, provide translators with localized versions of links in
+ the comments of the source file.
-
-
- MAJOR_RELEASE: an optional major release like 12 or 15. If you omit it,
- your link will be redirected to use the most recent release.
+ Other types of references to resources are described in
+ and
+ .
-
-
+
+
+ External links to &suse; documentation
- DEEP_LINK: the link that points to a specific chapter or section within a book
+ The &suse; documentation is hosted under
+ documentation.suse.com. This is the URL that must be provided
+ in all documents. The abbreviated URLs such as doc.suse.com
+ and docs.suse.com also work but must be avoided for SEO
+ reasons.
-
-
-
- Make sure you use html and not single-html. This
- is needed for SEO reasons.
-
-
- For example, the link
-
- points to the System requirements for &sle; Server High Availability Extension. To turn this link into an
- SP-independent link, you need to identify the different components first:
-
-
-
- PRODUCT is sle-ha
+ Make sure to use complete URLs instead of entities for an easy copy and
+ paste.
-
-
- MAJOR_RELEASE is 15 (no SP mentioned)
+ Most links in our documentation that goes to
+ documentation.suse.com refer to a specific product and
+ release. However, sometimes it makes sense to not
+ include the SP or even the major release. These are so-called
+ SP-independent links.
-
-
- DEEP_LINK is /html/SLE-HA-all/article-installation.html#sec-ha-inst-quick-req
+ The following reasons give you an idea when to use them:
-
-
-
- With the above parts, the redirection rules on our server allow expressing
- SP-independent links in several ways:
-
-
-
-
- https://documentation.suse.com/sle-ha-15/html/SLE-HA-all/article-installation.html#sec-ha-inst-quick-req
-
- Redirects to the most recent SP for the major release 15
-
-
-
- https://documentation.suse.com/sle-ha/html/SLE-HA-all/article-installation.html#sec-ha-inst-quick-req
-
- Redirects to the most recent major release, latest SP available
-
-
-
-
- If IDs have been changed between releases or SPs, this is what happens:
-
-
-
-
- If the hash part (everything after #) is not found, the browser will jump
- to the beginning of the file.
-
-
-
-
- If the file cannot be found (in our example, article-installation.html),
- the server will respond with a 404 error (file not found).
-
-
-
-
-
-
-
- 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 .
-
-
- All referenced image files must have a lowercase alphanumeric file name.
- When specifying figure names, follow the naming conventions at
- .
-
-
- Provide an appropriate image width using the width
- attribute. For both figure types, formal and informal, always add a
- textobject role="description"
- as in to provide an alternative text for the
- HTML output.
-
-
- Example of a figure
+
+
+
+ Your linked information is independent from any SP
+
+
+
+
+ You cannot or do not need to pick a specific SP
+
+
+
+
+ You want to link to the most recent SP without checking which one it
+ is
+
+
+
+
+ You want to support SEO where the most prominent SP is more important
+ than previous, older SPs
+
+
+
+
+ Make sure to follow this syntax:
+
+documentation.suse.com/<PRODUCT>[/<MAJOR_RELEASE>]/<DEEP_LINK>
+
+ The placeholders mean the following:
+
+
+
+
+ PRODUCT: the abbreviation of the product,
+ like sle for &sle;, sle-ha for &sle;
+ Server High Availability Extension, etc.
+
+
+
+
+ MAJOR_RELEASE: an optional major release
+ like 12 or 15. If you omit it, your link will be redirected to use
+ the most recent release.
+
+
+
+
+ DEEP_LINK: the link that points to a
+ specific chapter or section within a book
+
+
+
+
+ Make sure you use html and not
+ single-html. This is needed for SEO reasons.
+
+
+ For example, the link
+
+ points to the System requirements for &sle; Server High
+ Availability Extension. To turn this link into an SP-independent link,
+ you need to identify the different components first:
+
+
+
+
+ PRODUCT is sle-ha
+
+
+
+
+ MAJOR_RELEASE is 15 (no SP mentioned)
+
+
+
+
+ DEEP_LINK is
+ /html/SLE-HA-all/article-installation.html#sec-ha-inst-quick-req
+
+
+
+
+ With the above parts, the redirection rules on our server allow
+ expressing SP-independent links in several ways:
+
+
+
+
+ https://documentation.suse.com/sle-ha-15/html/SLE-HA-all/article-installation.html#sec-ha-inst-quick-req
+
+
+ Redirects to the most recent SP for the major release 15
+
+
+
+
+ https://documentation.suse.com/sle-ha/html/SLE-HA-all/article-installation.html#sec-ha-inst-quick-req
+
+
+ Redirects to the most recent major release, latest SP available
+
+
+
+
+
+ If IDs have been changed between releases or SPs, this is what happens:
+
+
+
+
+ If the hash part (everything after #) is not found, the browser
+ will jump to the beginning of the file.
+
+
+
+
+ If the file cannot be found (in our example,
+ article-installation.html), the server will respond with a 404
+ error (file not found).
+
+
+
+
+
+
+ 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
+ .
+
+
+ All referenced image files must have a lowercase alphanumeric file name.
+ When specifying figure names, follow the naming conventions at
+ .
+
+
+ Provide an appropriate image width using the
+ width attribute. For both figure types,
+ formal and informal, always add a textobject
+ role="description" as in to provide an
+ alternative text for the HTML output.
+
+
+ Example of a figure<figure xml:id="fig-picture">
<title>An interesting picture</title>
<mediaobject>
@@ -1202,264 +1203,268 @@ will be displayed in <emphasis role="bold">bold</emphasis>
</textobject>
</mediaobject>
</figure>
-
-
- Elements related to
- <tag class="emptytag">figure</tag>
-
-
-
- Element
- Web link
-
-
-
-
-
-
- <tag class="emptytag">figure</tag>
-
- Formal block element containing a
- title
- and a
- mediaobject.
-
-
-
-
-
-
-
-
-
- <tag class="emptytag">informalfigure</tag>
-
- Informal block element containing a
- mediaobject.
-
-
-
-
-
-
-
-
-
- <tag class="emptytag">mediaobject</tag>
-
- Block element containing one or more
- imageobject
- elements. Place additional textual descriptions inside
- textobject
- elements.
-
-
-
-
-
-
-
-
-
- <tag class="emptytag">imageobject</tag>
-
- Element containing
- imagedata
- and meta information about the image.
-
-
-
-
-
-
-
-
-
- <tag class="emptytag">imagedata</tag>
-
- Element that points to an external image file.
-
-
-
-
-
-
-
-
-
- <tag class="emptytag">textobject</tag>
-
- Element containing textual description of a media object as a
- fallback option.
-
-
-
-
-
-
-
-
-
-
- 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.
-
+
+
+ Elements related to <tag class="emptytag">figure</tag>
+
+
+
+ Element
+ Web link
+
+
+
+
+
+
+ <tag class="emptytag">figure</tag>
+
+ Formal block element containing a
+ title and a
+ mediaobject.
+
+
+
+
+
+
+
+
+
+ <tag class="emptytag">informalfigure</tag>
+
+ Informal block element containing a
+ mediaobject.
+
+
+
+
+
+
+
+
+
+ <tag class="emptytag">mediaobject</tag>
+
+ Block element containing one or more
+ imageobject elements. Place
+ additional textual descriptions inside
+ textobject elements.
+
+
+
+
+
+
+
+
+
+ <tag class="emptytag">imageobject</tag>
+
+ Element containing imagedata and
+ meta information about the image.
+
+
+
+
+
+
+
+
+
+ <tag class="emptytag">imagedata</tag>
+
+ Element that points to an external image file.
+
+
+
+
+
+
+
+
+
+ <tag class="emptytag">textobject</tag>
+
+ Element containing textual description of a media object as a
+ fallback option.
+
+
+
+
+
+
+
+
+
+
+ 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.
+
+
+
+ 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 .
+
+
+
+
+ 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.
+
+
+
+
-
- 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.
-
-
+
+ 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. Do not start the
+ definition with the term itself. Use lowercase for the term unless it is
+ a proper noun.
+
+
+ Where applicable, group your terms with the
+ glossdiv tag for higher ordering.
+
+
+ To support automatic alphabetical ordering in localized versions, use
+ glosslist so that glossary items are sorted
+ in alphabetical order by default.
+
+
+ Use cross-references in the following cases:
+
+
-
- Screenshots of individual application windows should be scaled to
- 75–99% page width.
-
+
+ To direct the reader to another glossary entry, use the
+ glosssee tag. This is helpful, for
+ example, when linking acronyms with their written out forms.
+
-
- Small windows such as message boxes should be scaled to
- 50–60% page width.
-
+
+ To provide the reader with additional information about related
+ glossary entries, use glossseealso.
+
-
-
-
-
- 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 .
-
-
-
-
- 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.
-
-
-
-
-
-
-
- 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. Do not start the definition with the term itself.
- Use lowercase for the term unless it is a proper noun.
-
- Where applicable, group your terms with the glossdiv
- tag for higher ordering.
- To support automatic alphabetical ordering in localized versions, use
- glosslist so that glossary items are sorted in alphabetical order by default.
-
- Use cross-references in the following cases:
-
-
-
- To direct the reader to another glossary entry, use the glosssee
- tag. This is helpful, for example, when linking acronyms with their written out forms.
-
-
-
- To provide the reader with additional information about related glossary entries,
- use glossseealso.
-
-
-
-
- The markup for a glossary entry is shown in
- .
-
-
- A typical example of a glossary
+
+
+ The markup for a glossary entry is shown in
+ .
+
+
+ A typical example of a glossary<glossary xmlns="http://docbook.org/ns/docbook" version="5.2">
<title>Glossary</title>
@@ -1490,525 +1495,463 @@ will be displayed in <emphasis role="bold">bold</emphasis>
</glossentry>
</glossary>
-
-
-
-
-
- Identifiers
-
-
-
- Always use an
- xml:id
- attribute in parts, chapters, appendixes, sections, figures, glossaries and
- examples. Identifiers can be used in other elements as well, for example,
- block elements, such as tables and procedures.
-
-
-
-
- In identifiers, only use lowercase basic Latin alphabetic and numeric
- characters and - (hyphen). Follow the regex pattern
- [\-0-9a-zA-Z]+. 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.
- Prefixes aid writers in creating logically named identifiers for
- elements.
- Use identifiers in accordance with .
-
-
-
- Do not add prefixes to identifiers for XML elements that are used to
- determine the name of HTML pages (such as section and chapter elements).
- Such exposure of identifiers can hurt SEO.
-
-
-
-
- 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.
-
-
-
-
-
- Examples of identifiers
+
+
+
+ Identifiers
+
+
+
+ Always use an xml:id attribute in parts,
+ chapters, appendixes, sections, figures, glossaries and examples.
+ Identifiers can be used in other elements as well, for example, block
+ elements, such as tables and procedures.
+
+
+
+
+ In identifiers, only use lowercase basic Latin alphabetic and numeric
+ characters and - (hyphen). Follow the regex
+ pattern [\-0-9a-zA-Z]+. 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. Prefixes aid writers in
+ creating logically named identifiers for elements. Use
+ identifiers in accordance with .
+
+
+
+ Do not add prefixes to identifiers for XML elements that are used
+ to determine the name of HTML pages (such as section and chapter
+ elements). Such exposure of identifiers can hurt SEO.
+
+
+
+
+ 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.
+
+
+
+
+
+ Examples of identifiersxml:id="pro-install-sles"
xml:id="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 install-yast.
-
-
- A figure in that section showing language selection could use the
- identifier fig-install-yast-language.
-
-
-
+
+
+
+
+ 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 install-yast.
+
+
+ A figure in that section showing language selection could use the
+ identifier fig-install-yast-language.
+
+
+
+
+ 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.
+
+
+
- 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.
-
-
-
- Do not rework identifiers in existing documentation, instead apply these
- rules to newly created documentation only.
-
-
- Abbreviations for different elements in an
- <tag class="attribute">xml:id</tag>
- attribute
-
-
-
- Element
- Prefix
-
-
-
-
-
- appendix
-
-
- No prefix
-
-
-
-
- book
-
-
- No prefix
-
-
-
-
- co
-
-
- co
-
-
-
-
- chapter
-
-
- No prefix
-
-
-
-
- example
-
-
- ex
-
-
-
-
- figure
-
-
- fig
-
-
-
-
- glossary
-
-
- No prefix
-
-
-
-
- glossterm
-
-
- gl
-
-
-
-
- itemizedlist
-
-
- il
-
-
- Only add an
- xml:id
- attribute when the list has a
- title
- element
-
-
-
-
-
-
- listitem
-
-
- li
-
-
-
-
- indexterm
-
-
- idx
-
-
- Only add when creating index ranges
-
-
-
-
-
-
- orderedlist
-
-
- ol
-
-
-
-
- part
-
-
- No prefix
-
-
-
-
- preface
-
-
- No prefix
-
-
-
-
- procedure
-
-
- pro
-
-
-
-
- qandaset,
+
+ Abbreviations for different elements in an <tag class="attribute">xml:id</tag> attribute
+
+
+
+ Element
+ Prefix
+
+
+
+
+ appendix
+
+ No prefix
+
+
+
+ book
+
+ No prefix
+
+
+
+ co
+
+ co
+
+
+
+ chapter
+
+ No prefix
+
+
+
+ example
+
+ ex
+
+
+
+ figure
+
+ fig
+
+
+
+ glossary
+
+ No prefix
+
+
+
+ glossterm
+
+ gl
+
+
+
+ itemizedlist
+
+ il
+
+
+ Only add an xml:id attribute when the list has a
+ title element
+
+
+
+
+
+ listitem
+
+ li
+
+
+
+ indexterm
+
+ idx
+
+
+ Only add when creating index ranges
+
+
+
+
+
+ orderedlist
+
+ ol
+
+
+
+ part
+
+ No prefix
+
+
+
+ preface
+
+ No prefix
+
+
+
+ procedure
+
+ pro
+
+
+
+ qandaset,
qandadiv,
qandaentry
-
-
- qa
-
-
-
-
- sect1,
+
+ qa
+
+
+
+ sect1,
sect2, etc.,
section
-
-
- No prefix
-
-
-
-
- set
-
-
- No prefix
-
-
-
-
- step
-
-
- st
-
-
-
-
- table
-
-
- tab
-
-
-
-
- topic
-
-
- No prefix
-
-
-
-
- variablelist
-
-
- vl
-
-
-
-
- varlistentry
-
-
- vle
-
-
-
-
-
-
-
-
- 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 .
-
-
-
-
- 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.
-
-
-
+
+ No prefix
+
+
+
+ set
+
+ No prefix
+
+
+
+ step
+
+ st
+
+
+
+ table
+
+ tab
+
+
+
+ topic
+
+ No prefix
+
+
+
+ variablelist
+
+ vl
+
+
+
+ varlistentry
+
+ vle
+
+
+
+
+
+
+
+ Lists
- 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.
+ &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
+ .
+
+
+
- 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.
+ 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.
+
+
+
+
+ Use a period after every list item that is a sentence. Do not use a
+ period after the items that are not complete sentences. Use either
+ all full sentences in your bullet lists or all fragments. Avoid a
+ mix.
+
+
+ Do not use commas and semicolons to end punctuation.
+
+
+
+
+ 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.
+
+
+
- Use a period after every list item that is a sentence. Do not use a period
- after the items that are not complete sentences. Use either all
- full sentences in your bullet lists or all fragments. Avoid a mix.
-
- Do not use commas and semicolons to end punctuation.
+ Never nest more than three lists within each other. Instead, restructure
+ the information using a combination of lists and running texts.
-
-
- 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.
+ To be able to reference untitled lists, use the
+ xreflabel attribute. For more information,
+ see .
-
-
-
- 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 .
-
-
- Elements related to lists
-
-
-
- Element
- Web link
-
-
-
-
-
-
- <tag class="emptytag">itemizedlist</tag>
-
- Block element for an unordered list. Contains multiple
- listitem
- elements.
-
-
-
-
-
-
-
-
-
- <tag class="emptytag">orderedlist</tag>
-
- Block element for a numbered list. Contains multiple
- listitem
- elements.
-
-
-
-
-
-
-
-
-
- <tag class="emptytag">variablelist</tag>
-
- Block element for a descriptive list. Contains multiple
- varlistentry
- elements.
-
-
-
-
-
-
-
-
-
- <tag class="emptytag">varlistentry</tag>
-
- Element within a
- variablelist
- that associates a
- term
- and a
- listitem.
-
-
-
-
-
-
-
-
-
- <tag class="emptytag">term</tag>
-
- Element whose content serves as the title of an element of a
- variablelist.
-
-
-
-
-
-
-
-
-
- <tag class="emptytag">listitem</tag>
-
- A single list element. To add text to this item, first add a
- para
- element.
-
-
-
-
-
-
-
-
-
-
- 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 of an itemized list (source)
+
+ Elements related to lists
+
+
+
+ Element
+ Web link
+
+
+
+
+
+
+ <tag class="emptytag">itemizedlist</tag>
+
+ Block element for an unordered list. Contains multiple
+ listitem elements.
+
+
+
+
+
+
+
+
+
+ <tag class="emptytag">orderedlist</tag>
+
+ Block element for a numbered list. Contains multiple
+ listitem elements.
+
+
+
+
+
+
+
+
+
+ <tag class="emptytag">variablelist</tag>
+
+ Block element for a descriptive list. Contains multiple
+ varlistentry elements.
+
+
+
+
+
+
+
+
+
+ <tag class="emptytag">varlistentry</tag>
+
+ Element within a variablelist
+ that associates a term and a
+ listitem.
+
+
+
+
+
+
+
+
+
+ <tag class="emptytag">term</tag>
+
+ Element whose content serves as the title of an element of a
+ variablelist.
+
+
+
+
+
+
+
+
+
+ <tag class="emptytag">listitem</tag>
+
+ A single list element. To add text to this item, first add a
+ para element.
+
+
+
+
+
+
+
+
+
+
+ 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 of an itemized list (source)<para>
The following operating systems are supported:
</para>
@@ -2024,38 +1967,37 @@ xml:id="tab-install-source"
</para>
</listitem>
</itemizedlist>
-
-
- Example of an itemized list (output)
-
- The following operating systems are supported:
-
-
-
-
- Linux, Kernel 2.4 and newer
-
-
-
+
+
+ Example of an itemized list (output)
+
+ The following operating systems are supported:
+
+
+
+
+ Linux, Kernel 2.4 and newer
+
+
+
+
+ FreeBSD 7 and newer
+
+
+
+
+
+
+ Ordered lists
- FreeBSD 7 and newer
+ 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 . If order is
+ not relevant, use an itemized list or a variable list.
-
-
-
-
-
- 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
- .
- If order is not relevant, use an itemized list or a variable list.
-
-
- Example of an ordered list (source)
+
+ Example of an ordered list (source)<para>
Before installing, make sure of the following:
</para>
@@ -2066,375 +2008,361 @@ xml:id="tab-install-source"
</para>
</listitem>
<listitem>
- <para>
- The latest security updates are installed.
- If you are in doubt, run an online update.
- </para>
- </listitem>
-</orderedlist>
-
-
- 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.
-
-
-
-
-
-
- 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 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 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.
-
-
-
-
-
-
-
-
-
- Keys and key combinations
-
- Capitalize all keys as printed on a standard keyboard. Capitalize all letter
- keys. To refer to a capitalized character,
- use 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 , use the
- function
- attribute with the appropriate value. When using the
- function
- attribute, make the tag self-closing—DocBook's language files
- will insert key names automatically. This simplifies both your work and
- the work of translators.
-
-
- For more information about creating cross-references, see
- .
-
-
- Example of a key
-To create a screenshot, press <keycap>Print Screen</keycap>.
-
-
- Example of a keyboard combination
-To save a file, press
-<keycombo><keycap function="control"/><keycap>S</keycap></keycombo>.
-
-
- Elements related to
- <tag class="emptytag">keycap</tag>
-
-
-
- Element
- Web link
-
-
-
-
-
-
- <tag class="emptytag">keycombo</tag>
-
- Inline element containing multiple
- keycap
- elements that together make up a key combination.
-
-
-
-
-
-
-
-
-
- <tag class="emptytag">keycap</tag>
-
- Inline element to mark up a single key. Contains either the key
- labels text inside it or is self-closing and has a
- function
- attribute with one of the following values:
-
-
-
-
-
- alt
-
-
-
-
- backspace
-
-
-
-
- command
-
-
-
-
- control
-
-
-
-
- delete
-
-
-
-
- down
-
-
-
-
- end
-
-
-
-
- enter
-
-
-
-
- escape
-
-
-
-
- home
-
-
-
-
- insert
-
-
-
-
- left
-
-
-
-
- meta
- (also known as Win, Windows or
- Super)
-
-
-
-
- option
- (macOS only)
-
-
-
-
- pagedown
-
-
-
-
- pageup
-
-
-
-
- right
-
-
-
-
- shift
-
-
-
-
- space
-
-
-
-
- tab
-
-
-
-
- up
-
-
-
-
-
-
-
-
-
-
-
-
-
- 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 about writing headlines, see
- .
-
-
-
-
- Procedures
-
- Use procedures to describe sequential tasks. A procedure consists of the
- following elements and attributes:
-
-
-
+ <para>
+ The latest security updates are installed.
+ If you are in doubt, run an online update.
+ </para>
+ </listitem>
+</orderedlist>
+
+
+ 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.
+
+
+
+
+
+
+ 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 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 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.
+
+
+
+
+
+
+
+
+ Keys and key combinations
- An
- xml:id
- attribute.
+ Capitalize all keys as printed on a standard keyboard. Capitalize all
+ letter keys. To refer to a capitalized character, use
+ Z, for
+ example. Introduce this convention by means of the Typographical
+ Conventions section of the introduction.
-
-
- A title.
+ To mark up key combinations, use keycombo as
+ a wrapper for multiple keycap elements.
+ Separators between keycap elements are then
+ created automatically.
-
-
- 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 a key is listed in , 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.
-
-
- If there are preconditions or prerequisites, add them as a second
- paragraph after the introduction.
+ For more information about creating cross-references, see
+ .
-
-
+
+ Example of a key
+To create a screenshot, press <keycap>Print Screen</keycap>.
+
+
+ Example of a keyboard combination
+To save a file, press
+<keycombo><keycap function="control"/><keycap>S</keycap></keycombo>.
+
+
+ Elements related to <tag class="emptytag">keycap</tag>
+
+
+
+ Element
+ Web link
+
+
+
+
+
+
+ <tag class="emptytag">keycombo</tag>
+
+ Inline element containing multiple
+ keycap elements that together
+ make up a key combination.
+
+
+
+
+
+
+
+
+
+ <tag class="emptytag">keycap</tag>
+
+ Inline element to mark up a single key. Contains either the
+ key labels text inside it or is self-closing and has a
+ function attribute with one of
+ the following values:
+
+
+
+
+
+ alt
+
+
+
+
+ backspace
+
+
+
+
+ command
+
+
+
+
+ control
+
+
+
+
+ delete
+
+
+
+
+ down
+
+
+
+
+ end
+
+
+
+
+ enter
+
+
+
+
+ escape
+
+
+
+
+ home
+
+
+
+
+ insert
+
+
+
+
+ left
+
+
+
+
+ meta (also known as
+ Win, Windows or
+ Super)
+
+
+
+
+ option (macOS only)
+
+
+
+
+ pagedown
+
+
+
+
+ pageup
+
+
+
+
+ right
+
+
+
+
+ shift
+
+
+
+
+ space
+
+
+
+
+ tab
+
+
+
+
+ up
+
+
+
+
+
+
+
+
+
+
+
+
+ Outline levels and sectioning
- Short, simple steps and, if necessary, substeps describing the actions
- to be performed. See also .
+ 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.
-
-
-
- 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 of a procedure (source)
+
+ Provide at least one paragraph of introductory information directly
+ within each section.
+
+
+ Do not create lone subsections. A lone subsection is a section that is
+ the only subsection of its parent section.
+
+
+ For more information about writing headlines, see
+ .
+
+
+
+ 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
+ .
+
+
+
+
+ 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 of a procedure (source)<procedure xml:id="pro-procedure">
<title>Example of a procedure</title>
<para>
@@ -2458,215 +2386,214 @@ xml:id="tab-install-source"
</para>
</step>
</procedure>
-
-
- Example of a procedure (output)
-
- To add a new user to the system, perform the following steps:
-
-
-
- In the YaST window, click
- User and group management.
-
-
-
-
- To open the Add a new user dialog, click
- Add.
-
-
-
-
- Type in the user name and click Create.
-
-
-
-
- Elements related to
- <tag class="emptytag">procedure</tag>
-
-
-
- Element
- Web link
-
-
-
-
-
-
- <tag class="emptytag">procedure</tag>
-
- Block element containing a
- title
- (optional) and multiple
- step
- elements.
-
-
-
-
-
-
-
-
-
- <tag class="emptytag">step</tag>
-
- Element signifying a single unit of action. Usually contains a
- para
- element, but can also house a
- substeps
- element.
-
-
-
-
-
-
-
-
-
- <tag class="emptytag">substeps</tag>
-
- Element containing multiple, subordinate
- step
- elements.
-
-
-
-
-
-
-
-
-
-
-
-
- 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:
-
+
+
+ Example of a procedure (output)
+
+ To add a new user to the system, perform the following steps:
+
+
+
+ In the YaST window, click
+ User and group management.
+
+
+
+
+ To open the Add a new user dialog, click
+ Add.
+
+
+
+
+ Type in the user name and click Create.
+
+
+
+
+ Elements related to <tag class="emptytag">procedure</tag>
+
+
+
+ Element
+ Web link
+
+
+
+
+
+
+ <tag class="emptytag">procedure</tag>
+
+ Block element containing a title
+ (optional) and multiple step
+ elements.
+
+
+
+
+
+
+
+
+
+ <tag class="emptytag">step</tag>
+
+ Element signifying a single unit of action. Usually contains
+ a para element, but can also
+ house a substeps element.
+
+
+
+
+
+
+
+
+
+ <tag class="emptytag">substeps</tag>
+
+ Element containing multiple, subordinate
+ step elements.
+
+
+
+
+
+
+
+
+
+
+
+ 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.
-
-
-
- Profiling
-
- Profiling is convenient for the creation of consistent documentation
- across different products or product lines. This is especially beneficial
- when similar products share a considerable amount of features, with only
- a few differences. Instead of maintaining separate documentation for
- each product, you can share most of the XML source code and only vary text
- snippets where necessary. In DocBook XML files, you can mark some elements
- as conditional by using profiling attributes. Specify which conditions
- apply to the output when processing the files to generate output. The style sheets
- will then include or exclude the marked text, according to the conditions.
- Profiling allows you to keep both common and product-specific content in
- one XML file and select at production time which information to include in
- the output.
- If you need to use profiling in your writing, adhere to the following guidelines:
-
-
-
- Identify different variants that you want to apply to the general piece of text
- and assign clear and short identifiers to them, sticking to lowercase.
- These identifiers act as aliases for longer products or
- deliverables.
- If you want to apply more than one identifier to an element, separate them
- with a semicolon.
-
-
-
-
- Select one or more profiling attributes and add them to the text snippets that
- are conditional. The tagged snippets will only be included in the output if
- all required conditions are fulfilled. In most cases, the attribute to use is
- os. For different processor architectures, use
- arch. The general-purpose attribute is condition.
-
-
-
- Mark the variants in your text with the relevant identifiers. Any content that
- is valid for all conditions does not need any profiling attributes. The
- respective content will always be included in the output formats generated
- from the XML sources.
-
-
-
- Create a different DC file for each variant. Add the respective profiling
- variable and its value to the DC file.
-
-
-
- DocBook allows you to use multiple profiling attributes to handle more
- complex scenarios. For example, if you have conditions for architecture
- (arch) and operating system (os),
- you can create different versions of a document for different combinations
- of these conditions, as shown in .
-
-
-
- Single profiling with the attribute <tag class="attribute">os</tag>
-
+
+
+ Profiling
+
+ Profiling is convenient for the creation of consistent documentation
+ across different products or product lines. This is especially beneficial
+ when similar products share a considerable amount of features, with only
+ a few differences. Instead of maintaining separate documentation for each
+ product, you can share most of the XML source code and only vary text
+ snippets where necessary. In DocBook XML files, you can mark some
+ elements as conditional by using profiling attributes. Specify which
+ conditions apply to the output when processing the files to generate
+ output. The style sheets will then include or exclude the marked text,
+ according to the conditions.
+
+
+ Profiling allows you to keep both common and product-specific content in
+ one XML file and select at production time which information to include
+ in the output.
+
+
+ If you need to use profiling in your writing, adhere to the following
+ guidelines:
+
+
+
+
+ Identify different variants that you want to apply to the general
+ piece of text and assign clear and short identifiers to them,
+ sticking to lowercase. These identifiers act as
+ aliases for longer products or deliverables. If you
+ want to apply more than one identifier to an element, separate them
+ with a semicolon.
+
+
+
+
+ Select one or more profiling attributes and add them to the text
+ snippets that are conditional. The tagged snippets will only be
+ included in the output if all required conditions are fulfilled. In
+ most cases, the attribute to use is os. For
+ different processor architectures, use arch. The
+ general-purpose attribute is condition.
+
+
+
+
+ Mark the variants in your text with the relevant identifiers. Any
+ content that is valid for all conditions does not need any profiling
+ attributes. The respective content will always be included in the
+ output formats generated from the XML sources.
+
+
+
+
+ Create a different DC file for each variant. Add the respective
+ profiling variable and its value to the DC file.
+
+
+
+
+ DocBook allows you to use multiple profiling attributes to handle
+ more complex scenarios. For example, if you have conditions for
+ architecture (arch) and operating system
+ (os), you can create different versions of a
+ document for different combinations of these conditions, as shown in
+ .
+
+
+
+
+ Single profiling with the attribute <tag class="attribute">os</tag>
+
<?xml version="1.0" encoding="UTF-8"?>
[...]
<phrase os="sles;sled">Note that the official update repository is only
available after registering your SUSE Linux Enterprise Server installation.</phrase>
-
-
-
- DC file with profiling for SLES
-
+
+
+ DC file with profiling for SLES
+
MAIN="MAIN.SLEDS.xml"
ROOTID=book-administration
## Profiling
PROFOS="sles"
...
-
-
-
- Multiple profiling with attributes <tag class="attribute">os</tag> and <tag class="attribute">arch</tag>
-
+
+
+ Multiple profiling with attributes <tag class="attribute">os</tag> and <tag class="attribute">arch</tag>
+
<?xml version="1.0" encoding="UTF-8"?>
[...]
Entire hard disks are listed as devices without numbers, such as
<filename>/dev/sda</filename><phrase arch="zseries;aarch64" os="sles;sled;slemicro"></phrase>.
-
-
-
-
-
- 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
- .
-
-
- 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 .
-
-
- 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 of a questions-and-answers section (source)
+
+
+
+ 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
+ .
+
+
+ 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 .
+
+
+ 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 of a questions-and-answers section (source)<qandaset>
<title>Example of a questions-and-answers section</title>
<qandaentry>
@@ -2696,280 +2623,293 @@ Entire hard disks are listed as devices without numbers, such as
</answer>
</qandaentry>
</qandaset>
-
-
- Example of a questions-and-answers section (output)
-
-
-
- How can I check if the product was correctly installed?
-
-
-
-
- Open the log file. Look for entries starting with
- Failed.
-
-
-
-
-
-
- Why does the error Not enough disk space occur
- during installation?
-
-
-
-
- There are less than 4 GB of space available on the selected partition.
-
-
-
-
-
- Elements related to
- <tag class="emptytag">qandaset</tag>
-
-
-
- Element
- Web link
-
-
-
-
-
-
- <tag class="emptytag">qandaset</tag>
-
- Block element containing a
- title
- (optional) and multiple
- qandaentry
- or
- qandadiv
- elements.
-
-
-
-
-
-
-
-
-
- <tag class="emptytag">qandadiv</tag>
-
- Block element containing a
- title
- and multiple
- qandaentry
- elements. Used to structure a
- qandaset
- into smaller topical subsections.
-
-
-
-
-
-
-
-
-
- <tag class="emptytag">qandaentry</tag>
-
- Block element used to associate a
- question
- with an
- answer.
-
-
-
-
-
-
-
-
-
- <tag class="emptytag">question</tag>
-
- Block element containing the question. Use a single
- para
- element inside.
-
-
-
-
-
-
-
-
-
- <tag class="emptytag">answer</tag>
-
- Block element containing the answer. Use
- para
- elements inside.
-
-
-
-
-
-
-
-
-
-
-
-
- References to other external resources
- sknorr, 2014-01-22: This section could probably use a better
+
+
+ Example of a questions-and-answers section (output)
+
+
+
+ How can I check if the product was correctly installed?
+
+
+
+
+ Open the log file. Look for entries starting with
+ Failed.
+
+
+
+
+
+
+ Why does the error Not enough disk space occur
+ during installation?
+
+
+
+
+ There are less than 4 GB of space available on the selected
+ partition.
+
+
+
+
+
+ Elements related to <tag class="emptytag">qandaset</tag>
+
+
+
+ Element
+ Web link
+
+
+
+
+
+
+ <tag class="emptytag">qandaset</tag>
+
+ Block element containing a title
+ (optional) and multiple
+ qandaentry or
+ qandadiv elements.
+
+
+
+
+
+
+
+
+
+ <tag class="emptytag">qandadiv</tag>
+
+ Block element containing a title
+ and multiple qandaentry elements.
+ Used to structure a qandaset into
+ smaller topical subsections.
+
+
+
+
+
+
+
+
+
+ <tag class="emptytag">qandaentry</tag>
+
+ Block element used to associate a
+ question with an
+ answer.
+
+
+
+
+
+
+
+
+
+ <tag class="emptytag">question</tag>
+
+ Block element containing the question. Use a single
+ para element inside.
+
+
+
+
+
+
+
+
+
+ <tag class="emptytag">answer</tag>
+
+ Block element containing the answer. Use
+ para elements inside.
+
+
+
+
+
+
+
+
+
+
+
+ References to other external resources
+ sknorr, 2014-01-22: This section could probably use a better
structure instead of this mishmash.
-
- 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 .
-
-
- Reference man pages and info pages in this format:
-
-
-
- the man page of command
+ 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
+ .
-
-
- the info page of command
+ 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. For example, use (man 9
+ command).
-
-
-
- In a situation where the category of the page is needed, append the
- category in parentheses. For example, use (man 9
- command).
- To learn more about subcommands, see the man page of
<command>command</command>.
-
- Insert references to external (non-&suse;) physical books in the format
- Title by Author (ISBN #00000000). Inclusion of the ISBN is
- optional. Place the title in a
- citetitle
- element. For example:
-
+
+ Insert references to external (non-&suse;) physical books in the format
+ Title by Author (ISBN #00000000). Inclusion of the ISBN is
+ optional. Place the title in a citetitle
+ element. For example:
+ <citetitle>Lorem Ipsum</citetitle> by Dolores S. Amet
(ISBN 0-246-52044-7) is a useful guide.
-Note that citetitle is not translated.
-
- As an author, where possible, provide language-specific references to
- translators in XML comments (see also ).
- 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
- and .
-
-
-
-
- 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.
-
-
- Typical use cases of tables include:
-
-
- Lookup tables for specific information
-
- Whenever users need to check for data that applies to them,
- create lookup tables. For example, use a table to sum up system requirements.
-
-
-
- Matrix tables
-
- Whenever users need to quickly check whether a specific combination
- of options works or not. For example, use a matrix table to visualize supported
- combinations or update options.
-
-
-
-
- As there are use cases for tables, there are cases when not
- to use tables:
-
-
-
- Value and description pairs are better handled by means of a descriptive list.
-
-
- Wordy explanations or descriptions should not be used in tables.
-
-
- Complex layout constructs (screens, code) should not be used in tables.
-
-
-
- Some general style tips for tables:
-
-
- Structure the table to have more rows than columns
-
- Readers prefer to skim for information that is aligned vertically. When designing
- tables, consider swapping rows and columns to provide a consistent
- user experience.
-
-
- Narrow down columns
-
- Compress the data in your table as much as you possibly can. Table
- cells with less content are more easily parsed by readers. Consider using
- icons, adding repeating words into column titles, or using shorter number
- formats.
-
-
- Use colors to lead the reader's eyes
-
- Use colors to make the information stand out. If you just want to
- highlight small bits, use bright colors. If you need to color entire cells,
- use pastels. This option should only be used with matrix type tables.
-
-
-
- Use striped rows
-
- Color every second row in light gray to make sure readers do not
- accidentally slip between lines. This should be the default for long
- tables. Do not use striped rows in matrix type tables with additional cell background coloring.
- You may also consider disabling striped rows for short tables to not confuse readers.
-
-
-
-
-
-
-
- Example of a table (source)
+
+ Note that citetitle is not translated.
+
+
+ As an author, where possible, provide language-specific references to
+ translators in XML comments (see also ).
+ 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
+ and .
+
+
+
+ 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.
+
+
+ Typical use cases of tables include:
+
+
+
+ Lookup tables for specific information
+
+
+ Whenever users need to check for data that applies to them, create
+ lookup tables. For example, use a table to sum up system
+ requirements.
+
+
+
+
+ Matrix tables
+
+
+ Whenever users need to quickly check whether a specific combination
+ of options works or not. For example, use a matrix table to
+ visualize supported combinations or update options.
+
+
+
+
+
+ As there are use cases for tables, there are cases when
+ not to use tables:
+
+
+
+
+ Value and description pairs are better handled by means of a
+ descriptive list.
+
+
+
+
+ Wordy explanations or descriptions should not be used in tables.
+
+
+
+
+ Complex layout constructs (screens, code) should not be used in
+ tables.
+
+
+
+
+ Some general style tips for tables:
+
+
+
+ Structure the table to have more rows than columns
+
+
+ Readers prefer to skim for information that is aligned vertically.
+ When designing tables, consider swapping rows and columns to
+ provide a consistent user experience.
+
+
+
+
+ Narrow down columns
+
+
+ Compress the data in your table as much as you possibly can. Table
+ cells with less content are more easily parsed by readers. Consider
+ using icons, adding repeating words into column titles, or using
+ shorter number formats.
+
+
+
+
+ Use colors to lead the reader's eyes
+
+
+ Use colors to make the information stand out. If you just want to
+ highlight small bits, use bright colors. If you need to color
+ entire cells, use pastels. This option should only be used with
+ matrix type tables.
+
+
+
+
+
+ Use striped rows
+
+
+ Color every second row in light gray to make sure readers do not
+ accidentally slip between lines. This should be the default for
+ long tables. Do not use striped rows in matrix type tables with
+ additional cell background coloring. You may also consider
+ disabling striped rows for short tables to not confuse readers.
+
+
+
+
+
+
+ Example of a table (source)<informaltable>
<tgroup cols="2">
<thead>
@@ -2990,225 +2930,210 @@ Entire hard disks are listed as devices without numbers, such as
</tbody>
</tgroup>
</informaltable>
-
-
- Example of a table (output)
-
-
-
-
- File System
- Maximum File Size
-
-
-
-
- Ext2 (1 kB block size)
- 16 GB
-
-
- Ext2 (2 kB block size)
- 256 GB
-
-
-
-
-
-
-
-
-
- Elements related to
- <tag class="emptytag">table</tag>
-
-
-
- Element
- Web link
-
-
-
-
-
-
- <tag class="emptytag">table</tag>
-
- Formal block element that contains a
- title
- and a
- tgroup
- element.
-
-
-
-
-
-
-
-
-
- <tag class="emptytag">informaltable</tag>
-
- Informal block element that contains a
- tgroup
- element.
-
-
-
-
-
-
-
-
-
- <tag class="emptytag">tgroup</tag>
-
- Wrapper for the content of a table. Can contain one or more
- colspec
- and one
- thead. Contains a
- tbody
-
-
-
-
-
-
-
-
-
- <tag class="emptytag">colspec</tag>
-
- Element to define common properties for a column.
-
-
-
-
-
-
-
-
-
- <tag class="emptytag">thead</tag>
-
- Element to mark up a table head. Contains a
- row
- element.
-
-
-
-
-
-
-
-
-
- <tag class="emptytag">tbody</tag>
-
- Element to mark up the table body. Contains multiple
- row
- elements.
-
-
-
-
-
-
-
-
-
- <tag class="emptytag">row</tag>
-
- Element to mark up a table row. Contains multiple
- entry
- elements.
-
-
-
-
-
-
-
-
-
- <tag class="emptytag">entry</tag>
-
- Element to mark up a table cell.
-
-
-
-
-
-
-
-
-
-
-
-
- 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 about language aspects, see
- .
-
-
- Example of a single user interface item
+
+
+ Example of a table (output)
+
+
+
+
+ File System
+ Maximum File Size
+
+
+
+
+ Ext2 (1 kB block size)
+ 16 GB
+
+
+ Ext2 (2 kB block size)
+ 256 GB
+
+
+
+
+
+
+ Elements related to <tag class="emptytag">table</tag>
+
+
+
+ Element
+ Web link
+
+
+
+
+
+
+ <tag class="emptytag">table</tag>
+
+ Formal block element that contains a
+ title and a
+ tgroup element.
+
+
+
+
+
+
+
+
+
+ <tag class="emptytag">informaltable</tag>
+
+ Informal block element that contains a
+ tgroup element.
+
+
+
+
+
+
+
+
+
+ <tag class="emptytag">tgroup</tag>
+
+ Wrapper for the content of a table. Can contain one or more
+ colspec and one
+ thead. Contains a
+ tbody
+
+
+
+
+
+
+
+
+
+ <tag class="emptytag">colspec</tag>
+
+ Element to define common properties for a column.
+
+
+
+
+
+
+
+
+
+ <tag class="emptytag">thead</tag>
+
+ Element to mark up a table head. Contains a
+ row element.
+
+
+
+
+
+
+
+
+
+ <tag class="emptytag">tbody</tag>
+
+ Element to mark up the table body. Contains multiple
+ row elements.
+
+
+
+
+
+
+
+
+
+ <tag class="emptytag">row</tag>
+
+ Element to mark up a table row. Contains multiple
+ entry elements.
+
+
+
+
+
+
+
+
+
+ <tag class="emptytag">entry</tag>
+
+ Element to mark up a table cell.
+
+
+
+
+
+
+
+
+
+
+
+ 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 about language aspects, see
+ .
+
+
+ Example of a single user interface itemTo open a file, click <guimenu>Open</guimenu>.
-
-
- Example of nested user interface items
+
+
+ Example of nested user interface itemsTo save a file, use
<menuchoice><guimenu>File</guimenu><guimenu>Save</guimenu></menuchoice>.
-
-
- Elements related to
- <tag class="emptytag">guimenu</tag>
-
-
-
- Element
- Web link
-
-
-
-
-
-
- <tag class="emptytag">menuchoice</tag>
-
- Inline element containing multiple
- guimenu
- elements that together form a nested menu structure.
-
-
-
-
-
-
-
-
-
- <tag class="emptytag">guimenu</tag>
-
- Inline element to mark up a single user interface item.
-
-
-
-
-
-
-
-
-
-
+
+
+ Elements related to <tag class="emptytag">guimenu</tag>
+
+
+
+ Element
+ Web link
+
+
+
+
+
+
+ <tag class="emptytag">menuchoice</tag>
+
+ Inline element containing multiple
+ guimenu elements that together
+ form a nested menu structure.
+
+
+
+
+
+
+
+
+
+ <tag class="emptytag">guimenu</tag>
+
+ Inline element to mark up a single user interface item.
+
+
+
+
+
+
+
+
+