Doc/examples: clarify usage messages

[openocd.git] / doc / manual / primer / commands.txt

diff --git a/doc/manual/primer/commands.txt b/doc/manual/primer/commands.txt
index c9db7ccb0a5b9d1891db88689f1c530d063a89ae..5f89d506253c07ffaab94c137d4714f9a5b186a9 100644 (file)
--- a/doc/manual/primer/commands.txt
+++ b/doc/manual/primer/commands.txt
@@ -55,7 +55,7 @@ static COMMAND_HELPER(handle_hello_args, const char **sep, const char **name)
 @endcode
 
 Of course, you may also call other macros or functions, but that extends
-beyond the scope of this tutorial on writing commands. 
+beyond the scope of this tutorial on writing commands.
 
 @section primercmdreg Command Registration
 
@@ -68,9 +68,9 @@ static const struct command_registration hello_command_handlers[] = {
        {
                .name = "hello",
                .mode = COMMAND_ANY,
-               .handler = &handle_hello_command,
-               .help = "print a warm greetings",
-               .usage = "[<name>]",
+               .handler = handle_hello_command,
+               .help = "print a warm greeting",
+               .usage = "[name]",
        },
        {
                .chain = foo_command_handlers,
@@ -84,7 +84,12 @@ int hello_register_commands(struct command_context_s *cmd_ctx)
 }
 @endcode
 
-That's it!  The command should now be registered and avaiable to scripts.
+Note that the "usage" text should use the same EBNF that's found
+in the User's Guide:  literals in 'single quotes', sequences of
+optional parameters in [square brackets], and alternatives in
+(parentheses|with|vertical bars), and so forth.  No angle brackets.
+
+That's it!  The command should now be registered and available to scripts.
 
 @section primercmdchain Command Chaining