[stringtemplate-interest] Moving closer to 4.0 ST release (what to do with the doc)

[Terence Parr]

I agree.Having multiple languages in the same spot is a bit distracting. I agree that we should simply move all target related stuff to individual documents. that said, I'm not sure how many of these triple code samples there are.

I'm kind of leading towards the cut-and-paste approach to create 4.0 documentation, btw.

Ter
On Feb 13, 2011, at 11:35 AM, Udo Borkowski wrote:

> I don't know if this is practical and efficient to do: 
> 
> what about providing separate "For Java Developer", "For C# Developer" and "For Python Developer" documents, beside the ones that handle all languages in one place with sections like:
> 
> 
> Java	
> StringTemplate query = new StringTemplate("SELECT $column; separator=\",\"$ FROM $table$;"
> );
> query.setAttribute(
> "column", "name"
> );
> query.setAttribute(
> "column", "email"
> );
> query.setAttribute(
> "table", "User"
> );
> 
> C#	
> StringTemplate query = new StringTemplate("SELECT $column; separator=\",\"$ FROM $table$;"
> );
> query.SetAttribute(
> "column", "name"
> );
> query.SetAttribute(
> "column", "email"
> );
> query.SetAttribute(
> "table", "User"
> );
> 
> Python	
> query = stringtemplate3.StringTemplate("SELECT $column; separator=\",\"$ FROM $table$;"
> )
> query[
> "column"] = "name"
> 
> query[
> "column"] = "email"
> 
> query[
> "table"] = "User"
> 
> 
> I found it very disturbing (at least at the beginning) to find these blocks, read "my section", skip the other section and continue reading the common text.
> 
> Depending on how the documents are "generated" providing these 4 flavors may be not such a big effort.
> 
> And maybe add a little "document overview" chapter explain the purpose/differences of the different documents. E.g. when I started I was wondering if it is sufficient to read the "StringTemplate Condensed" stuff or if I am missing something important. The "Documentation Map" is fine, but something more "prose" would be fine. Maybe also some kind of "suggested reading list", depending on the different kinds of users.
> 
> 
> Udo
> 
> 
> 
> On 13.02.2011, at 16:31, Collin Fagan wrote:
> 
>> I learned a lot from the ST3 documentation but I still think it could benefit from some attention.
>> 
>> Here are some things I consider "missing", I apologise if these are well documented and I just can't find them.
>> 
>> If statements support "and" and "or" logic.
>> <if(thing && otherThing)>
>> ... do stuff ...
>> <endif>
>> 
>> Using (" ") for map keys that contain special characters. (Wait, was that even in ST3?)
>> 
>> 
>> Also I can also never quickly find the following information, even though it is present.
>> 
>> Syntax for a map. - I never remember it. 
>> 
>> /**/ for comments in-between templates in a template group. -- I went a loong time without knowing this one, which was silly of me. 
>> 
>> All of this is easily fixable. 
>> 
>> At this point I would recommend each of us take a few minuets and try to put ourselves in the shoes of a beginner who just stumbled onto the ST project, then re-read the documentation. That might help highlight anything that might be missing. 
>> 
>> Collin
>> 
>> 
>> 
>> On Sun, Feb 13, 2011 at 3:49 AM, Oliver Zeigermann <oliver.zeigermann at gmail.com> wrote:
>> ST3 documentation was always good enough for me. Mosf of the time the cheating sheet was all I consulted.
>> 
>> Thus I agree to what Udo said.
>> 
>> Am 13.02.2011 10:28 schrieb "Udo Borkowski" <ub at abego-software.de>:
>> 
>> _______________________________________________
>> stringtemplate-interest mailing list
>> stringtemplate-interest at antlr.org
>> http://www.antlr.org/mailman/listinfo/stringtemplate-interest
>> 
>> 
> 
> _______________________________________________
> stringtemplate-interest mailing list
> stringtemplate-interest at antlr.org
> http://www.antlr.org/mailman/listinfo/stringtemplate-interest