Skip to content
Snippets Groups Projects
Commit bd7682b8 authored by Albert Gräf's avatar Albert Gräf
Browse files

Add document generation for ReadMe.html and Welcome.html.

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 at https://pandoc.org/installing.html
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.
parent 3e47ff87
No related branches found
No related tags found
1 merge request!835Add document generation for ReadMe.html and Welcome.html
Loading
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment