DocbookConventions

Differences between revisions 8 and 10 (spanning 2 versions)
Revision 8 as of 2009-07-29 08:38:51
Size: 3574
Editor: dyndsl-091-096-008-091
Comment:
Revision 10 as of 2011-06-14 02:51:54
Size: 3665
Editor: 24-205-79-243
Comment:
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. This page provides guidance on which Doc''''''Book tags to use in different situations.
Line 11: Line 11:
 1. How DocBook tags are used
 1. When to use a DocBook article, and when to use a DocBook book.
 1. How to markup screenshots and other graphics, sections, cross-refs, tables, etc.
 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.
Line 15: Line 15:
== Referring to the user interface == == Referring to the User Interface ==
Line 17: Line 17:
The standard methods of tagging items in user interfaces are detailed below. The standard methods of tagging items in user interfaces (UI) are detailed below.
Line 21: Line 21:
For push buttons, use {{{<guibutton>Button Caption</guibutton>}}}. The caption should match the exact caption used by the button in the UI. For push buttons, use the tag {{{<guibutton>Button Caption</guibutton>}}}. The caption should match the exact caption used by the button in the UI.
Line 23: Line 23:
The following controls should be referred to using the {{{<guibutton>}}} tag: The following controls should be referred to when using the {{{<guibutton>}}} tag:
Line 31: Line 31:
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. 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.
Line 33: Line 33:
The following controls should be referred to using the {{{<guilabel>}}} tag: The following controls should be referred to when using the {{{<guilabel>}}} tag:
Line 35: Line 35:
|| '''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.}}} ||
|| '''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 45: Line 54:
== Referring to files and commands == == Referring to Files and Commands ==
Line 47: Line 56:
This section describes the tags which should be used when referring to files, directories, and commands which the user inputs into the Terminal. This section describes the tags to be used when referring to files, directories, and commands that the user inputs into the terminal.
Line 49: Line 58:
=== Files and directories === === Files and Directories ===
Line 51: Line 60:
When referring to a file, use {{{<filename>/path/to/file</filename>}}} When referring to a file, use {{{<filename>/path/to/file</filename>}}}.
Line 53: Line 62:
Refer to directories using {{{<filename classname="directory">/path/to/directory</filename>}}} Refer to directories using {{{<filename classname="directory">/path/to/directory</filename>}}}.
Line 55: Line 64:
Refer to file extensions using {{{<filename classname="extension">.ext</filename>}}} Refer to file extensions using {{{<filename classname="extension">.ext</filename>}}}.
Line 61: Line 70:
{{{<command></command>}}} tags can also be used outside {{{<screen></screen>}}} tags if appropriate. For example, inside {{{<note></note>}}} tages. The tags {{{<command></command>}}} can also be used outside the {{{<screen></screen>}}} tags if appropriate. For example, inside {{{<note></note>}}} tags.
Line 65: Line 74:
=== Config Files and Source Code === === Configuration Files and Source Code ===
Line 67: Line 76:
Source code and config file examples should be placed in {{{<programlisting></programlisting>}}} tags. Source code and configuration file examples should be placed in {{{<programlisting></programlisting>}}} tags.

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

label.png

Find the section named <guilabel>Cursor Blinking</guilabel>.

Text entry

label-textentry.png

Type the name of the repository into the <guilabel>APT line</guilabel> box.

Checkbox

label-checkbox.png

Check <guilabel>Vertical Scrolling</guilabel> to enable your touchpad to scroll up and down.

Radio button

label-radio.png

Ensure that <guilabel>Only notify about available updates</guilabel> is selected.

Drop-down selection box

label-dropdown.png

Select a country from the list labelled <guilabel>Download from</guilabel>.

Combo box

label-combo.png

Type an IP address into the <guilabel>Network address</guilabel> box or select a previous address from the list.

Slider

label-slider.png

Slide <guilabel>Timeout</guilabel> to the right to increase the wait time.

Expander

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

DocumentationTeam/StyleGuide/DocbookConventions (last edited 2011-06-14 02:57:33 by 24-205-79-243)