1.21. Writing about User Interface¶
Several roles are used when describing user interactions.
-
:guilabel:
¶ Marks up actual UI text of form labels or buttons. For more details, see
guilabel
role.- The example
1
Press the :guilabel:`Submit` button.
- Which gives
Press the Submit button.
Marks up the actual UI text of a navigation menu or form select element. For more details, see
menuselection
role.- The example
1 2 3
Select :menuselection:`Help` from menu. To save your file, go to :menuselection:`File --> Save` in the Main Menu.
- Which gives
Select
from menu.To save your file, go to
in the Main Menu.
When writing about multi-level menus, use a single
:menuselection:
role, and separate menu choices with-->
.Note
In some situations you might not be clear about which option,
menuselection
orguilabel
, to use. GUIs in real life can sometimes be ambiguous. The general rule is:Actual UI text will always receive
guilabel
role unless the text could reasonably be understood to be part of a menu.If the actual UI text could be understood as a menu,
menuselection
should be used.
These both render the same on output, so don’t worry too much if you get it wrong. Just use your judgment and take your best guess.
-
:kbd:
¶ Marks up a sequence of literal keyboard strokes. For more details, see
kbd
role.- The example
1
To stop the local server, type :kbd:`CTRL+C`.
- Which gives
To stop the local server, type CTRL+C.
-
:command:
¶ Marks up a terminal command. For more details, see
command
role.- The example
1
To build the documentation, use :command:`sphinx-build`.
- Which gives
To build the documentation, use sphinx-build.
To document a CLI application, you will find more information in Semantic Descriptions and References.
1.21.1. Other Semantic Markup¶
-
:abbr:
¶ Marks up an abbreviation. If the role content contains a parenthesized explanation, it will be treated specially: it will be shown in a tool-tip in HTML. For more details, see
abbr
role.- The example
1 2
This is the :abbr:`ISDN (Integrated Services Digital Network)` device.
- Which gives
This is the ISDN device.