BTW, the example templates will need some reviewing. Something I saw a lot was using foo["bar"] instead if foo.bar. That's something people used to be confused about (when can they use which form), and just default to foo["bar"]. Thus we should use terser dotter form whenever we can, showing that it's safe and good practice to do so.
Also, I have noticed we still do the dataSources?values[0] thing. You didn't add anything for that case after all (or the examples are outdated)? So this is probably by far the most frequent use case, where we expected exactly 1 data source. The problem is that if you pass in 2 sources, dataSources?values[0] will silently ignore the 2nd source, instead of failing. On Sun, Aug 23, 2020 at 8:42 PM Siegfried Goeschl < [email protected]> wrote: > Hi Daniel, > > I'm using now "app.home" system property to bootstrap the configuration > and merged FREEMARKER-153. > > So in theory you could rebase/merge and try to use "app.home" ... > > Thanks in advance, > > Siegfried Goeschl > > > > On 22.08.2020, at 19:43, Daniel Dekany <[email protected]> wrote: > > > > Link was wrong as well: > > > https://github.com/apache/freemarker-generator/blob/FREEMARKER-154/freemarker-generator-website/pom.xml#L85 > > The you see what's needed currently only to get the info.ftl output. > > > > On Sat, Aug 22, 2020 at 7:39 PM Daniel Dekany <[email protected]> > > wrote: > > > >> Pf, lot of typos... so to clarify, I did solve it, it's just fragile. > Also > >> onE of the "main" artifacts is > >> freemarker-generator-cli-0.1.0-SNAPSHOT-app.tar.gz (so there, > classifier is > >> "app"). That's deployed to the repository, so it's a "real" artifact. > >> > >> On Sat, Aug 22, 2020 at 7:34 PM Daniel Dekany <[email protected]> > >> wrote: > >> > >>> I could hack it around, the problem is that it's fragile as it is: > >>> > https://github.com/apache/freemarker-generator/blob/FREEMARKER-154/pom.xml > >>> If it only needed app.home, then it would be much less fragile. (And > also > >>> easier for others to call it without the scripts. Well, OK, almost > nobody > >>> needs that... but it's cleaner overall.) > >>> > >>> There are main artifacts of different classifiers, on is "app". All > >>> belong to "main" from Maven's perspective. Anyway, the point is to > have a > >>> project structure that helps understanding stuff. > >>> > >>> main/app is fine with me. > >>> > >>> On Sat, Aug 22, 2020 at 10:01 AM Siegfried Goeschl < > >>> [email protected]> wrote: > >>> > >>>> Hi Daniel, > >>>> > >>>> I'm mostly fine with the current directory layout > >>>> > >>>> * There is some documentation here - > >>>> > https://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html > >>>> * As far as Maven is concerned the main artefact is the JAR > >>>> * Having said that the "Appassembler Maven plugin" makes assumptions > as > >>>> well > >>>> * The "config" is (sort of still) there because until recently I > >>>> packaged the config file as part of the JAR (currently > FREEMARKER-153) and > >>>> actually had two of them :-( > >>>> > >>>> I will review my changes before merging FREEMARKER-153 into master > (end > >>>> of this week hopefully) > >>>> > >>>> I do not fully understand the problem you had with the configuration > >>>> when generating the docs - in the meantime you can start the Main > class > >>>> without config file > >>>> > >>>> Thanks in advance, > >>>> > >>>> Siegfried Goeschl > >>>> > >>>> > >>>> > >>>>> On 21.08.2020, at 11:59, Daniel Dekany <[email protected]> > >>>> wrote: > >>>>> > >>>>> Also, I'm quite certain "templates" meant to be under "main", > >>>> similarly as > >>>>> "config" already is. (In case it's not just an oversight, it's > because > >>>> the > >>>>> top-level categories under "src" ("main", "test", and "site") are the > >>>>> different kind of deliverables. (OK, the test suite isn't really > >>>>> deliverable, but it's a separate unit.) "templates" and "config" are > >>>> both > >>>>> part of the main deliverable, which is the app artifact, so they > belong > >>>>> under "main".) > >>>>> > >>>>> "src/scripts" doesn't look right for the same reason. As we deliver > >>>> them > >>>>> with the app, they belong under "main". Where inside that is not that > >>>> clear > >>>>> to me... I mean Maven doesn't really establish a convention there, > but > >>>>> maybe unde the assembly? Or maybe there should be a main/app-home to > >>>> pack > >>>>> all the statics under the app home (tempaltes, config, > >>>> run-examples...). So > >>>>> that's a more like matter of preference thing, I guess. > >>>>> > >>>>> On Thu, Aug 20, 2020 at 10:17 PM Daniel Dekany < > >>>> [email protected]> > >>>>> wrote: > >>>>> > >>>>>> We will need your signature that's here: > >>>>>> https://dist.apache.org/repos/dist/dev/freemarker/KEYS and > >>>>>> https://dist.apache.org/repos/dist/release/freemarker/KEYS, at > least > >>>> if > >>>>>> you build the release artifacts. Otherwise I'm not exactly sure how > >>>> you > >>>>>> want to do this snapshot release thing. I think the best way to try > if > >>>>>> releasing is working is trying to do a release, but not actually > start > >>>>>> voting, and obviously not letting it outside the staging repo. > >>>>>> > >>>>>> I think you should merge back FREEMARKER-153 into the main branch, > >>>> because > >>>>>> it's the development head right now. (Like, if someone wanted to add > >>>> a PR, > >>>>>> it should be based on what's now 153, hence, that should be the > >>>> master.) > >>>>>> > >>>>>> One thing I just ran into, while trying to add the rest of the docs. > >>>> The > >>>>>> configuration/freemarker-generator.properties is found based on > >>>> CLASSPATH, > >>>>>> while templates is found based on the "app.home" system property. I > >>>> think > >>>>>> it would be good if bareily setting "app.home", and ensuring the the > >>>> Maven > >>>>>> dependencies (jar-s) are found by Java makes the CLI work. I ran > into > >>>> this, > >>>>>> because to generate documentation I need to class > >>>> freemarker-generator from > >>>>>> Maven (to capture the --help, etc.), and since the launcher scripts > >>>> are > >>>>>> platform dependent, I directly call > >>>>>> org.apache.freemarker.generator.cli.Main. But I think in general > that > >>>> would > >>>>>> be a step in the right direction, if that only has minimal > >>>> requirements. > >>>>>> > >>>>>> On Fri, Aug 14, 2020 at 12:22 PM Siegfried Goeschl < > >>>>>> [email protected]> wrote: > >>>>>> > >>>>>>> Hi Daniel, > >>>>>>> > >>>>>>> Regarding SNAPSHOTs - I would be glad to see all the moving parts > >>>>>>> working, e.g. generated artefacts, Hayes, signatures and upload :-) > >>>>>>> > >>>>>>> Thanks in advance, > >>>>>>> > >>>>>>> Siegfried Goeschl > >>>>>>> > >>>>>>> > >>>>>>> > >>>>>>>> On 13.08.2020, at 02:16, Daniel Dekany <[email protected]> > >>>> wrote: > >>>>>>>> > >>>>>>>> A SNAPSHOT version is not public, so it's not really a release, > and > >>>> for > >>>>>>>> internal testing you can build stuff. > >>>>>>>> > >>>>>>>> Also, I don't remember right now anything super important, but > >>>> there are > >>>>>>>> mails where I listed things. > >>>>>>>> > >>>>>>>> Yeah, I'm still in debt with the docgen conversion. It kind of > >>>> works, if > >>>>>>>> you saw that branch. I will continue to copy the md content into > >>>> it, and > >>>>>>>> hopefully won't run into any more stuff that makes me add Docgen > >>>>>>> features. > >>>>>>>> (Like last time I started shoveling in the Examples section, only > to > >>>>>>>> realize that we need to be able to insert external files, so now > we > >>>>>>> don't > >>>>>>>> have to copy-paste templates and such into the documentation, each > >>>> time > >>>>>>>> they are changed in the source code.) Though it's not strictly a > >>>> blocker > >>>>>>>> for any kind kind of release. > >>>>>>>> > >>>>>>>> On Wed, Aug 12, 2020 at 8:53 PM Siegfried Goeschl < > >>>>>>>> [email protected] <mailto:[email protected]>> > >>>>>>> wrote: > >>>>>>>> > >>>>>>>>> Hi Daniel, > >>>>>>>>> > >>>>>>>>> Anything other things in the way for preparing a SNAPSHOT > release? > >>>>>>>>> > >>>>>>>>> Thanks in advance, > >>>>>>>>> > >>>>>>>>> Siegfried Goeschl > >>>>>>>>> > >>>>>>>>> > >>>>>>>>>> On 11.08.2020, at 22:57, Siegfried Goeschl < > >>>>>>> [email protected]> > >>>>>>>>> wrote: > >>>>>>>>>> > >>>>>>>>>> Hi Daniel, > >>>>>>>>>> > >>>>>>>>>> Just pushed the changes > >>>>>>>>>> > >>>>>>>>>> freemarker-generator -t freemarker-generator/info.ftl > >>>>>>>>>> > >>>>>>>>>> Thanks in advance, > >>>>>>>>>> > >>>>>>>>>> Siegfried Goeschl > >>>>>>>>>> > >>>>>>>>>> > >>>>>>>>>>> On 11.08.2020, at 22:44, Daniel Dekany < > [email protected] > >>>>>>>>> <mailto:[email protected] <mailto:[email protected] > >>> > >>>>>>> wrote: > >>>>>>>>>>> > >>>>>>>>>>> OK, no classpath loading for now. Can be done later if it will > >>>> be a > >>>>>>>>> problem > >>>>>>>>>>> with Maven plugin or other non-CLI thing. After all, it's > pretty > >>>>>>>>>>> transparent where the templates are coming from. > >>>>>>>>>>> > >>>>>>>>>>> So, what about the reserved directory that holds all these > built > >>>> in > >>>>>>>>>>> templates? See earlier in this thread. That also eliminates the > >>>> issue > >>>>>>>>> with > >>>>>>>>>>> colliding with user templates (which you listed above). That's > >>>> why I > >>>>>>>>>>> brought it up actually, and for understability for the users. > (I > >>>>>>> don't > >>>>>>>>> get > >>>>>>>>>>> why you relate name clashes with loading from jar VS from plain > >>>>>>>>> directory. > >>>>>>>>>>> The name clash problem happens in both cases, and modifying the > >>>>>>>>>>> installation is not an acceptable solution anyway.) > >>>>>>>>>>> > >>>>>>>>>>> Users can supply their own templates in their home directory, > or > >>>>>>> maybe > >>>>>>>>> in > >>>>>>>>>>> the future in /etc/freemarker-generator, and again, not by > >>>> replacing > >>>>>>>>>>> installed templates. (Even then, shadowing a standard template > is > >>>>>>>>> something > >>>>>>>>>>> I would prevent. Preventing unwise users from hurting > themselves > >>>> is a > >>>>>>>>>>> pretty important design goal.) > >>>>>>>>>>> > >>>>>>>>>>> > >>>>>>>>>>> On Tue, Aug 11, 2020 at 9:49 PM Siegfried Goeschl < > >>>>>>>>>>> [email protected] <mailto: > [email protected]> > >>>>>>> <mailto:[email protected] <mailto: > >>>> [email protected] > >>>>>>>>>> > >>>>>>>>> wrote: > >>>>>>>>>>> > >>>>>>>>>>>> Hi Daniel, > >>>>>>>>>>>> > >>>>>>>>>>>> yesterday's email was a bit short since I was drained from the > >>>> heat > >>>>>>> :-( > >>>>>>>>>>>> > >>>>>>>>>>>> * I would like to provide a bunch of useful / generic > templates > >>>>>>>>> together > >>>>>>>>>>>> with the FreeMarker Generator CLI - if those templates solve > or > >>>>>>> mostly > >>>>>>>>>>>> solve one's problem we successfully increased the community > >>>>>>>>>>>> * The useful / generic templates will be relying on code from > >>>>>>>>>>>> freemarker-generator-tools so they are currently not generic > >>>> since > >>>>>>> the > >>>>>>>>>>>> Maven plugin will not use freemarker-generator-tools due to > the > >>>>>>>>> transitive > >>>>>>>>>>>> dependencies > >>>>>>>>>>>> * Bundling useful templates can be done as file or from a JAR > - > >>>>>>>>> personally > >>>>>>>>>>>> I prefer files to make things more visible by having files but > >>>> class > >>>>>>>>> path > >>>>>>>>>>>> resources are also possible > >>>>>>>>>>>> * Strictly personal opinion - problem with bundled templates > is > >>>> that > >>>>>>>>> they > >>>>>>>>>>>> might collide with user-supplied templates (rather theoretical > >>>> issue > >>>>>>>>> but > >>>>>>>>>>>> log4j.properties picked up from the class path drove me crazy > >>>> in the > >>>>>>>>> past) > >>>>>>>>>>>> * Consequently if a user really wants to remove / modify > >>>> provided > >>>>>>>>>>>> templates or add some new templates that's fine for me - it > is a > >>>>>>> free > >>>>>>>>>>>> country and they obviously know what they are doing > >>>>>>>>>>>> * On my last cloud project it would have been actually > feasible > >>>> to > >>>>>>>>>>>> assemble a custom "freemarker-generator-cli" with more / other > >>>>>>>>> templates, > >>>>>>>>>>>> e.g. dumping Java keystores (which was done by some ugly shell > >>>>>>> script) > >>>>>>>>>>>> > >>>>>>>>>>>> So at the end of the day I think we are discussing a very > minor > >>>>>>> point > >>>>>>>>>>>> where we have different opinions and I don't see any real > >>>> benefit > >>>>>>> from > >>>>>>>>>>>> using class path loading > >>>>>>>>>>>> > >>>>>>>>>>>> Thanks in advance, > >>>>>>>>>>>> > >>>>>>>>>>>> Siegfried Goeschl > >>>>>>>>>>>> > >>>>>>>>>>>> > >>>>>>>>>>>>> On 11.08.2020, at 09:30, Daniel Dekany < > >>>> [email protected] > >>>>>>> <mailto:[email protected]> > >>>>>>>>> <mailto:[email protected] <mailto:[email protected] > >>> > >>>>>>> wrote: > >>>>>>>>>>>>> > >>>>>>>>>>>>> On Mon, Aug 10, 2020 at 8:53 PM Siegfried Goeschl < > >>>>>>>>>>>>> [email protected] <mailto: > >>>> [email protected]> > >>>>>>> <mailto:[email protected] <mailto: > >>>> [email protected] > >>>>>>>>>> > >>>>>>>>> wrote: > >>>>>>>>>>>>> > >>>>>>>>>>>>>>> The fundamental problem with that is this. Currently, if > you > >>>>>>> pull in > >>>>>>>>>>>>>>> freemarker-generator-cli as Maven dependency, the templates > >>>> will > >>>>>>>>> not be > >>>>>>>>>>>>>>> available. Surely, because it's the CLI, you could say that > >>>> it's > >>>>>>> not > >>>>>>>>>>>>>>> supposed to be used without the FreeMarker Generator Home > >>>>>>> Directory > >>>>>>>>>>>>>> created > >>>>>>>>>>>>>>> somewhere, which contains the launch script and templates/ > >>>> and > >>>>>>> all. > >>>>>>>>>>>> But, > >>>>>>>>>>>>>> if > >>>>>>>>>>>>>>> these templates are guaranteed functionality in FreeMarker > >>>>>>>>> Generator, > >>>>>>>>>>>>>> then > >>>>>>>>>>>>>>> they don't strictly belong to the CLI. When we will have a > >>>> proper > >>>>>>>>> Maven > >>>>>>>>>>>>>>> plugin for example, they should be still accessible. In > that > >>>>>>> case > >>>>>>>>> you > >>>>>>>>>>>>>> only > >>>>>>>>>>>>>>> have your Maven dependencies, so the templates must come > from > >>>>>>> there. > >>>>>>>>>>>>>>> > >>>>>>>>>>>>>>> Regarding visibility, it's a bit like with Java. Java > >>>> classes are > >>>>>>>>> not > >>>>>>>>>>>> too > >>>>>>>>>>>>>>> readable without looking at the source code either. That's > >>>> not an > >>>>>>>>>>>>>> advantage > >>>>>>>>>>>>>>> when it comes to "visibility", sure. But luckily this is > open > >>>>>>>>> source, > >>>>>>>>>>>> and > >>>>>>>>>>>>>>> it's very easy to get to the source code, if someone really > >>>> cares > >>>>>>>>> (like > >>>>>>>>>>>>>>> from the Maven source artifact). That applies to core stuff > >>>>>>>>> implemented > >>>>>>>>>>>>>> in > >>>>>>>>>>>>>>> FTL as well. So, the previously mentioned advantage (that > >>>> they > >>>>>>> are > >>>>>>>>>>>>>>> available from a plain dependency) certainly overweights > this > >>>>>>>>>>>>>> disadvantage > >>>>>>>>>>>>>>> (less visibility). > >>>>>>>>>>>>>> > >>>>>>>>>>>>>> I currently disagree here - I like the visibility aspect and > >>>> it is > >>>>>>>>>>>> pretty > >>>>>>>>>>>>>> difficult to get rid of templates loaded from the classpath. > >>>>>>>>>>>>>> > >>>>>>>>>>>>> > >>>>>>>>>>>>> What do you mean by getting rid of them? I hope you agree > that > >>>>>>> users > >>>>>>>>>>>>> shouldn't remove or modify these templates directly in the > >>>>>>> FreeMarker > >>>>>>>>>>>>> Generator installation. > >>>>>>>>>>>>> > >>>>>>>>>>>>> What do you intend to do about the dependency problem, > >>>> described > >>>>>>>>> above? > >>>>>>>>>>>> > >>>>>>>>>>>> > >>>>>>>>>>> > >>>>>>>>>>> -- > >>>>>>>>>>> Best regards, > >>>>>>>>>>> Daniel Dekany > >>>>>>>>>> > >>>>>>>>> > >>>>>>>>> > >>>>>>>> > >>>>>>>> -- > >>>>>>>> Best regards, > >>>>>>>> Daniel Dekany > >>>>>>> > >>>>>>> > >>>>>> > >>>>>> -- > >>>>>> Best regards, > >>>>>> Daniel Dekany > >>>>>> > >>>>> > >>>>> > >>>>> -- > >>>>> Best regards, > >>>>> Daniel Dekany > >>>> > >>>> > >>> > >>> -- > >>> Best regards, > >>> Daniel Dekany > >>> > >> > >> > >> -- > >> Best regards, > >> Daniel Dekany > >> > > > > > > -- > > Best regards, > > Daniel Dekany > > -- Best regards, Daniel Dekany
