Thanks for the response.
Nope, I spoke to Ter a long time ago and I think he had a good idea of what I was looking for. He pointed me to www.stringtemlate.org <http://www.stringtemlate.org/> and the documentation there. I was trying to learn ST, but I could not get an intuitive understanding of how to debug it. I am specifically referring to developing the ST script that generates the C++ code for the lexer and parser for a domain-specific language developed by a user. I had just completed a rough draft of the C++ runtime and hit a brick wall with ST, primarily because I was in the learning mode for ST. This was caused by the amount of time necessary to debug a draft of a ST template to generate C++ the lexers and parsers. The issue was the time necessary to know where to look and make it do what I wanted it to do. I asked Ter about books on ST to help get me over the hurdle. Ter mentioned that discussions had been held (more that once I think) about the possibility of a ST book, apparently similar in nature to the books he has published on ANTLR. But, Ter said that the demand is not there to justify writing a book, which made perfect sense. It is a matter of economics. That's when he pointed me to the string template site It seems to end up being a chicken-and-egg issue for neophytes in ANTLR (admittedly like me). Neophytes like me could use the more basic documentation (like on ST) to work ourselves up to a higher level of understanding and proficiency. Then the other end of it is detailed documentation to fill in the gaps. But it may be difficult to find good contributors because they don't have the knowledge necessary to do this. My personal opinion is that the documentation helps improve the adoption rate for those new to the technology. It's all about speed and the learning curve to get a job done as quickly as possible. For example, I did not have a much time to figure out the internals of ST so I could debug effectively. Documentation helps overcome the initial hurdle. And in this particular case it could also benefit by starting with the simple stuff first and then incrementally build the user up to the hardcore details. In my specific case with debugging the ST script the issue was both levels (simple documentation building to the meaty details) to *really* understand what ST was doing. I simply was spending so much time on it and it got so confusing that I finally cried uncle and that was it, which is frustrating when someone is getting closer to the goal of a testable draft. I am sorry to make a big deal here, it wasn't my intention. I actually was trying to be empathetic to the needs of the open source community and the economic constraints. The main point I wanted to make is that adopting a new technology, like ST and ANTLR, can obviously have a high hurdle up front that can be reduced by good documentation. This in turn can help increase the adoption rate of the technology, which in turn may help increase the base of open-source contributors who get engaged and seriously contribute. Regards, George _____ From: Loring Craymer [mailto:[email protected]] Sent: Sunday, July 11, 2010 5:59 PM To: George Shannon; Ramanand Mandayam; [email protected]; [email protected] Subject: Re: [antlr-dev] Confusing class names in antlr-3.2.jar The ST docs at www.stringtemplate.org are adequate for most purposes, although the idiosyncrasies of ST syntax can be confusing at times. I suspect that Ter interpreted your request as asking for internals documentation for ANTLR. --Loring From: George Shannon <[email protected]> To: Loring Craymer <[email protected]>; Ramanand Mandayam <[email protected]>; [email protected]; [email protected] Sent: Sun, July 11, 2010 8:50:05 AM Subject: RE: [antlr-dev] Confusing class names in antlr-3.2.jar It appears that the reason for some confusion is because the documentation is not complete in certain key areas, so to speak. For example, I tried to create a C++ runtime for ANTLR, and got to the point where I was ready to test, the final step being creating the StringTemplate for the C++ runtime. This final step, i.e. StringTemplate, was a disaster. There is hardly any documentation available. I was eventually in the mode of trying to create the C++ version using pure trial and error. I asked Terry about it and the answer was that there is not enough demand for documentation to justify the investment (that is, no excellent resources like the books he has written for ANTLR). I assumed StringTemplate documentation was available since I already had Terry's books on ANTLR. I was wrong. So frankly I dropped the project. While there is a C runtime available, having a C++ runtime would have been awesome for us, and perhaps a few others (one person was very interested), BUT, without some serious documentation it ain't gonna happen. Open source is great, but without serious documentation in ALL the right places it is difficult to adopt; "difficult" being equivalent to "expensive" in terms of labor and time/lost opportunity. Please be patient while I digress. Many years ago I worked as an engineer at what was then McDonnell Douglas (now Boeing). I worked space programs - hypersonic space vehicles, single-stage-to-orbit stuff to replace the Space Shuttle. People in the industry had a saying: "No bucks, no Buck Rogers." What really makes those birds fly is: funding. I am suspicious that, in some ways, the same may apply to things like documentation (StringTemplate) - no bucks (or free labor), then no documentation (and no Buck Rogers). I make these comments as a small business startup trying to compete with the big dogs with deep pockets. Please note that I'm not criticizing Terry or any of the devoted people working on ANTLR and making it an excellent open source product. They are working hard within constraints. This is just my two cents worth on how the product adds value - to take it to the next level may not involve ONLY product development (i.e., new or improved functionality). It may involve simply providing more documentation to help make it easy to learn and ADOPT the product in innovative ways. Best Regards, George Shannon _____ From: [email protected] [mailto:[email protected]] On Behalf Of Loring Craymer Sent: Sunday, July 11, 2010 2:35 AM To: Ramanand Mandayam; [email protected] Cc: [email protected] Subject: Re: [antlr-dev] Confusing class names in antlr-3.2.jar ANTLR 3 is written in ANTLR 2, so the jar contains both ANTLR 2 under antlr.* and ANTLR 3 under org.antlr.*. --Loring From: Ramanand Mandayam <[email protected]> To: [email protected] Cc: [email protected] Sent: Sat, July 10, 2010 11:25:22 PM Subject: [antlr-dev] Confusing class names in antlr-3.2.jar Hi I downloaded the latest release (antlr-3.2.jar) of the runtime jar files and tried to generate a lexer. I ran into some errors which I was looking into and found this strange behavior. If I invoke the main method in the class 'antlr.Tool' as shown in the command line below, java -cp /usr/local/antlr/antlr-3.2.jar antlr.Tool mylexer.g the tool assumes that I want to use ANTLR v2.7.7 However, if I invoke teh main method in the class 'org.antlr.Tool' as shown in the command line below, java -cp /usr/local/antlr/antlr-3.2.jar org.antlr.Tool mylexer.g the tool assumes that I want to use ANTLR v3.2 This is very confusing and I have not yet been able to identify any portion of the documentation that describes this difference. Can we perhaps make this distinction clear in either the README or some other equivalent documentation describing the command line? Cheers Ramanand
_______________________________________________ antlr-dev mailing list [email protected] http://www.antlr.org/mailman/listinfo/antlr-dev
