On Sat, 2009-11-28 at 14:07 -0800, David Brownell wrote: > On Saturday 28 November 2009, Zach Welch wrote: > > Next, we should consider updating all help messages to full sentences, > > so the new command mode information will follow the final period. > > And make sure the "usage" is all strict BNF. I see angle brackets "<...>" > and have no idea what's meant; I've seen both: > > - one-or-the-other ... BNF writes as "( ... | ... )" > > - none-or-one-of ... BNF writes as "[ ... | ... ]" > > and so on.
The use of angle brackets intends to distinguish parameter names from literal arguments. Thus [<foo>] means an optional thing which semantically will be used as a "foo", whereas [foo|bar] means you can optionally provide the 'foo' or 'bar' options (literally). If the parameter is required, I used (foo|bar) or <foo|bar> depending on whether the parameter should be literal or figurative, respectively. By the end of my work, I intended for the usage follow these rules, but it was a long process and I did not have them formulated this clearly. The use of angle brackets may be non-standard for BNF, but it was based on the practices for usage information in most command line utilities. I had been considering parsing these strings and using them to automate argument parsing. Imagine a function (a la sscanf) that takes the usage string as the format specifier, a command_invocation, and the parameter variables to be filled as outputs. This requires a standard syntax throughout, and something that looks like BNF is a good choice for sure. That would make the series far more challenging, to be sure. :) For now, I think it would be helpful for us to add a section to the new command API documentation to record the desired rules. That should give the standard for writing and registering command handlers in OpenOCD. Would you mind taking a stab at this documentation task? It might also give you a chance to touch up that API information (or remark about possible omissions). As the author of both the code and the docs, it's likely that I have missed something therein that you will spot when making new changes. Cheers, Zach _______________________________________________ Openocd-development mailing list Openocd-development@lists.berlios.de https://lists.berlios.de/mailman/listinfo/openocd-development
