[stringtemplate-interest] another tweak

[Terence Parr]

On Jul 13, 2009, at 6:25 PM, Zenaan Harkness wrote:

>>> And the beauty of this situation: we already have a current,
>>> comprehensive implementation, with a goodly (though incomplete)  
>>> number
>>> of test cases :)
>
> One other thing, which should have been obvious, and is now, ST is
> implemented as an ANTLR grammar?\

yup...like 5.

> To the extent it is, an initial specification outline (with each  
> grammar
> rule heading up a section) may be an easy head start to kicking off  
> the
> wiki.

yup.

> Each section should then have a standard set of (initially empty) wiki
> headings:

...thanks for the info below...i'll look in detail after i finish the  
book sprint.

Ter
>
>
>   Grammar:
>      {this is the auto-generated (at least initially) bit}
>
>   Summary:
>      {one or two sentences technically concise languaging}
>
>   Overview:
>      {paragraph or two, to give experienced users the goss}
>
>   Detail:
>      {the full detail, suitable for those unfamiliar with ST}
>
>   Examples:
>
>   Test Cases:
>      {this would essentially be code, and because we will end up with
>      test suites in various languages, this section might end becoming
>      just a list of links to test cases in various languages, which
>      test cases are relevant to this section of the specification}
>
>   Links:
>      {links to relevant tutorial sections, related parts of the spec,
>      random-but-hopefully-useful links (hey, it's a wiki :)}
>
>   Implementaters:
>   Bootstrapping:
>      {Ter, you are in prime position with ST 3 rewrite, to discover
>      some key hints for implementers; one "standard" set of hints may
>      be those parts of the grammar that are essential for
>      'bootstrapping' a new ST implementation (which is kinda what
>      you're going to begin in a month or two);
>      I may not have the right terminology here, so this heading might
>      have to change, but you get the idea...}
>
>   Status:
>      {What is the status of this feature in each implementation of ST,
>      ie the Java instance, the dotnet instance, the cpp instance, etc.
>      This would be a little table I guess.
>      Whereas the section "Version Log:" (below) is like a changelog, a
>      historical perspective, Status: is a summary picture, which could
>      overlap in the information provided, and so perhaps these  
> sections
>      might be joined at some stage ?
>      I visualize Status: as a table and Version Log: as a list and  
> more
>      verbose than Status:.}
>
>   Version Log:
>      {This is an essential section. Every feature, every fix to the
>      spec, will from the point of this spec wiki creation, have a
>      version log, with date, brief and full description for each
>      version log entry, which entry states the versions applicable to
>      that part of the spec, differences with earlier/ previous  
> version,
>      etc. Since it's a wiki, we are not limited in the useful
>      information we can include/ provide.}
>
>
> *
> Non-applicable sections can be removed in due course.
>
>
> *
> There ought be a page which has better versions of the above list of
> section descriptions, then each section title can have an innocuous
> little "?" (without the quotes) which is a link to the respective
> description for what that section is intended to contain (which is of
> course also another wiki page).
>
>
> *
> Of course, there will need to be a TOC, and other sections, which for
> example (as I briefly scan the YAML spec) might be as follows:
>
>   -  Status of this Specification
>   -  Abstract
>   -  Introduction
>      -  Goals
>      -  Prior Art
>      -  Relation to ANTLR
>      -  Relation to Other Template Engines
>   -  Preview
>      -  Templates
>      -  Attributes
>      -  Lists
>      -  Maps
>      -  Full Length Example
>   etc
>   -  Syntax Conventions
>   -  Characters
>   etc
>
> It appears that _many_ of the yaml spec sections will be applicable,  
> or
> at the least useful in relation to creating a solid ST spec.
>
>
> *
> Ahh, here's one for the ST 3 version -> YAML has a versioning scheme,
> which provides for a much higher level of backward compatibility, a
> simple tag at the beginning of every YAML file (they basically did a
> spec before they did an implementation I think, not sure) eg:
>
>   %YAML 1.2
>
> I'm not sure how this might apply in ST case, but it certainly _feels_
> like the right thing to do (to have a simple ST version declaration at
> the start of an ST file); at this point, this would need to be  
> optional
> for ST, but would be useful for ST template authors to be able to
> declare minimum required ST spec version required for ST  
> implementations
> to expect to be able to process the file correctly.
>
>
> *
> One thing I particularly like about the YAML spec, is that each  
> grammar
> rule is clearly identified as such, eg:
>
>   [75]     c-nb-comment-text     ::=      “#”  nb-char*
>
> (Note the "[75]" identifying this as the 75th yaml 1.2 spec grammar
> rule.)
>
> Sequential numbering like this may not be practical in a wiki style of
> documentation, and so I guess the section headings above might do that
> job.
>
>
> *
> It would be really nice if, from the wiki pages, an all-in-one html  
> page
> could be auto-generated. Longer term, once a particular version of the
> spec is finalized, I or someone else might be motivated to convert  
> that
> version into Docbook for nice PDF (as well as HTML) generation.
>
>
> Zen
>
> -- 
> Homepage: www.SoulSound.net -- Free Australia: www.UPMART.org
> Please respect the confidentiality of this email as sensibly  
> warranted.