[Tb] Re: syntax for agent query

> >Is the syntax for the AgentQuery defined in any documentation, or is
> >this another area where we are forced to rely on trial and error?
>
> Tinderbox Manual pp. 103-107, of course.

On the one hand, I thank you again for your amazingly prompt replies
and interest in helping out. On the other hand, I am puzzled by a
reply such as this, as we both know that these pages neither answer
my questions nor contain anything that might reasonably be considered
documentation of the syntax. There is nothing in the manual that goes
beyond brief allusions to how to form the AgentQuery, and a few examples.

> Date arithmetic currently applies ONLY to TODAY.

Which is not mentioned anywhere in the manual. Not only that, but
the manual, to which you send me in search of wisdom, is incorrect:
on p. 86 we find

"For example, these are all acceptable values for a date attribute:
[...]
 yesterday + 4 months"

and

"When entering a value for a date, you can also use the terms yesterday,
today, and tomorrow, and add or subtract units of time."

with no mention that you can "add or subtract units of time" "ONLY to TODAY".

Then comes the strawman:

> On the one hand, a BNF
> definition might be useful, but on the other hand some people would
> find this alarming.

I didn't ask whether you had a formal definition for me. I don't want that.
What I could use is some basic, accurate documentation, where I could look
up the answers to questions like "what is the order of operations?" and
"where can I use parentheses?"

The User's manual is a fairly decent survey of the program that's probably
useful for getting new users started, and giving them some idea of what
they can do. But it is not actual documentation by any means. Some of the
holes are filled by the release notes, but the fact is, in order to find
out how Tinderbox behaves in detail in regard to HTML export, AgentQueries,
and in many other respects, one still is forced to rely on trial and error,
which is very time consuming and unproductive.

If that's the way it is, fine. Tinderbox is a complex program that is under
rapid development, and most experienced people would expect the documentation
to lag, or even to not yet exist in key areas. So you've answered my
question ("is this another area where we are forced to rely on trial
and error?") indirectly: yes, it is. Why not just say so, instead of sending
me to a chapter in the User's Manual that you must know I've already read
and that you also know does not contain the information I seek?

I have another question: is any serious documentation planned for Tinderbox?
If so, how far along is it? Or do you prefer to rely on the existing Manual,
the release notes, the wiki, and answering a lot of mail for the foreseeable
future (or hoping that enough people buy Tinderbox so that Matt Neuburg
finds it profitable to write a book about it)?
Received on Mon Sep 27 18:26:09 2004