Ubuntu Wiki

This page provides guidance on which DocBook tags to use in different situations.

TODO:

1. How to use DocBook tags.

2. When to use a DocBook article and when to use a DocBook book.

3. 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

  • 

• 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:

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