Documentation suggestions

[rurpy at yahoo.com]

Adam Olsen wrote:
> 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.

A language reference manual and a language specification
are two different things, and the existence of bnf/grammar info
in a language reference manual need to turn it into some
inpenaterable ISO-spec like document.

I know that I sometimes want to know if some unusual syntax
is legal or not, particularly when learning a language.  The
bnf/grammar stuff is relatively small and if sections are
organised consistently, easily skipped over by readers with
no interest it it.