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 #
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:
| 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 |
example | An example | Yes |
figure
title
mediaobject
imageobject
imagedata | Figure with title |
No For TM parser settings, set to Yes.
Child element |
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 |
| 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
| 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 |
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 |
|
| 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: H2O | Yes |
superscript |
A superscript. For example: X2 | 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.2 Using ITS tags #
With GeekoDoc 2, it is possible to use the Internationalization Tag Set (ITS) tags to explicitly indicate that a tag should be translated or not.
For this, you need to have the ITS namespace enabled in the XML file.
Make sure the following line is added to the root element:
xmlns:its="http://www.w3.org/2005/11/its".
For example: You have used the tag <guimenu>
which is usually translated but in this particular case it should not be
translated.
To mark the tag correctly, use the ITS tag as shown here:
Click <guimenu its:translate="no">Save</guimenu>.