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
