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
