On Wed, Jul 5, 2017 at 6:53 AM, Daniel Dekany <[email protected]> wrote:
> Here's a second take on this...
>
> As a reminder, my first idea was fm3, and then fm3s for square bracket
> syntax. Then "h" or "x" is added to that if you want to indicate the
> outputFormat in the file extension (which is recommended, as in FM2),
> so you end up with fm3, fm3h, fm3x, fm3s, fm3sh, fm3sx.
>
> A drawback of the above is that it's kind of ambiguous. Like, one day
> you see fm3r. Does that mean syntax "r", or it's the usual angle
> bracket syntax with output format "r"? Or, what if you want an output
> format with abbreviation "s", or a syntax with abbreviation "h"? Then
> f3s and f3h become ambiguous.
>
> So my second take on this is that the extension should be concatenated
> from these:
>
> 1. "f3" to indicate that it's a FreeMarker 3 thing
>
> 2. Required syntax identifier, exactly 1 letter: "a" for angle bracket
> tag syntax, "s" for square bracket tag syntax, and some other
> letters for whatever additional syntax there will be.
>
> 3. Optional output format identifier. "h" for HTML, "x" for XML. Other
> letters can be introduced when there's a need.
>
> So you end up with f3a, f3ah, f3ax, f3s, f3sh, f3sx.
+1
Woonsan
>
> Note that f3a and f3s are equally verbose this way. There's an agenda
> behind this, but I left this more subjective part last. I believe
> non-<>-plus-${} syntaxes shouldn't be secondary citizens. While
> supporting multiple syntaxes adds complexity (and I think several will
> be needed, like to avoid clashes with `${}` in the generated output),
> I hope it will worth it. To avoid confusion, such as when referring to
> a syntax in documentation, this kind of symmetry (that the syntax
> indicator is always consistently there) helps.
>
>
> Thursday, June 15, 2017, 5:38:29 PM, Daniel Dekany wrote:
>
>> Thursday, June 15, 2017, 1:42:49 PM, [email protected] wrote:
>>
>>> On Thu, 2017-06-15 at 10:05 +0200, Daniel Dekany wrote:
>>>> Thursday, June 15, 2017, 8:33:22 AM, Denis Bredelet wrote:
>>>>
>>>> > > BTW, we also have this thing (agreed upon earlier), that for the sake
>>>> > > of easier tooling like IDE plugins, we will remove syntax auto
>>>> > > detection, and instead rely on extension. (I'm yet to see any tool
>>>> > > that can deal with FM2 syntax detection, unless it has used FreeMarker
>>>> > > itself to parse the template... so we can conclude that it didn't work
>>>> > > out very well in practice.) So we will need one more variation on all
>>>> > > of all these for square bracket syntax. Maybe fm3s, fm3sx, fm3sh (ugh,
>>>> > > my eyes…).
>>>> >
>>>> > You can put is as prefix sfm3, sfm3x, sfm3h (or sf3, sf3x, sf3h - Street
>>>> > Fighter here we come!).
>>>>
>>>> Then the output format ("", "x", "h", etc.) is clearly separated from
>>>> the syntactical variation ("", "s", so far). That's an advantage. But
>>>> because everything has to be a compromise, there's the drawback that
>>>> it's somewhat harder to identify for users that the file belongs to
>>>> FreeMarker.
>>>>
>>>> Also note that because of the planned dialects feature, we will need
>>>> some rule regarding which file extensions we reserved for standard
>>>> language variations. One idea is that anything that starts with "fm"
>>>> is reserved for "official" FreeMarker files. (We could also reserver
>>>> "sfm", but it's not a future proof approach, as we possibly will have
>>>> more kind of files in the future.) Though we might as well reserve all
>>>> extensions that contain "fm" anywhere.
>>>
>>> I've always preferred the multiple extension approach to things
>>> like this, following a process and remove sort of pattern. For
>>> example instead of using something like .ftlx or .ftlh use .xml.ftl
>>> or .html.ftl that when processed result in a .xml or .html file
>>> or snippet. This is more clear (and in some cases editor/IDE
>>> friendly) because the standard extensions are used and chained as
>>> needed.
>>
>> I would prefer that too, but as far as I know multiple extensions are
>> rarely supported by other software. Like most text editors can't
>> associate different syntax highlight definition to *.ftl and
>> *.html.ftl, because they start by extracting the part after the last
>> dot. FreeMarker itself can be configured to treat *.html.ftl and
>> *.ftlh the same, as it can match things with globs and what not. Maybe
>> FM should recognize both variation by default; that's a good point.
>> But we still need to give a single recommendation that works for the
>> most users.
>>
>>> On .ftl vs .fm3: One nice thing about .ftl is it has a sort of
>>> brand recognition associated with FreeMarker (Template Language).
>>> It looks like .fm3 was for a Lotus 1-2-3 spreadsheet extension, now
>>> obsolete but a lot of software and existing mime type mappings may
>>> still use it.
>>
>> Out of blind luck nothing commonly known uses *.ftl (yet - FTL is
>> common abbreviation for Faster Than Light, which sounds cool :-) ).
>> But it can't remain ftl, as we have to differentiate it from the FM3
>> format. "ftl3" comes to mind naturally, but it gets a bit too long
>> when you also add "h" (and then even "s"...), plus then we still have
>> to keep the FTL term, which is unnecessarily cognitive burden for
>> newcomers. Compromises, compromises...
>>
>> BTW, Denis's idea, "f3", is not used by anything apparently. (It's not
>> as talking as fm3 though.)
>>
>>> A common pattern for syntax and other variations within a file is
>>> to use a header at the beginning of the file to describe them.
>>
>> We support that in FM2 (<#ftl outputFormat='HTML'> works since
>> 2.3.24), and certainly will continue doing so in FM3. However, it
>> doesn't mean that other software (like text editors) will recognize
>> headers. After all, it requires reading the file contents and parsing
>> the content to some extent. If we provide a simpler way, like using
>> some more specific file extensions, that's an escape route for the
>> users, in case the tools they use aren't the smartest. Because
>> ultimately they will suffer if we stick to more advanced solutions.
>>
>> Also, as of per-template output format, I think it's generally handy
>> to just be able to tell the output format right from the file name
>> (with double extension or a single more specific extension).
>>
>>> This is true of .xml and .html files, though in practice applied in
>>> different ways. In XML files something like the '<?xml
>>> version="1.0" encoding="UTF-8"?>' first line is always used as
>>> version '1.0' is the only commonly used version while 'dialects' (not
>>> really the exact concept we're discussing for FreeMarker, but
>>> similar) are described with additional attributes on the root element.
>>> For .html the standard header to use has varied over time.
>>>
>>> One advantage to using the first line approach is that it is much
>>> more flexible as you have more space and can even structure it, and
>>> another is that it allows the file extension (and related mime type)
>>> to remain stable over time.
>>
>> That's basically what we do, except that for the most common use cases
>> we can indicate things right in the file extensions. Those are also
>> the cases that are most likely to receive special treatment from tools
>> (like HTML syntax highlighting). Tool are still expected to parse the
>> headers (and so you might opt for using the generic extension, like
>> ftl), but that probably won't happen often in the real world.
>>
>>> On the topic of mime types I don't know if 'text/x-freemarker' is
>>> official in any way for .ftl files but it seems the most commonly
>>> used one. Along with file name extensions It is also nice to mime
>>> types for remain stable over time.
>>
>> The FM project haven't defined a MIME type for templates. Anyway, now
>> I guess it should be 'text/x-freemarker-3' then (and maybe
>> 'text/x-freemarker-html-3' and such).
>>
>>> Some food for thought... and apologies that these comments open the
>>> discussion more instead of narrowing down a decision.
>>>
>>> -David
>>
>
> --
> Thanks,
> Daniel Dekany
>
