Doc/examples: clarify usage messages
authorDavid Brownell <dbrownell@users.sourceforge.net>
Sat, 9 Jan 2010 07:13:39 +0000 (23:13 -0800)
committerDavid Brownell <dbrownell@users.sourceforge.net>
Sat, 9 Jan 2010 07:13:39 +0000 (23:13 -0800)
Update/bugfix the "hello" example; emphasize using EBNF syntax,
matching the User's Guide.  Correct the Texinfo style guide to
say EBNF, not BNF.

Signed-off-by: David Brownell <dbrownell@users.sourceforge.net>
doc/manual/primer/commands.txt
doc/manual/style.txt
src/hello.c

index 6169734..5f89d50 100644 (file)
@@ -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
 
index 71bb5f6..87b1e6b 100644 (file)
@@ -308,7 +308,7 @@ For technical reference material:
    - Else it's a "Config Command" if it must be used before the
      configuration stage completes.
    - For a "Driver", list its name.
-   - Use BNF style regular expressions to define parameters:
+   - Use EBNF style regular expressions to define parameters:
      brackets around zero-or-one choices, parentheses around
      exactly-one choices.
    - Use \@option, \@file, \@var and other mechanisms where appropriate.
index 0cd06ad..8cd5fab 100644 (file)
@@ -58,14 +58,14 @@ static const struct command_registration foo_command_handlers[] = {
                .name = "bar",
                .handler = &handle_foo_command,
                .mode = COMMAND_ANY,
-               .usage = "<address> [enable|disable]",
+               .usage = "address ['enable'|'disable']",
                .help = "an example command",
        },
        {
                .name = "baz",
                .handler = &handle_foo_command,
                .mode = COMMAND_ANY,
-               .usage = "<address> [enable|disable]",
+               .usage = "address ['enable'|'disable']",
                .help = "a sample command",
        },
        {
@@ -107,10 +107,10 @@ COMMAND_HANDLER(handle_hello_command)
 const struct command_registration hello_command_handlers[] = {
        {
                .name = "hello",
-               .handler = &handle_hello_command,
+               .handler = handle_hello_command,
                .mode = COMMAND_ANY,
                .help = "prints a warm welcome",
-               .usage = "[<name>]",
+               .usage = "[name]",
        },
        {
                .name = "foo",