[Python-Dev] funcdef grammar production

[Greg Ewing]

"Jewett, Jim J" <jim.jewett at eds.com>:

> There is value in keeping the grammar documentation as close 
> as possible to the actual coded grammar.

Yes, but the question is whether that value outweighs the disadvantage
of making the documented grammar hard to follow, and thus less useful
for the purpose of documentation. To my mind, being clear to a human
reader is the first and most important goal to satisfy when
documenting something.

> > BNF on its own doesn't seem
> > to be up to the task of specifying this sort of thing clearly
> > to a human reader.
> 
> Agreed, but text often fails.  The advantage of BNF is that it
> can be checked to ensure that the writer and the reader agree.

I was exploring a third option, which is to use a higher level
formalism. The ideas involved are not inherently difficult to
formalise, it's just that BNF seems to be too low-level to easily
express the particular combination we need here. It's natural to
wonder whether theres' some other tool that would do a better job.

Railroad diagrams might be just what we need here. Take a look
at this:

http://www.cosc.canterbury.ac.nz/~greg/python/paramlist.png

Greg Ewing, Computer Science Dept, +--------------------------------------+
University of Canterbury,	   | A citizen of NewZealandCorp, a	  |
Christchurch, New Zealand	   | wholly-owned subsidiary of USA Inc.  |
greg at cosc.canterbury.ac.nz	   +--------------------------------------+