ERPUI-001: AsciiDoc for Text Fields

ERPUI-001 Asciidoc for Text Fields

Date: 2021-06-01




Asciidoc is a well-established approach to write rich text documentation or comments. The casual user can learn and use the notation without excessive effort. The legibility and professional appearance of asciidoc texts are striking higher than plain text. Asciidoc is an open standard and used in various environments and tools [1].


All texts and comments in the ERP components shall use Asciidoc notation to improve legibility.

Alternatives would be proprietary formats such as Microsoft Word or similar notations such as Markdown. Our open-source approach to product development rejects any proprietary formats. Asciidoc is a very powerful and successful format [2]. The associated complexity for the users is probably an overkill for casual users of our product.

Text and comments in our system should have a limited length complexity. Activity description can be lengthy and use more complex syntax. Asciidoc is an optimal balance between expression power and ease of use.


Asciidoc is backward compatible with text fields. No migration of existing records is needed.

The user interface components shall be extended to support a Asciidoc visualization and editing component. Vaadin currently does not provide native support for Asciidoc or Markdown. The tangly-os components will be extended to provide such a component until Vaadin supports in the future such an approach.

1. The alternative would be to use Markdown notation. The expression power of Asciidoc is higher and better standardized.
2. The team acknowledged we have a preference for Asciidoc. We use the notation for all our architecture documents based on the arc42 template.