Documentation maintenance enhancement adding Jamal to the documentation toolset
[ ] Bug fix
[ ] New non-breaking feature
[ ] New breaking feature
[X] Documentation update
[X] Build improvement
Description
Goal
Adding this change to the build process, the documentation will automatically fetch and use the latest release.
Later the tool use can be gradually extended to reduce documentation and code redundancy, automatically pulling information from the documented source code into the documentation.
The pull request
adds Jamal as a test dependency to the toolset and
contains a test that converts the new README.adoc.jam file into README.adoc.
It also moved the content of the README.adoc to README.adoc.jam and extended it with macros to fetch the versions automatically when the documentation is processed while editing in IntelliJ/AsciidocFX or during the build.
An alternative way could be to write some specific test that updates the documentation, but Jamal does it, and it is a powerful framework for the very purpose. I do not know any professional alternative. It is also possible to keep editing the pure Asciidoc without macros and invest the manual effort to keep the version numbers and other features in the documentation up to date, which was unsuccessful.
Adding this pull request will require document editors to know a bit of Jamal, which complicates the markup being a hyper markup above the Asciidoc markup.
Documentation maintenance enhancement adding Jamal to the documentation toolset
Description
Goal
Adding this change to the build process, the documentation will automatically fetch and use the latest release. Later the tool use can be gradually extended to reduce documentation and code redundancy, automatically pulling information from the documented source code into the documentation.
The pull request
README.adoc.jamfile intoREADME.adoc.README.adoctoREADME.adoc.jamand extended it with macros to fetch the versions automatically when the documentation is processed while editing in IntelliJ/AsciidocFX or during the build.An alternative way could be to write some specific test that updates the documentation, but Jamal does it, and it is a powerful framework for the very purpose. I do not know any professional alternative. It is also possible to keep editing the pure Asciidoc without macros and invest the manual effort to keep the version numbers and other features in the documentation up to date, which was unsuccessful.
Adding this pull request will require document editors to know a bit of Jamal, which complicates the markup being a hyper markup above the Asciidoc markup.
Release notes
Documentation processing is extended using Jamal.