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.

:menuselection:

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 Help from menu.

To save your file, go to File ‣ Save 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 or guilabel, 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.

:dfn:

Marks the defining instance of a term outside the index or glossary. For more details, see dfn role.

The example
1
2
This library has a :dfn:`CAPI`, a Common ISDN Application
Programming Interface.
Which gives

This library has a CAPI, a Common ISDN Application Programming Interface.