DocbookConventions

Differences between revisions 4 and 6 (spanning 2 versions)
Revision 4 as of 2008-01-23 10:54:27
Size: 1571
Editor: cpc3-with4-0-0-cust432
Comment: Added new material
Revision 6 as of 2008-01-24 06:07:17
Size: 3539
Editor: cpe-075-183-108-021
Comment: Updated Terminal commands and config files sections.
Deletions are marked like this. Additions are marked like this.
Line 5: Line 5:
This page provides guidance on which Doc''''''Book tags should be used in different situations.
Line 7: Line 9:
''TODO: TODO:
Line 12: Line 14:
''
Line 20: Line 21:
attachment:button.png attachment:button-toggle.png For push buttons, use {{{<guibutton>Button Caption</guibutton>}}}. The caption should match the exact caption used by the button in the UI.
Line 22: Line 23:
For push buttons, use {{{<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 using the {{{<guibutton>}}} tag:

 * Normal push buttons
  attachment:button.png
 * Toggle buttons
Line 26: Line 31:
attachment:label-textentry.png attachment:label-tab.png attachment: For labels (such as the names of text entries and tabs), use {{{<guilabel>Label Text</guilabel>}}}. The label text should exactly match the text used in the UI, minus the trailing colon (":") if there is one.
Line 28: Line 33:
For labels (such as the names of text entries, checkboxes and tabs), use {{{<guilabel>Label Text</guilabel>}}}. The label text should exactly match the text used in the UI. The following controls should be referred to 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.}}} ||
Line 44: Line 59:
The commands them selves should be placed in {{{<screen><command>ls /root</command></screen>}}} if the intent is to type the command into a terminal prompt.
Line 45: Line 61:
{{{<command></command>}}} tags can also be used outside {{{<screen></screen>}}} tags if appropriate. For example, inside {{{<note></note>}}} tages.

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

=== Config Files and Source Code ===

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

This page provides guidance on which DocBook tags should be used in different situations.

TableOfContents(3)

TODO:

  1. How DocBook tags are used

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

  3. How to markup screenshots and other graphics, sections, cross-refs, tables, etc.

Referring to the user interface

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

Buttons

For push buttons, use <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 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 <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 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 which should be used when referring to files, directories, and commands which 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 them selves should be placed in <screen><command>ls /root</command></screen> if the intent is to type the command into a terminal prompt.

<command></command> tags can also be used outside <screen></screen> tags if appropriate. For example, inside <note></note> tages.

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

Config Files and Source Code

Source code and config file examples should be placed in <programlisting></programlisting> tags.


CategoryDocteam

DocumentationTeam/StyleGuide/DocbookConventions (last edited 2011-06-14 02:57:33 by calipengo)