Hi Daniel, I think there is a way to define a custom FreeMarker template path in IntelliJ - see https://intellij-support.jetbrains.com/hc/en-us/community/posts/115000686590-How-to-configure-the-freemarker-template-path-or-what-s-the-default-path-
Having said that we should take care that the IntelliJ plugin is happy * Some users do create web applications based on Apache FreeMarker * Having FTL support built-in is a huge bonus for beginners Regarding the intended role of "/templates" * The implemented template loading tries to resolve the given template name as file and if there is no file the actual template loading is delegated to a "MultiTemplateLoader" * In https://issues.apache.org/jira/browse/FREEMARKER-146 I split the existing templates into a reusable part (living now in "templates") and examples (living now in "examples") * IMHO the "templates" directory should contain commonly useful templates - so they could be considered as guaranteed functionality * Transforming CSVs * Transforming Excel files to CSV, HTML & Markdown (and maybe Confluence Markup) * Transform JSON to YAML and the other way around * I'm happy to have those templates as files in the installation directories - better visibility and user can add there own templates (if the want to play nasty) What I want to change * Use "templates" as FreeMarker template root for the CLI installation and "~/.freemarker-generator" directory * Adopt the examples and documentation, e.g. "freemarker-generator -t info.ftl" instead of "freemarker-generator -t templates/info.ftl" What do you think? Siegfried Goeschl > On 05.08.2020, at 13:28, Daniel Dekany <daniel.dek...@gmail.com> wrote: > > Ah, you have the FreeMarker plugin in IntelliJ, and that assumes something > crazy like that? The Community Edition doesn't have that plugin, and I > never saw it. But if that plugin indeed assumes that the template root is > the project root... that wouldn't make sense, in any real world project. > Even if some have a "templates" directory laying around in the directory as > the POM, then that would be the template root (means, a template path is > like "/foo.ftl", not "/templates/foo.ftl"), not the whole project. So, I > certainly don't think we should align with a broken plugin, especially as > most users won't be affected (they just use the binary). > > Also, I'm a bit confused about the intended role of "/templates". Is it > core (guaranteed) functionality in Generator CLI? As opposed to a core > functionality of Generator itself? (Sure, for now Generator can be called > via CLI only, but you see what I mean.) Or is it just some examples laying > around, whose presence users shouldn't count on in their projects? If it's > core functionality, then it certainly should be a Java resource, packed > into the jar. > > Also let's not skip the question from the earlier mail, regarding what path > should this be available for the TemplateLoader (and for -t)? > > On Wed, Aug 5, 2020 at 11:47 AM Siegfried Goeschl < > siegfried.goes...@gmail.com> wrote: > >> Hi Daniel, >> >> When moving the "templates" to a subdirectory IntelliJ complains about not >> finding the FTL include files - technically it is working but without >> tweaking IntelliJ it spits out errors. And the Travis tests failed while my >> local tests succeeded - see >> https://travis-ci.org/github/apache/freemarker-generator/builds/714600403. >> >> Regarding template root directory - I guess there is some room for >> improvements >> >> * I'm passing a list of template root directories (current directory, CLI >> installation directory, ~/.freemarker-cli/" >> * The "templates" directory is just the way I organised the overall file >> structure >> * Additional template root directory can be passed on the command line >> * The implementation can pick up any FTL file using absolute or relative >> file paths (and URLs) >> >> Thanks in advance, >> >> Siegfried Goeschl >> >> >>> On 04.08.2020, at 22:12, Daniel Dekany <daniel.dek...@gmail.com> wrote: >>> >>> Can you clarify, what part of IntelliJ is happy about that, and why? >>> >>> Also it reminds me of another thing I wrote about earlier. Generally, we >>> say that the template root directory shouldn't not contain anything but >>> templates, so if the project root is the template root directory, or the >>> freemarker-generator home directory, that's a bit fishy. Yes, the reason >>> for this purist approach is partially security concerns with web >>> applications, and this is not one. But whatever the original reasons are, >>> FreeMarker has this omnipresent concept of the template root directory, >>> which is kind of a virtual root directory for a template (i.e., they can >>> leave it, and it's all templates, or rarely files referred from >> templates, >>> like images). >>> >>> Also, it's strange/confusing if the template root directory has a >>> "templates" subdirectory. I mean, the template root directory is what one >>> would normally call the templates directory. As a template author, I >> would >>> expect some path like "/freemarker-generator/whatever.ftl" (also note >> that >>> it's an absolute path). There, "/freemarker-generator/" tells me that >> this >>> is something included in freemarker-generator, and not templates of my >>> project. >>> >>> On Tue, Aug 4, 2020 at 8:51 PM Siegfried Goeschl < >>> siegfried.goes...@gmail.com> wrote: >>> >>>> I'm not happy about it :-) >>>> >>>> * A top-level "templates" directory makes IntelliJ happy when includes >> are >>>> used >>>> * I have an ExamplesTest which tests each documented command line usage >>>> and I prefer to have it in sync with the documentation >>>> * I actually tried it but reverted the changes since the Travis build >> fails >>>> >>>> Thanks in advance, >>>> >>>> Siegfried Goeschl >>>> >>>> >>>>> On 28.07.2020, at 22:34, Daniel Dekany <daniel.dek...@gmail.com> >> wrote: >>>>> >>>>> It's just that "templates" belongs to the "main" source code of the >>>>> freemarker-generator-cli, similarly to >> config/freemarker-cli.properties, >>>>> which is under src/main. (I think many of us expect a Maven project >> root >>>>> directory to only contain the "noise" needed for build and legal, and >>>> "src" >>>>> that contains *all* the essential source code.) Also, as the source >> tree >>>>> doesn't mirror the binary distribution directory tree anyway, so I'm >> not >>>>> sure if there's any fundamental reason to make an exception with >>>>> "templates", and put it under the root. >>>>> >>>>> On Tue, Jul 28, 2020 at 4:09 PM Siegfried Goeschl < >>>>> siegfried.goes...@gmail.com> wrote: >>>>> >>>>>> Hi folks, >>>>>> >>>>>> Back from the mountains and in front of the keyboard again :-O >>>>>> >>>>>> * I created a JIRA ticket and will push a feature branch soon (bad >>>> habits >>>>>> die hard) >>>>>> * I will go through the licences (review and collect in "licenses" >>>>>> directory) >>>>>> * Good point about plugin versions being defined in apache POM - will >>>>>> rework them >>>>>> * I will delete the existing configuration of the "release" profile >>>>>> >>>>>> Some things to discuss >>>>>> >>>>>> * What are the benefits to move "templates" to "src/main/templates"? >>>>>> Currently they are in sync with "freemarker-cli" which is quite nice >> for >>>>>> tests & documentation ... >>>>>> >>>>>> Thanks in advance, >>>>>> >>>>>> Siegfried Goeschl >>>>>> >>>>>> >>>>>>> On 26.07.2020, at 01:27, Daniel Dekany <daniel.dek...@gmail.com> >>>> wrote: >>>>>>> >>>>>>> I said I will help in the Apache release process, so only focusing on >>>>>> that, >>>>>>> so some points: >>>>>>> >>>>>>> - We are required to have a so-called source release (every other >>>>>>> artifact is optional in the policy). As we are using the >>>>>> org.apache:apache >>>>>>> parent, that should generate that automatically, with .asc and sha512 >>>>>> and >>>>>>> all. But currently it doesn't, because maven-release-plugin >>>>>> config/argument >>>>>>> is overwritten with this: >>>>>> <arguments>-Dmaven.javadoc.skip=true</arguments>. >>>>>>> We should keep configuring release at minimum, to avoid such >>>> accidents. >>>>>>> Maybe as in >>>>>>> https://github.com/apache/freemarker-docgen/blob/master/pom.xml#L70. >>>>>>> - I assume we also want a binary release, for the CLI only, and >>>>>>> freemarker-generator-cli-x.y.z-*app*.zip (note the "-app") will be >> our >>>>>>> binary release artifact. Then: >>>>>>> - It bundles some dependency binaries that are not under ASL2 >> license. >>>>>>> Unfortunately, the licenses of those must be included in the >>>>>>> distribution. >>>>>>> See the LICENSE at >>>>>>> https://github.com/apache/freemarker-docgen/blob/master/LICENSE. >>>> At >>>>>>> the bottom, it lists the licenses, then it refers to the actual >>>>>> license >>>>>>> files. As we will have many licenses, let's create a "licenses" >>>>>> directory >>>>>>> for them. (In the future, the dependencies have to be checked >>>>>>> for changes. >>>>>>> Even version upgrades my pull in sneaky transient dependencies. >>>> Some >>>>>>> licenses are not even allowed, so anything but ASL2, MIT, >>>>>>> BSD-without-advertisement-clause, will need closer attention.) >>>>>>> - I noticed that the documentation is not included in the binary >>>>>>> distribution. But because of the extra legal burden including it >>>>>> would >>>>>>> bring (we have fonts and icons under CC-SA and SIL OFL in the >>>> Docgen >>>>>>> output), I actually prefer that to stay like that. >>>>>>> - .sha512 file is not yet generated >>>>>>> - freemarker-generator-cli/src/site: If you agree, instead of this I >>>>>>> will create freemarker-generator*-site*/src/docgen, and convert the >>>>>>> Markdown to XDocBook. For now this will be only the CLI >> documentation, >>>>>> and >>>>>>> the JavaDoc, as the freemarker-generator-maven-plugin is not ready. >>>> One >>>>>>> annoyance I realized is that we should have Docgen in Maven Central >>>>>> for the >>>>>>> builds to work reliably in the future, which means that Docgen has to >>>>>> be >>>>>>> officially released (it never was, it's an internal tool). That would >>>>>> be a >>>>>>> minimalistic release, means, no announcement, no web site, just the >>>>>> bare >>>>>>> minimum (i.e., source release, and deployment to Maven Central). I >>>> have >>>>>>> some backlog there (Google keeps nagging me about mobile issues), but >>>> I >>>>>>> hope I can fix that in the coming days, then go through the official >>>>>>> release process (takes 1-2 weeks). >>>>>>> - Some smaller things: >>>>>>> - >>>>>>> - Having a "release" profile is also hopefully unnecessary, >> because >>>>>>> org.apache:apache takes care of signing. >>>>>>> - We should also remove most plugin version management, as many of >>>>>>> those versions are set in org.apache:apache. >>>>>>> - freemarker-generator-cli/templates should be inside >>>>>>> freemarker-generator-cli/src/main/templates, I guess. >>>>>>> >>>>>>> P.s.: Siegfired asked our opinions in another thread. I did my part, >>>> even >>>>>>> too much (;, so, would be good if others participate in that as well. >>>>>>> >>>>>>> -- >>>>>>> Best regards, >>>>>>> Daniel Dekany >>>>>> >>>>>> >>>>> >>>>> -- >>>>> Best regards, >>>>> Daniel Dekany >>>> >>>> >>> >>> -- >>> Best regards, >>> Daniel Dekany >> >> > > -- > Best regards, > Daniel Dekany
