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