[Bug 3737] [FT] EBNF snippets confusing

http://www.w3.org/Bugs/Public/show_bug.cgi?id=3737

           Summary: [FT] EBNF snippets confusing
           Product: XPath / XQuery / XSLT
           Version: Working drafts
          Platform: PC
        OS/Version: Windows XP
            Status: NEW
          Severity: normal
          Priority: P2
         Component: Full Text
        AssignedTo: jim.melton@acm.org
        ReportedBy: holstege@mathling.com
         QAContact: public-qt-comments@w3.org


There is a general problem with the expression part of the EBNF, which is that
it makes the sections look unconnected to each other and (ironically enough)
obscures the actual syntax of each individual construct.  For example, look at
the EBNF at the top of section 3. FTSelection refers to FTOr. When we look
at the next section, there is an EBNF for FTWords, but what is the relation of
that to FTSelection? Dunno.  What is FTOr? Well, its EBNF talks about FTAnd,
which talks about FTUnaryNot, which talks about FTWordSelection
which... um.. is nowhere to be found.  So one is left to trolling through the
appendix to figure out the connection between FTWords and FTSelection.
Since FTWords is the workhorse, common case of FTSelection, this is a real
problem in specification clarity.  Fixing this in the grammar will be tricky, I
recognize.

Look in particular at sections 3.1.3/3.1.4/3.1.5 (FTAnd/FTMildNot/FTUnaryNot)

What does FTMildNot have to do with FTAnd? Having FTMildNot reference
FTUnaryNot is really really confusing, because you don't (can't) put
a real unary not in that expression.  And in 3.1.5 we go RIGHT off the deep end
and claim that the "!" is optional for FTUnaryNot, which is baffling for people
not deeply familiar with how the grammar is constructed.  For this specific
case I think we are better off making the grammar a teeny bit more complex and
not trying to put FTWords syntactically under FTUnaryNot.  

Some other minor tweaks may be possible to make the snippets more meaningful.

Received on Monday, 18 September 2006 19:14:06 UTC