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 b014a3c73c52a1b546a7d5cca9e5af46412fafee Author: ddekany <[email protected]> AuthorDate: Sun Feb 14 21:11:07 2021 +0100 Changed demo.ftl to use a system property instead of a -P parameter, as it's easier to pass that reliably from [docgen.insertWithOutput]. --- .../src/app/examples/templates/demo.ftl | 2 +- .../src/app/scripts/run-examples.bat | 2 +- .../src/app/scripts/run-examples.sh | 2 +- .../freemarker/generator/cli/ExamplesTest.java | 2 +- freemarker-generator-website/pom.xml | 49 ---- .../src/main/docgen/book.xml | 261 +++++++++------------ 6 files changed, 119 insertions(+), 199 deletions(-) diff --git a/freemarker-generator-cli/src/app/examples/templates/demo.ftl b/freemarker-generator-cli/src/app/examples/templates/demo.ftl index e35e2a9..9b30fc3 100644 --- a/freemarker-generator-cli/src/app/examples/templates/demo.ftl +++ b/freemarker-generator-cli/src/app/examples/templates/demo.ftl @@ -15,7 +15,7 @@ specific language governing permissions and limitations under the License. --> -<#assign deductSensitiveInformation = (tools.system.parameters.deductSensitiveInformation!'false') != 'false'> +<#assign deductSensitiveInformation = (tools.system.systemProperties["freemarkerGenerator.examples.deductSensitiveInformation"]!'false') != 'false'> 1) FreeMarker Special Variables --------------------------------------------------------------------------- FreeMarker version : ${.version} diff --git a/freemarker-generator-cli/src/app/scripts/run-examples.bat b/freemarker-generator-cli/src/app/scripts/run-examples.bat index 99991a1..f905306 100644 --- a/freemarker-generator-cli/src/app/scripts/run-examples.bat +++ b/freemarker-generator-cli/src/app/scripts/run-examples.bat @@ -35,7 +35,7 @@ REM Demo REM ========================================================================= echo "examples\templates\demo.ftl" -%FREEMARKER_CMD% -t examples\templates\demo.ftl --output-encoding CP1252 -PdeductSensitiveInformation=true README.md > target\out\demo.txt +%FREEMARKER_CMD% -t examples\templates\demo.ftl --output-encoding CP1252 -DfreemarkerGenerator.examples.deductSensitiveInformation=true README.md > target\out\demo.txt REM ========================================================================= REM Interactive Mode diff --git a/freemarker-generator-cli/src/app/scripts/run-examples.sh b/freemarker-generator-cli/src/app/scripts/run-examples.sh index 5d85cf0..cd8689c 100755 --- a/freemarker-generator-cli/src/app/scripts/run-examples.sh +++ b/freemarker-generator-cli/src/app/scripts/run-examples.sh @@ -40,7 +40,7 @@ $FREEMARKER_CMD -t freemarker-generator/info.ftl README.md > target/out/info.txt ############################################################################# echo "examples/templates/demo.ftl" -$FREEMARKER_CMD -t examples/templates/demo.ftl -PdeductSensitiveInformation=true README.md > target/out/demo.txt || { echo >&2 "Test failed. Aborting."; exit 1; } +$FREEMARKER_CMD -t examples/templates/demo.ftl -DfreemarkerGenerator.examples.deductSensitiveInformation=true README.md > target/out/demo.txt || { echo >&2 "Test failed. Aborting."; exit 1; } ############################################################################# # Interactive Mode diff --git a/freemarker-generator-cli/src/test/java/org/apache/freemarker/generator/cli/ExamplesTest.java b/freemarker-generator-cli/src/test/java/org/apache/freemarker/generator/cli/ExamplesTest.java index fa7a734..d144e62 100644 --- a/freemarker-generator-cli/src/test/java/org/apache/freemarker/generator/cli/ExamplesTest.java +++ b/freemarker-generator-cli/src/test/java/org/apache/freemarker/generator/cli/ExamplesTest.java @@ -44,7 +44,7 @@ public class ExamplesTest extends AbstractMainTest { @Test public void shouldRunDemoExamples() throws IOException { - assertValid(execute("-t src/app/examples/templates/demo.ftl -PdeductSensitiveInformation=true README.md")); + assertValid(execute("-t src/app/examples/templates/demo.ftl -DfreemarkerGenerator.examples.deductSensitiveInformation=true README.md")); } @Test diff --git a/freemarker-generator-website/pom.xml b/freemarker-generator-website/pom.xml index a365a22..4dbf604 100644 --- a/freemarker-generator-website/pom.xml +++ b/freemarker-generator-website/pom.xml @@ -53,55 +53,6 @@ <build> <plugins> <plugin> - <groupId>org.codehaus.mojo</groupId> - <artifactId>exec-maven-plugin</artifactId> - <executions> - <execution> - <id>generateCliHelp</id> - <phase>package</phase> - <goals> - <goal>exec</goal> - </goals> - <configuration> - <executable>java</executable> - <arguments> - <argument>-classpath</argument> - <classpath/> - - <!-- Setting up things without calling the launcher scripts in app/bin: --> - <argument>-Dapp.home=${freemarkerGeneratorAppHome}</argument> - - <argument>org.apache.freemarker.generator.cli.Main</argument> - <argument>--help</argument> - </arguments> - <outputFile>${docgenInsertedOutputsDirectory}/cli-help-output.txt</outputFile> - </configuration> - </execution> - <execution> - <id>generateInfoTemplateOutput</id> - <phase>package</phase> - <goals> - <goal>exec</goal> - </goals> - <configuration> - <executable>java</executable> - <arguments> - <argument>-classpath</argument> - <classpath/> - - <!-- Setting up things without calling the launcher scripts in app/bin: --> - <argument>-Dapp.home=${freemarkerGeneratorAppHome}</argument> - - <argument>org.apache.freemarker.generator.cli.Main</argument> - <argument>-t</argument> - <argument>freemarker-generator/info.ftl</argument> - </arguments> - <outputFile>${docgenInsertedOutputsDirectory}/info-template-output.txt</outputFile> - </configuration> - </execution> - </executions> - </plugin> - <plugin> <groupId>org.apache.freemarker.docgen</groupId> <artifactId>freemarker-docgen-maven</artifactId> <version>0.0.2-SNAPSHOT</version> diff --git a/freemarker-generator-website/src/main/docgen/book.xml b/freemarker-generator-website/src/main/docgen/book.xml index e6751b5..f3dd4e8 100644 --- a/freemarker-generator-website/src/main/docgen/book.xml +++ b/freemarker-generator-website/src/main/docgen/book.xml @@ -99,11 +99,11 @@ </note> </chapter> - <chapter> + <chapter xml:id="getting-started"> <title>Getting started</title> - <section> - <title>Getting started</title> + <section xml:id="installation"> + <title>Installation</title> <simplesect> <title>Installation</title> @@ -146,11 +146,11 @@ <programlisting>> which freemarker-generator /Applications/Java/freemarker-generator-[docgen.customVariables.version]/bin/freemarker-generator</programlisting> - <para>and check the version of Apache FreeMarker CLI</para> + <para>and check the version of Apache FreeMarker CLI:</para> - <programlisting>> freemarker-generator -V -version=[docgen.customVariables.version], time=2020-06-25T21:48:02+0200, commit=b320d00094be8789086ad6153d9d3fcaf4b8c75f -</programlisting> + <programlisting>[docgen.insertWithOutput] +freemarker-generator -V +[/docgen.insertWithOutput]</programlisting> </simplesect> <simplesect> @@ -159,8 +159,9 @@ version=[docgen.customVariables.version], time=2020-06-25T21:48:02+0200, commit= <para>Apache FreeMarker Generator provides command line help as shown below:</para> - <programlisting>> freemarker-generator -h -[docgen.insertFile "@websitePomGenerated/cli-help-output.txt"]</programlisting> + <programlisting>[docgen.insertWithOutput] +freemarker-generator -h +[/docgen.insertWithOutput]</programlisting> </simplesect> <simplesect> @@ -170,8 +171,9 @@ 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 freemarker-generator/info.ftl -[docgen.insertFile "@websitePomGenerated/info-template-output.txt"]</programlisting> + <programlisting>[docgen.insertWithOutput] +freemarker-generator -t freemarker-generator/info.ftl +[/docgen.insertWithOutput]</programlisting> <para>Above:</para> @@ -227,7 +229,9 @@ version=[docgen.customVariables.version], time=2020-06-25T21:48:02+0200, commit= <para>You can either use the existing JSON sample</para> - <programlisting>> freemarker-generator -t examples/templates/json/md/github-users.ftl examples/data/json/github-users.json</programlisting> + <programlisting>[docgen.insertWithOutput] +freemarker-generator -t [docgen.wd]/examples/templates/json/md/github-users.ftl [docgen.wd]/examples/data/json/github-users.json +[/docgen.insertWithOutput]</programlisting> <para>or pipe a <literal>curl</literal> response</para> @@ -244,6 +248,8 @@ version=[docgen.customVariables.version], time=2020-06-25T21:48:02+0200, commit= <imagedata fileref="images/examples/github.png" width="100%"/> </imageobject> </mediaobject> + + <remark>Above are real people, so we shouldn't include this.</remark> </section> <section> @@ -254,8 +260,12 @@ version=[docgen.customVariables.version], time=2020-06-25T21:48:02+0200, commit= 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> + <programlisting>[docgen.checkCommand] +freemarker-generator -t freemarker-generator/csv/md/transform.ftl [docgen.wd]/examples/data/csv/contract.csv +[/docgen.checkCommand] +[docgen.checkCommand] +freemarker-generator -t freemarker-generator/csv/html/transform.ftl [docgen.wd]/examples/data/csv/contract.csv +[/docgen.checkCommand]</programlisting> <para>The FreeMarker template is shown below.</para> @@ -276,13 +286,13 @@ version=[docgen.customVariables.version], time=2020-06-25T21:48:02+0200, commit= <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> + <programlisting>[docgen.insertWithOutput] +freemarker-generator -t [docgen.wd]/examples/templates/xml/txt/recipients.ftl [docgen.wd]/examples/data/xml/recipients.xml +[/docgen.insertWithOutput]</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> @@ -303,50 +313,13 @@ version=[docgen.customVariables.version], time=2020-06-25T21:48:02+0200, commit= provide backward compatibility yet, we better stick to runnable examples, or else they will become outdated here.</remark></para> - <programlisting><#ftl output_format="plainText" strip_text="true"> -<#assign json = tools.jsonpath.parse(dataSources?values[0])> -<#assign basePath = json.read("$.basePath")> -<#assign paths = json.read("$.paths")> - -<#compress> - ENDPOINT;METHOD;CONSUMES;PRODUCES;SUMMARY;DESCRIPTION - <#list paths as endpoint,metadata> - <#assign relative_url = basePath + endpoint> - <#assign methods = metadata?keys> - <#list methods as method> - <#assign summary = sanitize(paths[endpoint][method]["summary"]!"")> - <#assign description = sanitize(paths[endpoint][method]["description"]!"")> - <#assign consumes = join(paths[endpoint][method]["consumes"]![])> - <#assign produces = join(paths[endpoint][method]["produces"]![])> - ${relative_url};${method?upper_case};${consumes};${produces};${summary};${description} - </#list> - </#list> -</#compress> -${'\n'} - -<#function sanitize str> - <#return (((str?replace(";", ","))?replace("(\\n)+", "",'r')))?truncate(250)> -</#function> - -<#function join list> - <#if list?has_content> - <#return list?join(", ")> - <#else> - <#return ""> - </#if> -</#function></programlisting> - - <para>Invoking the FTL template</para> + <programlisting role="template">[docgen.insertFile "@exampleTemplates/json/csv/swagger-endpoints.ftl"]</programlisting> - <programlisting>> freemarker-generator -t examples/templates/json/csv/swagger-endpoints.ftl examples/data/json/swagger-spec.json</programlisting> + <para>Invoking the FTL template, and its output:</para> - <para>gives you</para> - - <programlisting role="output">ENDPOINT;METHOD;CONSUMES;PRODUCES;SUMMARY;DESCRIPTION -/api/pets;GET;;;;Returns all pets from the system that the user has access to -/api/pets;POST;;;;Creates a new pet in the store. Duplicates are allowed -/api/pets/{id};GET;;;;Returns a user based on a single ID, if the user does not have access to the pet -/api/pets/{id};DELETE;;;;Deletes a single pet based on the ID supplied</programlisting> + <programlisting>[docgen.insertWithOutput] +freemarker-generator -t [docgen.wd]/examples/templates/json/csv/swagger-endpoints.ftl [docgen.wd]/examples/data/json/swagger-spec.json +[/docgen.insertWithOutput]</programlisting> </section> <section> @@ -361,11 +334,18 @@ ${'\n'} transformation was provided to show the transformation of Excel documents.</para> - <programlisting>> freemarker-generator -t freemarker-generator/excel/html/transform.ftl examples/data/excel/test.xls -> freemarker-generator -t freemarker-generator/excel/html/transform.ftl examples/data/excel/test.xlsx -> freemarker-generator -t freemarker-generator/excel/html/transform.ftl examples/data/excel/test-multiple-sheets.xlsx -> freemarker-generator -t freemarker-generator/excel/md/transform.ftl examples/data/excel/test-multiple-sheets.xlsx -</programlisting> + <programlisting>[docgen.checkCommand] +freemarker-generator -t freemarker-generator/excel/html/transform.ftl [docgen.wd]/examples/data/excel/test.xls +[/docgen.checkCommand] +[docgen.checkCommand] +freemarker-generator -t freemarker-generator/excel/html/transform.ftl [docgen.wd]/examples/data/excel/test.xlsx +[/docgen.checkCommand] +[docgen.checkCommand] +freemarker-generator -t freemarker-generator/excel/html/transform.ftl [docgen.wd]/examples/data/excel/test-multiple-sheets.xlsx +[/docgen.checkCommand] +[docgen.checkCommand] +freemarker-generator -t freemarker-generator/excel/md/transform.ftl [docgen.wd]/examples/data/excel/test-multiple-sheets.xlsx +[/docgen.checkCommand]</programlisting> <para>The provided FTL transforms an Excel into a HTML document supporting multiple Excel sheets:</para> @@ -389,11 +369,15 @@ ${'\n'} directory (recursive search using include pattern) to a CSV file.</para> - <programlisting>> freemarker-generator --data-source-include *.properties -t examples/templates/properties/csv/locker-test-users.ftl examples/data/properties</programlisting> + <programlisting>[docgen.insertWithOutput] +freemarker-generator --data-source-include *.properties -t [docgen.wd]/examples/templates/properties/csv/locker-test-users.ftl [docgen.wd]/examples/data/properties +[/docgen.insertWithOutput]</programlisting> + + <para>The template it uses is this:</para> - <programlisting role="output">[docgen.insertFile "@exampleOutputs/locker-test-users.csv"]</programlisting> + <programlisting role="template">[docgen.insertFile "@exampleTemplates/properties/csv/locker-test-users.ftl"]</programlisting> - <para>The FTL uses a couple of interesting features:</para> + <para>The template uses a couple of interesting features:</para> <itemizedlist> <listitem> @@ -416,8 +400,6 @@ ${'\n'} <listitem> <para>We add a manual line break using <literal>${'\n'}</literal></para> - - <programlisting role="template">[docgen.insertFile "@exampleTemplates/properties/csv/locker-test-users.ftl"]</programlisting> </listitem> </itemizedlist> </section> @@ -435,7 +417,8 @@ ${'\n'} <para>In order to create the PDF you need to execute the following commands (assuming that you have Apache FOP installed):</para> - <programlisting>> freemarker-generator -t examples/templates/csv/fo/transform.ftl examples/data/csv/locker-test-users.csv > sample.fo + <programlisting>[docgen.insertWithOutput]freemarker-generator -t [docgen.wd]/examples/templates/csv/fo/transform.ftl [docgen.wd]/examples/data/csv/locker-test-users.csv[/docgen.insertWithOutput] > sample.fo + > fop -fo sample.fo sample.pdf Dec 29, 2018 10:24:30 PM org.apache.fop.events.LoggingEventListener processEvent WARNING: Font "Symbol,normal,700" not found. Substituting with "Symbol,normal,400". @@ -459,7 +442,8 @@ INFO: Rendered page #1.</programlisting> <programlisting role="template">[docgen.insertFile "@exampleTemplates/csv/fo/transactions.ftl"]</programlisting> - <programlisting>> freemarker-generator -t examples/templates/csv/fo/transactions.ftl examples/data/csv/transactions.csv > transactions.fo + <programlisting>[docgen.insertWithOutput]freemarker-generator -t [docgen.wd]/examples/templates/csv/fo/transactions.ftl [docgen.wd]/examples/data/csv/transactions.csv[/docgen.insertWithOutput] > transactions.fo + > fop -fo transactions.fo transactions.pdf Jan 16, 2019 11:15:21 PM org.apache.fop.events.LoggingEventListener processEvent WARNING: Font "Symbol,normal,700" not found. Substituting with "Symbol,normal,400". @@ -492,9 +476,9 @@ INFO: Rendered page #2.</programlisting> <para>Your dependencies as CSV can be generated as shown below:</para> - <programlisting>> freemarker-generator -t examples/templates/html/csv/dependencies.ftl examples/data/html/dependencies.html</programlisting> - - <programlisting role="output">[docgen.insertFile "@exampleOutputs/dependencies.csv"]</programlisting> + <programlisting>[docgen.insertWithOutput] +freemarker-generator -t [docgen.wd]/examples/templates/html/csv/dependencies.ftl [docgen.wd]/examples/data/html/dependencies.html +[/docgen.insertWithOutput]</programlisting> </section> <section> @@ -524,11 +508,7 @@ INFO: Rendered page #2.</programlisting> <para>Rendering the FreeMarker template:</para> - <programlisting>> freemarker-generator -t examples/templates/csv/shell/curl.ftl examples/data/csv/user.csv</programlisting> - - <para>generates the following shell script:</para> - - <programlisting role="output">[docgen.insertFile "@exampleOutputs/curl.sh"]</programlisting> + <programlisting>freemarker-generator -t examples/templates/csv/shell/curl.ftl examples/data/csv/user.csv</programlisting> <para>Looks a bit complicated but lets dissect the things</para> @@ -551,7 +531,7 @@ INFO: Rendered page #2.</programlisting> <para><remark>What specialty with generating shell scripts we want to demonstrate in this example? Is it escaping ${...} maybe? That belongs - to the FreeMarke documentation. But if we still want to show that + to the FreeMarker documentation. But if we still want to show that here, I would recommend using the [=...] interpolation syntax when generating something that already uses ${...}.</remark></para> @@ -564,7 +544,8 @@ INFO: Rendered page #2.</programlisting> 2019-09-27T21:02:54,CCCCCCC,200,0.529013,206 2019-09-27T21:02:54,DDDDDDD,200,0.528268,206</programlisting> - <remark>Can't generate the above...</remark> + <remark>We can't generate the above in Docgen, as curl is might not be + available, or can't fetch remote resource.</remark> </section> <section> @@ -582,11 +563,9 @@ INFO: Rendered page #2.</programlisting> more complex regular expression such as <literal>COMBINEDAPACHELOG</literal>.</para> - <programlisting>> bin/freemarker-generator -t examples/templates/accesslog/combined-access.ftl examples/data/accesslog/combined-access.log</programlisting> - - <para>which gives you the following output:</para> - - <programlisting role="output">[docgen.insertFile "@exampleOutputs/combined-access.log.txt"]</programlisting> + <programlisting>[docgen.insertWithOutput] +freemarker-generator -t [docgen.wd]/examples/templates/accesslog/combined-access.ftl [docgen.wd]/examples/data/accesslog/combined-access.log +[/docgen.insertWithOutput]</programlisting> <para>using the following FreeMarker template:</para> @@ -675,7 +654,7 @@ h3. AWS EC2 Instance <para><remark>Not in runnable examples (see same problem earlier, why that matters). Although, it's next to impossible to make a portable example of this. Question is, what do we want to demonstrate here? Lot - of lines to dig through for the reader, if the point is only + of lines to dig through for the reader, and the point is maybe just <#local output = tools.exec.execute(line)>.</remark></para> </section> @@ -687,27 +666,25 @@ h3. AWS EC2 Instance <literal>jq</literal> or <literal>pup</literal> - in this case you can pass a FreeMarker template in an interactive fashion.</para> - <programlisting>> bin/freemarker-generator -i 'Hello ${tools.system.envs.USER}'; echo -Hello sgoeschl + <programlisting>[docgen.insertWithOutput] +freemarker-generator -i 'Some template here... ${1 + 1}' +[/docgen.insertWithOutput] -> bin/freemarker-generator -i '${tools.jsonpath.parse(dataSources?values[0]).read("$.info.title")}' examples/data/json/swagger-spec.json; echo -Swagger Petstore +[docgen.insertWithOutput] +freemarker-generator -i '${tools.jsonpath.parse(dataSources?values[0]).read("$.info.title")}' [docgen.wd]/examples/data/json/swagger-spec.json +[/docgen.insertWithOutput] -> bin/freemarker-generator -i 'Post Title : ${tools.jsonpath.parse(dataSources?values[0]).read("$.title")}' https://jsonplaceholder.typicode.com/posts/2; echo -Post Title : qui est esse +[docgen.insertWithOutput] +freemarker-generator -i '${tools.xml.parse(dataSources?values[0])["recipients/person[1]/name"]}' [docgen.wd]/examples/data/xml/recipients.xml +[/docgen.insertWithOutput] -> bin/freemarker-generator -i '${tools.xml.parse(dataSources?values[0])["recipients/person[1]/name"]}' examples/data/xml/recipients.xml; echo -John Smith +[docgen.insertWithOutput] +freemarker-generator -i '${tools.jsoup.parse(dataSources?values[0]).select("a")[0]}' [docgen.wd]/examples/data/html/dependencies.html +[/docgen.insertWithOutput]</programlisting> -> bin/freemarker-generator -i '${tools.jsoup.parse(dataSources?values[0]).select("a")[0]}' examples/data/html/dependencies.html; echo -<a href="${project.url}" title="FreeMarker Generator">FreeMarker Generator</a> - -> freemarker-generator -i '<#list tools.system.envs as name,value>${name} ==> ${value}${"\n"}</#list>' -TERM ==> xterm-256color -LANG ==> en_US -DISPLAY ==> :0.0 -SHELL ==> /bin/bash -EDITOR ==> vi</programlisting> + <remark>I have deleted some examples above, as they were problematic + to generate. I think one or two would be enough anyway, as we just + demonstrate -i here.</remark> </section> <section> @@ -720,20 +697,18 @@ EDITOR ==> vi</programlisting> filtering (based on some primary key) and and transforming into a human-readable output format (Markdown).</para> - <para>So lets start the filtering & transformation using the + <para>So lets start the filtering & transformaction using the following command line</para> - <programlisting>> bin/freemarker-generator -e UTF-8 -l de_AT -Pcolumn="Order ID" \ + <programlisting>[docgen.insertWithOutput] +freemarker-generator -e UTF-8 -l de_AT -Pcolumn="Order ID" \ -Pvalues=226939189,957081544 \ - -t examples/templates/csv/md/filter.ftl examples/data/csv/sales-records.csv</programlisting> + -t [docgen.wd]/examples/templates/csv/md/filter.ftl [docgen.wd]/examples/data/csv/sales-records.csv +[/docgen.insertWithOutput]</programlisting> - <para>and Apache FreeMarker template</para> + <para>The FreeMarker template referred was this:</para> <programlisting role="template">[docgen.insertFile "@exampleTemplates/csv/md/filter.ftl"]</programlisting> - - <para>yields</para> - - <programlisting>[docgen.insertFile "@exampleOutputs/sales-records.md"]</programlisting> </section> <section> @@ -742,13 +717,13 @@ EDITOR ==> vi</programlisting> <para>Sometimes we simply need to transform a JSON into an equivalent YAML or the other way around.</para> - <programlisting>> freemarker-generator -t freemarker-generator/yaml/json/transform.ftl examples/data/yaml/swagger-spec.yaml -> freemarker-generator -i '${tools.gson.toJson(tools.yaml.parse(dataSources?values[0]))}' examples/data/yaml/swagger-spec.yaml -> freemarker-generator -i '${tools.gson.toJson(yaml)}' -m yaml=examples/data/yaml/swagger-spec.yaml + <programlisting>[docgen.insertWithOutput]freemarker-generator -t freemarker-generator/yaml/json/transform.ftl [docgen.wd]/examples/data/yaml/swagger-spec.yaml[/docgen.insertWithOutput] +[docgen.insertWithOutput]freemarker-generator -i '${tools.gson.toJson(tools.yaml.parse(dataSources?values[0]))}' [docgen.wd]/examples/data/yaml/swagger-spec.yaml[/docgen.insertWithOutput] +[docgen.insertWithOutput]freemarker-generator -i '${tools.gson.toJson(yaml)}' -m yaml=[docgen.wd]/examples/data/yaml/swagger-spec.yaml[/docgen.insertWithOutput] -> freemarker-generator -t freemarker-generator/json/yaml/transform.ftl examples/data/json/swagger-spec.json -> freemarker-generator -i '${tools.yaml.toYaml(tools.gson.parse(dataSources?values[0]))}' examples/data/json/swagger-spec.json -> freemarker-generator -i '${tools.yaml.toYaml(json)}' -m json=examples/data/json/swagger-spec.json</programlisting> +[docgen.insertWithOutput]freemarker-generator -t freemarker-generator/json/yaml/transform.ftl [docgen.wd]/examples/data/json/swagger-spec.json[/docgen.insertWithOutput] +[docgen.insertWithOutput]freemarker-generator -i '${tools.yaml.toYaml(tools.gson.parse(dataSources?values[0]))}' [docgen.wd]/examples/data/json/swagger-spec.json[/docgen.insertWithOutput] +[docgen.insertWithOutput]freemarker-generator -i '${tools.yaml.toYaml(json)}' -m json=[docgen.wd]/examples/data/json/swagger-spec.json[/docgen.insertWithOutput]</programlisting> </section> <section> @@ -779,21 +754,15 @@ EDITOR ==> vi</programlisting> </listitem> </itemizedlist> - <para>Running</para> - - <programlisting>freemarker-generator -t examples/templates/demo.ftl</programlisting> - - <para>gives you</para> - - <programlisting role="output">[docgen.insertFile "@exampleOutputs/demo.txt" charset="CP1252"]</programlisting> + <programlisting>[docgen.insertWithOutput]freemarker-generator -t [docgen.wd]/examples/templates/demo.ftl[/docgen.insertWithOutput]</programlisting> </section> </section> </chapter> - <chapter> + <chapter xml:id="concepts"> <title>Concepts</title> - <section> + <section xml:id="design-goals"> <title>Design goals</title> <itemizedlist> @@ -879,7 +848,7 @@ EDITOR ==> vi</programlisting> </section> <section xml:id="named-uri"> - <title>Named URI-s</title> + <title xml:id="named-uri">Named URI-s</title> <para>Named URIs allow to identify <literal>DataSource</literal>-s (not a JDBC <literal>DataSource</literal>, <link linkend="datasources">but @@ -947,29 +916,29 @@ EDITOR ==> vi</programlisting> <para>The following Named URI loads a <literal>user.csv</literal> and the data source is available as <literal>my_users</literal>:</para> - <programlisting>[docgen.insertOutput from="FreeMarker Generator DataSources" to=r"^\s*$" printCommand=true] + <programlisting>[docgen.insertWithOutput from="FreeMarker Generator DataSources" to=r"^\s*$"] freemarker-generator -t freemarker-generator/info.ftl my_users=[docgen.wd]/examples/data/csv/user.csv -[/docgen.insertOutput]</programlisting> +[/docgen.insertWithOutput]</programlisting> <para>A Named URI allows to pass additional information as part of the fragment, e.g. the charset of the text file:</para> - <programlisting>[docgen.insertOutput from="FreeMarker Generator DataSources" to=r"^\s*$" printCommand=true] + <programlisting>[docgen.insertWithOutput from="FreeMarker Generator DataSources" to=r"^\s*$"] freemarker-generator -t freemarker-generator/info.ftl my_users=[docgen.wd]/examples/data/csv/user.csv#charset=UTF-16 -[/docgen.insertOutput]</programlisting> +[/docgen.insertWithOutput]</programlisting> <para>In addition to the simplified file syntax full URIs can be used:</para> - <programlisting>[docgen.insertOutput from="FreeMarker Generator DataSources" to=r"^\s*$" printCommand=true] + <programlisting>[docgen.insertWithOutput from="FreeMarker Generator DataSources" to=r"^\s*$"] freemarker-generator -t freemarker-generator/info.ftl https://www.google.com#charset=ISO-8859-1 -[/docgen.insertOutput]</programlisting> +[/docgen.insertWithOutput]</programlisting> <para>and also combined with a name:</para> - <programlisting>[docgen.insertOutput from="FreeMarker Generator DataSources" to=r"^\s*$" printCommand=true] + <programlisting>[docgen.insertWithOutput from="FreeMarker Generator DataSources" to=r"^\s*$"] freemarker-generator -t freemarker-generator/info.ftl page=http://www.google.com#charset=ISO-8859-1 -[/docgen.insertOutput]</programlisting> +[/docgen.insertWithOutput]</programlisting> </section> <section xml:id="datasources"> @@ -1013,45 +982,45 @@ freemarker-generator -t freemarker-generator/info.ftl page=http://www.google.com </simplesect> </section> - <section> + <section xml:id="data-models"> <title>Data Models</title> <para>TODO</para> </section> - <section> + <section xml:id="passing-configuration-data"> <title>Passing Configuration Data</title> <para>TODO</para> </section> - <section> + <section xml:id="template-loading"> <title>Template Loading</title> <para>TODO</para> </section> - <section> + <section xml:id="transformation"> <title>Transformation</title> <para>TODO</para> </section> - <section> + <section xml:id="tools"> <title>Tools</title> <para>TODO</para> </section> </chapter> - <chapter> + <chapter xml:id="usage-details"> <title>Usage details</title> <remark role="editorialNote">In the markdown version this chapter was "Usage", but I though that clashes with "Getting Started" in meaning.</remark> - <section> + <section xml:id="transforming-directories"> <title>Transforming Directories</title> <section> @@ -1074,17 +1043,17 @@ freemarker-generator -t freemarker-generator/info.ftl page=http://www.google.com </section> </chapter> - <chapter> + <chapter xml:id="advanced-topics"> <title>Advanced topics</title> - <section> + <section xml:id="freemarker-cli-configuration"> <title>FreeMarker CLI Configuration</title> <para>TODO</para> </section> </chapter> - <chapter> + <chapter xml:id="appendixes"> <title>Appendixes</title> <section xml:id="download">
