Applies to 2024-05

8 DocBook tags #

The SUSE and openSUSE user documentation is written with DocBook and uses a Relax NG schema that defines a restricted set of DocBook tags.

The following tables list and describe all DocBook tags used for writing most of the SUSE user documentation. They also show which tags are translated and which tags will be blocked for translation, which means that those tags stay in English. The tables are divided into four categories, listing the elements of each respective category.

With GeekoDoc 2, it is also possible to use the Internationalization Tag Set (ITS) to explicitly indicate whether a tag should be translated or not. For more information on ITS tags, see Section 8.2, “Using ITS tags”.

For more information on GeekoDoc, see https://opensuse.github.io/geekodoc/

For more information on all tags available in DocBook, see https://tdg.docbook.org/tdg/5.2/

8.1 Using DocBook tags #

8.1.1 Meta elements #

All the elements at the section level and above, and many other elements, include a wrapper for meta information about the content. The meta information wrapper is designed to contain bibliographic information about the content (author, title, publisher, etc.) as well as other meta information such as revision histories, keyword sets and index terms.

Element name	Description	Translation
abstract	Use an abstract to summarize the information provided in a book, article, or set in five or fewer sentences.	Yes
author personame firstname surname	Name of an individual author	No
authorgroup author personame firstname surname	Wrapper for author information when a document has multiple authors or collaborators	No
date	Date of publication or revision of a document	No
info dm:docmanager dm:bugtracker dm:url dm:component dm:product dm:assignee dm:version dm:translation dm:editurl	`<info>`: Wrapper to contain bibliographic information about the content and other meta info. `<dm:PLACEHOLDER>`: SUSE-specific info needed by the doc-manager tool and DAPS to process and build SUSE user documentation.	No
indexterm primary secondary	To create an index	Yes Legacy element, do not use for new documentation
keywordset keyword	A set of keywords describing the content of a document	No For TM parser settings, set to Yes.
legalnotice		Yes
productname	The formal name of a product	No
productnumber	A number assigned to a product	No
remark	A remark (or comment) intended for presentation in a draft manuscript	No
subtitle	The subtitle of a document. Often used for SUSE Best Practices guides	Yes
title	The text of the title for a section of a document or for a formal block-level element For document titles, such as book, article and set titles, use title-style capitalization. Apply sentence-style capitalization to all running text and all types of headings and titles that are part of the document content.	Yes
titleabbrev	The abbreviation of a title. For example, it can be used to show shorter titles in the table of contents.	Yes

8.1.2 Structure elements #

Note

Structure elements are needed for sectioning and structuring your document, such as defining chapters, appendix, etc.

Most structure elements do not need translations. The child elements like <title> are translated.

Element name	Description	Translation
article	An article	Yes
appendix	An appendix in a book or article	No For TM parser settings, set to Yes.
bridgehead	A free-floating heading. Use sparingly and work with sections instead.	Yes
book	A book	No For TM parser settings, set to Yes.
chapter	A chapter, as of a book	No For TM parser settings, set to Yes.
formalpara	A paragraph with the title rendered as a run-in head. Use to create more compact lists, for example: `who`. Lists currently logged in users. `w`. Shows who is logged in and what they are doing.	Yes
section	A recursive section, unnumbered	No For TM parser settings, set to Yes.
sect1 sect2 sect3 ...	Numbered sections that must be properly nested	No For TM parser settings, set to Yes.
set	A collection of books	Yes
para	A paragraph	Yes
part	A division in a book	No For TM parser settings, set to Yes.
preface	Introductory matter preceding the first chapter of a book	No For TM parser settings, set to Yes.
qandaset qandaentry question answer	Used for FAQs	Yes

8.1.3 Block elements #

The block elements occur immediately below the component and sectioning elements. These are the (roughly) paragraph-level elements in DocBook. They can be divided into a number of categories: lists, admonitions, line-specific environments, synopses of several sorts, tables, figures, examples, and a dozen or more miscellaneous elements.

Element name	Description	Translation
calloutlist callout para	List of callouts and their descriptions. A called out description of a marked area.	No For TM parser settings, set to Yes. Child element `<para>` is translated.
example	An example	Yes
figure title mediaobject imageobject imagedata	Figure with title	No For TM parser settings, set to Yes. Child element `<title>` is translated.
glossary glossdef glossdiv glossentry glossterm	A glossary	Yes
important tittle	Use this elements to give vital information.	Yes
informalfigure	Figure without a title	No
informaltable	Table without a title	Yes
itemizedlist listitem	Unordered, bulleted list	Yes
note title para	A message set off from the text. Use this element to highlight software version differences.	Yes
orderedlist listitem	Numbered list with attributes to control the type of enumeration	Yes
procedure step substeps stepalternatives	`<procedure>`: A list of operations to be performed in a well-defined sequence `<step>`: A unit of action in a procedure	Yes
programlisting	A literal listing of a program or a part of a program. Use for program source or source fragment listings. Formatted as a displayed block. Similar to `<screen>`.	No
qandset qandaentry question answer	List of questions and answers, used for FAQs	Yes
screen	Text that a user sees on a computer screen	No
simplelist member	Undecorated list of single words or short phrases	Yes
table title tgroup colspec thead row entry tbody row entry	Formal table with title	No For TM parser settings, set to Yes. Except for child elements `<title>` and `<entry>`
textobject	Explanatory text for images to aid visually impaired users and show when the image cannot be loaded because of an error	Yes
tip title para	To introduce guidelines or give tips	Yes
variablelist varlistentry term	List of terms and definitions or descriptions	Yes
warning title para	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.	Yes

8.1.4 Inline elements #

Inline elements are used to mark up running text. In published documents, inline elements often cause a font change or other small change, but they do not cause line or paragraph breaks.

Element name	Description	Translation
citetitle	To reference names of printed books. To refer to any of our guides, use `<xref/>` or `<link/>`.	No
co	Part of calloutlist. The location of a callout embedded in text.	No
code	An inline code fragment	No
command	A software command	No
constant	A programming or system constant	No
email	An e-mail address	No
emphasis	Emphasized text	Yes
envar	A software environment variable	No
filename	Name of a file or path as well as directories, printers or flash drives	No
function	Name of a function or subroutine, as in a programming language	No
guimenu	To mark up all GUI elements like button, label and menu	Yes Depends on whether UI is translated or not. If not, use ITS tag.
indexterm primary secondary	Index marker	Yes Legacy element, do not use for new documentation
inlinemediaobject	An inline media object (video, audio, image...)	No
keycap	The text printed on a key on a keyboard For function keys, always use with function, for example: <keycap function="control"></keycap>	Yes
keycombo keycap	A combination of input actions on a keyboard	Yes
link	A hypertext link. Use the secure protocol prefix (`https://`), if possible.	No
literal	To mark up data taken literally from a computer system	No
menuchoice	A selection or series of selections from a menu	Yes
option	An option for a software command	No
package	Name of a software or application package. Replaces `<systemitem class="resource">`.	No
parameter	A value or a symbolic reference to a value	No
phrase	A span of text	Yes
productname	The formal name of a product	No
prompt	A character or string indicating the start of an input field in a computer display	No
quote	To quote from sources, such as books. In all other cases, do not use quotation marks.	Yes
replaceable	Content that may or must be replaced by the user. Capitalize placeholder text in all contexts where this is not detrimental to content intelligibility. Do not use spaces within placeholders, use underscores instead.	No
systemitem	A system-related item or term	No
subscript	A subscript. For example: H₂O	Yes
superscript	A superscript. For example: X²	Yes
tag	A component of XML (or SGML) markup	No
trademark	To mark a trademark with TM™	No
uri	For links that should not be clickable	No
varname	The name of a variable	No
xi:include	To construct documents from different files	No
xref	A cross-reference to another part of the document	No

8 DocBook tags #

8.1 Using DocBook tags #

8.1.1 Meta elements #

8.1.2 Structure elements #

8.1.3 Block elements #

8.1.4 Inline elements #

8.2 Using ITS tags #