Documentation suggestions

Adam Olsen rhamph at gmail.com
Wed Dec 7 14:10:02 CET 2005


On 12/7/05, skip at pobox.com <skip at pobox.com> wrote:
>
>     Adam> I don't expect everything to make the transition.  Are discussions
>     Adam> of "atoms" and fragments of BNF really better than calling them
>     Adam> expressions and linking to CPython's Grammar file?
>
> Actually, yes.  The actual Grammar file isn't designed for explanation
> (mostly it's more complex, but it also has extra productions) and is
> somewhat (maybe a lot) different than the BNF in the ref manual.

IMO the only people who are going to appreciate BNF used for
explanation are those working on language implementations, and they'll
need to understand the Grammar file anyway.  The rest of us need a
simpler explanation involving examples.

Having a large and detailed language specification, although an
admirable ideal, is a waste of time when the target audience is
perhaps a few dozen people.  Make it useful for everybody and it'll be
worth maintaining.

--
Adam Olsen, aka Rhamphoryncus



More information about the Python-list mailing list