Parameter syntax:

[ choices ]? message

choices -> single_char_delimiter ( 'single' '|' 'multiple' ) 
           single_char_delimiter [ choice ]+

choice -> [ '*' ]? choice_value '=' choice_text single_char_delimiter

This command is useful when writing interactive macro-commands. It displays a dialog box containing specified message and requesting the user to confirm an action (generally the command which follows this confirm command in the macro). If the user clicks on the OK button, the action is to be performed. If the user clicks on the Cancel button, the action is to be canceled.

Some choices may be specified to let the user select one or more options before clicking the OK button.

Options are separated using a single character. This delimiter must be chosen in order to be absent from choice_value, choice_text and message. It's typically '|', '/', '^', '~', or ';'.

A choice comprises an option value and some short text describing the option. The value of an option which is turned on is immediately preceded by '*'. Examples: "*yes=Yes, I want this!" and "no=No, please don't.".

Keyword 'single' specifies that the user may select just one option. Keyword 'multiple' specifies that the user may select zero or more options.

When some choices have been specified and the user clicks the OK button, this commands returns the values of all selected options separated by a space character.

Examples:

confirm Convert selected text to computeroutput?
confirm |single|*doc=Entire document|sel=Selection only| Print