You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@freemarker.apache.org by dd...@apache.org on 2020/08/22 17:11:47 UTC
[freemarker-generator] 02/02: Continued working on porting the .md
documentation to XDocBook. Changed the build process a bit as well.
This is an automated email from the ASF dual-hosted git repository.
ddekany pushed a commit to branch FREEMARKER-154
in repository https://gitbox.apache.org/repos/asf/freemarker-generator.git
commit 9d04cd95fdc0bdccc32c872e12dd9a48180cb849
Author: ddekany <dd...@apache.org>
AuthorDate: Sat Aug 22 19:11:29 2020 +0200
Continued working on porting the .md documentation to XDocBook. Changed the build process a bit as well.
---
.../cli/config/TemplateDirectorySupplier.java | 6 +-
freemarker-generator-website/README.md | 15 ++-
freemarker-generator-website/pom.xml | 31 ++++-
.../src/main/docgen/book.xml | 125 +++++++++------------
.../src/main/docgen/docgen.cjson | 4 +-
pom.xml | 2 +-
6 files changed, 101 insertions(+), 82 deletions(-)
diff --git a/freemarker-generator-cli/src/main/java/org/apache/freemarker/generator/cli/config/TemplateDirectorySupplier.java b/freemarker-generator-cli/src/main/java/org/apache/freemarker/generator/cli/config/TemplateDirectorySupplier.java
index 8e644a9..886a9ea 100644
--- a/freemarker-generator-cli/src/main/java/org/apache/freemarker/generator/cli/config/TemplateDirectorySupplier.java
+++ b/freemarker-generator-cli/src/main/java/org/apache/freemarker/generator/cli/config/TemplateDirectorySupplier.java
@@ -95,6 +95,10 @@ public class TemplateDirectorySupplier implements Supplier<List<File>> {
}
private static boolean isDirectory(File directory) {
- return directory != null && directory.exists() && directory.isDirectory() && directory.canRead();
+ boolean exists = directory.exists();
+ boolean isDirectory = directory.isDirectory();
+ boolean canRead = directory.canRead();
+ boolean r = directory != null && exists && isDirectory && canRead;
+ return r;
}
}
diff --git a/freemarker-generator-website/README.md b/freemarker-generator-website/README.md
index 2f928b8..7f0008b 100644
--- a/freemarker-generator-website/README.md
+++ b/freemarker-generator-website/README.md
@@ -1,5 +1,16 @@
Apache FreeMarker Generator Website
=============================================================================
-Generates the FreeMarker Generator website, which also contains the documentation;
-this is used internally.
+Generates the FreeMarker Generator website, which also contains the documentation.
+This module is used internally. The output artifact shouldn't be deployed to the
+Maven Central. The output is merely to be uploaded to our website. The source code
+can be part of the Apache released though.
+
+Building
+--------
+
+This module is deliberately not built automatically when you build the top-level
+module. To build successfully, first you must build the `freemarker-generator-cli`,
+so that we will have `target/appassembler`. Then run the examples in
+`target/appassembler`, as the documentation includes the output of some examples.
+Only after these run `mvn package` in `freemarker-generator-website`.
diff --git a/freemarker-generator-website/pom.xml b/freemarker-generator-website/pom.xml
index 898bc90..b199bb8 100644
--- a/freemarker-generator-website/pom.xml
+++ b/freemarker-generator-website/pom.xml
@@ -35,9 +35,11 @@
<maven.compiler.target>1.8</maven.compiler.target>
<websiteOutputDirectory>${project.build.directory}/website</websiteOutputDirectory>
- <freemarkerGeneratorBaseDirectory>${project.basedir}/../freemarker-generator-cli</freemarkerGeneratorBaseDirectory>
+ <freemarkerGeneratorAppHome>${project.basedir}/../freemarker-generator-cli/target/appassembler</freemarkerGeneratorAppHome>
<docgenInsertedOutputsDirectory>${project.build.directory}/docgen-insertable-outputs</docgenInsertedOutputsDirectory>
- <docgenInsertedExamplesDirectory>${freemarkerGeneratorBaseDirectory}/examples</docgenInsertedExamplesDirectory>
+ <docgenInsertedExampleTemplatesDirectory>${freemarkerGeneratorAppHome}/examples/templates</docgenInsertedExampleTemplatesDirectory>
+ <docgenInsertedExampleOutputDirectory>${freemarkerGeneratorAppHome}/target/out</docgenInsertedExampleOutputDirectory>
+ <docgenInsertedTemplatesDirectory>${freemarkerGeneratorAppHome}/templates</docgenInsertedTemplatesDirectory>
</properties>
<dependencies>
@@ -65,6 +67,15 @@
<arguments>
<argument>-classpath</argument>
<classpath/>
+
+ <!-- Setting up things without calling the launcher scripts in app/bin: -->
+ <!-- TODO in freemarker-generator-cli: Ideally, only setting -Dapp.home should be enough. -->
+ <argument>org.apache.freemarker.generator.cli.Main</argument>
+ <argument>--config</argument>
+ <argument>${freemarkerGeneratorAppHome}/config/freemarker-generator.properties</argument>
+ <argument>--template-dir</argument>
+ <argument>${freemarkerGeneratorAppHome}/templates</argument>
+
<argument>org.apache.freemarker.generator.cli.Main</argument>
<argument>--help</argument>
</arguments>
@@ -82,11 +93,17 @@
<arguments>
<argument>-classpath</argument>
<classpath/>
+
+ <!-- Setting up things without calling the launcher scripts in app/bin: -->
+ <!-- TODO in freemarker-generator-cli: Ideally, only setting -Dapp.home should be enough. -->
<argument>org.apache.freemarker.generator.cli.Main</argument>
- <argument>-b</argument>
- <argument>${freemarkerGeneratorBaseDirectory}</argument>
+ <argument>--config</argument>
+ <argument>${freemarkerGeneratorAppHome}/config/freemarker-generator.properties</argument>
+ <argument>--template-dir</argument>
+ <argument>${freemarkerGeneratorAppHome}/templates</argument>
+
<argument>-t</argument>
- <argument>templates/info.ftl</argument>
+ <argument>freemarker-generator/info.ftl</argument>
</arguments>
<outputFile>${docgenInsertedOutputsDirectory}/info-template-output.txt</outputFile>
</configuration>
@@ -111,7 +128,9 @@
<outputDirectory>${websiteOutputDirectory}</outputDirectory>
<insertableFiles>
<outputs>${docgenInsertedOutputsDirectory}/**</outputs>
- <examples>${docgenInsertedExamplesDirectory}/**</examples>
+ <templates>${docgenInsertedTemplatesDirectory}/**</templates>
+ <exampleTemplates>${docgenInsertedExampleTemplatesDirectory}/**</exampleTemplates>
+ <exampleOutputs>${docgenInsertedExampleOutputDirectory}/**</exampleOutputs>
</insertableFiles>
<customVariables>
<version>${project.version}</version>
diff --git a/freemarker-generator-website/src/main/docgen/book.xml b/freemarker-generator-website/src/main/docgen/book.xml
index 4520c0e..a2a5278 100644
--- a/freemarker-generator-website/src/main/docgen/book.xml
+++ b/freemarker-generator-website/src/main/docgen/book.xml
@@ -170,7 +170,7 @@ version=[docgen.customVariables.version], time=2020-06-25T21:48:02+0200, commit=
the <literal>templates/info.ftl</literal> is particularly helpful to
better understand Apache FreeMarker CLI.</para>
- <programlisting>> freemarker-generator -t templates/info.ftl
+ <programlisting>> freemarker-generator -t freemarker-generator/info.ftl
[docgen.insertFile "@outputs/info-template-output.txt"]</programlisting>
<para>Above:</para>
@@ -212,73 +212,9 @@ version=[docgen.customVariables.version], time=2020-06-25T21:48:02+0200, commit=
<literal>run-examples.bat</literal> in the Apache FreeMarker Generator
installation directory, and have a look at the generated output.</para>
- <programlisting>./run-examples.sh
-templates/info.ftl
-examples/templates/demo.ftl
-templates/csv/html/transform.ftl
-templates/csv/md/transform.ftl
-examples/templates/csv/shell/curl.ftl
-examples/templates/csv/md/filter.ftl
-examples/templates/csv/fo/transform.ftl
-fop -fo target/out/locker-test-users.fo target/out/locker-test-users.pdf
-examples/templates/csv/fo/transactions.ftl
-fop -fo target/out/transactions.fo target/out/transactions-fo.pdf
-templates/csv/html/transform.ftl
-wkhtmltopdf -O landscape target/out/transactions.html target/out/transactions-html.pdf
-examples/templates/dataframe/example.ftl
-examples/templates/accesslog/combined-access.ftl
-examples/templates/excel/dataframe/transform.ftl
-templates/excel/html/transform.ftl
-templates/excel/md/transform.ftl
-templates/excel/csv/transform.ftl
-examples/templates/excel/csv/custom.ftl
-examples/templates/html/csv/dependencies.ftl
-examples/templates/json/csv/swagger-endpoints.ftl
-templates/json/yaml/transform.ftl
-examples/templates/json/md/github-users.ftl
-examples/templates/properties/csv/locker-test-users.ftl
-examples/data/template
-examples/templates/yaml/txt/transform.ftl
-templates/yaml/json/transform.ftl
-examples/templates/xml/txt/recipients.ftl
-Created the following sample files in ./target/out
-total 1464
--rw-r--r-- 1 sgoeschl staff 646 Jun 27 16:38 combined-access.log.txt
--rw-r--r-- 1 sgoeschl staff 25676 Jun 27 16:38 contract.html
--rw-r--r-- 1 sgoeschl staff 7933 Jun 27 16:38 contract.md
--rw-r--r-- 1 sgoeschl staff 784 Jun 27 16:38 curl.sh
--rw-r--r-- 1 sgoeschl staff 232 Jun 27 16:38 customer.txt
--rw-r--r-- 1 sgoeschl staff 6486 Jun 27 16:38 dataframe.txt
--rw-r--r-- 1 sgoeschl staff 15613 Jun 27 16:38 demo.txt
--rw-r--r-- 1 sgoeschl staff 1310 Jun 27 16:38 dependencies.csv
--rw-r--r-- 1 sgoeschl staff 2029 Jun 27 16:38 github-users-curl.md
--rw-r--r-- 1 sgoeschl staff 2627 Jun 27 16:38 info.txt
--rw-r--r-- 1 sgoeschl staff 8075 Jun 27 16:38 interactive-dataframe.txt
--rw-r--r-- 1 sgoeschl staff 66 Jun 27 16:38 interactive-html.txt
--rw-r--r-- 1 sgoeschl staff 16 Jun 27 16:38 interactive-json.txt
--rw-r--r-- 1 sgoeschl staff 25090 Jun 27 16:38 interactive-swagger.json
--rw-r--r-- 1 sgoeschl staff 16870 Jun 27 16:38 interactive-swagger.yaml
--rw-r--r-- 1 sgoeschl staff 10 Jun 27 16:38 interactive-xml.txt
--rw-r--r-- 1 sgoeschl staff 285 Jun 27 16:38 locker-test-users.csv
--rw-r--r-- 1 sgoeschl staff 6341 Jun 27 16:38 locker-test-users.fo
--rw-r--r-- 1 sgoeschl staff 5526 Jun 27 16:38 locker-test-users.pdf
--rw-r--r-- 1 sgoeschl staff 921 Jun 27 16:38 recipients.txt
--rw-r--r-- 1 sgoeschl staff 910 Jun 27 16:38 sales-records.md
--rw-r--r-- 1 sgoeschl staff 2453 Jun 27 16:38 swagger-spec.csv
--rw-r--r-- 1 sgoeschl staff 25090 Jun 27 16:38 swagger-spec.json
--rw-r--r-- 1 sgoeschl staff 16870 Jun 27 16:38 swagger-spec.yaml
-drwxr-xr-x 4 sgoeschl staff 128 Jun 27 16:38 template
--rw-r--r-- 1 sgoeschl staff 154 Jun 27 16:38 test-multiple-sheets.xlsx.csv
--rw-r--r-- 1 sgoeschl staff 1917 Jun 27 16:38 test-multiple-sheets.xlsx.html
--rw-r--r-- 1 sgoeschl staff 389 Jun 27 16:38 test-multiple-sheets.xlsx.md
--rw-r--r-- 1 sgoeschl staff 155 Jun 27 16:38 test-transform-xls.csv
--rw-r--r-- 1 sgoeschl staff 1439 Jun 27 16:38 test.xls.dataframe.txt
--rw-r--r-- 1 sgoeschl staff 1556 Jun 27 16:38 test.xls.html
--rw-r--r-- 1 sgoeschl staff 1558 Jun 27 16:38 test.xslx.html
--rw-r--r-- 1 sgoeschl staff 25757 Jun 27 16:38 transactions-fo.pdf
--rw-r--r-- 1 sgoeschl staff 66016 Jun 27 16:38 transactions-html.pdf
--rw-r--r-- 1 sgoeschl staff 330128 Jun 27 16:38 transactions.fo
--rw-r--r-- 1 sgoeschl staff 51008 Jun 27 16:38 transactions.html</programlisting>
+ <remark>Removed console output showing list of examples and ls like
+ output from here. I think it doesn't help users, and had to be generated
+ in Maven somehow.</remark>
<para>Please note that generated PDF files are very likely not found
since they require wkhtmltopdf and Apache FOP installation.</para>
@@ -293,13 +229,60 @@ drwxr-xr-x 4 sgoeschl staff 128 Jun 27 16:38 template
<programlisting>> freemarker-generator -t examples/templates/json/md/github-users.ftl examples/data/json/github-users.json</programlisting>
- <para>or pipe a cURL response</para>
+ <para>or pipe a <literal>curl</literal> response</para>
<programlisting>> curl -s https://api.github.com/users | freemarker-generator -t examples/templates/json/md/github-users.ftl --stdin</programlisting>
- <para>Below you see the Apache FreeMarker Template</para>
+ <para>Below you see the Apache FreeMarker Template:</para>
- <programlisting role="template">[docgen.insertFile "@examples/templates/json/md/github-users.ftl"]</programlisting>
+ <programlisting role="template">[docgen.insertFile "@exampleTemplates/json/md/github-users.ftl"]</programlisting>
+
+ <para>This creates the following output:</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/examples/github.png" width="100%"/>
+ </imageobject>
+ </mediaobject>
+ </section>
+
+ <section>
+ <title>CSV to HTML/Markdown Transformation</title>
+
+ <para>Sometimes you have a CSV file which needs to be translated in
+ Markdown or HTML - there are on-line solutions
+ available<remark>[removed external product link from here]</remark>,
+ but having a local solution gives you more flexibility.</para>
+
+ <programlisting>> freemarker-generator -t freemarker-generator/csv/md/transform.ftl examples/data/csv/contract.csv
+> freemarker-generator -t freemarker-generator/csv/html/transform.ftl examples/data/csv/contract.csv</programlisting>
+
+ <para>The FreeMarker template is shown below.</para>
+
+ <programlisting role="template">[docgen.insertFile "@templates/freemarker-generator/csv/md/transform.ftl"]</programlisting>
+
+ <para>The resulting file actually looks pleasant when compared to raw
+ CSV</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/examples/contract.png" width="100%"/>
+ </imageobject>
+ </mediaobject>
+ </section>
+
+ <section>
+ <title>Transform XML To Plain Text</title>
+
+ <para>Of course you can also transform an XML document:</para>
+
+ <programlisting>> freemarker-generator -t examples/templates/xml/txt/recipients.ftl examples/data/xml/recipients.xml</programlisting>
+
+ <para>This is using the following template:</para>
+
+ <programlisting role="template">[docgen.insertFile "@exampleTemplates/xml/txt/recipients.ftl"]</programlisting>
+
+ <programlisting role="output">[docgen.insertFile "@exampleOutputs/recipients.txt"]</programlisting>
</section>
</section>
</chapter>
diff --git a/freemarker-generator-website/src/main/docgen/docgen.cjson b/freemarker-generator-website/src/main/docgen/docgen.cjson
index 4152684..8b76b0e 100644
--- a/freemarker-generator-website/src/main/docgen/docgen.cjson
+++ b/freemarker-generator-website/src/main/docgen/docgen.cjson
@@ -99,5 +99,7 @@ customVariables: {
insertableFiles: {
outputs: null // Must be overridden by the caller
- examples: null // Must be overridden by the caller
+ templates: null // Must be overridden by the caller
+ exampleTemplates: null // Must be overridden by the caller
+ exampleOutputs: null // Must be overridden by the caller
}
diff --git a/pom.xml b/pom.xml
index d74bb29..78484f3 100644
--- a/pom.xml
+++ b/pom.xml
@@ -78,7 +78,7 @@
<module>freemarker-generator-tools</module>
<module>freemarker-generator-cli</module>
<module>freemarker-generator-maven-plugin</module>
- <module>freemarker-generator-website</module>
+ <!-- Don't build this automatically: <module>freemarker-generator-website</module> -->
</modules>
<properties>