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

Follow these rules when writing admonitions:

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

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.

Callouts allow annotating examples, such as configuration files or commands with many options. Add callout elements directly after the part of a verbatim block that you want to annotate. Do not try to align them above the part of a screen to annotate. Do not use more than ten callouts per example.

See also Section 8.6, “Examples”.

[source]
----
color white/blue black/light-gray <1>
default 0 <2>
----
<1> Colors of the boot loader menu.
<1> Defines the preselected option.

color white/blue black/light-gray 1
default 0 2

When dealing with user input and system output shorter than 30 characters, enclose it with single backticks (`). In all other cases, close the current paragraph and enclose the user input and/or system output in a verbatim block. See also Section 8.6, “Examples”.

When using a stand-alone command elements outside of a verbatim block, do not use prompt elements before or within them. For more information about prompts, see Section 8.3.3, “Prompts”.

To start LibreOffice from the command line, use
`loffice`.

To start LibreOffice Writer from the command line, use
`loffice --writer`.

Find the log file `configuration.xml`
in the directory `/etc/sysconfig`.

8.3.3 Prompts #

 

When documenting commands entered into Bash with a verbatim block, always prefix them with a prompt marked up this way:

> ls

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 Chapter 4, Names of example items.

Whenever you provide commands in a verbatim block, 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:

# yast

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 (attributes) for the prompts used in your documentation. Doc Kit repository contains entities for user, root and sudo prompts. For more information, see Section 9.1, “Entities”.

Tip

Verbatim blocks normally do not expand attributes with their values. To use attributes for prompts in a verbatim block, add subs="+attributes" in its header:

[source,subs="+attributes"]
----
{prompt_root}zypper upgrade
----

To select another display manager, start the YaST system configuration editor
and change the value of `DISPLAYMANAGER`.

Use double angled brackets <<ID>> when referring to an appendix, chapter, example, figure, part, preface, section, table or question and answer set. The element referenced needs to have an identifier (ID). Create identifiers to reference from cross-references using the rules under Section 8.11, “Identifiers”. Note that a cross-reference 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 Section 8.18, “References to other external resources” and Section 8.7, “External links”.

[#sec-cross-reference,reftext=Custom cross reference]
=== Cross-references
Use double angled brackets for xrefs ...
See <<sec-cross-reference>>.

Keep in mind the following cases where listing cross-references is discouraged and must be avoided:

Do not prefix or suffix cross-references with text labels such as “appendix,” “chapter,” “table,” or “figure.” Such labels are generated automatically.

Where possible, indicate stress with language only. If that is not possible, surround the phrase with underscores (_phrase_) to indicate stress.

Where added emphasis is needed, enclose the phrase in a single pair of asterisks (*phrase*). To emphasize characters within a word, use a pair of double asterisks (char**act**ers).

 This will be displayed in _italics_.
This will be displayed in *bold*.

Use examples to illustrate complex processes. The rules established in Section 8.9.1, “Graphics” also apply to examples.

Examples usually contain source code blocks. Additionally, there can be callouts and explanatory text.

Always give examples a title and an identifier.

For more information about screen environments, see Section 8.3.4, “Verbatim blocks”. For more information about displaying computer input and output, see Section 8.3, “Command-line input and command-line output”. To annotate examples, use callouts. Callouts are described in Section 8.2, “Callouts”.

[#ex-example]
.Example of an example
====
[source]
----
tux > ps -xa

5170 ?        S      0:00 kdeinit: khotkeys
5172 ?        S      0:02 kdeinit: kdesktop
5174 ?        S      0:04 kdeinit: kicker
----
====

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:

In certain cases, product managers request avoiding all or selected external links to avoid issues for customers impacted by restrictive firewall rules.

Common URL schemes are automatically detected from the text and converted into links. To disable this conversion, use a single backlash (\) in front of the link (\https://example.org). To use a custom link title, use a URL macro:

Ask questions in the https://example.com[An example title]

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:

Do not 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 Section 5.1, “Books”.

To mark up multiple links, insert them into an unordered list. 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 Section 8.12.1, “Itemized lists”.

Where possible, provide translators with localized versions of links in the comments of the source file.

Other types of references to resources are described in Section 8.4, “Cross-references” and Section 8.18, “References to other external resources”.

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:

Make sure to follow this syntax:

documentation.suse.com/<PRODUCT>[/<MAJOR_RELEASE>]/<DEEP_LINK>

The placeholders mean the following:

Make sure you use html and not single-html. This is needed for SEO reasons.

For example, the link https://documentation.suse.com/sle-ha/15-SP3/html/SLE-HA-all/article-installation.html#sec-ha-inst-quick-req/ points to the “System requirements” for SUSE Linux Enterprise Server High Availability Extension. To turn this link into an SP-independent link, you need to identify the different components first:

With the above parts, the redirection rules on our server allow expressing SP-independent links in several ways:

Note

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

Use the image macro to insert an image. Always supply an identifier, title, appropriate width and alternative text to the image.

All referenced image files must have a lowercase alphanumeric file name. When specifying figure names, follow the naming conventions at https://github.com/SUSE/doc-modular/blob/main/templates/README.md.

.An interesting picture
[#fig-picture]
image::sunset.jpg[Cat chasing Geeko,200]

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.

Tip

To keep definitions consistent, check SUSE's official terminology database called TermWeb (https://suse.termweb.eu/search/terms). It contains company-specific terminology in English and all our supported languages. When defining a term, consult TermWeb first to ensure you are using the approved wording and preferred spelling.

You can include a glossary in an article, book and book part by setting the glossary style on a section.

The markup for a glossary entry is shown in Example 8.8, “A typical example of a glossary”.

[glossary]
== Glossary

[glossary]
AsciiDoc:: a lightweight markup language used to write structured documents in
  plain text.
DocBook:: an XML-based markup language designed for writing structured technical
  documentation.

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

SUSE documentation uses the following types of lists:

Follow these rules when creating or editing lists:

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, insert a label in the cross reference. For more information, see Section 8.4, “Cross-references”.

The following operating systems are supported:
* Linux, Kernel 2.4 and newer
* FreeBSD 7 and newer

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.

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.

To enter keys and their combinations in the text, use the keyboard macro: kbd:[key] Capitalize all keys as printed on a standard keyboard. Capitalize all letter keys.

To mark up key combinations, enter multiple keys concatenated with +, such as kbd:[key+key+key+...].

Tip

If the last key is a backslash (\), it must be followed by a space. Otherwise the processor will not recognize the macro. If one of the keys is a closing square bracket (]), it must be preceded by a backslash. Without the backslash escape, the macro will end prematurely.

To create a screenshot, press kbd:[Print Screen].

To save a file, press kbd:[Ctrl+S]

Create sections by inserting = characters in front of their titles. The number of = characters determines the depth of the section in the document structure. Do not go deeper than section level 3. Instead, create a flatter structure in which more elements are visible at a glance.

= Document Title (Level 0)

== Level 1 Section Title

=== Level 2 Section Title

==== Level 3 Section Title

== Another Level 1 Section Title

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 Section 7.10, “Headings”.

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

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

[#pro-procedure]
.Example of a procedure

To add a new user to the system, perform the following steps:
. In the YaST window, click btn:[User and group management].
. To open the btn:[Add a new user] dialog, click btn:[Add].
. Type in the user name and click btn:[Create].

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 source code and only vary text snippets where necessary. When profiling, you can mark specific elements as conditional and 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 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:

[...]
ifeval::["{prof-os}" == "sles"]
Note that the official update repository is only available after registering
your SLES installation.
endif::[]

MAIN="MAIN.SLEDS.xml"
ROOTID=book-administration
    
## Profiling
PROFOS="sles"
...

MAIN=book.adoc
# Profiling
PROFOS="sles"
...

Use question and answer sections to present information about troubleshooting or commonly asked questions about a product. Never use question and answer sections to explain trivia, such as how a product got its name. Keep your audience in mind. See also Chapter 2, Writing technical documentation.

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 question and answer section. See also Section 8.4, “Cross-references”.

[qanda]
.Example of a question and answer section
How can I check if the product was correctly installed?::
Open the log file.
Look for entries starting with `Failed`.

Why does the error `N` occur during installation?::
There are less than 4 GB of space available on the selected partition.

To reference file names, use a monospaced `filename` without the file:// prefix. To reference e-mail addresses, use the clickable mailto:john@example.com[] macro or unclickable monospaced `john@example.com`. See also Section 8.3.2, “File names”.

Reference man pages and info pages in this format:

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

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 an italics snippet. For example:

_Lorem Ipsum<_ by Dolores S. Amet
(ISBN 0-246-52044-7) is a useful guide.

As an author, where possible, provide language-specific references to translators in comments. As a translator, look for corresponding language-specific resources where none have been provided. For URLs, provide only the language-specific version of a site. Use the English version as a fallback. For books, provide the title of the translated version along with the original title if such a translation exists.

Other types of references to resources are described in Section 8.4, “Cross-references” and Section 8.7, “External links”.

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

Typical use cases of tables include:

As there are use cases for tables, there are cases when not to use tables:

Some general style tips for tables:

.A table with a title
|===
|File System |Maximum File Size

|Ext2 (1 kB block size)
|16 GB

|Ext2 (2 kB block size)
|entry
|===

To mark up buttons when describing the user interface, use the button macro.

Press the btn:[OK] button to confirm your choice.

To explain how to select a menu item, use the menu macro.

Save the file by selecting menu:File[Save].
Select menu:View[Zoom > Reset] to reset the zoom level to the default setting.