Skip to content
Snippets Groups Projects
  1. Aug 10, 2022
    • Albert Gräf's avatar
      Add document generation for ReadMe.html and Welcome.html. · bd7682b8
      Albert Gräf authored
      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.
      bd7682b8
Loading