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:
parent
b800eb0336
commit
ae71005929
|
@ -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
|
||||||
|
|
||||||
|
|
|
@ -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.
|
||||||
|
|
|
@ -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",
|
||||||
|
|
Loading…
Reference in New Issue