Any properly written documentation on any subject always begins with an executive summary (no more than a few pages), an overview (usually a dozen more pages), then gets into the nitty gritty.
Consider if I want you to write a paragraph in Egyptian Hieroglyphics. So I provide you with a few "sample" sentences already written in Egyptian Hieroglyphics. Would you be able to both understand my examples, and write a proper paragraph in Egyptian Hieroglyphics? Regarding a formal definition. That should be the first thing you write when creating something new. That is where the details start to show collisions, issues, problems. To the contrary, when I start using something new, I do not want to sift through 22k pages of text just to get the concept. Very few manuals are written well. You need to be able to explain the entire language in "A Few" pages. A summary of the hieroglyphics. (operators. This is what, a dozen or so symbols) A one or two sentence description of each key word. (e.g. JOIN, SELECT, INSERT,... especially anything new) A one or two sentence explanation for each key word (or symbol) how it relates to the equivalent SQL. Any documentation on any topic should be structured as such. The need for a formal definition is obvious, but is usually used in the same fashion as a dictionary (the printed on paper kind). A few people will read the entire book. But most will just turn to the entry of interest skipping everything else. The trick is being able to find that one word quickly and getting "All" the needed information in a concise deliberate fashion. --------------------- Scott Doctor scott at scottdoctor.com --------------------- On 6/7/2015 10:28 PM, david at andl.org wrote: > Thanks for pointing it out, but I knew that the best way to show off a > language is with examples. That's why there are nine sample Andl scripts > comprising dozens of individual examples in the Samples folder. My guess is > if that you're asking me to write examples, the real lesson is that I didn't > make them easy enough to find. > > I have a formal grammar, but I don't expect anyone to read that. More and > better examples is the way to go.
