Support reading specification items from AsciiDoc files

[sophokles73]

The Eclipse uProtocol project would like to adopt OpenFastTrace. All of its requirements and design specifications are written in AsciiDoc.

It would be great, if we could keep these files and instead of moving all content to standard Markdown files, teach OpenFastTrace how to retrieve the information from the AsciiDoc content model.

I have already created a prototypical implementation of an AsciiDocImporter based on the asciidoctorj library, which recognizes some custom labels and tags on otherwise standard AsciiDoc blocks and creates SpecificationItems from them.

This approach is a little different from what I have seen in the other Importers which seem to be mostly based on RegEx matching. That is because the asciidoctorj library actually parses the content model of files and provides direct access to parts of the document.

Would you be interested in a PR for adding this functionality?

[redcatbear]

Hi @sophokles73. An AsciiDoc importer would be welcome of course. We are discussing loading that plugin at runtime, since we try to keep the core product free of external libraries (other than the JRE). The current plugin mechanism is not far away from being able to load plugins at startup, so that should be possible.

The reason for the current importer strategy was that this way we did not need to parse the whole file structure and did not need a Markdown library. For RST we did not even have a choice, since all RST libraries we found were not maintained properly.

[sophokles73]

#413 sounds interesting. Would this mean that the AsciiDoc Importer would/should not be contributed to OFT but instead live in a separate project/repo? Or would you rather have it in your code base but do not include it in the fat jar but maybe provide some extra or addon plugins as separate downloads/components?

[sophokles73]

@redcatbear any thoughts?

[redcatbear]

Hi @sophokles73, sorry for the late response. @kaklakariada kept me busy with #416 — that's a pretty substantial PR. :-)

I rolled that thought back and forth in my head.

From our experience software with 3rd-party dependencies is best managed in a separate repository.

The most important part is that it has an independent release cycle. This allows us to quickly do dependency updates and limits the blast radius of changes. It is also a good motivator to keep the core product backward compatible, an art form that imho is not practiced enough anymore these days.

So I suggest we create a new repository openfasttrace-asciidoc-plugin and setup our standard environment there. Later that repo will serve as a template for new plugins. You and your team then directly work on that repository. How does that sound to you?

[sophokles73]

That sounds pretty good to me :+1: Let me know when the new repo is available, I will then create the PR against that repo. Does #413 still require all plugins to be Java Modules? I had quite some difficulties getting this to work because my dependencies are not modules themselves and setting up the module path accordingly etc.

[kaklakariada]

Java modules are not required, if you run OFT using the normal classpath, i.e. "java -jar ...".

I will create the repository on the weekend. Who else needs access?

[sophokles73]

It will be just me (for now) :-)

[kaklakariada]

@sophokles73 I created repo https://github.com/itsallcode/openfasttrace-asciidoc-plugin and added you as a contributor. Once the project setup PR https://github.com/itsallcode/openfasttrace-asciidoc-plugin/pull/3 is merged, you can start development :-)