[stringtemplate-interest] another tweak

[Zenaan Harkness]

>> 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?

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.

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

   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.