#title DocBook Conventions

||<tablestyle="float:right; font-size: 0.9em; background:#F1F1ED;margin: 0 0 1em 1em;" style="padding:2.0em;"><<Include(DocumentationTeam/StyleGuide/TableOfContents)>>||

This page provides guidance on which Doc''''''Book tags to use in different situations.

<<TableOfContents(3)>>

TODO:

 1. How to use DocBook tags.
 1. When to use a DocBook article and when to use a DocBook book.
 1. How to markup screenshots and other graphics, sections, cross-references, tables, etc.

== Referring to the User Interface ==

The standard methods of tagging items in user interfaces (UI) are detailed below.

=== Buttons ===

For push buttons, use the tag {{{<guibutton>Button Caption</guibutton>}}}. The caption should match the exact caption used by the button in the UI.

The following controls should be referred to when using the {{{<guibutton>}}} tag:

 * Normal push buttons
  {{attachment:button.png}}
 * Toggle buttons

=== Labels ===

For labels such as the names of text entries and tabs, use the tag {{{<guilabel>Label Text</guilabel>}}}. The label text should exactly match the text used in the UI, minus the trailing colon (":") if there is one.

The following controls should be referred to when using the {{{<guilabel>}}} tag:

|| '''Control''' || '''Image''' ||
|||| '''Example''' ||
|| '''Label''' || {{attachment:label.png}} ||
|||| {{{Find the section named <guilabel>Cursor Blinking</guilabel>.}}} ||
|| '''Text entry''' || {{attachment:label-textentry.png}} ||
|||| {{{Type the name of the repository into the <guilabel>APT line</guilabel> box.}}} ||
|| '''Checkbox''' || {{attachment:label-checkbox.png}} ||
|||| {{{Check <guilabel>Vertical Scrolling</guilabel> to enable your touchpad to scroll up and down.}}} ||
|| '''Radio button''' || {{attachment:label-radio.png}} ||
|||| {{{Ensure that <guilabel>Only notify about available updates</guilabel> is selected.}}} ||
|| '''Drop-down selection box''' || {{attachment:label-dropdown.png}} ||
|||| {{{Select a country from the list labelled <guilabel>Download from</guilabel>.}}} ||
|| '''Combo box''' || {{attachment:label-combo.png}} ||
|||| {{{Type an IP address into the <guilabel>Network address</guilabel> box or select a previous address from the list.}}} ||
|| '''Slider''' || {{attachment:label-slider.png}} ||
|||| {{{Slide <guilabel>Timeout</guilabel> to the right to increase the wait time.}}} ||
|| '''Expander''' || {{attachment:label-expander.png}} ||
|||| {{{Press <guilabel>Pressure sensitivity</guilabel> to see more options for this brush.}}} ||

== Referring to Files and Commands ==

This section describes the tags to be used when referring to files, directories, and commands that the user inputs into the terminal.

=== Files and Directories ===

When referring to a file, use {{{<filename>/path/to/file</filename>}}}.

Refer to directories using {{{<filename classname="directory">/path/to/directory</filename>}}}.

Refer to file extensions using {{{<filename classname="extension">.ext</filename>}}}.

=== Terminal Commands ===

The commands themselves should be placed in {{{<screen><command>ls /root</command></screen>}}} if the intent is to type the command into a terminal prompt.

The tags {{{<command></command>}}} can also be used outside the {{{<screen></screen>}}} tags if appropriate.  For example, inside {{{<note></note>}}} tags.

'''Output''' from terminal commands should be wrapped in {{{<screen></screen>}}} tags as well.

=== Configuration Files and Source Code ===

Source code and configuration file examples should be placed in {{{<programlisting></programlisting>}}} tags.

----
CategoryDocteam