Button and Menu UI Macros

In order to use the UI macros, you must set the experimental document attribute. Although this attribute is named experimental, the UI macros are considered a stable feature of the AsciiDoc language. The requirement to specify the attribute is merely an optimization for the processor. If the specification committee determines that an attribute is still necessary, the name of the attribute will likely change to better reflect that the macros are integral to the language.

Button macro syntax

It can be difficult to communicate to the reader that they need to press a button. They can’t tell if you are saying “OK” or they are supposed to look for a button labeled OK. It’s all about getting the semantics right. The btn macro to the rescue!

Example 1. Using the button macro syntax
Press the btn:[OK] button when you are finished.

Select a file in the file navigator and click btn:[Open].

The result of Example 1 is displayed below.

Press the OK button when you are finished.

Select a file in the file navigator and click Open.

Trying to explain how to select a menu item can be a pain. With the menu macro, the symbols do the work.

Example 2. Using the menu macro syntax
To save the file, select menu:File[Save].

Select menu:View[Zoom > Reset] to reset the zoom level to the default setting.

The instructions in Example 2 appear below.

To save the file, select File  Save.

Select View  Zoom  Reset to reset the zoom level to the default setting.

If the menu has more than one item, it can be expressed using a shorthand.

The shorthand syntax for menu is not on a standards track. You can use it for transient documents, but do not rely on it long term.

In the shorthand syntax:

  • each item is separated by a greater than sign (>) with spaces on either side

  • the whole expression must be enclosed in double quotes (")

The text of the item itself may contain spaces.

Example 3. Using the shorthand menu syntax
Select "Zoom > Reset" to reset the zoom level.

The shorthand syntax can be escaped by preceding the opening double quote with a backslash character.

Both the menu macro and menu shorthand require the first menu item start with a word character (alphanumeric character or underscore) or ampersand (to accommodate a character reference). If you need the first menu item to start with a non-word character, you will need to substitute it with the equivalent character reference. For example, to make a menu item that starts with vertical ellipsis, you must use ⋮.

Example 4. Using a character reference at the start of the menu
Select "⋮ > More Tools > Extensions" to find and enable extensions.

Subsequent menu items don’t have this requirement and thus can start with any character.