Skip to content

Add document generation for ReadMe.html and Welcome.html

Albert Gräf requested to merge aggraef/purr-data:gendoc into master

These two are now generated from Markdown source, using awk for preprocessing (macro substitution and selection of OS-dependent sections) and pandoc for formatting. A nice-looking GH-style-alike style sheet is also included. All this stuff including the Markdown source can be found in packages/gendoc.

This replaces the jumble of echo commands in the packages/Makefile which was hardly maintainable and produced subpar results. The content of the ReadMe document was outdated as well, so I updated it.

The main advantages are that it is now much easier to edit these documents (simply edit the Markdown source in gendoc/ReadMe.md and gendoc/Welcome.md), replacement of version numbers and OS-dependent information is automatically performed by the awk script, and the resulting html documents produced with pandoc look much better.

I consider this important, since these documents (especially ReadMe.html) are pretty much the first bits of Purr Data related documentation the user sees when installing the package, on Mac and Windows at least where they are prominently featured during the installation. If ReadMe.html then looks like some webpage from the 1990s, with information that is hopelessly outdated, that doesn't make for a great onboarding experience. The new system solves this problem.

The only downside that I see is that this requires special tools, awk and pandoc. Awk is readily available on all platforms we support, but pandoc must be installed in the runners. Fortunately, pandoc is available from both Homebrew and MacPorts. For Windows there is a package from the upstream website which works in msys2 just fine, if PATH is set up accordingly. On Arch and Debian/Ubuntu, pandoc is readily available in the official package repositories. So this shouldn't be a big issue.

Merge request reports