Switch to Apache Velocity for Custom Layouts

[koppor]

Context

Our layout files are very strange.

• Documentation: https://docs.jabref.org/import-export/export/customexports
• Repository for all layout files: https://github.com/JabRef/layouts.jabref.org
• Directory for all internal layout files: https://github.com/JabRef/jabref/tree/master/src/main/resources/resource/layout
• Example: HTML Export: https://github.com/JabRef/jabref/blob/master/src/main/resources/resource/layout/html.layout
• Example: Simple HTML: https://github.com/JabRef/jabref/blob/master/src/main/resources/resource/layout/simplehtml.layout
• Example: Simple Open Office Export: https://github.com/JabRef/jabref/tree/master/src/main/resources/resource/layout/openoffice

Tasks

Steps:

1. Define new template format (based on Apache Velocity)
2. Implement a template for a simple example
3. Call the template in JabRef (includes JUnit test cases)
4. Iterate steps 1 to 3 until a "good" template language is there
5. Choose a larger example (e.g., convert BibTeX to JSON, manually port existing .layout files)

If possible:

1. Define a converter of existing .layout files to the new format (can be called via the command line)
2. Convert all existing layouts to the new format
3. Delete the old layout formats

Variants

We could keep both the new engine and the old engine in JabRef and gradually migrate to the new one.

Background/Links

Check whether we could switch to some other export engine. Apache Velocity, yeoman-based, ...

See https://github.com/latextemplates/generator-latex-template/blob/master/docs/adr/0001-use-yeoman.md for options for template generators.

See https://github.com/latextemplates/generator-latex-template/blob/master/generators/app/templates/main.de.tex for the Yeoman syntax.

Refs xJREB/swe-research-methods#1 (comment)

---

Velocity was chosen at JabRef#11900.

[Siedlerchr]

Just an additional remark, the keygenerator, OpenOffice/LibreOffice and the custom Preview all rely on our custom bracketed pattern "engine" and on the resulting html.

[koppor]

https://freemarker.apache.org/ seems to be the choice as of today

https://stackoverflow.com/a/1984458/873282 --> Velocity

[Siedlerchr]

Add Thymeleaf as an option https://www.thymeleaf.org/
https://www.thymeleaf.org/faq.html#can-it-non-web

[koppor]

Other example where the language is used:

JabRef/user-documentation#525

It did work for me with this exact regex: [auth:regex("(?<=.\\p{IsLatin})\\b.*|(?<=\\p{IsLatin}{2})\\p{Lu}.*", "")][shortyear]

[jeanprbt]

After doing a bit of research, I found that Thymeleaf was originally designed for web applications, and was particularly better optimized for html than for other text formats. On the other hand, Apache Freemarker seems to be a better alternative because it's not built around web apps and seems to be more versatile. As our use isn't web-related, I wanted to ask you for your opinion. Freemarker's syntax looks pretty easy to get to grips with, and the configuration doesn't seem unusually complex.

https://freemarker.apache.org/ seems to be the choice as of today

https://stackoverflow.com/a/1984458/873282 --> Velocity

Below this conversation there were other arguments in favor of Freemarker.

[koppor]

@jeanprbt To really judge, two minimal examples have to be build. One for each engine

Thymeleaf docs:

There are two markup template modes (HTML and XML), three textual template modes (TEXT, JAVASCRIPT and CSS) and a no-op template mode (RAW).

Source: https://www.thymeleaf.org/doc/tutorials/3.1/usingthymeleaf.html

Thus, I do not follow your argument with "web technologies"

[koppor]

As usual, the main pros and cons should be gathered in a MADR document