Doc/examples: clarify usage messages

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>
This commit is contained in:
David Brownell 2010-01-08 23:13:39 -08:00
parent b800eb0336
commit ae71005929
3 changed files with 14 additions and 9 deletions

View File

@ -68,9 +68,9 @@ static const struct command_registration hello_command_handlers[] = {
{ {
.name = "hello", .name = "hello",
.mode = COMMAND_ANY, .mode = COMMAND_ANY,
.handler = &handle_hello_command, .handler = handle_hello_command,
.help = "print a warm greetings", .help = "print a warm greeting",
.usage = "[<name>]", .usage = "[name]",
}, },
{ {
.chain = foo_command_handlers, .chain = foo_command_handlers,
@ -84,7 +84,12 @@ int hello_register_commands(struct command_context_s *cmd_ctx)
} }
@endcode @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 @section primercmdchain Command Chaining

View File

@ -308,7 +308,7 @@ For technical reference material:
- Else it's a "Config Command" if it must be used before the - Else it's a "Config Command" if it must be used before the
configuration stage completes. configuration stage completes.
- For a "Driver", list its name. - 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 brackets around zero-or-one choices, parentheses around
exactly-one choices. exactly-one choices.
- Use \@option, \@file, \@var and other mechanisms where appropriate. - Use \@option, \@file, \@var and other mechanisms where appropriate.

View File

@ -58,14 +58,14 @@ static const struct command_registration foo_command_handlers[] = {
.name = "bar", .name = "bar",
.handler = &handle_foo_command, .handler = &handle_foo_command,
.mode = COMMAND_ANY, .mode = COMMAND_ANY,
.usage = "<address> [enable|disable]", .usage = "address ['enable'|'disable']",
.help = "an example command", .help = "an example command",
}, },
{ {
.name = "baz", .name = "baz",
.handler = &handle_foo_command, .handler = &handle_foo_command,
.mode = COMMAND_ANY, .mode = COMMAND_ANY,
.usage = "<address> [enable|disable]", .usage = "address ['enable'|'disable']",
.help = "a sample command", .help = "a sample command",
}, },
{ {
@ -107,10 +107,10 @@ COMMAND_HANDLER(handle_hello_command)
const struct command_registration hello_command_handlers[] = { const struct command_registration hello_command_handlers[] = {
{ {
.name = "hello", .name = "hello",
.handler = &handle_hello_command, .handler = handle_hello_command,
.mode = COMMAND_ANY, .mode = COMMAND_ANY,
.help = "prints a warm welcome", .help = "prints a warm welcome",
.usage = "[<name>]", .usage = "[name]",
}, },
{ {
.name = "foo", .name = "foo",