On Saturday 28 November 2009, Zach Welch wrote:
> 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.
I've seen it used in places where it's optional ... e.g. the typical
"if no parameter, just dump current state" stuff.
> 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.
Command line utility docs I've seen rely on fonts to distinguish
stuff like that ... '<' and '>' and '|' are shell metacharacters!
> 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.
doc/manual/style.txt says:
- Use BNF style regular expressions to define parameters:
brackets around zero-or-one choices, parentheses around
exactly-one choices.
> 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.
Yeah, I know *that* phenomonon well. IN the same vein, one wants
people really *new* to things as reviewers/testers ... everyone
else has applied blinders they don't even know about.
- Dave
_______________________________________________
Openocd-development mailing list
Openocd-development@lists.berlios.de
https://lists.berlios.de/mailman/listinfo/openocd-development
