You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@freemarker.apache.org by Siegfried Goeschl <si...@gmail.com> on 2020/08/04 18:51:43 UTC
Re: FreeMarker generator release preparations
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 <da...@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.goeschl@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 <da...@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
Re: FreeMarker generator release preparations
Posted by Siegfried Goeschl <si...@gmail.com>.
Also got some interesting test errors
https://travis-ci.org/github/apache/freemarker-generator <https://travis-ci.org/github/apache/freemarker-generator>
Currently looking into it
Siegfried
> On 10.08.2020, at 20:53, Siegfried Goeschl <si...@gmail.com> wrote:
>
> Hi Daniel,
>
> Please see my comments below
>
> Thanks in advance,
>
> Siegfried Goeschl
>
>> On 09.08.2020, at 22:00, Daniel Dekany <daniel.dekany@gmail.com <ma...@gmail.com>> wrote:
>>
>> See my answers inline...
>>
>> On Sun, Aug 9, 2020 at 7:16 PM Siegfried Goeschl <
>> siegfried.goeschl@gmail.com <ma...@gmail.com>> wrote:
>>
>>> 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- <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
>>>
>>
>> What do you mean, realistically what can we do, in case that plugin is
>> indeed that broken? I mean, for FreeMarker Generator alone it doesn't
>> really matter for users. For all the other projects, FreeMarker doesn't
>> prevent them from doing dirty things to accomodate to the plugin (as you
>> saw yourself ;) ), and I'm not sure what else could FreeMarker itself do
>> about this. Fixing/extending the plugin itself is also not likely, as it's
>> closed source. (Of course, it would be great to have an open source LSP
>> language server, and then adding open source plugins based on that... but
>> things go very, very slowly around here.)
>
> Played around with the IntelliJ plugin but I don't get it perfectly working ...
>>
>> 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 <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)
>>>
>>
>> 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 don't think we want users to add their own templates to /templates, as
>> they will be potentially lost when someone updates FreeMarker Generator,
>> and is confusing for colleagues, etc. If we can prevent bad practices,
>> let's do it. Especially as we also provide a cleaner
>> solution, ~/.freemarker-generator/ added to the template root (which will
>> change to ~/.freemarker-generator/templates now, as you say below). If
>> people need a system-wide one, we can also add /etc/freemarker-generator,
>> or something like that.
>>
>
> I currently disagree here - I like the visibility aspect and it is pretty difficult to get rid of templates loaded from the classpath.
>
>> 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"
>>>
>>
>> Except, we should avoid adding info.ftl and such to the template directory
>> root. Not only because of potential name clashes, but because it can be
>> confusing if someone looks at that (where's info.ftl coming from). How
>> about reserving the "freemarker-generator" directory on the top level, and
>> then it's "freemarker-generator -t freemarker-generator/info.ftl".
>> (Hopefully that helps realizing that it's something built into FreeMarker
>> Generator.) Actually, maybe it should be even
>> "freemarker-generator:/info.ftl ".
>
> Mhmm, already pushed the changes :-(
>
> Need to think about it
>
>>
>> Thanks!
>> Daniel Dekany
>>
>>
>>> What do you think?
>>>
>>> Siegfried Goeschl
>>>
>>>
>>>> On 05.08.2020, at 13:28, Daniel Dekany <daniel.dekany@gmail.com <ma...@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.goeschl@gmail.com <ma...@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 <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.dekany@gmail.com <ma...@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.goeschl@gmail.com <ma...@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.dekany@gmail.com <ma...@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.goeschl@gmail.com <ma...@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.dekany@gmail.com <ma...@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 <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 <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
>>>
>>>
>>
>> --
>> Best regards,
>> Daniel Dekany
Re: FreeMarker generator release preparations
Posted by Siegfried Goeschl <si...@gmail.com>.
Mhmm, master is broken after merging - will check tomorrow
Thanks in advance,
Siegfried Goeschl
> On 23.08.2020, at 20:42, Siegfried Goeschl <si...@gmail.com> 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 <da...@gmail.com> 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 <da...@gmail.com>
>> 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 <da...@gmail.com>
>>> 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 <
>>>> siegfried.goeschl@gmail.com> 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 <da...@gmail.com>
>>>>> 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 <
>>>>> daniel.dekany@gmail.com>
>>>>>> 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 <
>>>>>>> siegfried.goeschl@gmail.com> 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 <da...@gmail.com>
>>>>> 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 <
>>>>>>>>> siegfried.goeschl@gmail.com <ma...@gmail.com>>
>>>>>>>> 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 <
>>>>>>>> siegfried.goeschl@gmail.com>
>>>>>>>>>> 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 <daniel.dekany@gmail.com
>>>>>>>>>> <mailto:daniel.dekany@gmail.com <ma...@gmail.com>>>
>>>>>>>> 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 <
>>>>>>>>>>>> siegfried.goeschl@gmail.com <ma...@gmail.com>
>>>>>>>> <mailto:siegfried.goeschl@gmail.com <mailto:
>>>>> siegfried.goeschl@gmail.com
>>>>>>>>>>>
>>>>>>>>>> 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 <
>>>>> daniel.dekany@gmail.com
>>>>>>>> <ma...@gmail.com>
>>>>>>>>>> <mailto:daniel.dekany@gmail.com <ma...@gmail.com>>>
>>>>>>>> wrote:
>>>>>>>>>>>>>>
>>>>>>>>>>>>>> On Mon, Aug 10, 2020 at 8:53 PM Siegfried Goeschl <
>>>>>>>>>>>>>> siegfried.goeschl@gmail.com <mailto:
>>>>> siegfried.goeschl@gmail.com>
>>>>>>>> <mailto:siegfried.goeschl@gmail.com <mailto:
>>>>> siegfried.goeschl@gmail.com
>>>>>>>>>>>
>>>>>>>>>> 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
>
Re: FreeMarker generator release preparations
Posted by Daniel Dekany <da...@gmail.com>.
As far as I see, it's a case where you can know very well that there's a
problem, but don't tell the user. Suppressing an error.
On Mon, Aug 24, 2020 at 8:12 PM Siegfried Goeschl <
siegfried.goeschl@gmail.com> wrote:
> Hi Daniel,
>
> Please see my comments below
>
> Thanks in advance,
>
> Siegfried Goeschl
>
>
>
> > On 24.08.2020, at 13:12, Daniel Dekany <da...@gmail.com> wrote:
> >
> > 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.
>
> I will have a look ...
>
> >
> > 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.
>
> Yes, we had discussion about it ;-)
>
> * IMHO it is a bit of gold-plating so I did not change anything
> * I tried to to implement "dataSources[0]" instead of using
> "dataSources?values[0]" but I had to revert the changes to due mirroring
> problems (but it is still on my todo list)
>
> Thanks in advance,
>
> Siegfried Goeschl
>
>
>
>
>
>
> >
> > On Sun, Aug 23, 2020 at 8:42 PM Siegfried Goeschl <
> > siegfried.goeschl@gmail.com> 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 <da...@gmail.com>
> 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 <daniel.dekany@gmail.com
> >
> >>> 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 <
> daniel.dekany@gmail.com>
> >>>> 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 <
> >>>>> siegfried.goeschl@gmail.com> 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 <da...@gmail.com>
> >>>>>> 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 <
> >>>>>> daniel.dekany@gmail.com>
> >>>>>>> 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 <
> >>>>>>>> siegfried.goeschl@gmail.com> 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 <daniel.dekany@gmail.com
> >
> >>>>>> 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 <
> >>>>>>>>>> siegfried.goeschl@gmail.com <mailto:siegfried.goeschl@gmail.com
> >>
> >>>>>>>>> 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 <
> >>>>>>>>> siegfried.goeschl@gmail.com>
> >>>>>>>>>>> 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 <
> >> daniel.dekany@gmail.com
> >>>>>>>>>>> <mailto:daniel.dekany@gmail.com <mailto:
> daniel.dekany@gmail.com
> >>>>>
> >>>>>>>>> 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 <
> >>>>>>>>>>>>> siegfried.goeschl@gmail.com <mailto:
> >> siegfried.goeschl@gmail.com>
> >>>>>>>>> <mailto:siegfried.goeschl@gmail.com <mailto:
> >>>>>> siegfried.goeschl@gmail.com
> >>>>>>>>>>>>
> >>>>>>>>>>> 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 <
> >>>>>> daniel.dekany@gmail.com
> >>>>>>>>> <ma...@gmail.com>
> >>>>>>>>>>> <mailto:daniel.dekany@gmail.com <mailto:
> daniel.dekany@gmail.com
> >>>>>
> >>>>>>>>> wrote:
> >>>>>>>>>>>>>>>
> >>>>>>>>>>>>>>> On Mon, Aug 10, 2020 at 8:53 PM Siegfried Goeschl <
> >>>>>>>>>>>>>>> siegfried.goeschl@gmail.com <mailto:
> >>>>>> siegfried.goeschl@gmail.com>
> >>>>>>>>> <mailto:siegfried.goeschl@gmail.com <mailto:
> >>>>>> siegfried.goeschl@gmail.com
> >>>>>>>>>>>>
> >>>>>>>>>>> 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
>
>
--
Best regards,
Daniel Dekany
Re: FreeMarker generator release preparations
Posted by Siegfried Goeschl <si...@gmail.com>.
Hi Daniel,
Please see my comments below
Thanks in advance,
Siegfried Goeschl
> On 24.08.2020, at 13:12, Daniel Dekany <da...@gmail.com> wrote:
>
> 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.
I will have a look ...
>
> 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.
Yes, we had discussion about it ;-)
* IMHO it is a bit of gold-plating so I did not change anything
* I tried to to implement "dataSources[0]" instead of using "dataSources?values[0]" but I had to revert the changes to due mirroring problems (but it is still on my todo list)
Thanks in advance,
Siegfried Goeschl
>
> On Sun, Aug 23, 2020 at 8:42 PM Siegfried Goeschl <
> siegfried.goeschl@gmail.com> 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 <da...@gmail.com> 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 <da...@gmail.com>
>>> 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 <da...@gmail.com>
>>>> 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 <
>>>>> siegfried.goeschl@gmail.com> 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 <da...@gmail.com>
>>>>>> 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 <
>>>>>> daniel.dekany@gmail.com>
>>>>>>> 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 <
>>>>>>>> siegfried.goeschl@gmail.com> 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 <da...@gmail.com>
>>>>>> 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 <
>>>>>>>>>> siegfried.goeschl@gmail.com <ma...@gmail.com>>
>>>>>>>>> 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 <
>>>>>>>>> siegfried.goeschl@gmail.com>
>>>>>>>>>>> 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 <
>> daniel.dekany@gmail.com
>>>>>>>>>>> <mailto:daniel.dekany@gmail.com <mailto:daniel.dekany@gmail.com
>>>>>
>>>>>>>>> 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 <
>>>>>>>>>>>>> siegfried.goeschl@gmail.com <mailto:
>> siegfried.goeschl@gmail.com>
>>>>>>>>> <mailto:siegfried.goeschl@gmail.com <mailto:
>>>>>> siegfried.goeschl@gmail.com
>>>>>>>>>>>>
>>>>>>>>>>> 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 <
>>>>>> daniel.dekany@gmail.com
>>>>>>>>> <ma...@gmail.com>
>>>>>>>>>>> <mailto:daniel.dekany@gmail.com <mailto:daniel.dekany@gmail.com
>>>>>
>>>>>>>>> wrote:
>>>>>>>>>>>>>>>
>>>>>>>>>>>>>>> On Mon, Aug 10, 2020 at 8:53 PM Siegfried Goeschl <
>>>>>>>>>>>>>>> siegfried.goeschl@gmail.com <mailto:
>>>>>> siegfried.goeschl@gmail.com>
>>>>>>>>> <mailto:siegfried.goeschl@gmail.com <mailto:
>>>>>> siegfried.goeschl@gmail.com
>>>>>>>>>>>>
>>>>>>>>>>> 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
Re: FreeMarker generator release preparations
Posted by Daniel Dekany <da...@gmail.com>.
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 <
siegfried.goeschl@gmail.com> 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 <da...@gmail.com> 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 <da...@gmail.com>
> > 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 <da...@gmail.com>
> >> 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 <
> >>> siegfried.goeschl@gmail.com> 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 <da...@gmail.com>
> >>>> 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 <
> >>>> daniel.dekany@gmail.com>
> >>>>> 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 <
> >>>>>> siegfried.goeschl@gmail.com> 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 <da...@gmail.com>
> >>>> 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 <
> >>>>>>>> siegfried.goeschl@gmail.com <ma...@gmail.com>>
> >>>>>>> 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 <
> >>>>>>> siegfried.goeschl@gmail.com>
> >>>>>>>>> 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 <
> daniel.dekany@gmail.com
> >>>>>>>>> <mailto:daniel.dekany@gmail.com <mailto:daniel.dekany@gmail.com
> >>>
> >>>>>>> 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 <
> >>>>>>>>>>> siegfried.goeschl@gmail.com <mailto:
> siegfried.goeschl@gmail.com>
> >>>>>>> <mailto:siegfried.goeschl@gmail.com <mailto:
> >>>> siegfried.goeschl@gmail.com
> >>>>>>>>>>
> >>>>>>>>> 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 <
> >>>> daniel.dekany@gmail.com
> >>>>>>> <ma...@gmail.com>
> >>>>>>>>> <mailto:daniel.dekany@gmail.com <mailto:daniel.dekany@gmail.com
> >>>
> >>>>>>> wrote:
> >>>>>>>>>>>>>
> >>>>>>>>>>>>> On Mon, Aug 10, 2020 at 8:53 PM Siegfried Goeschl <
> >>>>>>>>>>>>> siegfried.goeschl@gmail.com <mailto:
> >>>> siegfried.goeschl@gmail.com>
> >>>>>>> <mailto:siegfried.goeschl@gmail.com <mailto:
> >>>> siegfried.goeschl@gmail.com
> >>>>>>>>>>
> >>>>>>>>> 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
Re: FreeMarker generator release preparations
Posted by Siegfried Goeschl <si...@gmail.com>.
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 <da...@gmail.com> 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 <da...@gmail.com>
> 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 <da...@gmail.com>
>> 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 <
>>> siegfried.goeschl@gmail.com> 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 <da...@gmail.com>
>>>> 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 <
>>>> daniel.dekany@gmail.com>
>>>>> 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 <
>>>>>> siegfried.goeschl@gmail.com> 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 <da...@gmail.com>
>>>> 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 <
>>>>>>>> siegfried.goeschl@gmail.com <ma...@gmail.com>>
>>>>>>> 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 <
>>>>>>> siegfried.goeschl@gmail.com>
>>>>>>>>> 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 <daniel.dekany@gmail.com
>>>>>>>>> <mailto:daniel.dekany@gmail.com <ma...@gmail.com>>>
>>>>>>> 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 <
>>>>>>>>>>> siegfried.goeschl@gmail.com <ma...@gmail.com>
>>>>>>> <mailto:siegfried.goeschl@gmail.com <mailto:
>>>> siegfried.goeschl@gmail.com
>>>>>>>>>>
>>>>>>>>> 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 <
>>>> daniel.dekany@gmail.com
>>>>>>> <ma...@gmail.com>
>>>>>>>>> <mailto:daniel.dekany@gmail.com <ma...@gmail.com>>>
>>>>>>> wrote:
>>>>>>>>>>>>>
>>>>>>>>>>>>> On Mon, Aug 10, 2020 at 8:53 PM Siegfried Goeschl <
>>>>>>>>>>>>> siegfried.goeschl@gmail.com <mailto:
>>>> siegfried.goeschl@gmail.com>
>>>>>>> <mailto:siegfried.goeschl@gmail.com <mailto:
>>>> siegfried.goeschl@gmail.com
>>>>>>>>>>
>>>>>>>>> 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
Re: FreeMarker generator release preparations
Posted by Daniel Dekany <da...@gmail.com>.
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 <da...@gmail.com>
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 <da...@gmail.com>
> 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 <
>> siegfried.goeschl@gmail.com> 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 <da...@gmail.com>
>>> 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 <
>>> daniel.dekany@gmail.com>
>>> > 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 <
>>> >> siegfried.goeschl@gmail.com> 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 <da...@gmail.com>
>>> 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 <
>>> >>>> siegfried.goeschl@gmail.com <ma...@gmail.com>>
>>> >>> 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 <
>>> >>> siegfried.goeschl@gmail.com>
>>> >>>>> 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 <daniel.dekany@gmail.com
>>> >>>>> <mailto:daniel.dekany@gmail.com <ma...@gmail.com>>>
>>> >>> 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 <
>>> >>>>>>> siegfried.goeschl@gmail.com <ma...@gmail.com>
>>> >>> <mailto:siegfried.goeschl@gmail.com <mailto:
>>> siegfried.goeschl@gmail.com
>>> >>>>>>
>>> >>>>> 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 <
>>> daniel.dekany@gmail.com
>>> >>> <ma...@gmail.com>
>>> >>>>> <mailto:daniel.dekany@gmail.com <ma...@gmail.com>>>
>>> >>> wrote:
>>> >>>>>>>>>
>>> >>>>>>>>> On Mon, Aug 10, 2020 at 8:53 PM Siegfried Goeschl <
>>> >>>>>>>>> siegfried.goeschl@gmail.com <mailto:
>>> siegfried.goeschl@gmail.com>
>>> >>> <mailto:siegfried.goeschl@gmail.com <mailto:
>>> siegfried.goeschl@gmail.com
>>> >>>>>>
>>> >>>>> 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
Re: FreeMarker generator release preparations
Posted by Daniel Dekany <da...@gmail.com>.
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 <da...@gmail.com>
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 <
> siegfried.goeschl@gmail.com> 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 <da...@gmail.com> 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 <daniel.dekany@gmail.com
>> >
>> > 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 <
>> >> siegfried.goeschl@gmail.com> 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 <da...@gmail.com>
>> 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 <
>> >>>> siegfried.goeschl@gmail.com <ma...@gmail.com>>
>> >>> 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 <
>> >>> siegfried.goeschl@gmail.com>
>> >>>>> 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 <daniel.dekany@gmail.com
>> >>>>> <mailto:daniel.dekany@gmail.com <ma...@gmail.com>>>
>> >>> 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 <
>> >>>>>>> siegfried.goeschl@gmail.com <ma...@gmail.com>
>> >>> <mailto:siegfried.goeschl@gmail.com <mailto:
>> siegfried.goeschl@gmail.com
>> >>>>>>
>> >>>>> 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 <daniel.dekany@gmail.com
>> >>> <ma...@gmail.com>
>> >>>>> <mailto:daniel.dekany@gmail.com <ma...@gmail.com>>>
>> >>> wrote:
>> >>>>>>>>>
>> >>>>>>>>> On Mon, Aug 10, 2020 at 8:53 PM Siegfried Goeschl <
>> >>>>>>>>> siegfried.goeschl@gmail.com <mailto:siegfried.goeschl@gmail.com
>> >
>> >>> <mailto:siegfried.goeschl@gmail.com <mailto:
>> siegfried.goeschl@gmail.com
>> >>>>>>
>> >>>>> 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
Re: FreeMarker generator release preparations
Posted by Daniel Dekany <da...@gmail.com>.
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 <
siegfried.goeschl@gmail.com> 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 <da...@gmail.com> 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 <da...@gmail.com>
> > 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 <
> >> siegfried.goeschl@gmail.com> 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 <da...@gmail.com>
> 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 <
> >>>> siegfried.goeschl@gmail.com <ma...@gmail.com>>
> >>> 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 <
> >>> siegfried.goeschl@gmail.com>
> >>>>> 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 <daniel.dekany@gmail.com
> >>>>> <mailto:daniel.dekany@gmail.com <ma...@gmail.com>>>
> >>> 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 <
> >>>>>>> siegfried.goeschl@gmail.com <ma...@gmail.com>
> >>> <mailto:siegfried.goeschl@gmail.com <mailto:
> siegfried.goeschl@gmail.com
> >>>>>>
> >>>>> 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 <daniel.dekany@gmail.com
> >>> <ma...@gmail.com>
> >>>>> <mailto:daniel.dekany@gmail.com <ma...@gmail.com>>>
> >>> wrote:
> >>>>>>>>>
> >>>>>>>>> On Mon, Aug 10, 2020 at 8:53 PM Siegfried Goeschl <
> >>>>>>>>> siegfried.goeschl@gmail.com <ma...@gmail.com>
> >>> <mailto:siegfried.goeschl@gmail.com <mailto:
> siegfried.goeschl@gmail.com
> >>>>>>
> >>>>> 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
Re: FreeMarker generator release preparations
Posted by Daniel Dekany <da...@gmail.com>.
Yeah, you are right.
On Thu, Aug 27, 2020 at 9:38 PM Siegfried Goeschl <
siegfried.goeschl@gmail.com> wrote:
> Hi Daniel,
>
> IMHO I'm using the right place ...
>
> The src directory contains all of the source material for building the
> project, its site and so on. It contains a subdirectory for each type: main
> for the main build artifact, test for the unit test code and resources,
> site and so on.
>
> The main artefact as far as Maven is concerned is a JAR file so things
> contained in the JAR goes under "src/main".
>
> We have an additional artefacts built by the maven-appassembler-pugin and
> the things needed are found in "src/app" - it follows the same pattern as
>
> > mvn jar:test-jar
> > mvn site:jar
>
> Thanks in advance,
>
> Siegfried Goeschl
>
>
> > On 27.08.2020, at 01:15, Daniel Dekany <da...@gmail.com> wrote:
> >
> > But currently we have src/app as I noticed now, not src/main/app. ("app"
> is
> > a classifier of a "main" artifact, so it belongs under there.)
> >
> > On Sat, Aug 22, 2020 at 10:10 AM Siegfried Goeschl <
> > siegfried.goeschl@gmail.com> wrote:
> >
> >> I think the "main/app" looks better :)
> >>
> >>> On 22.08.2020, at 10:01, Siegfried Goeschl <
> siegfried.goeschl@gmail.com>
> >> 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 <da...@gmail.com>
> 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 <
> daniel.dekany@gmail.com
> >>>
> >>>> 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 <
> >>>>> siegfried.goeschl@gmail.com> 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 <da...@gmail.com>
> >> 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 <
> >>>>>>> siegfried.goeschl@gmail.com <ma...@gmail.com>>
> >>>>>> 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 <
> >>>>>> siegfried.goeschl@gmail.com>
> >>>>>>>> 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 <daniel.dekany@gmail.com
> >>>>>>>> <mailto:daniel.dekany@gmail.com <mailto:daniel.dekany@gmail.com
> >>>
> >>>>>> 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 <
> >>>>>>>>>> siegfried.goeschl@gmail.com <mailto:siegfried.goeschl@gmail.com
> >
> >>>>>> <mailto:siegfried.goeschl@gmail.com <mailto:
> >> siegfried.goeschl@gmail.com
> >>>>>>>>>
> >>>>>>>> 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 <
> daniel.dekany@gmail.com
> >>>>>> <ma...@gmail.com>
> >>>>>>>> <mailto:daniel.dekany@gmail.com <mailto:daniel.dekany@gmail.com
> >>>
> >>>>>> wrote:
> >>>>>>>>>>>>
> >>>>>>>>>>>> On Mon, Aug 10, 2020 at 8:53 PM Siegfried Goeschl <
> >>>>>>>>>>>> siegfried.goeschl@gmail.com <mailto:
> siegfried.goeschl@gmail.com
> >>>
> >>>>>> <mailto:siegfried.goeschl@gmail.com <mailto:
> >> siegfried.goeschl@gmail.com
> >>>>>>>>>
> >>>>>>>> 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
Re: FreeMarker generator release preparations
Posted by Siegfried Goeschl <si...@gmail.com>.
Hi Daniel,
IMHO I'm using the right place ...
The src directory contains all of the source material for building the project, its site and so on. It contains a subdirectory for each type: main for the main build artifact, test for the unit test code and resources, site and so on.
The main artefact as far as Maven is concerned is a JAR file so things contained in the JAR goes under "src/main".
We have an additional artefacts built by the maven-appassembler-pugin and the things needed are found in "src/app" - it follows the same pattern as
> mvn jar:test-jar
> mvn site:jar
Thanks in advance,
Siegfried Goeschl
> On 27.08.2020, at 01:15, Daniel Dekany <da...@gmail.com> wrote:
>
> But currently we have src/app as I noticed now, not src/main/app. ("app" is
> a classifier of a "main" artifact, so it belongs under there.)
>
> On Sat, Aug 22, 2020 at 10:10 AM Siegfried Goeschl <
> siegfried.goeschl@gmail.com> wrote:
>
>> I think the "main/app" looks better :)
>>
>>> On 22.08.2020, at 10:01, Siegfried Goeschl <si...@gmail.com>
>> 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 <da...@gmail.com> 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 <daniel.dekany@gmail.com
>>>
>>>> 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 <
>>>>> siegfried.goeschl@gmail.com> 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 <da...@gmail.com>
>> 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 <
>>>>>>> siegfried.goeschl@gmail.com <ma...@gmail.com>>
>>>>>> 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 <
>>>>>> siegfried.goeschl@gmail.com>
>>>>>>>> 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 <daniel.dekany@gmail.com
>>>>>>>> <mailto:daniel.dekany@gmail.com <ma...@gmail.com>>>
>>>>>> 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 <
>>>>>>>>>> siegfried.goeschl@gmail.com <ma...@gmail.com>
>>>>>> <mailto:siegfried.goeschl@gmail.com <mailto:
>> siegfried.goeschl@gmail.com
>>>>>>>>>
>>>>>>>> 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 <daniel.dekany@gmail.com
>>>>>> <ma...@gmail.com>
>>>>>>>> <mailto:daniel.dekany@gmail.com <ma...@gmail.com>>>
>>>>>> wrote:
>>>>>>>>>>>>
>>>>>>>>>>>> On Mon, Aug 10, 2020 at 8:53 PM Siegfried Goeschl <
>>>>>>>>>>>> siegfried.goeschl@gmail.com <mailto:siegfried.goeschl@gmail.com
>>>
>>>>>> <mailto:siegfried.goeschl@gmail.com <mailto:
>> siegfried.goeschl@gmail.com
>>>>>>>>>
>>>>>>>> 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
Re: FreeMarker generator release preparations
Posted by Daniel Dekany <da...@gmail.com>.
But currently we have src/app as I noticed now, not src/main/app. ("app" is
a classifier of a "main" artifact, so it belongs under there.)
On Sat, Aug 22, 2020 at 10:10 AM Siegfried Goeschl <
siegfried.goeschl@gmail.com> wrote:
> I think the "main/app" looks better :)
>
> > On 22.08.2020, at 10:01, Siegfried Goeschl <si...@gmail.com>
> 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 <da...@gmail.com> 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 <daniel.dekany@gmail.com
> >
> >> 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 <
> >>> siegfried.goeschl@gmail.com> 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 <da...@gmail.com>
> 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 <
> >>>>> siegfried.goeschl@gmail.com <ma...@gmail.com>>
> >>>> 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 <
> >>>> siegfried.goeschl@gmail.com>
> >>>>>> 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 <daniel.dekany@gmail.com
> >>>>>> <mailto:daniel.dekany@gmail.com <ma...@gmail.com>>>
> >>>> 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 <
> >>>>>>>> siegfried.goeschl@gmail.com <ma...@gmail.com>
> >>>> <mailto:siegfried.goeschl@gmail.com <mailto:
> siegfried.goeschl@gmail.com
> >>>>>>>
> >>>>>> 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 <daniel.dekany@gmail.com
> >>>> <ma...@gmail.com>
> >>>>>> <mailto:daniel.dekany@gmail.com <ma...@gmail.com>>>
> >>>> wrote:
> >>>>>>>>>>
> >>>>>>>>>> On Mon, Aug 10, 2020 at 8:53 PM Siegfried Goeschl <
> >>>>>>>>>> siegfried.goeschl@gmail.com <mailto:siegfried.goeschl@gmail.com
> >
> >>>> <mailto:siegfried.goeschl@gmail.com <mailto:
> siegfried.goeschl@gmail.com
> >>>>>>>
> >>>>>> 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
Re: FreeMarker generator release preparations
Posted by Siegfried Goeschl <si...@gmail.com>.
I think the "main/app" looks better :)
> On 22.08.2020, at 10:01, Siegfried Goeschl <si...@gmail.com> 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 <da...@gmail.com> 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 <da...@gmail.com>
>> 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 <
>>> siegfried.goeschl@gmail.com> 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 <da...@gmail.com> 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 <
>>>>> siegfried.goeschl@gmail.com <ma...@gmail.com>>
>>>> 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 <
>>>> siegfried.goeschl@gmail.com>
>>>>>> 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 <daniel.dekany@gmail.com
>>>>>> <mailto:daniel.dekany@gmail.com <ma...@gmail.com>>>
>>>> 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 <
>>>>>>>> siegfried.goeschl@gmail.com <ma...@gmail.com>
>>>> <mailto:siegfried.goeschl@gmail.com <mailto:siegfried.goeschl@gmail.com
>>>>>>>
>>>>>> 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 <daniel.dekany@gmail.com
>>>> <ma...@gmail.com>
>>>>>> <mailto:daniel.dekany@gmail.com <ma...@gmail.com>>>
>>>> wrote:
>>>>>>>>>>
>>>>>>>>>> On Mon, Aug 10, 2020 at 8:53 PM Siegfried Goeschl <
>>>>>>>>>> siegfried.goeschl@gmail.com <ma...@gmail.com>
>>>> <mailto:siegfried.goeschl@gmail.com <mailto:siegfried.goeschl@gmail.com
>>>>>>>
>>>>>> 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
>
Re: FreeMarker generator release preparations
Posted by Siegfried Goeschl <si...@gmail.com>.
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 <da...@gmail.com> 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 <da...@gmail.com>
> 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 <
>> siegfried.goeschl@gmail.com> 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 <da...@gmail.com> 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 <
>>>> siegfried.goeschl@gmail.com <ma...@gmail.com>>
>>> 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 <
>>> siegfried.goeschl@gmail.com>
>>>>> 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 <daniel.dekany@gmail.com
>>>>> <mailto:daniel.dekany@gmail.com <ma...@gmail.com>>>
>>> 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 <
>>>>>>> siegfried.goeschl@gmail.com <ma...@gmail.com>
>>> <mailto:siegfried.goeschl@gmail.com <mailto:siegfried.goeschl@gmail.com
>>>>>>
>>>>> 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 <daniel.dekany@gmail.com
>>> <ma...@gmail.com>
>>>>> <mailto:daniel.dekany@gmail.com <ma...@gmail.com>>>
>>> wrote:
>>>>>>>>>
>>>>>>>>> On Mon, Aug 10, 2020 at 8:53 PM Siegfried Goeschl <
>>>>>>>>> siegfried.goeschl@gmail.com <ma...@gmail.com>
>>> <mailto:siegfried.goeschl@gmail.com <mailto:siegfried.goeschl@gmail.com
>>>>>>
>>>>> 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
Re: FreeMarker generator release preparations
Posted by Daniel Dekany <da...@gmail.com>.
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 <da...@gmail.com>
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 <
> siegfried.goeschl@gmail.com> 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 <da...@gmail.com> 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 <
>> > siegfried.goeschl@gmail.com <ma...@gmail.com>>
>> 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 <
>> siegfried.goeschl@gmail.com>
>> >> 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 <daniel.dekany@gmail.com
>> >> <mailto:daniel.dekany@gmail.com <ma...@gmail.com>>>
>> 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 <
>> >>>> siegfried.goeschl@gmail.com <ma...@gmail.com>
>> <mailto:siegfried.goeschl@gmail.com <mailto:siegfried.goeschl@gmail.com
>> >>>
>> >> 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 <daniel.dekany@gmail.com
>> <ma...@gmail.com>
>> >> <mailto:daniel.dekany@gmail.com <ma...@gmail.com>>>
>> wrote:
>> >>>>>>
>> >>>>>> On Mon, Aug 10, 2020 at 8:53 PM Siegfried Goeschl <
>> >>>>>> siegfried.goeschl@gmail.com <ma...@gmail.com>
>> <mailto:siegfried.goeschl@gmail.com <mailto:siegfried.goeschl@gmail.com
>> >>>
>> >> 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
Re: FreeMarker generator release preparations
Posted by Daniel Dekany <da...@gmail.com>.
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 <
siegfried.goeschl@gmail.com> 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 <da...@gmail.com> 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 <
> > siegfried.goeschl@gmail.com <ma...@gmail.com>> 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 <
> siegfried.goeschl@gmail.com>
> >> 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 <daniel.dekany@gmail.com
> >> <mailto:daniel.dekany@gmail.com <ma...@gmail.com>>>
> 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 <
> >>>> siegfried.goeschl@gmail.com <ma...@gmail.com>
> <mailto:siegfried.goeschl@gmail.com <ma...@gmail.com>>>
> >> 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 <daniel.dekany@gmail.com
> <ma...@gmail.com>
> >> <mailto:daniel.dekany@gmail.com <ma...@gmail.com>>>
> wrote:
> >>>>>>
> >>>>>> On Mon, Aug 10, 2020 at 8:53 PM Siegfried Goeschl <
> >>>>>> siegfried.goeschl@gmail.com <ma...@gmail.com>
> <mailto:siegfried.goeschl@gmail.com <ma...@gmail.com>>>
> >> 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
Re: FreeMarker generator release preparations
Posted by Siegfried Goeschl <si...@gmail.com>.
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 <da...@gmail.com> 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 <
> siegfried.goeschl@gmail.com <ma...@gmail.com>> 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 <si...@gmail.com>
>> 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 <daniel.dekany@gmail.com
>> <mailto:daniel.dekany@gmail.com <ma...@gmail.com>>> 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 <
>>>> siegfried.goeschl@gmail.com <ma...@gmail.com> <mailto:siegfried.goeschl@gmail.com <ma...@gmail.com>>>
>> 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 <daniel.dekany@gmail.com <ma...@gmail.com>
>> <mailto:daniel.dekany@gmail.com <ma...@gmail.com>>> wrote:
>>>>>>
>>>>>> On Mon, Aug 10, 2020 at 8:53 PM Siegfried Goeschl <
>>>>>> siegfried.goeschl@gmail.com <ma...@gmail.com> <mailto:siegfried.goeschl@gmail.com <ma...@gmail.com>>>
>> 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
Re: FreeMarker generator release preparations
Posted by Daniel Dekany <da...@gmail.com>.
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 <
siegfried.goeschl@gmail.com> 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 <si...@gmail.com>
> 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 <daniel.dekany@gmail.com
> <ma...@gmail.com>> 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 <
> >> siegfried.goeschl@gmail.com <ma...@gmail.com>>
> 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 <daniel.dekany@gmail.com
> <ma...@gmail.com>> wrote:
> >>>>
> >>>> On Mon, Aug 10, 2020 at 8:53 PM Siegfried Goeschl <
> >>>> siegfried.goeschl@gmail.com <ma...@gmail.com>>
> 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
Re: FreeMarker generator release preparations
Posted by Siegfried Goeschl <si...@gmail.com>.
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 <si...@gmail.com> 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 <daniel.dekany@gmail.com <ma...@gmail.com>> 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 <
>> siegfried.goeschl@gmail.com <ma...@gmail.com>> 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 <daniel.dekany@gmail.com <ma...@gmail.com>> wrote:
>>>>
>>>> On Mon, Aug 10, 2020 at 8:53 PM Siegfried Goeschl <
>>>> siegfried.goeschl@gmail.com <ma...@gmail.com>> 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
>
Re: FreeMarker generator release preparations
Posted by Siegfried Goeschl <si...@gmail.com>.
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 <da...@gmail.com> 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 <
> siegfried.goeschl@gmail.com> 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 <da...@gmail.com> wrote:
>>>
>>> On Mon, Aug 10, 2020 at 8:53 PM Siegfried Goeschl <
>>> siegfried.goeschl@gmail.com> 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
Re: FreeMarker generator release preparations
Posted by Daniel Dekany <da...@gmail.com>.
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 <
siegfried.goeschl@gmail.com> 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 <da...@gmail.com> wrote:
> >
> > On Mon, Aug 10, 2020 at 8:53 PM Siegfried Goeschl <
> > siegfried.goeschl@gmail.com> 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
Re: FreeMarker generator release preparations
Posted by Siegfried Goeschl <si...@gmail.com>.
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 <da...@gmail.com> wrote:
>
> On Mon, Aug 10, 2020 at 8:53 PM Siegfried Goeschl <
> siegfried.goeschl@gmail.com> 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?
Re: FreeMarker generator release preparations
Posted by Daniel Dekany <da...@gmail.com>.
On Mon, Aug 10, 2020 at 8:53 PM Siegfried Goeschl <
siegfried.goeschl@gmail.com> 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?
Re: FreeMarker generator release preparations
Posted by Siegfried Goeschl <si...@gmail.com>.
Hi Daniel,
Please see my comments below
Thanks in advance,
Siegfried Goeschl
> On 09.08.2020, at 22:00, Daniel Dekany <da...@gmail.com> wrote:
>
> See my answers inline...
>
> On Sun, Aug 9, 2020 at 7:16 PM Siegfried Goeschl <
> siegfried.goeschl@gmail.com <ma...@gmail.com>> wrote:
>
>> 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
>>
>
> What do you mean, realistically what can we do, in case that plugin is
> indeed that broken? I mean, for FreeMarker Generator alone it doesn't
> really matter for users. For all the other projects, FreeMarker doesn't
> prevent them from doing dirty things to accomodate to the plugin (as you
> saw yourself ;) ), and I'm not sure what else could FreeMarker itself do
> about this. Fixing/extending the plugin itself is also not likely, as it's
> closed source. (Of course, it would be great to have an open source LSP
> language server, and then adding open source plugins based on that... but
> things go very, very slowly around here.)
Played around with the IntelliJ plugin but I don't get it perfectly working ...
>
> 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)
>>
>
> 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 don't think we want users to add their own templates to /templates, as
> they will be potentially lost when someone updates FreeMarker Generator,
> and is confusing for colleagues, etc. If we can prevent bad practices,
> let's do it. Especially as we also provide a cleaner
> solution, ~/.freemarker-generator/ added to the template root (which will
> change to ~/.freemarker-generator/templates now, as you say below). If
> people need a system-wide one, we can also add /etc/freemarker-generator,
> or something like that.
>
I currently disagree here - I like the visibility aspect and it is pretty difficult to get rid of templates loaded from the classpath.
> 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"
>>
>
> Except, we should avoid adding info.ftl and such to the template directory
> root. Not only because of potential name clashes, but because it can be
> confusing if someone looks at that (where's info.ftl coming from). How
> about reserving the "freemarker-generator" directory on the top level, and
> then it's "freemarker-generator -t freemarker-generator/info.ftl".
> (Hopefully that helps realizing that it's something built into FreeMarker
> Generator.) Actually, maybe it should be even
> "freemarker-generator:/info.ftl ".
Mhmm, already pushed the changes :-(
Need to think about it
>
> Thanks!
> Daniel Dekany
>
>
>> What do you think?
>>
>> Siegfried Goeschl
>>
>>
>>> On 05.08.2020, at 13:28, Daniel Dekany <da...@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.goeschl@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 <da...@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.goeschl@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 <da...@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.goeschl@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 <da...@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
>>
>>
>
> --
> Best regards,
> Daniel Dekany
Re: FreeMarker generator release preparations
Posted by Daniel Dekany <da...@gmail.com>.
See my answers inline...
On Sun, Aug 9, 2020 at 7:16 PM Siegfried Goeschl <
siegfried.goeschl@gmail.com> wrote:
> 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
>
What do you mean, realistically what can we do, in case that plugin is
indeed that broken? I mean, for FreeMarker Generator alone it doesn't
really matter for users. For all the other projects, FreeMarker doesn't
prevent them from doing dirty things to accomodate to the plugin (as you
saw yourself ;) ), and I'm not sure what else could FreeMarker itself do
about this. Fixing/extending the plugin itself is also not likely, as it's
closed source. (Of course, it would be great to have an open source LSP
language server, and then adding open source plugins based on that... but
things go very, very slowly around here.)
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)
>
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 don't think we want users to add their own templates to /templates, as
they will be potentially lost when someone updates FreeMarker Generator,
and is confusing for colleagues, etc. If we can prevent bad practices,
let's do it. Especially as we also provide a cleaner
solution, ~/.freemarker-generator/ added to the template root (which will
change to ~/.freemarker-generator/templates now, as you say below). If
people need a system-wide one, we can also add /etc/freemarker-generator,
or something like that.
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"
>
Except, we should avoid adding info.ftl and such to the template directory
root. Not only because of potential name clashes, but because it can be
confusing if someone looks at that (where's info.ftl coming from). How
about reserving the "freemarker-generator" directory on the top level, and
then it's "freemarker-generator -t freemarker-generator/info.ftl".
(Hopefully that helps realizing that it's something built into FreeMarker
Generator.) Actually, maybe it should be even
"freemarker-generator:/info.ftl ".
Thanks!
Daniel Dekany
> What do you think?
>
> Siegfried Goeschl
>
>
> > On 05.08.2020, at 13:28, Daniel Dekany <da...@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.goeschl@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 <da...@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.goeschl@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 <da...@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.goeschl@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 <da...@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
>
>
--
Best regards,
Daniel Dekany
Re: FreeMarker generator release preparations
Posted by Siegfried Goeschl <si...@gmail.com>.
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 <da...@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.goeschl@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 <da...@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.goeschl@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 <da...@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.goeschl@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 <da...@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
Re: FreeMarker generator release preparations
Posted by Daniel Dekany <da...@gmail.com>.
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.goeschl@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 <da...@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.goeschl@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 <da...@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.goeschl@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 <da...@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
Re: FreeMarker generator release preparations
Posted by Siegfried Goeschl <si...@gmail.com>.
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 <da...@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.goeschl@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 <da...@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.goeschl@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 <da...@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
Re: FreeMarker generator release preparations
Posted by Daniel Dekany <da...@gmail.com>.
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.goeschl@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 <da...@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.goeschl@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 <da...@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