On Sat, 2009-11-28 at 15:26 -0800, David Brownell wrote: > 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.
Okay, but how could you then distinguish constant and variable tokens? > > 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! What about using them for notational purposes as I suggested, then parsing them and displaying proper fonts if possible. Of course, that would mean escaping them if you needed them literally, but these tokens should be _highly_ unlikely to show up as literal command arguments. I'd almost say "never", but I am feeling wise enough today to avoid making such laughable claims. > > 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. I guess this requires more detail (and suggests that I should remember to re-read our style guide on occasion). Can we have Extended BNF? ;) > > 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. The fresh perspective at the point of first working on a project can never be recovered after gaining some experience. Although, I suppose rotating teams of development would help this. If someone goes away from an active project for a year, things should have changed enough to cause them to induce a similar state again by the time they return. ;) Everyone needs to use this logic to get themselves a paid 1 month sabbatical every year: you need keep yourself from "going native" with your projects. :) --Z _______________________________________________ Openocd-development mailing list Openocd-development@lists.berlios.de https://lists.berlios.de/mailman/listinfo/openocd-development
