Product SiteDocumentation Site

Warning

The information in this guide should only be used as a quick reference for older content captured in XML if needed to understand tagging in making the conversion from XML to AsciiDoc. For content produced in AsciiDoc, please see the Curriculum Guidelines site instead.
DocBook XML Standards

Red Hat Training + Certification

Edition 3

Connie Petlitzer

Red Hat Training + Certification

David O'Brien

Red Hat Training + Certification

Legal Notice

Copyright © 2020 Red Hat, Inc.
This document is licensed by Red Hat under the Creative Commons Attribution-ShareAlike 3.0 Unported License. If you distribute this document, or a modified version of it, you must provide attribution to Red Hat, Inc. and provide a link to the original. If the document is modified, all Red Hat trademarks must be removed.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.
1. Course skeleton
1.1. Downloading the Course Skeleton
1.2. Building an RHT Course
2. Supported Tags
2.1. List of Supported Tags
2.2. Unsupported Tags
3. Building a Student Guide
3.1. Adding Chapters
3.2. Adding Sections
3.3. Adding Titles
3.4. Adding Tasks
3.5. Adding Media
3.6. Adding a Summary
3.7. Adding an Appendix
4. Enhancing Your Student Guide with Lists, Tables, and Other Features
4.1. Using Lists
4.2. Using Tables
4.3. Using Admonitions
4.4. Using Callouts and Callout Lists
4.5. Emphasizing Text
4.6. Using References
5. Interacting with the System
5.1. URI and URL
5.2. Code
5.3. User Input
5.4. Replaceable User Input
5.5. Application Names
5.6. Product Names
5.7. Identifying System Output
5.8. Recommended Practices for Remote Logins
5.9. Using Other Operating Systems
5.10. Using Shortcuts, Keycombos, and Keycaps
5.11. Recommended Practices for Remote Logins
6. Representing GUI Objects
6.1. Comparing Graphical, Terminal, and Browser-based User Interfaces
6.2. Referring to Menus and Submenus
6.3. Referring to UI Labels, Fields, and Buttons
7. Describing Sets of Data
7.1. Configuration Files
7.2. Databases
8. Conditional Tagging
8.1. Conditional tagging
9. Using ID Attributes
9.1. Using ID Attributes
10. Other DocBook Elements
10.1. Using Subscripts, Superscripts, and Copyright and Trademark Symbols
10.2. Using Blockquotes
10.3. Using Email Addresses
10.4. Quotation marks
11. Presentation Methods
11.1. Standard Lecture
12. Engagement Methods
12.1. Usage Guidelines
12.2. Guided Exercise Overview and XML
12.3. Sample Guided Exercise
12.4. Guided Exercise - Multiple Tasks
12.5. Sample Guided Exercise with Multiple Tasks
12.6. Resequencing Quiz Overview and XML
12.7. Resequence Title
12.8. Matching Quiz Overview and XML
12.9. Matching Quiz Sample Title
12.10. Multiple-choice Overview and XML
12.11. Multiple-choice Sample Title
12.12. Lab Overview and XML
12.13. Creating Widgets with Microtools
12.14. Comprehensive Review Overview and XML
Index

Chapter 1. Course skeleton

Download a new course skeleton using Git and build an RHT Course.

Important

This content is for Red Hat Training internal use only.

1.1. Downloading the Course Skeleton

To obtain a copy of the latest templates and course skeleton, run the following command:
[user@demo ~] $ git clone git@github.com:RedHatTraining/skeleton.git
This creates a directory called skeleton in your current directory. The skeleton contains all required files for building a course, and templates for each different kind of section within a course.
If you already have the repository cloned, run the following command to get the latest version:
[user@demo skeleton] $ git pull
If you are new to Git, see Pro Git for both an introduction to Git, basic usage, and more advanced topics for the curious.

1.2. Building an RHT Course

RHT uses a custom toolset to build training courses. Refer to RedHatTraining/curriculum-build-setup for details on how to set up your system to build training courses.
After you have cloned a course from GitHub, navigate to the guides directory of your course and run flamel sg to build the student guide.
You should always build a course before committing changes to the Git repository, to ensure that the course is always in a state from which a course can be generated.

Chapter 2. Supported Tags

Red Hat Training (RHT) only supports a subset of the available DocBook 4.5 elements. These are described below.

Note

Even though RHT does not use DocBook 5 yet, it does use XML elements in a forward-compatible manner.

2.1. List of Supported Tags

This section lists DocBook tags that have been tested and approved for output using the Publican toolset.

Important

DocBook tags not listed in this section are unsupported, and should not be used in GLS material.
Docbook ElementDefinitionPurposePurpose Explanation
abstract A summaryContent UXAbstracts must be tagged in order to generate styling on the goals and objectives, which give users an at a glance summation of what they will find in a given chapter.
answerAn answer to a question posed in a question and answer setContent UXAnswer options must be clearly marked so that:
  • answer options are clear
  • the correct answer is clearly shown
appendix An appendix in a Book or ArticleSupplementary MaterialAppendices contain more supplementary information than chapters and adhere to different rules.
areaValue pointer to an area of an image that is annotated.Content UXAllows for a callout list against images
areasetA collection of regions in a graphic exampleStructureAllows for a callout list against images
areaspecTag used to group multiple area elementsStructureAllows for a callout list against images
authorThe name of an individual authorMetadataAuthor information allows us to know who is responsible for a work's production.
authorgroupWrapper for author information when a document has multiple authors or collaboratorsStructureNecessity for Docbook data model for author tagging.
blockquote A quotation set off from the main textContent UXStyles quotations so it is clear for the user the differentiation to the regular text.
book A wrapper to contain chapters and appendices. Equivalent to a single course.StructureRequired to bundle Docbook 4.5 chapters together into a course
bookinfoMeta-information for a BookMetadataInformation about the course, including course title, number, publish date, product, etc.
callout A “called out” description of a marked areaContent UXCallouts act as annotation and can be directly linked to portions of an image or screen capture.
calloutlist A list of calloutsStructureRequired to bundle Docbook 4.5 callouts together
caption A brief description of the object.Content UXOffers narrative about a media object (figure, screenshot, video, etc)
chapter A topic within a bookStructureMajor topic based piece of content in our structures, made up of sections.
citetitle The title of a cited workMetadataThe title of a cited work in a reference.
co The location of a callout embedded in textContent UXLinks callout annotations to particular pieces of information in an image or screenshot.
code An inline code fragmentContent UXCaptures blocks of text that represent code to distinguish this from narrative content.
colspec Specifications for a column in a tableStructureUsed by the OASIS/CALS table model in Docbook to ensure correct table alignment
editionThe name or number of an edition of a documentMetadataCaptures information about the edition of a course
editorThe name of the editor of a documentMetadataEditor information allows us to know who is responsible for a work's production.
email An email addressMetadataIdentifying information for references.
emphasis Emphasized textContent UXEmphasizes and highlights important text to the user.
entry A cell in a tableStructureUsed by the OASIS/CALS table model in Docbook for correct table alignment
firstnameThe first name of a personStructureRequired by the Docbook data model to validate <author> tags.
firsttermThe first occurrence of a termContent UXIdentifies the first use of a term.
formalpara A paragraph with a titleContent UXOnly used within tasksummary and taskprerequisites within guided exercises to create structure (due to the limitations of the Docbook data model). Do not use to create general structure in chapters - use nested sections instead.
guibutton The text of a button in a GUIContext UXDistinguishes GUI buttons.
guiicon The text of a icon in a GUIContext UXDistinguishes GUI icons.
guilabel The text of a label in a GUIContext UXDistinguishes GUI labels
guimenu The name of a menu in a GUIStructureDistinguishes GUI menus and auto-generates arrows when used within menuchoice
guimenuitem The name of a terminal menu item in a GUIStructureDistinguishes GUI menus and auto-generates arrows when used within menuchoice
guisubmenu The name of a submenu in a GUIStructureDistinguishes GUI menus and auto-generates arrows when used within menuchoice
imagedata Pointer to external image dataStructureRequired by the Docbook data model to point to image files
imageobject A wrapper for image data and its associated meta-informationStructureRequired by the Docbook data model to use imagedata
imageobjectco A wrapper for an image object with calloutsStructureRequired by the Docbook data model to use imagedata with callouts
important An admonition set off from the textContent UXHighlights important content as an aside to the main content for the user.
informaltable A table without a titleContent UXUsed to render tables without titles, as regular tables require them in the Docbook data model.
invpartnumberAn inventory part numberMetadataCaptures the value of the course number.
itemizedlistA list in which each entry is marked with a bullet or other dingbatContent UXUsed to generate standard bullet lists.
keycap The text printed on a key on a keyboardStructureNeeded by keycombo, autogenerates + signs between key values.
keycombo A combination of input actionsContent UXAutogenerates a '+' between keycaps. This markup is necessary since it keeps the generated text in the same style as keycap
legalnoticeA statement of legal obligations or requirementsMetadataExplains copyright, trademark, and other legal formalities of a course
listitem A wrapper for the elements of a list itemStructureUsed to identify constituents within a itemizedlist, orderedlist, or variablelist structure
mediaobject A displayed media object (video, audio, image, etc.)StructureWrapper required in Docbook model to use imageobject. Also useful for other media (audio, video) that wouldn't use imageobject. Also allows for 'alternative versioning' of media content where one format works for one output better than another, e.g. video for ROL vs. a screencap image for the PDF.
mediaobjectco A media object that contains calloutsStructureFollows the same logic as mediaobject, while also allowing for call-outs.
memberAn item in a simplelist.StructureItems in a simplelist.
menuchoice A selection or series of selections from a menuContent UXGenerates a '→' with special handling for shortcuts. Ensures that the generated text and children elements are styled the same.
note A message set off from the textContent UXAllows us to style information that is an aside to the general sections of content.
orderedlist A list in which each entry is marked with a sequentially incremented labelContent UXUsed to generate standard numbered lists.
othercreditA person or entity, other than an author or editor, credited in a documentMetadataAllows us to know who is responsible for a work's production.
packageA packageContent UXPackage names are given special styling (italicization) to distinguish them from other plain text content.
paraA paragraphContent UXNeeded for basic paragraph blocks.
phrase A span of textContent UXphrase with a @role='fixedcase' is used very specifically to ensure that regardless of styling, the casing of a word or phrase does not change.
prefaceIntroductory matter preceding the first chapter of a bookSupplementary MaterialPrefaces contain more supplementary information that introduces a user to the course and adhere to different rules.
procedure A list of operations to be performed in a well-defined sequenceStructureUsed by the Docbook data model as a wrapper for a set of steps to be completed in a particular order.
productnameThe formal name of a productMetadataIdentifies the full product that the course is about in the metadata. QA should ensure this is not used within main chapters in lieu of application
productnumberA number assigned to a productMetadataIdentifies the course number in the metadata.
prompt A character or string indicating the start of an input field in a computer displayContent UXIdentifies content generated by the computer terminal, rather than a users input within a <screen>. Styling between the two within screen is differentiated so that the user can intuit the information.
pubdateThe date of publication of a documentMetadataAppears in Book_Info.xml and defines the publication date of a course. This is not listed in the Docbook guide.
publisherThe publisher of a documentMetadataIdentifies the publisher of the course
pubsnumberA number assigned to a publication other than an ISBN or ISSN or inventory part numberMetadata 
qandaentryA question/answer combination within a QandASetStructureRequired by the Docbook model to group a question and its answer together
qandasetA set of multiple questions and answer entriesStructureRequired by the Docbook model to group multiple qandaentries together (e.g. multiple questions and answers)
questionA question in a QandASetContent UXA question in a question and answer set.
quote An inline quotationContent UX and TranslationThis tag is used to generate inline quotation marks for content that the author wants to offset. This tag also makes it simple to translate quotes into different languages, which may use different punctuation.
replaceable Content that may or must be replaced by the userContent UXOffsets text that the user should understand is meant to be replaced with values unique to their local machine.
row A row in a tableStructureNeeded in order to organize a table or informaltable according to the data model
screen Text that a user sees or might see on a computer screenContent UXA wrapper containing all of the elements a user will see in a terminal / command line screen window
section A recursive sectionStructureUsed to group paragraphs together and title them according to topics outlined within the chapter.
simplelistAn undecorated short list.Content UXThis element should be used only for short lists within tables.
shortcut A key combination for an action that is also accessible through a menuStructureVery specifically used within menuchoice as a wrapper for keycombo. This is very much a Docbook restriction as keycombo can't be used directly within menuchoice.
step A unit of action in a procedureContent UXOutlines steps that a user should take to complete a particular task.
stepalternatives Alternative steps in a procedureContent UXOffers alternative methods to complete a step in a given procedure.
subscript A subscript (as in H2O, the molecular formula for water)Content UXStylizes numerals so that they appear correctly in certain circumstances where they are required such as chemical equations or mathematical formula.
substeps A wrapper for steps that occur within steps in a procedureStructureUsed by the Docbook model to create tiers of steps in a procedure
subtitle The subtitle of a documentMetadataDistinguishes supplementary title information from the main title. Only allowed within bookinfo
superscript A superscript (as in x2, the mathematical notation for x multiplied by itself)Content UXStylizes numerals so that they appear correctly in certain circumstances where they are required such as chemical equations or mathematical formula.
surnameA family name; in western cultures the last nameStructureRequired by the Docbook data model to validate <author> tags.
table A formal table in a documentContent UXUsed to capture titled tables with headed columns
task A task to be completedContent UXAn activity a student is expected to complete
taskprerequisites The prerequisites for a taskContent UXAny prerequisites a user should have completed before starting the task.
taskrelated Information related to a taskContent UXSupplementary information related to the activity.
tasksummary A summary of a taskContent UXSummarizes the activity for the user
tbody A wrapper for the rows of a table or informal tableStructureRequired by the data model to distinguish the body rows of a table from the header and the footer
term The word or phrase being defined or described in a variable listContent UX'Heading' in a variable list. Usually the term has distinct styling applied.
textobject A wrapper for a text description of an object and its associated meta-informationAccessibilityUsed specifically to cover alt text content on an image.
tfoot A table footer consisting of one or more rowsStructureRequired by the data model to distinguish table footers from other table content.
tgroup A wrapper for the main content of a table, or part of a tableStructureAllows tables to be divided into sections.
thead A table header consisting of one or more rowsStructureRequired by the data model to distinguish column headings in a table.
title The text of the title of a section of a document or of a formal block-level elementContent UXIdentifies the title of content - in a chapter, section, table, etc so that the user can identify portions of content.
trademark A trademarkComplianceAutogenerates the trademark symbol where relevant
ulink A link that addresses its target by means of a URL (Uniform Resource Locator)Content UXAllows a user to jump to other relevant external resources
uri A Uniform Resource IdentifierContent UXUsed to create pseudo links that we would never want the user to click but want to appear as a link. These dead links serve a purpose to the example but do not represent content we want to direct a user to.
userinput Content that must be entered, and possibly changed, by a user.Quality Assurance and ScriptingImproves quality by testing values in scripts such as pre-commit or automated lab testing.
variablelist A list in which each entry is composed of a set of one or more terms and an associated descriptionContent UXA headed list, where the 'heading' and following information are tied to each other. Very specifically used to cover 'glossary-like' content
varlistentry A wrapper for a set of terms and the associated description in a variable listStructureUsed to group a term and its definition in a headed list.
videodataPointer to external video dataContent UXRequired by the Docbook data model to point to video files
videoobjectA wrapper for video data and its associated meta-informationStructureRequired by the Docbook data model to use videodata
warning An admonition set off from the textContent UXCautions the user with a graphic and style as an aside to the main content.
xi:fallback A default string of text when xi:include fails.StructureEnsures that xi:includes can not fully fail and that some text is displayed to the user.
xi:include A pointer element to pull in referenced pieces of content.StructureTranscludes other XML documents into each other.
xrefA cross reference to another chunk.Content UXAllows users to jump to other, relevant parts of a course.

2.2. Unsupported Tags

The following Docbook XML elements are unsupported or have been deprecated from continued use in the GLS subset. The render of these tags is not guaranteed in the GLS subset of the Docbook data model. Where applicable, supported substitutions are listed.
Docbook ElementExplanation
applicationUse code instead.
beginpageDo not use this element - disrupts autogeneration in FOP
bridgeheadUse nested sections instead.
cautionUnnecessary admonition levels. Use important or warning instead.
classnameUse code instead.
commandUse code instead.
computeroutputUse code instead.
corefUse arearef instead.
entrytblFOP does not support nested tables.
envarUse code instead.
filenameUse code instead.
glossdivGlossaries are not currently in use in GLS titles.
glosslistGlossaries are not currently in use in GLS titles.
highlightsUse emphasis instead.
informalfigureThis tag specifically causes render issues in ROLE and should be removed when old versions are re-worked.
inlinegraphicDoes not support text alternative to allow accessibility to the visually impaired. (Breaches US "Section 508" standards.)
inlinemediaobjectUse mediaobject instead.
keycodeUse keycap instead.
keysymUse keycap instead.
linkRedundant to ulink.
literalUse code instead.
literallayoutUse screen instead.
olinkUse ulink instead. This tag is not only unsupported, it is prohibited - using olink will prevent the book from building.
optionUse code instead.
parameterUse code instead.
programlistingUse screen instead.
systemitemUse code instead.
tipUnnecessary admonition levels. Use note instead.
varnameUse code instead.

Chapter 3. Building a Student Guide

Student guides consist primarily of abstracts, chapters, and sections. Chapters and sections contain a range of other elements, depending on the requirements of the course and how it is to be delivered.

3.1. Adding Chapters

The <chapter> element is the root element of a chapter file, and use the following children:
  • One <title> element, rendered as the chapter title.
    Depending on the stylesheet, some titles may be converted to uppercase. If your title contains a word or phrase that must not be changed (for example, a trademark with specific case requirements), wrap the phrase in <phrase role="fixedcase">.
  • One <abstract> element, rendered as the chapter introduction. This includes a table.
  • A list of <xi:include> elements listing section content contained in separate XML files in the topics directory.
All course presentation and engagement content is in section files, contained in the topics directory. Section content is assembled in XML chapter files contained in the sg-chapter directory.
The XML layout for a basic chapter file for the Student Guide is provided in the zzz-chapter-template.xml file, included in the https://github.com/RedHatTraining/skeleton repository.

Note

The skeleton repository https://github.com/RedHatTraining/skeleton is for Red Hat Training internal use only.
The remainder of the chapter file includes section content from the topics directory:
<!-- Include section content from topics directory -->
    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="topics/SG-Sample-ContentSection.xml"/>
    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="topics/SG-Sample-PracticeSection.xml"/>
    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="topics/SG-Sample-Lab.xml"/>
</chapter>

3.2. Adding Sections

The bulk of the course content is included in sections, which can contain presentation or engagement content. Each top-level section should be contained in its own file. Each presentation section should be followed by a guided exercise section. Each presentation section includes:
  • Title
  • Objective
  • Presentation methods
  • References
Use nested <section> elements to structure content into a hierarchy within the section title. You can only nest sections to three levels; the build will fail with a warning if you attempt to use more. Try to keep the number of sections in a chapter to 10 or fewer.
Each presentation section must be followed by a guided exercise section, which contains a guided exercise, quiz, or lab. The XML layout of a sample presentation section is provided in the topics/zzz/zzz-content-template.xml file in the https://github.com/RedHatTraining/skeleton repository.
See the RHT Presentation and Engagement Methods chapters for more examples of presentation and guided exercise sections.

File Naming Conventions

It is important that file and directory names follow a consistent pattern. This helps to improve efficiency and is a requirement for automation and scripting. Place all section files for a particular chapter in a topics/chapter directory. This is illustrated in XML File Naming.
The following guidelines apply to all directories and file names in Red Hat Training courses:
  • Do not use numbers.
  • Do not use spaces or punctuation. Use dashes as separators, not underscores.
  • Always use lowercase.
  • The chapter and section names should be short, logical, single words that clearly identify the title.
  • Avoid file names and commands. Focus on the task at hand and introduce any files and commands in the text.

Example File Names

The following examples illustrate how to use the guidelines described above for a chapter called "Linux Networks".
XML File Naming
  • sg-chapters/linuxnet.xml
  • sg-chapters/topics/linuxnet/clusters-lecture.xml
  • sg-chapters/topics/linuxnet/clusters-practice.xml
  • sg-chapters/topics/linuxnet/review.xml
  • sg-chapters/topics/linuxnet/summary.xml
Grading Script Naming
  • lab linuxnet-clusters subcommand (guided exercise)
  • lab linuxnet-review subcommand (end of chapter lab)
Materials Organization
  • http://materials.example.com/linuxnet/clusters/file
Video File Naming
  • Syntax: COURSE-linuxnet-clusters-FLAST-YYYYMM
ID Names
  • Syntax: CHAPTER-SECTION[-TYPE]
  • linuxnet-clusters-lecture
  • linuxnet-clusters-practice
  • linuxnet-review
  • linuxnet-summary
  • linuxnet-clusters-video1
  • linuxnet-clusters-multi1
  • linuxnet-clusters-reseq1
Images
  • images/linuxnet/clusters-TOPIC.png
  • images/linuxnet/clusters-TOPIC.svg
IG File Names
  • ig-chapters/linuxnet-ig.xml

Presentation section XML

The first part of the section file contains the title and objectives. This is followed by the lecture content, and finally any references.

3.3. Adding Titles

The <title> element defines a headline title for a <chapter>, <section>, or <task>. The automatically generated Table of Contents also makes use of the <title> elements, so try to keep them short. See the tagging example above.

Note

If you cannot reduce the length of your chapter title so that it works for the TOC, you can use a <titleabbrev> element after the <title> element. This abbreviation is only used in the TOC.
The <subtitle> element is only allowed in the <bookinfo> section of the document.

3.4. Adding Tasks

A <task> element defines an activity that a student is expected to complete, including end-of-section practices, end-of-chapter labs, and end-of-course reviews. The <task> element uses a role attribute to define the type of <task> that is rendered. See the Chapter 12, Engagement Methods chapter for the list of allowed role values. A <task> must be nested within a <section>, although you may have multiple <task> tags within a single <section> (to support multiple procedures within a single GE).
<task> elements can use a number of sub-elements, depending on the usage. For complete usage information, see the Engagement Methods chapter of this guide. The most commonly used elements are listed below:
  • <taskprerequisites>
    The taskprerequisites render as a "Before you begin" section. The initial paras or other content before the Instructions section is for any script the student must run or other minor prereqs to prepare their systems before starting on the instructions. These are for things specific to the setup that the student is NOT reviewing as part of the exercise and should be minimal.
  • <taskrelated>
    The taskrelated section contains any final information relevant to the exercise. In particular for labs and comprehensive reviews, the Evaluation formalpara within taskrelated should tell the students how to evaluate the success of their work, either through manual checks or a grading script. The Finish formalpara within taskrelated concludes the activity.
  • <tasksummary>
    The initial para is a one sentence statement of the goal of this particular exercise or lab. The Outcomes formalpara will list the specific results the student should achieve.
  • <step>
  • <substeps>
  • <stepalternatives>
  • <procedure>
  • <qandaset>
  • <qandaentry>
  • <question>
  • <answer>

Important

The <task> and <qandaentry> tags require a unique id attribute.

3.5. Adding Media

3.5.1. Marking up Graphics

This section describes how to add graphics to your course content.
The XML markup for adding a graphic is shown below:
<mediaobject id="topic-shortname">
  <imageobject>
    <imagedata fileref="images/memory-tlb-flowchart.svg" [width=""] scalefit="1" align="center"/>
  </imageobject>
  <textobject>
    <phrase>Translation buffer flowchart</phrase>
  </textobject>
  <caption>Translation buffer flowchart</caption>
</mediaobject>
  • The id attribute, if used, allows for cross-referring to mediaobjects.
  • The width attribute, if used, is measured as a percentage of the page body (the part of the page that contains text, less margins and the running header/footer). The default width is set to 100% if no width is provided.
  • The scalefit="1" attribute causes the height to be proportionally adjusted to match the width.
  • The <textobject> element renders as an <alt> element and should be included for ADA accessibility.
  • The align attribute is optional. If omitted, the style sheet defaults to align="left".
  • The <caption> element is optional unless you need to refer to the graphic by title, or if they are not suitably explained by the surrounding text.
 Translation buffer flowchart
Translation buffer flowchart

Important

Do not use <textobject> or the scale="x" attribute of <imagedata>, or you will get rendering issues in HTML output (ROLE).

Note

The <graphic> element is being eliminated in DocBook 5.0 because it does not properly allow for accessibility features for devices or tools such as screen readers. This will be an issue with current documentation that uses <graphic> elements, and will need to be addressed.

Note

For Red Hat Training internal users, more guidance on creating graphics can be found here: GLS Graphic Guidelines.

3.5.2. Marking up Motion Graphics and Videos

The markup for motion graphics (which use the mp4 video format) and videos is very similar to the markup for graphics. Use the <videoobject> and <videodata> elements respectively in place of <imageobject> and <imagedata>. Red Hat uses the @fileref attribute to hold a platform jwplayer id value for rendering the graphic online. Mark-up the file location with the @xml:base attribute instead.
<mediaobject id="topic-shortname-value">
  <videoobject>
    <videodata align="center" fileref="jwplayer:xRthnc134sk" xml:base="videos/deploy/deploy-arch.mp4"/>
  </videoobject>
  <textobject>Pods running on OpenShift</textobject>
  <caption>Pods running on OpenShift</caption>
</mediaobject>
For motion graphics and videos, the @width and @scalefit attributes are not recommended.

3.5.3. Cross-referring to Media

To reference media content do the following:
  • Ensure that the <mediaobject> element contains a unique @id value. If one does not yet exist, add it, and ensure that it is a unique value.
  • Use an <xref> element to create a cross-reference to the <mediaobject> element.
  • Make sure the targets have a title or suitable link text or the link will be created as "?"
  • Do not reference items inside solutions.
Example of cross-reference markup:
For clear guidance on the workflow, see the <xref linkend="buffer-flowchart"/>.

3.6. Adding a Summary

Add a chapter summary to a separate section file at the end of each chapter.

Note

For Red Hat Training internal, the XML layout of a sample summary section is provided in the topics/zzz/zzz-summary-template.xml file in the https://github.com/RedHatTraining/skeleton repository.

Important

Legacy courses may have a <highlights> element, which is now suppressed in PDF renders. Remove any existing <highlights> elements when creating a new course.

3.7. Adding an Appendix

An appendix works like a chapter. It is placed in its own file, and is placed in the list of includes in the main course XML document at the end of the chapter entries list. Order is respected. Appendixes are given letters, rather than numbers. The major differences between a chapter and an appendix are listed below:
  • Appendixes do not include abstracts.
  • Appendixes do not include sections. If you need a section, add another appendix.
  • Appendixes use a DOCTYPE of appendix, rather than chapter, in the header.

Note

For Red Hat Training internal, the XML layout of a sample appendix section is provided in the topics/zzz/zzz-appendix-template.xml file in the https://github.com/RedHatTraining/skeleton repository.

Chapter 4. Enhancing Your Student Guide with Lists, Tables, and Other Features

4.1. Using Lists

RHT documentation supports several types of lists, namely:
Itemized lists
These appear as a bullet list. Use this list type for three or more entries where order is not important, or in a demonstration section when students are encouraged to not perform steps but to watch the instructor instead. Titles are optional.
Ordered lists
These appear as a numbered list. Use this list type for multiple entries where order is important, for example, listing the order of operations required to prepare for an installation, or listing a sequence of events that occurs. Titles are optional.
Variable lists
These appear as a list of terms followed by definitions. Use this list type to list and describe a series of terms, such as variables, command options or arguments, and similar items. Titles are optional. (This list is written as a variable list.)
A variable list is often preferable to a table, because tables have the additional overhead of calculating column width for every translation. Tables are best reserved for information that relies upon, or benefits greatly from, a grid layout.
Procedures
These appear as a list of numbered steps. Procedures always include a title, and are used to list the steps required to achieve a task.
Simple lists
These appear as undecorated lists of words or phrases, and can appear in either serial, horizontal, or vertical form. Use the columns attribute to specify the number of horizontal or vertical columns. The default is a single-column vertical list. Use this type of list in table cells where you need to provide a list but do not want or need bullets or other decorations.
Simple lists are only supported inside tables in the RHT DocBook model.
You can nest all list types except <simplelist>, but try to keep the number of levels to two or fewer. To nest procedures, use <substep> elements. Do not use sub-substeps.

Note

For Red Hat Training internal users, the XML layout of a sample list is provided in the topics/zzz/zzz-chapter-template.xml file and the layout of a smaple procedure is provided in the topics/zzz/zzz-exercise-template.xml file in the https://github.com/RedHatTraining/skeleton repository.
Creating a Variable List
Refer to the following example for guidance on creating a variable list. Be aware of the difference between using a variable list and a table to display data. See Section 4.2, “Using Tables” for more information.
<variablelist><title>Example Variable List</title>
    <varlistentry>
        <term>Example term</term>
        <listitem>
            <para>
                Example definition.
            </para>
        </listitem>
    </varlistentry>
    <varlistentry>
        <term>Another term</term>
        <listitem>
            <para>
                Another definition.
            </para>
        </listitem>
    </varlistentry>
</variablelist>
The above example renders as follows:

Example Variable List

Example term
Example definition.
Another term
Another definition.

4.2. Using Tables

Tables are a common feature in RHT courses. Tables created using <table> elements require a title, but those created using <informaltable> elements do not. Formal tables are preferred, with a column heading for each column. Always include a <thead> element, regardless of the type of table.
Use title case for table titles, and use sentence case for column headings.

Important

Be cautious when adding long file names, URIs, and similar objects to a table, because they can overflow the cell or table. Adjust column widths to avoid this.
Example of a Basic Table
The following example displays the DocBook structure of a basic table. It uses a simple numbering and naming scheme for columns (colnum and colname). You can use the colwidth attribute to adjust the relative width of columns to suit your data.
<table frame="all">
  <title>Example of a Basic Table</title>
  <tgroup cols="3" align="left" colsep="1" rowsep="1">
    <colspec colname="c1" colnum="1" colwidth="1.0*"/>
    <colspec colname="c2" colnum="2" colwidth="2.0*"/>
    <colspec colname="c3" colnum="3" colwidth="2.0*"/>
    <thead>
      <row>
        <entry>Header 1</entry>
        <entry>Header 2</entry>
        <entry>Header 3</entry>
      </row>
    </thead>

    <tbody>
      <row>
        <entry>b1</entry>
        <entry>b2</entry>
        <entry>b3</entry>
      </row>
      <row>
        <entry>c1</entry>
        <entry>c2</entry>
        <entry>c3</entry>
      </row>
      <row>
        <entry>d1</entry>
        <entry>d2</entry>
        <entry>d3</entry>
      </row>
    </tbody>
  </tgroup>
</table>
The example above renders approximately as follows:

Table 4.1. Example of a Basic Table

Header 1Header 2Header 3
b1b2b3
c1c2c3
d1d2d3
Example of a Complex Table
The following example displays the DocBook structure of a more complex table that employs a variety of different options.
<table frame="all">
  <title>Example of a Complex Table</title>
  <tgroup cols="5" align="left" colsep="1" rowsep="1">
    <colspec colname="c1" colnum="1" colwidth="1.0*"/>
    <colspec colname="c2" colnum="2" colwidth="2.0*"/>
    <colspec colname="c3" colnum="3" colwidth="2.0*"/>
    <colspec colname="c5" colnum="5"/>
    <thead>
      <row>
        <entry namest="c1" nameend="c2" align="center">Horizontal header span</entry>
        <entry>Header 3</entry>
        <entry>Header 4</entry>
        <entry>Header 5</entry>
      </row>
    </thead>

    <tbody>
      <row>
        <entry>a1</entry>
        <entry>a2</entry>
        <entry>a3</entry>
        <entry>a4</entry>
        <entry morerows="1" valign="middle">
          <para>
            Vertical span across two rows.
          </para>
        </entry>
      </row>
      <row>
        <entry>b1</entry>
        <entry namest="c2" nameend="c3" align="center" morerows="1" valign="bottom">
          Span two rows and two columns.
        </entry>
        <entry>b4</entry>
      </row>
      <row>
        <entry>c1</entry>
        <entry>c4</entry>
        <entry>c5</entry>
      </row>
    </tbody>
  </tgroup>
</table>
The example above renders approximately as follows:

Table 4.2. Example of a Complex Table

Horizontal header spanHeader 3Header 4Header 5
a1a2a3a4
Vertical span across two rows.
b1 Span two rows and two columns. b4
c1c4c5
The <colspec> element helps to create ad hoc spans across columns with the namest and nameend attributes on the <entry> elements.

4.3. Using Admonitions

An admonition is a block of text that highlights a specific point by separating it from the main body of the text. You can use admonitions to:
  • Emphasize a specific point
  • Isolate a comment that may be useful in passing to some students
  • Draw attention to critical information

Important

Do not add <title> elements to admonitions. RHT style sheets automatically handle all aspects of titles in admonitions.
RHT content uses three primary admonition elements:

Table 4.3. Primary Admonition Elements

ElementPurpose
<note> An item of interest, but not critical information. Best practices, comparisons, supplementary information, or other guidance that if ignored may be inconvenient but not problematic. Should be the most common admonition.
<important> Details things that are important to the student, which may cause confusion, frustration, or irritation if ignored, but will not cause data loss or permanent damage.
<warning> Critical information that if ignored could lead to data loss, permanent damage, or other major problems. Use sparingly.

Note

RHT no longer uses the BestPractices attribute. Convert any existing instances to a Note, Important, or Warning admonition. If required, you can indicate that you are discussing a recommended practice as part of the admonition.

4.4. Using Callouts and Callout Lists

Callouts define areas of a <screen> elements for annotation. They are only to be used in lecture material, not labs, which should not require instructional guidance.
<screen>[user01@host ~]$ cd /etc/yum.repos.d <co id="yum.co" linkends="a"/>
[user01@host yum.repos.d]$ ls
dropbox.repo  fedora.repo  fedora-updates.repo  fedora-updates-testing.repo</screen>

<calloutlist>
    <callout id="a" arearefs="yum.co" >
        <para>This command moves you to the /etc/yum.repos.d directory.</para>
    </callout>
    </calloutlist>
This renders as:
[user01@host ~]$ cd /etc/yum.repos.d 1
[user01@host yum.repos.d]$ ls
dropbox.repo  fedora.repo  fedora-updates.repo  fedora-updates-testing.repo

1

This command moves you to the /etc/yum.repos.d directory.

Note

The <co> element can also appear in <prompt>, <replaceable>, and <code> elements in our documentation. Callouts associated with an image are supported with <mediaobjectco>. See the standard DocBook documentation for more details.

4.5. Emphasizing Text

Generally, writers do not control the style of the course. The style of RHT courses can change between modalities and as Red Hat's branding evolves. Sometimes, however, you may have a clear need to emphasize text.
If you need to emphasize text, use the <emphasis> Docbook element.
To emphasize code, nest <code> tags within <emphasis>. As code renders in regular monospace, emphasis will highlight the text as important for the reader. The default rendition of emphasized code is bold monospace.
<emphasis>italic</emphasis>
<emphasis role="bold">bold</emphasis>
<emphasis role="bold"><code>emphasized code text</code></emphasis>
Example output:
  • italic
  • bold
  • emphasized code text
However, you are encouraged to divorce yourself from visual style, and you should not rely upon your interpretation of what emphasis should look like. All style can be overridden by Red Hat XSL style sheets, so just using the plain <emphasis> tag ensures that your work integrates smoothly into the current style.

4.6. Using References

RHT uses the role attribute on <note> admonitions to collect information about useful references for further information on a topic. These are used primarily at the end of a section in Red Hat courses. References require particular XML tagging patterns so that they are consistent from section to section and unit to unit.

Important

Always use the correct title of any reference or other work to which you create links.

Examples of References

A basic reference is shown first, followed by examples showing references that apply to a RHEL System Administration course. Be sure to use the <ulink> tag instead of the <uri> tag if you are including a URL in a reference. This includes links to any bugs on https://bugzilla.redhat.com or similar sites.
Basic Link Reference
The XML layout for basic link references is provided in the zzz-content-template.xml file, included in the https://github.com/RedHatTraining/skeleton/blob/master/guides/en-US/sg-chapters/topics/zzz/zzz-content-template.xml repository.

Red Hat Documentation Reference

Red Hat documentation as published at https://access.redhat.com has limitations in its ability to provide permanent URLs to chapter and section titles. It is acceptable to use "deep links" (links to specific chapters and sections), but ensure that you only link to the html-single version of any documentation.
The XML layout for Red Hat Documentation references is provided in the zzz-content-template.xml file, included in the https://github.com/RedHatTraining/skeleton/blob/master/guides/en-US/sg-chapters/topics/zzz/zzz-content-template.xml repository.
Referring to Multiple References
Sometimes you need to refer to multiple chapters or sections within the same book. It can become unwieldy to create multiple links with associated lead-in paragraphs, and so the preferred practice is to use separate statements for up to two references, and then to combine the links as logically as possible for three or more.
The goal is to make the references easy to find and follow. For example:
  
  <note role="References">
    <para>
      For more information, refer to the <citetitle>Graphical Installation</citetitle>, <citetitle>Remote Installation</citetitle>, and <citetitle>Automated Installation </citetitle> sections in the <citetitle>Red&nbsp;Hat Enterprise Linux 7 Installation Guide</citetitle> at <ulink url="https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html-single/installation_guide/index#chap-getting-started"/>
    </para>
  </note>
  

Note

For more information, refer to the Graphical Installation, Remote Installation, and Automated Installation sections in the Red Hat Enterprise Linux 7 Installation Guide at https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html-single/installation_guide/index#chap-getting-started
Should you legitimately need to point readers to something specific and unique, each in a different place within the same book, you may list them individually for clarity. However, be clear in your reference why you are listing each reference individually so that the reader understands why several individual references are being made to the same source.

Combining Multiple Reference Types

Follow the order and styles below when combining more than one reference type into one reference note. All references should be at the end of a section and consolidated into one reference note.
Info Nodes
Info nodes are referenced first. An info node should start with the command used to open the relevant info node, then the name of the node being opened in parentheses and <citetitle> tags. An itemized list with one element can be used to list a specific section of the info document.
<note role="References">
      <para>
        <code>info libc</code> (<citetitle>GNU C Library Reference Manual</citetitle>) <itemizedlist>
          <listitem>
            <para>Section 29.2: The Persona of a Process</para>
          </listitem>
        </itemizedlist>
      </para>
      </note>

Note

info libc (GNU C Library Reference Manual)
  • Section 29.2: The Persona of a Process
In some cases, an info node can be directly referenced by a shortcut. If we know that, we can direct the student there as follows:
<note role="References">
      <para>
        <code>info libc 'file name resolution'</code> (<citetitle>GNU C Library Reference Manual</citetitle>) <itemizedlist>
          <listitem>
            <para>Section 11.2.2: File name resolution</para>
          </listitem>
        </itemizedlist>
      </para>
      </note>

Note

info libc 'file name resolution' (GNU C Library Reference Manual)
  • Section 11.2.2: File name resolution
Man Pages
Man pages should be listed as a single, comma-separated list of items as shown below. The order of the man pages is at the discretion of the course author and project manager. The section of the manual for the man page must always be listed in parentheses after the man page, even if there is no man page of the same name in any other section of the online manual. The section number must be outside the <code> tag.
<note role="References">
      <para>
        <code>ls</code>(1), <code>mv</code>(1), and <code>su</code>(1) man pages
      </para>
      </note>

Note

ls(1), mv(1), and su(1) man pages
Yelp
When referencing a page from GNOME help, try to reference a command that can be used to bring up the exact page. Deep links to individual pages can be determined by looking in /usr/share/help/C in the gnome-help directory. Look for the XML files (*.page). Doing a grep -R for the title is easiest.
The tag format is a <para> with "GNOME Help: <emphasis>title</emphasis>, followed by a one-item itemized list with the direct command listed.
<note role="References">
      <para> GNOME Help: <emphasis>Getting Started with GNOME</emphasis>
        <itemizedlist>
          <listitem>
            <para>
              <code>yelp help:gnome-help/getting-started</code>
            </para>
          </listitem>
        </itemizedlist>
      </para>
      </note>

Note

GNOME Help: Getting Started with GNOME
  • yelp help:gnome-help/getting-started
An entire application yelp document can be referenced if needed as follows. If multiple sections from one yelp document are needed, referencing the whole document is preferred. If the whole document is referenced, do not reference individual sections as well.
<note role="References">
      <para> Vinagre Help <itemizedlist>
          <listitem>
            <para>
              <code>yelp help:vinagre</code>
            </para>
          </listitem>
        </itemizedlist>
      </para>
      </note>

Note

Vinagre Help
  • yelp help:vinagre
Local Documentation
URLs that point to documentation on web pages served by the machine appear next. This is rare; two examples are the CUPS help pages and the httpd-manual pages.
<note role="References">
      <para>
        <ulink url="http://localhost:631/help/">CUPS Online Help</ulink>
      </para>
      </note>
Knowledgebase and Customer Portal References
Knowledgebase articles are stable and should be referenced with a ulink to the article. Titles should be verified. If the article title does not match and seems wildly different, the author must validate that the article reference is correct.
<note role="References">
      <para>
        <ulink url="https://access.redhat.com/site/solutions/253273"> Knowledgebase: &quot;How to register and subscribe a system using Red Hat Subscription Manager&quot; </ulink>
      </para>
      </note>
Red Hat Documentation
See Red Hat Documentation Reference for information about creating these references.
Third-party References
Third-party (external, non-Red Hat) URL references go last. These should be used sparingly, and generally only when the site is truly an authority. For example, listing an IETF RFC when discussing the standard it sets makes sense. Pointing to the web site of an upstream project discussed in the chapter may be acceptable.
Sometimes you need to use example references, such as URLs on customer systems. In these cases you cannot use an active link. If you use a <uri> element instead of a <ulink> element in a Reference section, the standard formatting is not applied. The introductory text and the resulting dead link appear on the same line. You can use a <ulink> element with an empty url attribute to work around this issue.
<note role="References">
      <para>
        <ulink url="http://www.rfc-editor.org/rfcs/rfc2460.txt"> RFC 2460: Internet Protocol,
          Version 6 (IPv6) Specification</ulink>
      </para>
      <para>
        <ulink url="http://www.ntp.org/">NTP: Network Time Protocol</ulink>
      </para>
      <para>
        <ulink url="http://www.pool.ntp.org/en/use.html">NTP Pool Project: How do I use
          pool.ntp.org?</ulink>
      </para>
      </note>

Referencing Other Sections and Chapters

For information about mentioning sections and chapters of the same book you are currently writing, see the section called “Referencing Other Sections and Chapters”

Chapter 5. Interacting with the System

5.1. URI and URL

Use a <uri> element to identify example URLs, or URLs that are otherwise inaccessible in a classroom environment. This element creates a highlighted address but does not create an active link (that is, a dead link). Use a <ulink> element to create an active link to a URL. This includes links to any accessible documentation, bug reports, and so on.
You can use either of these elements as inline elements or as part of a block element, such as <note>.
Creating an Inactive Link
The following example illustrates the DocBook markup and output of an inline, inactive link:
<uri>http://samplelink.com</uri>
Output: http://samplelink.com
Creating an Active Link
The following example illustrates the DocBook markup and output of an active link in a <note> admonition:
<note role="References">
  <para>
    <ulink url="http://localhost:631/help/">CUPS Online Help</ulink>
  </para>
</note>

5.2. Code

In general, use <code> elements to identify code that students should examine.
<code>public class Plane</code>
Example Output: public class Plane
This also applies to more extensive examples, such as SQL queries:
<para>
  Use the following query to retrieve the required information:
</para>
<para>
  <code>SELECT student_name, subject1 FROM marks WHERE subject1 > AVG(subject1);</code>
</para>
The above example displays as follows:
Use the following query to retrieve the required information:
SELECT student_name, subject1 FROM marks WHERE subject1 > AVG(subject1);

Warning

The spell checker ignores the <code> element. Ensure that you manually inspect the contents of these elements for accuracy.
You can use <code> elements in a variety of places, for different purposes.
Highlighting Output
The <code> element is also used in <screen> and similar elements to highlight various parts of displayed output. Notice its use in the following example:
<screen>[user01@host]$ cd /etc/yum.repos.d
[user01@host yum.repos.d]$ ls
dropbox.repo  fedora.repo  <code>fedora-updates.repo</code>  fedora-updates-testing.repo</screen>
The above example displays as follows:
[user01@host]$ cd /etc/yum.repos.d
[user01@host yum.repos.d]$ ls
dropbox.repo  fedora.repo  fedora-updates.repo  fedora-updates-testing.repo

Note

If the output that you want to highlight is extensive or diverse, requires a description or further identification, consider using a calloutlist instead.
The following examples further illustrate the broad uses of code:
Syntax
Use the VARIABLENAME=value syntax to assign values to variables.
Editing Configuration Files
Remove the extension> entry and its corresponding subsystem> section from the configuration file.
Filenames and Directories
Switch directories to /etc/init.d/functions.
Namespaces
The other objects belong to the system or the flowers namespaces.
Registries
Log in to the OpenShift cluster, and then inspect the resources from the OpenShift internal registry and its operator in the openshift-image-registry project.
Roles
Create a data role called eu-customers and map it to the eu role.
Modules
Add the pam_tty_audit.so PAM module to the relevant configurations.
Classes
Typical classes might include hdd, ssd, or nvme.
Commands
This includes compound commands, commands that consist of a parent or root command, and subcommands
java -version
hammer user create --login user_name
Shell Scripts
The one.sh script produces the word one when executed. To change its output to two, open one.sh in a text editor, and change one to two.
Privileges (Root Command)
$ ssh student@remote-host ; sudo -i
Terminal and pseudoterminal names
Review tty2, tty3, pts/0, etc.
System Calls and Functions
The getcwd system call returns the current working directory to the application, and then write displays it to the screen.
Options and Arguments
Use the -l option to display a long directory listing.
Parameters
The standalone domain should be started as usual with an additional parameter, the jboss.node.name parameter, as well as providing the bind address.
Literals
Create a new API manually. Use Echo API and echo_api as the new API name and system name respectively.
Variables
Create two variables named SYSTEM_ACCESS_KEY and SYSTEM_SECRET_KEY.
Permissions
All unprivileged users will have a umask setting that causes new files to have a permission of -rw-rw---- and directories to have a permission of drwxrwx---.
Boolean Values
Set the use_nfs_home_dirs SELinux Boolean to 'true'.
Error Codes / Status Codes
On the Headers tab, verify that the Status Code is 200 OK.
Kernel and Related Capabilities
This behavior is configured by the crashkernel=auto setting.
Endpoints
When the reply from the hola-chained endpoint is immediate you know that the circuit is open and the fallback is invoked immediately.
Examples
Set the user's email address to user@example.com.

Note

Sometimes you need to have students run multiple, different commands. Include those commands and their output in the same <screen> element. Two exceptions exist: you need to run the commands on different machines, or the output of the first command is excessively long. In each of these cases, use separate <screen> elements.

5.3. User Input

Use the <userinput> element to indicate what a student should type.

Important

Where values that a user should type ought to be replaced, see Section 5.4, “Replaceable User Input”.
Consider the following example and the corresponding output:

Example 5.1. Identifying User Input

<screen>[user01@host ~]$ <userinput>cd /etc/yum.repos.d</userinput>
[user01@host yum.repos.d]$ <code>ls</code>
dropbox.repo  fedora.repo  fedora-updates.repo  fedora-updates-testing.repo</screen>
[user01@host ~]$ cd /etc/yum.repos.d
        [user01@host yum.repos.d]$ ls
        dropbox.repo  fedora.repo  fedora-updates.repo  fedora-updates-testing.repo

5.4. Replaceable User Input

Use the <replaceable> element to mark a certain part of a <screen> or <code> element for replacement. Consider the following example and corresponding output, where the student is required to substitute their station number for "X." In this example, the student is on station 10:

Example 5.2. Identifying Replaceable Input

<screen>[user01@station10 ~]$ <code>ping station<replaceable>X</replaceable></code>
PING station10 (10.1.1.61) 56(84) bytes of data.
64 bytes from station10 (10.1.1.61): icmp_seq=1 ttl=64 time=0.082 ms
64 bytes from station10 (10.1.1.61): icmp_seq=2 ttl=64 time=0.086 ms
^C
--- station10 ping statistics ---
2 packets transmitted, 2 received, 0% packet loss, time 15ms
rtt min/avg/max/mdev = 0.082/0.084/0.086/0.002 ms</screen>
[user01@station10 ~]$ ping stationX
PING station10 (10.1.1.61) 56(84) bytes of data.
64 bytes from station10 (10.1.1.61): icmp_seq=1 ttl=64 time=0.082 ms
64 bytes from station10 (10.1.1.61): icmp_seq=2 ttl=64 time=0.086 ms
^C
--- station10 ping statistics ---
2 packets transmitted, 2 received, 0% packet loss, time 15ms
rtt min/avg/max/mdev = 0.082/0.084/0.086/0.002 ms
To refer to a path that students need to replace with something specific to their system, use <replaceable> tags, with the correct syntax for the system and object in question, and an indicative name.
If you are referring to a different object class or type with different delimiters, use the appropriate delimiters. For example, a PATH variable for Bash:
<replaceable>/usr/bin:/usr/local/bin</replaceable>
Or a package path in Lua:
<replaceable>local.share.lua</replaceable>

5.5. Application Names

Use the <code> element for human-facing application names, such as those that GNOME presents in the UI. Often, this is literally the value of the name field in a .desktop file. Also use the <code> element for the literal executable name of an application that either has no .desktop file, or for which a .desktop file would be unreasonable, or when you are specifically referring to a command.
<para>
  The <code>FFmpeg</code> project does not provide a desktop launcher or a GUI.
  To convert the footage for this exercise, open a terminal and type <code>ffmpeg -i slug.mp2 slug.mp4</code>.
  It is standard industry protocol that while <code>FFmpeg</code> is running, you are expected to go get a cup of coffee whilst loudly declaring to your coworkers that your work is rendering.
</para>
Using <code> is also appropriate to describe applications defined or developed as part of courseware. For example: Deploy the <code>hello-openshift</code> application.

5.6. Product Names

Do not tag product names, such as Red Hat Enterprise Linux, OpenStack, JBoss, and so on.

Note

If you are unsure about how to correctly write or abbreviate a product name, refer to Master product and solution names list .

5.7. Identifying System Output

Use <screen> elements to represent output that will appear on a student's terminal, or if you need to string together multiple lines of code or commands. You can also use CDATA (character data) sections within <screen> elements, which has the benefit of preventing XML errors from displaying characters that would otherwise need to be escaped.
CDATA is written similarly to a comment: <![CDATA[Your XML elements are here but you need to use entities to actually <emphasis>display</emphasis> them.]]>

Note

You cannot use CDATA if you need to display XML elements, for example to demonstrate syntax in a configuration file.
Use a Bash prompt containing the user and host names to remind the reader where the command is being run. Keep the prompt as minimal as possible, to avoid confusing the reader or filling up an entire line with just the prompt. For example:
<prompt>[user01@host ~] $ </prompt><userinput>cd /etc/yum.repos.d</userinput>
<prompt>[user01@host yum.repos.d] $ </prompt><userinput>ls</userinput>
dropbox.repo  fedora.repo  fedora-updates.repo  fedora-updates-testing.repo
Example output:
[user01@host ~] $ cd /etc/yum.repos.d
[user01@host yum.repos.d] $ ls
dropbox.repo  fedora.repo  fedora-updates.repo  fedora-updates-testing.repo
<screen> elements respect white space. Thus, any newline characters, tabs, or other white space you place in a <screen> element is printed as-is.
As in a Bash script or command, use the backslash (\) symbol to extend a single command across multiple lines. If a single command extends beyond 80 characters, then it may not wrap properly in HTML or PDF, so use line breaks as needed. Try to break commands into logical chunks, for example:
[user@host ~]$ oc process mysql-persistent -n openshift \
> -v MYSQL_USER=dev -v MYSQL_PASSWORD=$P4SSD -v MYSQL_DATABASE=bank \
> -v VOLUME_CAPACITY=10Gi | oc create -f -
To avoid very long lines in code samples, abbreviate UUIDs, SHAsums, hashes, and other long computations. Shorten the lines in a text table in an attempt to fit it within a traditional 80-character line limit. For example, instead of writing:
  [user01@host]$ awk 'BEGIN { FS="=" } /UUID/ { print $2 }' /etc/fstab
  98d0ce6b-c381-4902-b713-3e49f5465ef4 /boot                   ext4    defaults        1 2
  4f5465ef-c381-4902-b713-74d0de6b2e1  /var                    ext4    defaults        1 2
Use the first four and last four characters of the string, separated by an ellipsis:
  [user01@host]$ awk 'BEGIN { FS="=" } /UUID/ { print $2 }' /etc/fstab
  98d0...5ef4 /boot  ext4   defaults  1 2
  4f54...b2e1 /var   ext4   defaults  1 2

5.8. Recommended Practices for Remote Logins

When you instruct students to perform tasks as root on a remote host, first have them log in as the student user or another unprivileged user. They can then use sudo or su - to escalate their privileges. This encourages students to adopt best practices by helping to circumvent several audit and security concerns:
  • Logging in as root leaves no trail of who actually logged in to make changes. The system only records that the root user logged in. If you log in as an unprivileged user and escalate your privileges then the system records who logged in and may log that information elsewhere.
  • The SSH port is routinely scanned by attackers and passwords attempted on that port. If root logins are allowed, then it is possible for someone to get that password and use it to log in as root directly. It is a faster route to compromise, and is also a known account to probe.
  • If users require sudo to escalate to root then they do not need to know the actual root user password, only their own. There are trade-offs with this approach but the sudo configuration can limit what they can run.
  • It is easier to drop privileges (back to the user account) when you no longer need them; you do not need to log out.

5.9. Using Other Operating Systems

Use a leading slash (/) if the absolute path is required. For example, on Linux systems:
Mount the ISO file in <code><replaceable>/path/to/iso/file</replaceable></code>.
For example, on Windows systems:
Mount the ISO file in <code><replaceable>C:\path\to\iso\file</replaceable></code>.
Most examples in RHT courses use the Bash shell. For some courses and examples, you need to refer to a different shell or environment, such as the Microsoft Windows command shell (cmd.exe). In these cases, you need to use the associated command prompts, line break, and line continuation characters.
RHT courses currently assume that students use cmd.exe as the default shell, and not the PowerShell equivalent. However, the basic rule for prompts and userinput in a screen showing a computer terminal session is to duplicate what students see. The Bash shell uses the backslash character (\) and the greater-than symbol (>) to indicate line breaks and line continuation, respectively. The Windows command shell uses the caret symbol (^) and "More?" for the same purpose. Construct your examples to take these and any other differences into account.
The following two examples illustrate how to mark up a very similar command in two different command shells; Bash on Red Hat Enterprise Linux and cmd.exe on Windows. An approximate rendition of each is shown below the DocBook markup:

Example 5.3. Wrapping Long Commands in Bash

<prompt>[user@host ~] $ </prompt><userinput>traceroute -m 100 -w 2000 \</userinput>
<prompt>&gt; </prompt><code>www.google.com</userinput>
[user@host ~] $ traceroute -m 100 -w 2000 \
> www.google.com

Example 5.4. Wrapping Long Commands in Microsoft Windows

<prompt>c:\Users\user01&gt;</prompt><userinput>tracert -h 100 -w 2000 ^</userinput>
<prompt>More? </prompt><code>www.google.com</code>
c:\Users\user01>tracert -h 100 -w 2000 ^
More? www.google.com

5.10. Using Shortcuts, Keycombos, and Keycaps

A keycombo is a key combination that you type on the keyboard. It consists of keycap items, each one a key on the keyboard. These are inline elements, so they can be used in running text. The following example shows a keyboard shortcut for a GUI menu item:
<menuchoice>
  <shortcut>
    <keycombo>
      <keycap>Ctrl</keycap>
      <keycap>N</keycap>
    </keycombo>
  </shortcut>
  <guimenu>GLSPublican</guimenu>
  <guisubmenu>Link</guisubmenu>
  <guimenuitem>Insert URI</guimenuitem>
</menuchoice>.
This renders as GLSPublicanLinkInsert URI (Ctrl+N).
When describing which keys to press, capitalize the first letter of modifier keys such as Super, Shift, Ctrl, and so on. If a key combination requires that the Shift key be pressed, list the Shift key explicitly.
In other words, Ctrl+Shift+N correctly instructs the reader to press Ctrl and Shift and N together, while Ctrl+n only conveys Ctrl and n.

5.11. Recommended Practices for Remote Logins

This section explains why we prefer to use unprivileged remote logins instead of root logins, and to use sudo or su -i to escalate privileges as required. For example:

Example 5.5. Correct

$ ssh student@remote-host ; sudo -i
Avoid using the root login approach:

Example 5.6. Incorrect

$ ssh root@remote-host
When you instruct students to perform tasks as root on a remote host, first have them log in as the student user or another unprivileged user. They can then use sudo or su - to escalate their privileges. This encourages students to adopt best practices by helping to circumvent several audit and security concerns:
  • Logging in as root leaves no trail of who actually logged in to make changes. The system only records that the root user logged in. If you log in as an unprivileged user and escalate your privileges then the system records who logged in and may log that information elsewhere.
  • The SSH port is routinely scanned by attackers and passwords attempted on that port. If root logins are allowed, then it is possible for someone to get that password and use it to log in as root directly. It is a faster route to compromise, and is also a known account to probe.
  • If users require sudo to escalate to root then they do not need to know the actual root user password, only their own. There are tradeoffs with this approach but the sudo configuration can limit what they can run.
  • It is easier to drop privileges (back to the user account) when you no longer need them; you do not need to log out.

Note

In some cases it might still be necessary to log in as the root user. In these cases you should consider setting up SSH keys to avoid password-based authentication.

Chapter 6. Representing GUI Objects

The nature and scope of graphical user interface (GUI) objects is steadily expanding and it is often difficult to determine if something is a menu, a button, a list, a link, or some combination of those.
Some GUI designs use object types that do not appear to have any suitable DocBook class. This chapter clarifies which element to use, and when.

6.1. Comparing Graphical, Terminal, and Browser-based User Interfaces

A graphical user interface (GUI) traditionally refers to a graphical element displayed by a graphical server, such as X11 or Wayland. For instructional purposes, however, GUI also includes the Terminal User Interface (TUI) and the browser-based user interface (web UI). A TUI and a web UI conceptually use the same elements as a GUI, such as buttons, menus, lists, and so on. For that reason, a TUI and a web UI can safely be described by Docbook using the same conventions as describing a GUI.
The cfdisk application is an example of a TUI.
cfdisk is an example of a TUI

6.2. Referring to Menus and Submenus

Use the <menuchoice> element and the appropriate children to represent a GUI menu selection that students need to follow to accomplish a task. Consider the following illustration, which demonstrates how to replace a string in GNU Emacs:
Selecting the menu item to replace a string in GNU Emacs.
An example of a GUI menu
To represent this menu navigation, use the following markup:
<menuchoice>
  <guimenu>Edit</guimenu>
  <guisubmenu>Replace</guisubmenu>
  <guimenuitem>Replace String</guimenuitem>
</menuchoice>
This renders as EditReplaceReplace String.

Note

  • The <menuchoice> element automatically inserts the navigation indicators (→). You do not need to enter them manually.
  • The manual line breaks in the Docbook markup are recommended for readability. They do not affect the actual render.
In general, wrap the entire path in <menuchoice> elements, use one <guimenu> element for the first level, one <guimenuitem> for the last level, and one or more <guisubmenu> entries for the middle levels.
Red Hat OpenShift Container Platform provides an example of a web UI. Some of the button, menu, and other elements display slightly differently from typical GUI and TUI designs, but the same DocBook elements are used. Consider the following example:

Example 6.1. Navigating Menus in a web UI

Navigating the menus in OpenShift Container Platform.
Navigating the menus in OpenShift Container Platform
To describe the navigation path in Example 6.1, “Navigating Menus in a web UI”, use wording and markup similar to the following:
<para>
In the Red&nbsp;Hat OpenShift Container Platform (RHOCP) web UI, click <menuchoice>
  <guimenu>Builds</guimenu>
  <guimenuitem>Images</guimenuitem>
  </menuchoice> to display the <guilabel>Image Streams</guilabel> page.
</para>
This renders as shown below:
In the Red Hat OpenShift Container Platform (RHOCP) web UI, click BuildsImages to display the Image Streams page.

6.3. Referring to UI Labels, Fields, and Buttons

The <guilabel> and <guibutton> elements are self-explanatory. They should enclose the text that makes up a label in a UI, or the text on a button in a UI. Both are common in <task> elements, because they represent either a label on a text box or area where students need to enter, or a button that students need to click.

Chapter 7. Describing Sets of Data

RHT courses often involve programming in a variety of languages, configuration files in a variety of formats, and references to data from many different sources. It is useful to have metadata, in the form of DocBook tags, about the elements being described, but the wide assortment of different formats and contexts can make it confusing when selecting the best DocBook tag.

7.1. Configuration Files

A configuration file is often a collection of key and value pairs which, when imported into an application or script, become variables and values. RHT uses the <code> element in both cases.
In the configuration file, set the value of <code>rsync</code> to <code>True</code>.
Sometimes a configuration format features other elements, such as groups or headers. Treat these as unassigned values, using the <code> element:
In the configuration file, create a new section named <code>[Hosts]</code>.

Note

Include the associated section or header syntax (%, #, [], and so on) inside the <code> element.
If a configuration file does not logically have a variable name, then default to the <code> element, because usually you are referring to the literal value contained within the text of a configuration file rather than what that text resolves to when the code using the value is being executed.
Create a new YAML file and enter <code>pre-commit:</code> as the initial value.
Under <code>pre-commit:</code>, add <code>checkout: true</code>.

7.2. Databases

The nature of data contained in a database can vary even more than in configuration files. RHT uses the <code> element in these cases, which covers both the literal value of the data and what the data represents. For example:
Join the content of the first record, <code>GNU</code>, with the content of the second record, <code>Linux</code>, to complete the project.

Chapter 8. Conditional Tagging

Using conditional tags in a RHT course.

8.1. Conditional tagging

Adding the condition="ilt" attribute to an element ensures that only that element and its children are rendered in an ILT build. The same applies for the condition="role" attribute and ROLE builds. Any text referring to instructors should appear only in ILT, not ROLE. An example is the element we use for videos (see the media section). The following example applies to labs:
<task condition="ilt" role="Checklist">
<emphasis>...output omitted...</emphasis>
</task>
<task condition="role" role="Resequence">
<emphasis>...output omitted...</emphasis>
</task>
If the procedure only contains one or two steps, apply the condition to the element, otherwise include two separate labs with conditions.

Important

If you refer to videos in paragraph text, use condition="rolehtml" and not condition="role". Text marked with condition="role" appears in ROLE PDF files, which is not the desired result.

Important

You might find condition="ilt, vt" in older content. You must update these to condition="ilt" because commas are not allowed in publican on RHEL 7.
You cannot put a condition on the top-level element in a file. This causes issues with xi:include elements and publican will probably fail. Neither can you put a condition on an xi:include element.

Note

Hint: You can use "flamel rolesg" to build a PDF version of the ROL material.

Chapter 9. Using ID Attributes

This chapter covers conventions for ID attributes in RHT courses.

9.1. Using ID Attributes

To support tracking items on Red Hat Academy (RHA), some DocBook elements need unique IDs in an id attribute. Use the following guidelines to create unique IDs. Remember that your build will either fail or produce warnings if any IDs are duplicated.

Creating a New Course

Add IDs to the following tags using the conventions shown:
  • <book id="sku-SG"> for student guide
  • <book id="sku-IG"> for instructor guide
  • <chapter id="shortchaptername">
  • <section id="shortsectionname">
    This only applies to top-level sections. ID attributes on other section levels are only required if you need to link to them.
  • <itemizedlist id="shortname"> (optional)
  • <mediaobject id="topic-shortname">
  • <co id="topic-id">
  • <task id="topic-id">
  • <qandaentry id="questionx">
  • <callout id="calloutx">

Updating Existing Courses

When updating existing courses, keep any existing IDs. If no IDs exist, then add them as shown in the section called “Creating a New Course”.

Reusing Content in a New Course

When reusing unmodified content from another course in a new course, keep the IDs intact. If major changes are made, update the ID to reflect the new content. It may make sense to keep the topic part the same, but the subtopic and ID part should change.

Example 9.1. Example of Section ID Attribute

A section ID could appear as <section id="lvm-basics"> or <section id="cgroups-create">, which indicate a topic and subtopic.
For subjects where more sections might be written about the topic, you can add an extra qualifier.

Example 9.2. Example of Task ID Attribute

A task ID could appear as <task id="lvm-basics-practice">.

Referencing Other Sections and Chapters

When you reference another section or chapter, use the <xref> tag. Our courses are designed to be modular, so avoid qualifying language such as a previous section or an earlier chapter and so on. For example, instead of writing Supported tags can be found in the earlier chapter, Supported Tags, write this:
  Supported tags are listed in <xref linkend="supported-yes" />.
The <xref> reference is replaced with its title content, as a hyperlink to the corresponding section, during the document render:
Supported tags are listed in Section 2.1, “List of Supported Tags”.

Chapter 10. Other DocBook Elements

This section covers DocBook elements that are used infrequently, and not with any particular task or presentation.
In general, it is better to allow Publican to generate the formatting as much as possible, but there are some cases when the following tags are needed.

10.1. Using Subscripts, Superscripts, and Copyright and Trademark Symbols

The <subscript>, <superscript>, and <trademark> tags are fairly self explanatory. Some examples are provided below. Note that the DocBook layout is designed for readability; the actual rendition is shown below.
<trademark class="registered">Linux</trademark>,
<trademark class="copyright">JBoss</trademark>,
<trademark>Java</trademark>,
e = mc<superscript>2</superscript>,
H<subscript>2</subscript>O
The default attribute for the class attribute is trade. The rendering of various classes is shown below:
Linux®, JBoss©, Java™, e = mc2, H2O

Note

For more information about the correct use of trademark and copyright symbols, see https://mojo.redhat.com/docs/DOC-999829

10.2. Using Blockquotes

A <blockquote> represents text that is to be offset from the general flow of the other text, most commonly a long running quote from other material. Use sparingly. In general, any text of this nature should trigger a <note>, <warning> or <important> admonition.

10.3. Using Email Addresses

It is not common that you should need the <email> element, but it is available, as shown below.
<screen><email>samplemail@example.com</email></screen>

10.4. Quotation marks

This tag makes it simple to translate quotes into different languages, which may use different punctuation.
<quote>Sample Quote</quote>
Sample Quote

Chapter 11. Presentation Methods

This chapter outlines XML tagging examples for presentation methods used in RHT courses.

11.1. Standard Lecture

A standard lecture contains text and supporting graphics when needed. Use a nested section element as the first subsection under a section, and one more nested section element if you need to descend another level. Do not exceed two levels of nesting.

11.1.1. Standard Lecture Example XML

<section><title>Introducing Package Documentation</title>

      <para>
        In addition to <code>man</code> and <code>pinfo</code>, developers may also choose to include documentation in their application's RPM distribution package.
        When the package is installed, files recognized as documentation are moved to <code>/usr/share/doc/<replaceable>packagename</replaceable></code>.
        Software package builders may include anything deemed helpful as a complement to, but not duplicating, <code>man</code> pages.
        GNU packages also use <code>/usr/share/doc</code> to supplement info nodes.
      </para>

      <para>
        Most packages include files describing package distribution licensing.
        Some packages include extensive PDF- or HTML-based documentation.
        Accordingly, a useful package browsing method is pointing a browser to <uri>file:///usr/share/doc</uri> and using a mouse.
      </para>

  <screen><prompt>[&stu;@&ex_dsk1; ~]$ </prompt> <code>firefox file:///usr/share/doc</code></screen>

      <para>
        Some packages come with extensive examples, configuration file templates, scripts, tutorials, or user guides.
        Browse <code>/usr/share/doc/vsftpd-*</code> as an example.
        Some documentation is sparse; the <package>zip</package> utility includes the compression algorithm used and little else.
        Other packages includes large user manuals or developer guides, or electronic copies of related, published books.
      </para>

      <note>
        <para>
          The kernel itself has a significant documentation package.
          The <package>kernel-doc</package> package is a treasure of kernel, driver, tuning, and advanced configuration information.
          Experienced system administrators regularly research <package>kernel-doc</package> files.
        </para>
      </note>

      <note role="References">
        <para>
          <code>hier</code>(7) man page <itemizedlist>
            <listitem>
              <para>
                Discusses the hierarchy of Linux directories, including <code>/usr/share/doc</code>.
              </para>
            </listitem>
          </itemizedlist>
        </para>
      </note>
    </section>

11.1.2. Standard Lecture Example Render

The following is an approximate rendition of the XML example shown above.

11.1.2.1. Introducing Package Documentation

In addition to man and pinfo, developers may also choose to include documentation in their application's RPM distribution package. When the package is installed, files recognized as documentation are moved to /usr/share/doc/packagename. Software package builders may include anything deemed helpful as a complement to, but not duplicating, man pages. GNU packages also use /usr/share/doc to supplement info nodes.
Most packages include files describing package distribution licensing. Some packages include extensive PDF- or HTML-based documentation. Accordingly, a useful package browsing method is pointing a browser to file:///usr/share/doc and using a mouse.
[student@desktop1 ~]$ firefox file:///usr/share/doc
Some packages come with extensive examples, configuration file templates, scripts, tutorials, or user guides. Browse /usr/share/doc/vsftpd-* as an example. Some documentation is sparse; the zip utility includes the compression algorithm used and little else. Other packages includes large user manuals or developer guides, or electronic copies of related, published books.

Note

The kernel itself has a significant documentation package. The kernel-doc package is a treasure of kernel, driver, tuning, and advanced configuration information. Experienced system administrators regularly research kernel-doc files.

Note

hier(7) man page
  • Discusses the hierarchy of Linux directories, including /usr/share/doc.

Chapter 12. Engagement Methods

This chapter outlines XML tagging examples for methods that actively engage students and test their knowledge.

12.1. Usage Guidelines

Follow these guidelines for incorporating engagement methods into RHT courses:
  • Every presentation section must be followed by a guided exercise section, which can be a guided exercise or quiz (matching, multiple-choice, or resequencing).
  • Every chapter must end with a lab contained in its own section.
  • Certification-based courses should end with a comprehensive review chapter.

Important

Be aware that new and revised courses should not include fill-in-the-blank quizzes; they have been phased out. For knowledge tests, use the new templates for matching, multiple-choice, or resequencing quizzes instead. If you need assistance planning this approach, contact Content Services.

12.1.1. Title Conventions

Guided exercise, lab, and review titles should follow the naming conventions listed below:
Course Title
    Chapter One Content Title
         Section One Content Title
         Guided Exercise: [Section One Content Title] or Lab: [Section One Content Title] or Quiz: [Section One Content Title]
         Section Two Content Title
         Guided Exercise: [Section One Content Title] or Lab: [Section One Content Title] or Quiz: [Section One Content Title]
     Lab: [Chapter One Content Title]
Comprehensive Review

12.1.2. Procedure

While it is legal within DocBook for procedures to contain <xref> elements, the current Red Hat XSL style sheet cannot resolve an <xref> in a <procedure>. For that reason, do not use the <xref> element within a <procedure>.

12.1.2.1. Steps

Ideally, a step is an atomic, singular action within a process. Do not put a preamble about why a step is being taken inside the <step> tag. Explanations and background information can be placed inside the <procedure> tag, but before a <step> For example:

<procedure>
  <para>
    You must update the project first, and then create a new branch.
  </para>

  <step>
    <para>
      Change directory to your project folder.
    </para>

    <screen>
<![CDATA[
$ cd project.git
]]&#62;</screen>
  </step>

12.1.3. Solution Usage

The brand displays solutions in the Student Guide directly following the blank version. As the XML examples illustrate, all solutions need the attribute role="solution" to display. Use the following solution guidance depending on the type of engagement method:
  • Guided Exercise: Guided exercises are at the end of a section and should include steps for the student to complete the assignment as well as detailed instructions on how to execute those steps, so no solution is needed.
  • Quizzes: Quizzes always require solutions.
  • Lab: A chapter lab is derived from the combined practices for all sections in a chapter and should include only the steps for the student to complete with no additional instructions. Whenever possible, build your end-of-chapter lab around an example, analogy, simulation, or case study that directly relates to the task being taught.
  • Comprehensive Review: A review is at the end of a course and consists of situational task assignments without instructions, therefore solutions are required. Write an end-of-course comprehensive review to prove your student’s ability to solve a real-world problem using the solutions taught and practiced in the course.

Important

Do not use <informalexample> because it triggers solution boxes in ROLE (but not in the PDF). It was used in practices for previous courses, but we do not want the ROLE behavior now, so remove it as you come across it.

12.2. Guided Exercise Overview and XML

A guided exercise is a performance-based type of exercise included at the end of a section that explicitly walks the student through the steps of a task with complete instructions. Because all instructions are included, solutions are not needed.
Guided Exercise XML
The first part of the file includes the task summary, outcomes, and prerequisites:
<section>
  <title>Guided Exercise: Sample Title</title>
<!-- Task should have id that is short version of topic -->
  <task role="Checklist" id="topic-practice">
    <title>Can't be empty, won't be used</title>
    <tasksummary>
      <para>
        In this lab, you will .....
      </para>

      <formalpara>
        <title>Outcomes</title>
        <para>
          List outcomes.
        </para>
      </formalpara>
    </tasksummary>
    <taskprerequisites>
      <para>
        List prerequisites.
      </para>
    </taskprerequisites>
The next part of the file outlines the steps in the procedure:
<procedure>
   <title>Steps</title>
      <step>
        <para>
          Sample instructions, include solutions. We are holding hands here.
        </para>
        <substeps>
          <step>
            <para>
              Substep One
            </para>
          </step>
          <step>
            <para>
              Substep Two
            </para>
            <para>
              You can include output in <screen> elements. If you need to omit some output that is not relevant, use the format <emphasis>...output omitted...</emphasis>. Note: if this produces questionable output, consult with your scrum master and architect.
            </para>
<screen>The first part of the output.
<code>The important part of the output.</code>
The last part of the output. Everything after this is mostly irrelevant.
<emphasis>...output omitted...</emphasis>
          </step>
        </substeps>
      </step>
      <step>
        <para>
          More Sample instructions
        </para>
        <substeps>
          <step>
            <para>
              You don't have to use these substeps.
            </para>
          </step>
          <step>
            <para>
              Try to limit the number of substeps to six.
            </para>

          </step>
        </substeps>
      </step>
    </procedure>
The last part of the file concludes the exercise:
    <taskrelated>
      <formalpara>
        <title>Finish</title>
        <para>
          On the <code>workstation</code> machine, use the <code>lab</code> command to complete this exercise.
          This is important to ensure that resources from previous exercises do not impact upcoming exercises.
        </para>
      </formalpara>
      <screen><prompt>[student@workstation ~]$ </prompt><userinput>lab chapter-topic finish</userinput></screen>
    </taskrelated>
  </task>
</section>

Important

Do not use sub-substeps. Keep steps to two levels.
Rendering shown in the next section.

12.3. Sample Guided Exercise

Must exist but is not used.

In this lab, you will ...
Outcomes
You should be able to...xxx
List prerequisites.
  1. Sample instructions, include solutions. We are holding hands here.
    1. Substep One
    2. Substep Two
      You can include command or other output in <screen> elements. If you need to omit some output that is not relevant, use the format <emphasis>...output omitted...</emphasis>. Note: if this produces questionable output, consult with your scrum master and architect.
      The first part of the output.
      The important part of the output.
      The last part of the output. Everything after this is mostly irrelevant.
      ...output omitted...
  2. More Sample instructions
    1. You can use substeps to clarify procedures.
    2. Avoid using more than six substeps. Do not use sub-substeps.
Finish
On the workstation machine, use the lab command to complete this exercise. This is important to ensure that resources from previous exercises do not impact upcoming exercises.
[student@workstation ~]$ lab chapter-topic finish

12.4. Guided Exercise - Multiple Tasks

A guided exercise may be split into multiple tasks with tailored procedures where the format makes sense for the class and user experience.
All of the rules for regular guided exercises stand. The structure differs only in a few key ways:
  • Use multiple <task> elements for each procedure needed. Ensure this element has a unique @id as well as @role='Checklist'.
    <tasksummary> and <taskprerequisites> are retained only in the first <task>. Even though these elements are only in the first task, the content provides coverage for all tasks in the GE.
    <taskrelated> is retained only in the second <task>. Even though this element isonly in the second task, the content provides coverage for all tasks in the GE.
Rendering shown in the next section.

12.5. Sample Guided Exercise with Multiple Tasks

In this exercise, you will...
Outcomes
You should be able to list of outcomes.
Sample prerequisites.
As the student user on the workstation machine, use the lab command to prepare your system for this exercise.
This command ensures that ...
[student@workstation ~]$ lab chapter-topic start

Procedure 12.1. Part 1

  1. Sample instructions for Part 1
    1. Substep one.
  2. More sample instructions.
    1. You do not have to use these substeps.
    2. Limit substeps to six or fewer. Do not use sub-substeps.

Procedure 12.2. Part 2

  1. Sample instructions for Part 2
    1. Substep one.
  2. Additional instructions.
Finish
On the workstation machine, use the lab command to complete this exercise. This is important to ensure that resources from previous exercises do not impact upcoming exercises.
[student@workstation ~]$ lab chapter-topic finish
This concludes the section.

12.6. Resequencing Quiz Overview and XML

A resequencing quiz is a type of practice that gives students a list of items in incorrect order, and asks them to identify the correct order. This is particularly useful to review a procedure that has been presented by the instructor in order to reinforce the broad procedure without dwelling on the fine details of execution.
Resequencing Quiz XML
<!-- Section should have id that is short version of title -->
<section id="shortsectionname-resequence">
  <title>Quiz: Resequence Title</title>
  <!-- Task should have id that is short version of topic -->
  <task role="Resequence" id="topic-resequence">
    <title>Can't be empty, won't be used</title>
    <!-- Modify the directions to describe your quiz and include "Indicate the order the steps should be taken." -->
    <tasksummary>
      <para> The steps to (fill in the blank) are shown below. Indicate the order the steps should
        be taken. </para>
      <para condition="rolehtml"> Drag and drop the items into the correct order. When you have
        completed ordering the items, click <guilabel>check</guilabel>. Your correct answers will
        have a blue background and your incorrect answers will be crossed out. If you wish to try
        again, click <guilabel>reset</guilabel>. Click <guilabel>show solution</guilabel> to see
        all of the correct answers. </para>
    </tasksummary>
    <procedure role="solution">
      <step role="2">
        <para> Sample step 2 </para>
      </step>
      <step role="6">
        <para> Sample step 6 </para>
      </step>
      <step role="4">
        <para> Sample step 4 </para>
      </step>
      <step role="3">
        <para> Sample step 3 </para>
      </step>
      <step role="1">
        <para> Sample step 1 </para>
      </step>
      <step role="7">
        <para> Sample step 7 </para>
      </step>
      <step role="5">
        <para> Sample step 5 </para>
      </step>
    </procedure>
  </task>
</section>
Rendering shown in the next section.

12.7. Resequence Title

Can't be empty, won't be used

The steps to (fill in the blank) are shown below. Indicate the order the steps should be taken.
Drag and drop the items into the correct order. When you have completed ordering the items, click check. Your correct answers will have a blue background and your incorrect answers will be crossed out. If you wish to try again, click reset. Click show solution to see all of the correct answers.
  1. Sample step 2
  2. Sample step 6
  3. Sample step 4
  4. Sample step 3
  5. Sample step 1
  6. Sample step 7
  7. Sample step 5

12.8. Matching Quiz Overview and XML

A matching quiz matches items in one list to items in another list. It is useful for mapping terms to definitions, options to effects, and items like the names of various firewall chains to their purpose/the packets they affect.
The tagging is a procedure with one step containing an informal table. All column entries with role="solution"will appear blank, and students will choose from solutions listed above the table in alphabetical order. Options include:
  • Additional columns (the table is not limited to two columns)
  • Blanks from a different column
  • Optional table headings
Matching Quiz XML
The first part of the file contains the title and task summary:
 <!-- Section should have id that is short version of title -->
<section id="shortsectionname-matching">
  <title>Quiz: Matching Quiz Sample Title</title>

  <!-- Task should have id that is short version of topic -->
  <task role="Matching" id="topic-matching">
    <title>Titles are still mandatory, but replaced by the stylesheet</title>
    <tasksummary>
      <para> Match the items below to their counterparts in the table. </para>
      <para condition="rolehtml"> Drag and drop the items to the cell next to the correct answer. Each cell should contain one answer. If you want to change an answer, either drag it to another location, or click <guilabel>reset</guilabel> to return the quiz to its original settings. </para>
      <para condition="rolehtml"> When you have completed the quiz, click <guilabel>check</guilabel>. Your correct answers will have a blue background and your incorrect answers will be crossed out. If you want to try again, click <guilabel>reset</guilabel>. Note: If you have trouble getting the quiz to function a second time, try refreshing your browser. Click <guilabel>show solution</guilabel> to see all of the correct answers. </para>
    </tasksummary>
The next part of the file contains the procedure:
<procedure>
      <step>
        <informaltable frame="all">
          <tgroup cols="2">
            <colspec colname="c1" colnum="1" colwidth="1.0*"/>
            <colspec colname="c2" colnum="2" colwidth="2.0*"/>
            <thead>
              <row>
                <entry>Project</entry>
                <entry>Technology</entry>
              </row>
            </thead>
            <tbody>
              <row>
                <entry> Red Hat </entry>
                <entry role="solution"> Ansible </entry>
              </row>
              <row>
                <entry> GNU </entry>
                <entry role="solution"> libc </entry>
              </row>
              <row>
                <entry> KDE </entry>
                <entry role="solution"> Plasma </entry>
              </row>
              <row>
                <entry> Mozilla </entry>
                <entry role="solution"> Firefox </entry>
              </row>
              <row>
                <entry> FreeDesktop.org </entry>
                <entry role="solution"> colord </entry>
              </row>
              <row>
                <entry> OpenBSD </entry>
                <entry role="solution"> OpenSSH </entry>
              </row>
            </tbody>
          </tgroup>
        </informaltable>
      </step>
    </procedure>
  </task>
</section>

12.9. Matching Quiz Sample Title

Titles are still mandatory, but replaced by the style sheet

Match the items below to their counterparts in the table.
Drag and drop the items to the cell by the correct answer. Each cell should contain one answer. If you wish to change an answer, either drag it to another location, or click reset to return the quiz to its original settings.
When you have completed the quiz, click check. Your correct answers will have a blue background and your incorrect answers will be crossed out. If you want to try again, click reset. Note: If you have trouble getting the quiz to function a second time, try refreshing your browser. Click show solution to see all of the correct answers.
  • ProjectTechnology
    Red Hat Ansible
    GNU libc
    KDE Plasma
    Mozilla Firefox
    FreeDesktop.org colord
    OpenBSD OpenSSH

12.10. Multiple-choice Overview and XML

Multiple-choice questions provide a valid, reliable, and economical measurement of a wide range of content in a relatively short testing time. Multiple-choice questions, while harder to write, tend to be more effective than matching questions when you need to test a student's ability to interpret facts, evaluate situations, explain cause and effect, make inferences, and predict results.

Note

For guidance on creating multiple-choice questions, see GLS Multiple-choice Writing Guidelines
The questions in the following example illustrate these types of questions:
  1. Single correct response
  2. Multiple correct responses
  3. Includes an exhibit
Multiple-choice XML
The first part of the file shows the title and instructions:
<!-- Section should have id that is short version of title -->
<section id="shortsectionname-multchoice">
<title>Quiz: Multiple-choice Sample Title</title>

<!-- Tasks should have an id that is a short version of the topic -->
<task role="MultChoice" id="topic-multchoice">
    <title>will not show</title>
    <tasksummary>
        <para> Choose the correct answer to the following questions: </para>
        <!--  <para condition="role"> When you have completed the quiz, click <guilabel>check</guilabel>. If you want to try again, click <guilabel>reset</guilabel>. Click <guilabel>show solution</guilabel> to see all of the correct answers. </para>-->
    </tasksummary>
The next part of the file shows a question with one correct answer:
<procedure>
<step>
    <qandaset>
    <!--  Question with one correct answer-->
        <qandaentry role="multi-radio" id="questionx">
        <!-- Question should have id that is short version of topic -->
            <question>
                <para>
                    The designer needs to limit the chart display to the set of products that contribute 20 percent of the total sales using the top contributors.
                </para>
            </question>
            <answer>
                <para>
                    Show only values that are Greater Than or Equal To 20 percent and select the Show Total checkbox.
                </para>
            </answer>
            <answer>
                <para>
                    Show only First 20 Values, select the Global Grouping Mode checkbox, and select the Exclude Others checkbox.
                </para>
            </answer>
            <answer role="solution">
                <para>
                    Show only values that accumulate to 20 percent and Use Largest Values and select the Check Include Boundary Values checkbox.
                </para>
            </answer>
            <answer>
                <para>
                    Show only Largest 20 Values and select the Show Others checkbox.
                </para>
            </answer>
        </qandaentry>
    </qandaset>
</step>
The next part of the file shows a question with more than one correct answer:
<!--  Question with more than one correct answer. Indicate how many choices at end of question.-->
<step>
    <qandaset>
        <qandaentry role="multi-check" id="questiony">
            <question>
            <para>
                Based on the Linux partition naming system, which of the following two device names point to "logical" partitions (assuming the corresponding partitions exist at all on the system in question)? (Choose two.)
            </para>
            </question>
            <answer>
                <para> /dev/sda3 </para>
            </answer>
            <answer>
                <para> /dev/fd0 </para>
            </answer>
            <answer role="solution">
                <para> /dev/hdb7 </para>
            </answer>
            <answer>
                <para> /dev/hda4 </para>
            </answer>
            <answer>
                <para> /dev/fd7 </para>
            </answer>
            <answer role="solution">
                <para> /dev/sdc11 </para>
            </answer>
        </qandaentry>
    </qandaset>
</step>
The next part of the file shows a question with an exhibit and more than one answer:
<step>
          <qandaset>
            <qandaentry role="multi-check" id="questionz">
              <question>
                <para>
                  <screen>Name           Null?       Type
  ----------    -------      --------
  STUDENT_ID    NOT NULL  VARCHAR2(4)
  STUDENT_NAME          VARCHAR2(25)
  SUBJECT1            NUMBER(3)
  SUBJECT2            NUMBER(3)
  SUBJECT3            NUMBER(3)</screen>
                </para>
                <para> Given the structure of the MARKS table in the above Exhibit, which two
                  statements would execute successfully? (Choose two.) </para>
              </question>
              <answer>
                <para> SELECT student_name, subject1 FROM marks WHERE subject1 > AVG(subject1);
                </para>
              </answer>
              <answer>
                <para> SELECT student_name, SUM(subject1) FROM marks WHERE student_name LIKE ‘R%’;
                </para>
              </answer>
              <answer role="solution">
                <para> SELECT SUM (subject1+subject2+subject3) FROM marks WHERE student_name is
                  NULL; </para>
              </answer>
              <answer role="solution">
                <para> SELECT SUM (DISTINCT NVL(subject1,0)), MAX(subject1) FROM marks WHERE
                  subject1 > subject2; </para>
              </answer>
            </qandaentry>
          </qandaset>
        </step>
      </procedure>
    </task>
  </section>

Important

If there is more than one answer, indicate how many items to choose at the end of the question.

12.11. Multiple-choice Sample Title

won't show

Choose the correct answer to the following questions:
  1. Q: The designer needs to limit the chart display to the set of products that contribute 20 percent of the total sales using the top contributors.
    Q:
    The designer needs to limit the chart display to the set of products that contribute 20 percent of the total sales using the top contributors.
    A:
    Show only values that are Greater Than or Equal To 20 percent and select the Show Total checkbox.
    A:
    Show only First 20 Values, select the Global Grouping Mode checkbox, and select the Exclude Others checkbox.
    A:
    Show only values that accumulate to 20 percent and Use Largest Values and select the Check Include Boundary Values checkbox.
    A:
    Show only Largest 20 Values and select the Show Others checkbox.
  2. Q: Based on the Linux partition naming system, which of the following two device names point to "logical" partitions (assuming the corresponding partitions exist at all on the system in question)? (Choose two.)
    Q:
    Based on the Linux partition naming system, which of the following two device names point to "logical" partitions (assuming the corresponding partitions exist at all on the system in question)? (Choose two.)
    A:
    /dev/sda3
    A:
    /dev/fd0
    A:
    /dev/hdb7
    A:
    /dev/hda4
    A:
    /dev/fd7
    A:
    /dev/sdc11
  3. Q: Name Null? Type ---------- ------- -------- STUDENT_ID NOT NULL VARCHAR2(4) STUDENT_NAME VARCHAR2(25) SUBJECT1 NUMBER(3) SUBJECT2 NUMBER(3) SUBJECT3 NUMBER(3)
    Q:
    Name           Null?       Type
      ----------    -------      --------
      STUDENT_ID    NOT NULL  VARCHAR2(4)
      STUDENT_NAME          VARCHAR2(25)
      SUBJECT1            NUMBER(3)
      SUBJECT2            NUMBER(3)
      SUBJECT3            NUMBER(3)
    Given the structure of the MARKS table in the above Exhibit, which two statements would execute successfully? (Choose two.)
    A:
    SELECT student_name, subject1 FROM marks WHERE subject1 > AVG(subject1);
    A:
    SELECT student_name, SUM(subject1) FROM marks WHERE student_name LIKE ‘R%’;
    A:
    SELECT SUM (subject1+subject2+subject3) FROM marks WHERE student_name is NULL;
    A:
    SELECT SUM (DISTINCT NVL(subject1,0)), MAX(subject1) FROM marks WHERE subject1 > subject2;

12.12. Lab Overview and XML

A lab is a performance-based exercise included at the end of a chapter that walks the student through the steps of a task without complete instructions. For help, student can be referred back to complete instructions in a guided exercise section, or solutions can be included if needed.
Lab XML
The first part of the section includes the title, task summary, resources, prerequisites, and outcomes:
<!-- Section should have id that is short version of title -->
<section role="Test" id="shortsectionname-lab">
  <title>Lab: Creating Widgets wth Microtools</title>
  <!-- Task should have id that is short version of topic -->
  <task role="Lab" id="topic-lab">
    <title>Can't be empty, will be ignored</title>
    <tasksummary>
      <para>In this lab, you will .....</para>
      <formalpara>
        <title>Outcomes</title>
       <para>You should be able to...xxx</para>
<!--Outcomes tell students what they will be able to do after completing a guided lab, lab, or an instructor-led lab.-->
      </formalpara>
    </tasksummary>
    <taskprerequisites>
      <para>Sample prerequisites</para>
      </taskprerequisites>
The next part contains the procedure:
<procedure>
   <title>Steps</title>
      <step>
        <para> General instruction </para>
        <para role="solution"> Sample solution </para>
      </step>
      <step>
        <para> More objective </para>
        <para role="solution"> Sample solution </para>
      </step>
</procedure>
The last part contains the evaluation and conclusion of the lab:
    <taskrelated>
      <formalpara>
        <title>Evaluation</title>
        <para>
          As the <code>student</code> user on the <code>workstation</code> machine, use the <code>lab</code> command to grade your work.
          Correct any reported failures and rerun the command until successful.
        </para>
      </formalpara>
      <screen><prompt>[student@workstation ~]$ </prompt><userinput>lab chapter-topic grade</userinput></screen>

      <formalpara>
        <title>Finish</title>
        <para>
          As the <code>student</code> user on the <code>workstation</code> machine, use the <code>lab</code> command to complete this exercise.
          This is important to ensure that resources from previous exercises do not impact upcoming exercises.
        </para>
      </formalpara>
      <screen><prompt>[student@workstation ~]$ </prompt><userinput>lab chapter-topic finish</userinput></screen>
    </taskrelated>
  </task>
</section>
Rendering shown in the next section.

12.13. Creating Widgets with Microtools

Can't be empty, will be ignored

Performance Checklist
In this lab, you will .....
Outcomes
You should be able to...xxx
Sample prerequisites
  1. General instruction
    Sample solution
  2. More objective
    Sample solution
Evaluation
As the student user on the workstation machine, use the lab command to grade your work. Correct any reported failures and rerun the command until successful.
[student@workstation ~]$ lab chapter-topic grade
Finish
As the student user on the workstation machine, use the lab command to complete this exercise. This is important to ensure that resources from previous exercises do not impact upcoming exercises.
[student@workstation ~]$ lab chapter-topic finish

12.14. Comprehensive Review Overview and XML

A comprehensive review is a performance-based exercise included in a chapter at the end of a course. Courses that count towards certification will have a review, but other RHT courses may not have one.
Create a comprehensive review using the comprehensive review xml template in the xml skeleton. As in a lab, create a procedure without complete instructions and include solutions with role="solution". See RH124 for a more detailed example of a comprehensive review.

Index

A

application, Application Names

M

Microsoft Windows, Using Other Operating Systems

P

product, Product Names
productname, Product Names
project name, Application Names

Q

quotes
quotation marks , Quotation marks