DIG DocBook referenceElementsBelow is a non-exhaustive list of DocBook elements used in Evergreen documentation.
Authors may use other elements but are encouraged to draw from this list first. Each
term links to the authoritative DocBook 5 reference pages at http://www.docbook.org/tdg5/en/html/part2.html.
section
A titled subdivision of a chapter, only
required if a chapter has two or more sections. Sections appear in TOC and
have their own pages in HTML output (use simplesect to exclude from TOC). The xml:id attribute is optional and can be applied ad hoc when
linking to a section.The section element can be nested to
create subsections. Here are some examples used in The Book of Evergreen: section -> section (for a section and
subsection, both appearing in TOC)section -> simplesect (for a section and
subsection, w/ only the top level in the TOC)section -> section -> simplesect (for a
section, subsection, and sub-subsection, with the top 2 in the
TOC))
xref
A cross reference to another part of the document (use link for external links). The destination is set
with the linkend attribute, which matches
the xml:id of the destination element. Link
text is auto-generated.oXygen returns a validation error if the link
destination is in another xml file; this is resolved when the files are
assembled for publication and can be ignored.
guimenu
Use for the names of staff client menus; formatted in italics.
menuchoice
Use to describe a menu selection. Usually contains guimenu and guimenitiem elements (may also contain guisubmenu). Output displays an arrow
between each child element. To clear the staff client cache go to
AdminFor developersClear Cache]]>
displays as To clear the staff client cache go to AdminFor developersClear Cache
guimenuitem
An option in a staff client menu or submenu; formatted in italics.
guibutton
A button in the staff client. Currently formatted with italics, though this can be changed in the stylesheets.Click Modify Copies to save your changes]]>
displays asClick Modify Copies to save your
changes
informalfigure
A wrapper for a mediaobject and optional
associated text. Stylesheet customizations ensure the contents of an informfigure are kept together during PDF pagination. The
step in the following example will not
split across a page break: STEP TEXT GOES HEREOPTIONAL DESCRIPTION OF IMAGE
]]>
figure
Wrapper for a mediaobject that has
a title and appears in list of figures (in the book's front matter). Content in figure and informalfigure is not split across PDF page breaks.
example
An example with a title.
informalexample
An example with no title.
formalpara
A titled paragraph. The following Paragraph titleParagraph body...
]]>
displays asParagraph titleParagraph body...
mediaobject
A wrapper for imageobjects. May be wrapped in an
informalfigure to keep image and text together across page breaks. See for more
on image formatting.
alt
Metadata describing an element, usually for accessibility. For example, each mediaobject may contain an
alt element with a generic description of the
image content.
imageobject
Contained by mediaobject and a
wrapper for imagedata. See for more on
image formatting in The Book of Evergreen.
imagedata
Contained by imageobject, its
attributes determine sizing, scaling, alignment, and source file. See for more on Sitka image formatting.
guilabel
Use for labels and titles in the staff client. Where applicable guimenu, guimenuitem, and guibutton are preferred. HTML is formatted in italics, PDF is
not formatted.
guisubmenu
A staff client submenu. Used when a submenu is part of a menuchoice sequence. Not italicized.
keycap
The label on a keyboard button; formatted in bold (eg Press
F5).
keycap
For a combination of two or more keystrokes, wrap keycap elements in a keycombo. Format is bold with a + between
keystrokes. Open a new tab with
CtrlT ]]>
displays asOpen a new tab with CtrlT
application
The name of a software program or application such as
Evergreen. Currently not formatted, but
consistent use would allow for future batch formatting (e.g. italicize content of all application tags).
emphasis
Use to italicize regular text. Use with the ROLE attribute for bold textFor italic and bold output.
]]>
displays asFor italic and bold output.
tip
Enclose tip text and images in this element for consistent formatting.
Display options are set with CSS and XSL stylesheets and include custom tip
text, icons, formatting, etc.
Tip text goes here
]]>
displays asTip text goes here
glossary
Wrapper for a glossary. Must contain title element (to hide the title in published
output use an empty ]]> tag).
glossentry
Wrapper for each glossary entry. Should always have an xml:id for cross referencing. Entries are
sorted alphabetically in published output, regardless of order in xml source
document (this is optional and is set with stylesheet parameters). Full glossentry markup including child elements is shown below: guisubmenuA staff client submenu. Used primarily when a submenu is part
of a menuchoice sequence. Not italicized.]]>
glossterm
Wrapper for the term in a glossentry.
glosssee
A "see" link that points from one glossentry to another. Always has an otherterm attribute that corresponds to the
xml:id of the referenced term.
glossseealso
A "see also" link that points from one glossentry to another. Always has an otherterm attribute corresponds to the
xml:id of the referenced term.
itemizedlist
A bulleted list with an optional title.
orderedlist
A numbered list with an optional title.
listitem
Wrapper for individual entries on an itemizedlist or orderedlist.
programlisting
When used with , text in a
programlisting is published exactly as it appears in the xml file (including
line breaks and white space). Formatted as a block with a shaded background,
used only for coding examples (see
/style/style_glossary.xml for syntax example).
link
For external links. Must have an xlink:href attribute with the destination URL. In PDF output
the full URL is printed in brackts after the link text.
procedure
A multi-step process consisting of two or more steps. Applies to most converted Sitka docs.step
step
Component part of a procedure. Steps
are auto-numbered and may contain text, figures, examples, etc. The xml:id attribute is optional and only required
if linking to a particular step. To keep step content together during
pagination (eg text w/ associated image), use informalfigure.
para
A paragraph; a required wrapper for text in most contexts.
info
A wrapper for metadata about an element, including title.
book
The top level element for Evergreen documentation, appears only in the file
root.xml
part
A subdivision of a book. Used only in
root.xml; each part should have a title and xml:id.
chapter
A subdivision of a part, further divided
into sections. In Evergreen documentation each chapter
is a separate xml file referenced by root.xml. Each chapter should
have an xml:id. The xml:id is required for cross-referencing and stable links to published html files. If there is no xml:id the generated html files names may change as content is added or re-located.
title
Sets the title for the element which contains it. Required in
chapters and sections.
date
Wrapper for date info in any context. Format is YYYY-MM-DDsimplesectA subdivision of a section that does
not appear in the TOC. A simplesect is terminal, i.e. cannot be further
subdivided with section or simplesect elements.
systemitem
Indicates various system related resources and items. See the Docbook entry for classification possibilities. Use this in place of emphasis where applicable.
command
The name of an executable program or other software command. Use this instead of emphasis where applicable.
option
Specify an option for a software command. Use this instead of emphasis where applicable.
filename
Specify a name of a file or directory. See docbook entrey for class options.
screen
Text that a user sees or might see on a computer screen
userinput
Data entered by the user. Used with screen to differentiate input from output.
computeroutput
Computer generated output. Used with screen to differentiate output from input.
code
An inline code fragment.
errortext
An error message.
function
The name of a function or subroutine, as in a programming language.
prompt
A character or string indicating the start of an input field in a computer display. Used with screen to indicate a prompt for user input.
varname
The name of a variable. Use this instead of emphasis where applicable.AttributesDocBook elements can be modified by one or more attributes. The attibutes below are commonly used in The Book of Evergreen. More info on DocBook 5 attributes is available at http://www.docbook.org/tdg5/en/html/ref-elements.html#common.attributesAttributes
xml:id
Optional xml identifier for an element, required for cross references and
linking. Must be unique within the entire documentation set. Good practice is to make sure that, at minimum, all
book, part, chapter, and glossentry elements have an
xml:id. In html output, the xml:id becomes the name the html file and the URL for that segment of the documentation (if there is no xml:id, the html file is auto-numbered).
linkend
Attribute that sets the link destination. Any DocBook 5 inline
element can become a link by adding a linkend attribute that corresponds to the
xml:id of the destination. See
for more detailed info.
otherterm
Applied exclusively to glosssee and
glossseealso elements, it points
to the referenced glossary term. ]]>displays as See also date.
role
ParaApplied to
para tags to track changes to draft
docs for approval by other editors. Can have value of
added, deleted, or
changed; in html output will be highlighted in
green, red, and yellow
respectively.