Hi Daniel,
thanks for your feedback ...
# 1. Site Generation
Maven is not soo bad - I uploaded the generated site to
http://www.senilesoftwareengineer.org/freemarker-generator/ - I
personally have no problem using FreeMarker documentation approach but
decided no to follow it up for the time being due to time constraints.
# 2. Design/Architectural Doubts
## 2.1 Parsed Data
Currently we can load files/URLs as "DataSource" (which need to be
processed in FTL) or we can use "-m / --data-model" to parse and expose
the content directly (see
http://www.senilesoftwareengineer.org/freemarker-generator/freemarker-generator-cli/cli/concepts/data-models.html).
Regarding a less programmatic way - Named URIs are used (see
http://www.senilesoftwareengineer.org/freemarker-generator/freemarker-generator-cli/cli/concepts/named-uris.html)
to pass additional metadata but the implementation requires some re-work
to pass arbitrary metadata in the fragment.
E.g. what should be possible is
```
freeMarker-cli -t some.ftl -m
user=somepath/user.csv#delimiter=TAB&format=DEFAULT&charset=UTF-16&header=false
${CSVtool.parse(DataSources["user"])}
```
The idea is to be able to pass all metadata being used to parse the data
source - that would be also helpful for defining a SQL data source.
## Data versus Template Driven Generation
Currently a variety of transformations are supported on the command line
(see
http://www.senilesoftwareengineer.org/freemarker-generator/freemarker-generator-cli/cli/concepts/transformation.html)
* single template
* multiple templates
* directory of templates
Regarding "template versus data driven" generation - CLI does not
support data-driven generation where one output file is generated per
data source.
## 2.2 Convergence of Maven Plugin & CLI
It is on my list but does not have high priority since it should not
affect Maven plugin usage (regarding backward compatibility).
# 3. Maturity / Backward Compatibility
The project is not mature - we have no real users and little field
testing - in short I don't want to guarantee backward-compatibility for
now because some of my decisions might turn out to be plain wrong (or
even stupid) :-)
According to https://semver.org we can release 0.x.y and follow
https://semver.org/#spec-item-4 - not so nice but pragmatic.
# 4. General Considerations
There is a danger we never get "freemarker-generator" out of the door
("perfect is the enemy of good") therefore the whole PMC should look
into the questions/answers
* "freemarker-generator" needs community usage to become really useful -
the unreleased stuff does not add any value
* Is it acceptable to release a 0.X.Z where we not backward-compatible
until 1.0.0?
* Are there any deal breakers which needs to fixed before we start with
a first public release?
Thanks in advance,
Siegfried Goeschl
On 4 Jul 2020, at 1:10, Daniel Dekany wrote:
It should be in https://freemarker.apache.org/generator/. You will
need to
commit/push into
https://github.com/apache/freemarker-site/tree/asf-site
for that. (See
https://freemarker.apache.org/committer-howto.html#updating-homepage)
We need to generate the web pages somehow though. I saw you try to do
that
with Maven "site", but personally, I can't imagine that it can be
tweaked
to generate reasonable output. Not sure how others see this. Maven
"site"
is basically the Maven model dumped into HTML pages, and "reports"
like
even the log of the Rat run etc. Dozens of menus and sub-pages for
details
users mostly don't care about. The actual content users do care about
is
stuffed under "About", and from there it's not properly navigable or
searchable, as apparently it's assumed to be a single page. I know
back
then you didn't want to use the tool that's used both for the main web
site
and for the FreeMarker documentation, but I think that's the most
economical solution currently (and then we also have common styling,
and
common place to fix whatever technical issues), so please reconsider
that.
(I can help setting that up, of course.)
Now, some more difficult-to-address problematic things. My problem is
that
these just weren't concluded. Discussion just died. To be concluded
can
even mean that other PMC members say we should step over these, even
if I
disagree. But these should be understood, and considered. So, these
are:
- Design/architectural doubts that are probably not realistic to
address
much later:
- Currently, data sources are just URL-s (locations), and
templates
are meant to call tool API-s to parse them. As I said back then,
one
consequence is that then, you can't put parsed data into the
data-model
shared by all templates (i.e., via -m/--data-model). Because,
you have no
convenient/concise way to load the actual (parsed) data, instead
you have
to "program it" in FTL, because the assumption was that you only
want to do
that in templates anyway. Furthermore, as I saw it just now,
--data-model
actually supports some ad-hoc way of parsing the data pointed by
a
data-source-like URL, as JSON, YAML, maybe some more. Here's an
example of
that: `-m config=env:///DB_CONFIG#mimetype=application/json`. So
there is a
need actually. But compared to what you can do in templeats,
it's totally
different, and of course very restrictive. I was also looking
for a less
"programmatic" way of loading data because even doing it in
templates is
not very friendly as it is. (For ultimate flexibility you might
need
program logic for sure, but certainly not just to grab a
worksheet from an
Excel file.) We also should have a POC for loading from a less
file centric
data source, like from a DB with a SQL query, to see if the
concept works.
- Not sure what's with template-driven VS data driven output
generation. Data driven is when you generate one output file per
some data
unit (like per JSON file, or per DB record), and all is
transformed by a
common template. How would that look currently in
freemarker-cli?
- The Maven plugin provides very different functionality than the
CLI.
The original concept was that they are just two interfaces to the
same
product. That was also brought up, and I don't think it was
addressed much,
like, why you disagree, if you do, or what's going on. Anyway,
regarding
what we have now. The naming implies that, as both are "FreeMarker
Generator", just one is "CLI", and the other is "Maven". But as far
as I
see, they are two different "products" really, focusing on
different use
cases. So, if it stays like this, then some of them have to be
renamed at
least. Or I don't know what others think we can do. (Then it's
still
somewhat weird to release them together.)
(I have also run through the CLI documentation, and found a lot of
less
fundamental things to address, but I don't want to overload the
thread.)
Also, if the project is released mostly as it is now, what will we
promise
regarding backward compatibility? What do we communicate about the
matureness of the project?
On Wed, Jul 1, 2020 at 8:29 AM Siegfried Goeschl <
siegfried.goes...@gmail.com> wrote:
Hi folks,
I'm pretty much finished with the stuff I would like to have for the
first
public release but there is a still a lot of work ahead
* FREEMARKER-148 [freemarker-cli] Make usage of "DataSources" more
"Freemarker" like
* FREEMARKER-150 [freemarker-cli] Setup "freemarker-generator" web
site
* Setup the release process (Daniel, I guess I need some help here)
* An iteration of reviews and discussions
Some thought along the line
* I would like to finish FREEMARKER-148 this week
* Daniel, any suggestion where to host the public website?
Thanks in advance,
Siegfried Goeschl
--
Best regards,
Daniel Dekany
