Guys, especially at least one or two PMC-s... I know it's not exactly
a bike shed paining topic, but still it's really not rocket science.
At least tell if you have read it, and saw no blocker in it. (Yes,
it's kind of long, I know... Then imagine implementing it... (-; )
Sunday, March 25, 2018, 6:51:47 PM, Daniel Dekany 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.
>
> 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.
>
>
> 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?).
> 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.
>
>
> 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.
>
>
> 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.
>
> - 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.)
>
--
Thanks,
Daniel Dekany
