From 65b9fcfd2fc5cfbc4040833912ac6016c41e75a3 Mon Sep 17 00:00:00 2001 From: InAnYan Date: Wed, 9 Oct 2024 10:34:03 +0300 Subject: [PATCH 01/12] Add template engine ADR --- docs/decisions/0039-template-engine.md | 74 ++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) create mode 100644 docs/decisions/0039-template-engine.md diff --git a/docs/decisions/0039-template-engine.md b/docs/decisions/0039-template-engine.md new file mode 100644 index 00000000000..54ac3e88252 --- /dev/null +++ b/docs/decisions/0039-template-engine.md @@ -0,0 +1,74 @@ +--- +nav_order: 39 +parent: Decision Records +--- + +# Template engine + +## Context and Problem Statement + +We need to choose a template engine for [custom export filters](https://docs.jabref.org/collaborative-work/export/customexports) and [AI features](https://github.com/JabRef/jabref/pull/11884). + +A discussion of template engines was also in [one of the JabRef repos](https://github.com/koppor/jabref/issues/392). + +A discussion was raised on StackOverflow ["Velocity vs. FreeMarker vs. Thymeleaf"](https://stackoverflow.com/q/1459426/10037342). + +## Decision Drivers + +* It should support different formats, in case JabRef changes in the future. Also, AI features require just plain text manipulation. +* It should have all necessary constructs from programming languages: loops, conditions, variables. It should support list or object (map) variables. +* It should be embeddable and small. AI features require that templates could be generated out of simple `String` type. + +## Considered Options + +* Apache Velocity +* Apache FreeMarker +* Thymeleaf + +## Decision Outcome + +Chosen option: "{title of option 1}", because +{justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force {force} | … | comes out best (see below)}. + +## Pros and Cons of the Options + +### Apache Velocity + +Main page: . +User guide: . +Developer guide: . + +* Good, because supports plain text templating. +* Good, because it is possible to use `String` as a template. +* Good, because it is minimalistic. +* Bad, because {argument d} +* Bad, because not in active development (but support is still available). + +### Apache FreeMarker + +Main page: . +User guide: . +Developer guide: . + +* Good, because supports plain text templating. +* Good, because it is possible to use `String` as a template. +* Good, because in active development. +* Good, because it is powerful and flexible. +* Neutral, because {argument c} +* Bad, because {argument d} + +### Thymeleaf + +Main page: . +Documentation: . + +* Good, because supports plain text templating. +* Good, because it is possible to use `String` as a template. +* Good, because it has [several template modes](https://www.thymeleaf.org/doc/tutorials/3.1/usingthymeleaf.html#what-kind-of-templates-can-thymeleaf-process), that helps to make HTML, XML, and other templates. +* Good, because it is powerful and flexible. +* Neutral, because the API is a bit more complex than the other options. +* Bad, because {argument d} + +## More Information + +As stated in [the template discussion issue](https://github.com/koppor/jabref/issues/392), we should choose a template engine, and then slowly migrate previous code and templates to the chosen engine. From 8d14743a75eb37951599ee7f24768367ac698da8 Mon Sep 17 00:00:00 2001 From: Ruslan Date: Fri, 11 Oct 2024 10:21:30 +0300 Subject: [PATCH 02/12] Update docs/decisions/0039-template-engine.md Co-authored-by: Oliver Kopp --- docs/decisions/0039-template-engine.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/decisions/0039-template-engine.md b/docs/decisions/0039-template-engine.md index 54ac3e88252..c6665215442 100644 --- a/docs/decisions/0039-template-engine.md +++ b/docs/decisions/0039-template-engine.md @@ -17,7 +17,8 @@ A discussion was raised on StackOverflow ["Velocity vs. FreeMarker vs. Thymeleaf * It should support different formats, in case JabRef changes in the future. Also, AI features require just plain text manipulation. * It should have all necessary constructs from programming languages: loops, conditions, variables. It should support list or object (map) variables. -* It should be embeddable and small. AI features require that templates could be generated out of simple `String` type. +* It should be fast. +* It should be possible to provide templates out of Strings (required by the AI feature) ## Considered Options From 88cc4a2aded58672ec720a639b5f46279ecb76e2 Mon Sep 17 00:00:00 2001 From: Ruslan Date: Fri, 11 Oct 2024 10:21:53 +0300 Subject: [PATCH 03/12] Update docs/decisions/0039-template-engine.md Co-authored-by: Oliver Kopp --- docs/decisions/0039-template-engine.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/decisions/0039-template-engine.md b/docs/decisions/0039-template-engine.md index c6665215442..4429eeb77fc 100644 --- a/docs/decisions/0039-template-engine.md +++ b/docs/decisions/0039-template-engine.md @@ -15,7 +15,7 @@ A discussion was raised on StackOverflow ["Velocity vs. FreeMarker vs. Thymeleaf ## Decision Drivers -* It should support different formats, in case JabRef changes in the future. Also, AI features require just plain text manipulation. +* Text output has to be supported. * It should have all necessary constructs from programming languages: loops, conditions, variables. It should support list or object (map) variables. * It should be fast. * It should be possible to provide templates out of Strings (required by the AI feature) From 06a270c6bc26251da76b4155866981af8d4bd1d8 Mon Sep 17 00:00:00 2001 From: Ruslan Date: Fri, 11 Oct 2024 10:23:10 +0300 Subject: [PATCH 04/12] Update docs/decisions/0039-template-engine.md Co-authored-by: Oliver Kopp --- docs/decisions/0039-template-engine.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/decisions/0039-template-engine.md b/docs/decisions/0039-template-engine.md index 4429eeb77fc..19b7fec0a58 100644 --- a/docs/decisions/0039-template-engine.md +++ b/docs/decisions/0039-template-engine.md @@ -43,7 +43,7 @@ Developer guide: * Good, because it is possible to use `String` as a template. * Good, because it is minimalistic. * Bad, because {argument d} -* Bad, because not in active development (but support is still available). +* Bad, because it is in maintenance mode. ### Apache FreeMarker From a2050eddaa4d9e734fee3d77dad6b9cfb740041d Mon Sep 17 00:00:00 2001 From: InAnYan Date: Sat, 12 Oct 2024 14:04:49 +0300 Subject: [PATCH 05/12] Update from code review --- docs/decisions/0039-template-engine.md | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/docs/decisions/0039-template-engine.md b/docs/decisions/0039-template-engine.md index 54ac3e88252..f0d706a7381 100644 --- a/docs/decisions/0039-template-engine.md +++ b/docs/decisions/0039-template-engine.md @@ -16,7 +16,6 @@ A discussion was raised on StackOverflow ["Velocity vs. FreeMarker vs. Thymeleaf ## Decision Drivers * It should support different formats, in case JabRef changes in the future. Also, AI features require just plain text manipulation. -* It should have all necessary constructs from programming languages: loops, conditions, variables. It should support list or object (map) variables. * It should be embeddable and small. AI features require that templates could be generated out of simple `String` type. ## Considered Options @@ -34,21 +33,21 @@ Chosen option: "{title of option 1}", because ### Apache Velocity -Main page: . -User guide: . -Developer guide: . +- Main page: . +- User guide: . +- Developer guide: . * Good, because supports plain text templating. * Good, because it is possible to use `String` as a template. -* Good, because it is minimalistic. +* Good, because it has simple syntax. * Bad, because {argument d} * Bad, because not in active development (but support is still available). ### Apache FreeMarker -Main page: . -User guide: . -Developer guide: . +- Main page: . +- User guide: . +- Developer guide: . * Good, because supports plain text templating. * Good, because it is possible to use `String` as a template. @@ -59,8 +58,8 @@ Developer guide: . ### Thymeleaf -Main page: . -Documentation: . +- Main page: . +- Documentation: . * Good, because supports plain text templating. * Good, because it is possible to use `String` as a template. @@ -72,3 +71,5 @@ Documentation: ## More Information As stated in [the template discussion issue](https://github.com/koppor/jabref/issues/392), we should choose a template engine, and then slowly migrate previous code and templates to the chosen engine. + + From 73fed6d0bbee91680d97db000450d8b0ee10cf32 Mon Sep 17 00:00:00 2001 From: InAnYan Date: Sat, 12 Oct 2024 14:37:48 +0300 Subject: [PATCH 06/12] Add examples --- docs/decisions/0039-template-engine.md | 35 ++++++++++++++++++++++++-- 1 file changed, 33 insertions(+), 2 deletions(-) diff --git a/docs/decisions/0039-template-engine.md b/docs/decisions/0039-template-engine.md index 1010d9ae677..60e73ae5d83 100644 --- a/docs/decisions/0039-template-engine.md +++ b/docs/decisions/0039-template-engine.md @@ -15,9 +15,9 @@ A discussion was raised on StackOverflow ["Velocity vs. FreeMarker vs. Thymeleaf ## Decision Drivers -* Text output has to be supported. * It should be fast. -* It should be possible to provide templates out of Strings (required by the AI feature) +* It should be possible to provide templates out of Strings (required by the AI feature). +* It should have short and understandable syntax. Especially. Work with unset fields and empty Optionals should be easy. ## Considered Options @@ -38,6 +38,16 @@ Chosen option: "{title of option 1}", because - User guide: . - Developer guide: . +Example: +```text +You are an AI assistant that analyses research papers. You answer questions about papers. + +Here are the papers you are analyzing: +#foreach( $entry in $entries ) +${CanonicalBibEntry.getCanonicalRepresentation($entry)} +#end +``` + * Good, because supports plain text templating. * Good, because it is possible to use `String` as a template. * Good, because it has simple syntax. @@ -50,6 +60,15 @@ Chosen option: "{title of option 1}", because - User guide: . - Developer guide: . +```text +You are an AI assistant that analyzes research papers. You answer questions about papers. + +Here are the papers you are analyzing: +<#list entries as entry> +${CanonicalBibEntry.getCanonicalRepresentation(entry)} + +``` + * Good, because supports plain text templating. * Good, because it is possible to use `String` as a template. * Good, because in active development. @@ -62,6 +81,18 @@ Chosen option: "{title of option 1}", because - Main page: . - Documentation: . +Example (not related to AI): +```text +Dear [(${customer.name})], + +This is the list of our products: +[# th:each="p : ${products}"] + - [(${p.name})]. Price: [(${#numbers.formatdecimal(p.price,1,2)})] EUR/kg +[/] +Thanks, + The Thymeleaf Shop +``` + * Good, because supports plain text templating. * Good, because it is possible to use `String` as a template. * Good, because it has [several template modes](https://www.thymeleaf.org/doc/tutorials/3.1/usingthymeleaf.html#what-kind-of-templates-can-thymeleaf-process), that helps to make HTML, XML, and other templates. From 4a06011b6cbd6eac1899b27e274efb329c0ccf00 Mon Sep 17 00:00:00 2001 From: InAnYan Date: Mon, 14 Oct 2024 17:44:39 +0300 Subject: [PATCH 07/12] Update examples --- docs/decisions/0039-template-engine.md | 23 +++++++++++------------ 1 file changed, 11 insertions(+), 12 deletions(-) diff --git a/docs/decisions/0039-template-engine.md b/docs/decisions/0039-template-engine.md index 60e73ae5d83..852fba43f71 100644 --- a/docs/decisions/0039-template-engine.md +++ b/docs/decisions/0039-template-engine.md @@ -15,7 +15,7 @@ A discussion was raised on StackOverflow ["Velocity vs. FreeMarker vs. Thymeleaf ## Decision Drivers -* It should be fast. +* It should be fast. * It should be possible to provide templates out of Strings (required by the AI feature). * It should have short and understandable syntax. Especially. Work with unset fields and empty Optionals should be easy. @@ -39,6 +39,7 @@ Chosen option: "{title of option 1}", because - Developer guide: . Example: + ```text You are an AI assistant that analyses research papers. You answer questions about papers. @@ -51,7 +52,6 @@ ${CanonicalBibEntry.getCanonicalRepresentation($entry)} * Good, because supports plain text templating. * Good, because it is possible to use `String` as a template. * Good, because it has simple syntax. -* Bad, because {argument d} * Bad, because it is in maintenance mode. ### Apache FreeMarker @@ -60,6 +60,8 @@ ${CanonicalBibEntry.getCanonicalRepresentation($entry)} - User guide: . - Developer guide: . +Example: + ```text You are an AI assistant that analyzes research papers. You answer questions about papers. @@ -73,24 +75,21 @@ ${CanonicalBibEntry.getCanonicalRepresentation(entry)} * Good, because it is possible to use `String` as a template. * Good, because in active development. * Good, because it is powerful and flexible. -* Neutral, because {argument c} -* Bad, because {argument d} ### Thymeleaf - Main page: . - Documentation: . -Example (not related to AI): +Example: + ```text -Dear [(${customer.name})], +You are an AI assistant that analyzes research papers. You answer questions about papers. -This is the list of our products: -[# th:each="p : ${products}"] - - [(${p.name})]. Price: [(${#numbers.formatdecimal(p.price,1,2)})] EUR/kg +Here are the papers you are analyzing: +[# th:each="entry : ${entries}"] +[(${CanonicalBibEntry.getCanonicalRepresentation(entry)})] [/] -Thanks, - The Thymeleaf Shop ``` * Good, because supports plain text templating. @@ -98,7 +97,7 @@ Thanks, * Good, because it has [several template modes](https://www.thymeleaf.org/doc/tutorials/3.1/usingthymeleaf.html#what-kind-of-templates-can-thymeleaf-process), that helps to make HTML, XML, and other templates. * Good, because it is powerful and flexible. * Neutral, because the API is a bit more complex than the other options. -* Bad, because {argument d} +* Bad, because the syntax is more complex than the other options. Especially for text output. ## More Information From 174410de6f62400e8dfd14f15673176e30f7b4e2 Mon Sep 17 00:00:00 2001 From: InAnYan Date: Sun, 20 Oct 2024 17:18:26 +0300 Subject: [PATCH 08/12] Update from code review --- docs/decisions/0039-template-engine.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/decisions/0039-template-engine.md b/docs/decisions/0039-template-engine.md index 852fba43f71..42862d424b5 100644 --- a/docs/decisions/0039-template-engine.md +++ b/docs/decisions/0039-template-engine.md @@ -51,7 +51,8 @@ ${CanonicalBibEntry.getCanonicalRepresentation($entry)} * Good, because supports plain text templating. * Good, because it is possible to use `String` as a template. -* Good, because it has simple syntax. +* Good, because it has simple syntax and it is designed for simple template workflows. +* Good, because it has a stable syntax ([source](https://stackoverflow.com/a/1984458/10037342)). * Bad, because it is in maintenance mode. ### Apache FreeMarker @@ -75,6 +76,9 @@ ${CanonicalBibEntry.getCanonicalRepresentation(entry)} * Good, because it is possible to use `String` as a template. * Good, because in active development. * Good, because it is powerful and flexible. +* Good, because it has extensive documentation ([source](https://stackoverflow.com/a/1984458/10037342)). +* Neutral, because it has received some API and syntax changes recently ([source](https://stackoverflow.com/a/1984458/10037342)). +* Neutral, because FreeMarker is used for complex template workflow, which we do not need in JabRef. ### Thymeleaf From ccff125e427647b2325902a84c62bedaba76ae89 Mon Sep 17 00:00:00 2001 From: InAnYan Date: Wed, 23 Oct 2024 15:55:00 +0300 Subject: [PATCH 09/12] Fix wording --- docs/decisions/0039-template-engine.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/decisions/0039-template-engine.md b/docs/decisions/0039-template-engine.md index 42862d424b5..07148806727 100644 --- a/docs/decisions/0039-template-engine.md +++ b/docs/decisions/0039-template-engine.md @@ -16,8 +16,8 @@ A discussion was raised on StackOverflow ["Velocity vs. FreeMarker vs. Thymeleaf ## Decision Drivers * It should be fast. -* It should be possible to provide templates out of Strings (required by the AI feature). -* It should have short and understandable syntax. Especially. Work with unset fields and empty Optionals should be easy. +* It should be possible to provide templates out of `String`s (required by the AI feature). +* It should have short and understandable syntax. Especially, it should work well with unset fields and empty `Optional`s. ## Considered Options @@ -27,8 +27,7 @@ A discussion was raised on StackOverflow ["Velocity vs. FreeMarker vs. Thymeleaf ## Decision Outcome -Chosen option: "{title of option 1}", because -{justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force {force} | … | comes out best (see below)}. +Chosen option: "", because ## Pros and Cons of the Options @@ -51,7 +50,7 @@ ${CanonicalBibEntry.getCanonicalRepresentation($entry)} * Good, because supports plain text templating. * Good, because it is possible to use `String` as a template. -* Good, because it has simple syntax and it is designed for simple template workflows. +* Good, because it has simple syntax, and it is designed for simple template workflows. * Good, because it has a stable syntax ([source](https://stackoverflow.com/a/1984458/10037342)). * Bad, because it is in maintenance mode. From 90aff35794cf922c1834b00852a7eaeb99744fc2 Mon Sep 17 00:00:00 2001 From: InAnYan Date: Wed, 23 Oct 2024 15:59:25 +0300 Subject: [PATCH 10/12] Add chosen option --- docs/decisions/0039-template-engine.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/decisions/0039-template-engine.md b/docs/decisions/0039-template-engine.md index 07148806727..e57ad30905a 100644 --- a/docs/decisions/0039-template-engine.md +++ b/docs/decisions/0039-template-engine.md @@ -27,7 +27,9 @@ A discussion was raised on StackOverflow ["Velocity vs. FreeMarker vs. Thymeleaf ## Decision Outcome -Chosen option: "", because +Chosen option: "Apache Velocity", because "Velocity's goal is to keep templates as simple as possible" ([source](https://stackoverflow.com/a/1984458/873282)). It is sufficient for our use case. + +Also, Apache Velocity is lightweight, and it allows to generate text output. This is a good fit for the AI feature. ## Pros and Cons of the Options From bf9c5b0284c459b0d5bebc21f3a76d0c9db34431 Mon Sep 17 00:00:00 2001 From: InAnYan Date: Wed, 23 Oct 2024 16:00:07 +0300 Subject: [PATCH 11/12] Add chosen option --- ...engine.md => 0039-use-apache-velocity-as-template-engine.md} | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename docs/decisions/{0039-template-engine.md => 0039-use-apache-velocity-as-template-engine.md} (99%) diff --git a/docs/decisions/0039-template-engine.md b/docs/decisions/0039-use-apache-velocity-as-template-engine.md similarity index 99% rename from docs/decisions/0039-template-engine.md rename to docs/decisions/0039-use-apache-velocity-as-template-engine.md index e57ad30905a..68990d94ba9 100644 --- a/docs/decisions/0039-template-engine.md +++ b/docs/decisions/0039-use-apache-velocity-as-template-engine.md @@ -3,7 +3,7 @@ nav_order: 39 parent: Decision Records --- -# Template engine +# Use Apache Velocity as template engine ## Context and Problem Statement From c4218331286a0a523d4245fb6b525357b15b1e9e Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Wed, 23 Oct 2024 18:04:22 +0200 Subject: [PATCH 12/12] Remove blank line --- docs/decisions/0039-use-apache-velocity-as-template-engine.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/decisions/0039-use-apache-velocity-as-template-engine.md b/docs/decisions/0039-use-apache-velocity-as-template-engine.md index 68990d94ba9..5e6ca8d1072 100644 --- a/docs/decisions/0039-use-apache-velocity-as-template-engine.md +++ b/docs/decisions/0039-use-apache-velocity-as-template-engine.md @@ -28,8 +28,7 @@ A discussion was raised on StackOverflow ["Velocity vs. FreeMarker vs. Thymeleaf ## Decision Outcome Chosen option: "Apache Velocity", because "Velocity's goal is to keep templates as simple as possible" ([source](https://stackoverflow.com/a/1984458/873282)). It is sufficient for our use case. - -Also, Apache Velocity is lightweight, and it allows to generate text output. This is a good fit for the AI feature. +Furthermore, Apache Velocity is lightweight, and it allows to generate text output. This is a good fit for the AI feature. ## Pros and Cons of the Options