On Mon, Apr 2, 2018 at 2:04 PM, Daniel Dekany <ddek...@apache.org> wrote:
> Monday, April 2, 2018, 3:40:09 PM, Woonsan Ko wrote:
>> Hi Daniel,
>> Sorry for late response. I appreciate for your thorough thoughts and
>> ideas. See my comments inline.
>> On Sun, Mar 25, 2018 at 12:51 PM, Daniel Dekany <ddek...@apache.org> wrote:
>>> In FM3 there's a configuration (ParsingConfiguration to be precise)
>>> setting called "templateLanguage" (of type TemplateLanguage). This is
>>> kind of a dummy ATM, but will be important in supporting multiple
>>> template languages in FM3. For example, many prefer a syntax that's
>>> closer to Velocity or WebMacro in some respects (myself included). I
>>> expect that TemplateLanguage will be really just mean template syntax.
>>> Surely I don't plan to support various language semantics, apart from
>>> different set of core directives/functions (i.e., user-defined
>>> dialects). So maybe "templateLanguage" is a misnomer, and it should be
>>> "templateSyntax", or just "syntax". But dialects makes it less
>>> clear... well I don't want to mix them in now, it's already a too
>>> convoluted mail.
>> Yeah, just "Syntax" sounds clearer and simpler to me, too.
> If it will be just syntax... but, we will see as things evolve anyway.
Right. Good point!

>>> Please bear with me till the end, and then tell me if you have better
>>> ideas, or if you will want to "veto" something for some reason.
>>> 1. Remove the tagSyntax and interpolationSyntax settings
>>> The configuration setting "tagSyntax" and "interpolationSyntax" should
>>> be inside the TemplateLanguage, because, for example, for a syntax
>>> like #import(x = 'x.ftl') angleBracket and squareBracket tagSyntax is
>>> clearly meaningless. (OK, "interpolationSyntax" happens to be
>>> meaningful, there but for some other TemplateLanguage it maybe isn't.)
>>> So "tagSyntax" and "interpolationSyntax" will be removed as top-level
>>> settings, and then then a concrete TemplateLanguage subclass may
>>> reintroduces them as its own language specific settings.
>> +1
>>> 2. Restrict FM2-like syntax permutations
>>> Currently we have two TemplateLangauge-s, TemplateLangauge.STATIC_TEXT
>>> (it's like when in FM2 you get a template with the noParse option),
>>> and TemplateLangauge.FTL. The behavior of FTL currently depends on the
>>> top-level "tagSyntax" and "interpolationSyntax" settings (which will
>>> be removed or moved as per 1.)
>>> I will introduce (if nobody says no) StaticTextTemplateLanguage and
>>> FreeMarker2LikeTemplateLanguage (ugh... better name?).
>> Perhaps FM2LegacyTemplateLanguage (FM2LegacySyntax if we rename it)?
> But it won't be the legacy syntax, just has a similar look-and-feel.
> Apart from cleaning up trivial legacy mistakes, note the following
> planned major changes (also mentioned on the Wiki page):
> - Regular directive call syntax. There's won't be such thing as
>   #import or #if on the parser-level, because the syntax of all
>   directives is the same, and the TemplateDirectiveModel (or such)
>   behind tells what parameters are accepted, etc. Thus, for example
>   <#include 'x.f3ah' as ns> becomes to <#import ns='x.f3ah'>. This
>   is crucial both for tooling, but to support custom dialects.
> - #assign/#local/#global will be gone. There will be #var (block-scope
>   declaration) and #set. (Also maybe #val too, I'm not yet sure). BTW,
>   Java 10 has also chosen `val` as the keyword for this (so it will be
>   more familiar).
I see.
Thanks for your explanations!

>>> StaticTextTemplateLanguage will contain a single INSTANCE. But what
>>> about FreeMarker2LikeTemplateLanguage? It could be publicly
>>> instantiateable with a "tagSyntax" and an "interpolationSyntax"
>>> parameter. But instead, I consider just adding ANGLE_BRACKET_INSTANCE
>>> (uses <#> and ${}) and SQUARE_BRACKET_INSTANCE (uses [#] and [=]), and
>>> there won't be other permutations possible (like [#] abd ${}). Bear
>>> with me in point 3 to understand why not.
>> +1
>> I like this reduced set of syntaxes in a template language as this is
>> not a generic interpolation library.
> Or rather, a "templating" library. Is there a such word? Now there is.
>>> 3. File extensions and language names
>>> The main issue with using multiple syntaxes where all is a "FreeMarker
>>> 3 template" is the confusion it can cause. This includes what syntax
>>> are you using in the official documentation? But I think it's a waste
>>> when you already have an engine, yet if someone needs or even just
>>> prefer a different syntax (people tend to be emotional about
>>> look-and-feel), they need a whole another engine as well (or a fork).
>>> If they need substantially different semantics, then's it's OK or even
>>> preferable to have multiple engines, but just for the syntax? I don't
>>> think so.
>>> So, I think all TemplateLanguage-s need a short name that's identical
>>> to its (preferred) file extension (well, apart from the last letter
>>> for the output format, but see that later). Then, on the top of the
>>> Manual you can have a dropdown component where you select which
>>> language are you using, which is the same as what file extension you
>>> have, so it should be easy to figure out for the user. As the
>>> languages only differ in syntax, it's possible to safely translate
>>> between them automatically.
>>> Also, the one-to-one mapping between the exact syntax and the file
>>> extension is important, as that's how most editors/IDE-s figure out
>>> which syntax highlight rules (and such) to active.
>>> So now it's hopefully clear why I don't want to support all 4
>>> permutations of that tagSyntax-es and interpolationSyntax-es... We
>>> already will have at least two funny file extensions.
>>> But wait, all those have to be combined with the output format (as in
>>> *.ftlx VS *.ftlh in FM2), which decides the auto-escaping applied. It
>>> also influences how the static text parts should be syntax highlighted
>>> in an editor/IDE, so we can't get away without a distinct file
>>> extension for each. So we have to add a last letter to the extension,
>>> which indicates the output format... h for HTML, x for XML, etc.
>>> The consensus (kind of...) on file extensions last time was these,
>>> because there were no interpolationSyntax yet: f3<a|s>, f3<a|s>x,
>>> f3<a|s>h. Like, if you want angle bracket tag syntax and HTML output
>>> format, then the file name will be "foo.f3ah", but if you want the
>>> same with square bracket tagSyntax then it will be "foo.f3sh". As of
>>> 2.3.28 we also have interpolationSyntax, but if as per point 2 the
>>> interpolationSyntax becomes square bracket together with the tag
>>> syntax, the earlier extension remain usable, and we don't need
>>> abominations like f3adh (Angle tag + Dollar interp.), f3ash (Angle tag
>>> + Square interp.), etc.
>> +1
>>> 4. File extension *always* should end with the output format letter
>>> In the case of f3<a|s>, where the output format is "undefined", it
>>> should be f3<a|s>u. That is, the last letter of the extension should
>>> always correspond to the output format. Because:
>>> - Forgetting about the output format is a security risk (XSS
>>>   attacks), or it can be sneaky bug as it bites rarely. So it's
>>>   better if the user is more explicit/conscious about not doing
>>>   auto-escaping.
>> +1
>>> - Then the part of the file extension that indicates the template
>>>   language and the part that indicates the output format can be
>>>   unambiguously separated, even if someone one day will need
>>>   multi-letter syntax indicators. (This can be especially useful for
>>>   custom dialects, as they will need a separate set of file
>>>   extensions.)
>> +1
>> So, file extension comprise prefix ("f3"), syntax indicator(s) and
>> output format indicator, and the syntax indicator(s) justifies itself
>> as it is very useful in IDE and tools for example.
>> I don't think those single character indicator would be a problem in
>> the future practically, so all sound like reasonable choices.
>> As you mentioned above, we will have many funny extensions, but I
>> think it would be useful in the end and easy to understand based on
>> this convention.
>> I suppose if someone wants to loads template sources with a specific
>> syntax from one of the pre-defined static TemplateLanguage instance
>> programmatically, regardless of the template name and extensions, it
>> should be still possible, right?
> Kind of. It would work similarly as in FM2. That is, you can provide a
> ParsingConfiguration to the Template constructor (or for Template-s
> managed by FreeMarker itself, you can use TemplateConfiguration-s for
> similar purse). Also, the Configuration itself is the default
> ParsingConfiguration. After all that, if the file extension is
> recognized, it will override the templateLanguage and outputFormat
> settings in the ParsingConfiguration. So you can't specify things
> "regardless" of the file extension, because when the file extension is
> recognized, its meaning is enforced (to avoid confusion). If it's not
> recognized, then you have full control.
I see.

>> e.g, embedding FM3 engine to use specific expressional templating.
>> Then I think everything seems very reasonable to me.
> Great, and thanks for the feedback! So now... I will still have to get
> rid of syntax auto-detection with the #ftl header, and then I guess I
> can implement this. (And then probably null handling. And then I guess
> #var/#set...)
Cool! Looking forward to it.



>> Regards,
>> Woonsan
>>> --
>>> Thanks,
>>>  Daniel Dekany
> --
> Thanks,
>  Daniel Dekany

Reply via email to