1. How commands are executed

1. How commands are executed
	Chapter 2. Writing macro-commands

Before attempting to write a macro-command, it is important to understand how commands (native or not) are executed.

The execution of a command can be described as a sequence of two steps:

The command tests if it can be successfully executed. If this test fails, the command will not attempt to execute itself: step #2 is silently skipped (that is, no warning or error messages are reported).
For this test to pass:
1. The command must successfully parse its parameter string (if any).
2. The current text or node selection (if any) must be compatible with the command. For example, command replace cannot be applied to text selection.
3. The grammar constraining the document (if any) must allow the operation.
The command is actually executed. It may return a result (a Java object) to its invocation environment.
Very few commands return a result. Unless explicitly documented, one must assume that commands do not return a result.
Some commands such as selectFile return an actual result (a file name or an URL in the case of command selectFile) or a special result understood by the invocation environment as ``command has failed or has been canceled by user'' (in the case of command selectFile, user has clicked on the Cancel button of the file chooser dialog box).