Markdown, which is currently used for user-facing documentation, is good
for a lot of things. However, it's not great for the kind of complex
documentation we have and our need to produce both multi-page HTML and
single-page PDF output via Maven.
Markdown lacks features which would make the documentation easier to
read, easier to navigate, and just look better overall.
The current tool-chain uses honkit and a tool called Calibre. Honkit is
written in TypeScript and is installed via NPM. Calibre is a native tool
so it must be installed via an OS-specific package manager. All this
complexity makes building, releasing, uploading, etc. a pain.
AsciiDoc is relatively simple like Markdown, but it has more features
for presentation and navigation not to mention Java-based Maven tooling
to generate both HTML and PDF. Migrating will improve both the
appearance of the documentation as well as the processes to generate and
upload it.
This commit contains the following changes:
- Convert all the Markdown for the User Manual, Migration Guide, and
Hacking guide to AsciiDoc via kramdown [1].
- Update the `artemis-website` build to use AsciiDoctor Maven tooling.
- Update `RELEASING.md` with simplified instructions.
- Update Hacking Guide with simplified instructions.
- Use AsciiDoc link syntax in Artemis Maven doc plugin.
- Drop EPUB & MOBI docs for User Manual as well as PDF for the Hacking
Guide. All docs will be HTML only except for the User Manual which
will have PDF.
- Move all docs up out of their respective "en" directory. This was a
hold-over from when we had docs in different languages.
- Migration & Hacking Guides are now single-page HTML since they are
relatively short.
- Refactor README.md to simplify and remove redundant content.
Benefits of the change:
- Much simplified tooling. No more NPM packages or native tools.
- Auto-generated table of contents for every chapter.
- Auto-generated anchor links for every sub-section.
- Overall more appealing presentation.
- All docs will use the ActiveMQ favicon.
- No more manual line-wrapping! AsciiDoc recommends one sentence per
line and paragraphs are separated by a blank line.
- AsciiDoctor plugins for IDEA are quite good.
- Resulting HTML is less than *half* of the previous size.
All previous links/bookmarks should continue to work.
[1] https://github.com/asciidoctor/kramdown-asciidoc
https://issues.apache.org/jira/browse/ARTEMIS-163
On this pass I'm just converting the native layer to a simpler one.
It wasn't very easy to change the alignment at the current framework,
so I did some refactoring simplifying the native layer
The volume of the nubmer of changes here is because:
- The API is changed, we now don't close the libaio queue between files
- The native layer won't use malloc as much as it used to, saving some CPU and memory defragmentation
- I organized the code around nio and libaio
This patch moves test dependencies into out of the main pom and into the
tests module pom. This will make managing 3rd party category X
dependencies much easier going forward. In addition each dependency
license has been outlined in the pom and README entry added to outline
future policy when adding 3rd party depdendencies.
https://issues.apache.org/jira/browse/ACTIVEMQ6-9
The release profile now builds a static html version of the user manual for the web site using gitbook.
Also added a new profile 'distro' that builds the distribution but without the docs.
Updated read me with build process.
https://issues.apache.org/jira/browse/ACTIVEMQ6-3
We are renaming packages from activemq6 to activemq as that's more generic and version independent
The previous commit renamed the directories. On this commit now I'm changing the code.
If we changed the code and the directories on the same commit git would remove and add a lot of files
without recognizing the renames.
Justin Bertram
Robbie Gemmell
Andy Taylor
Paul Wright
Otavio Rodolfo Piske
Jiri Danek
Clebert Suconic
Claus Ibsen
Martyn Taylor
Christian Schneider
Andy Taylor