Skip to content
Snippets Groups Projects
  • Albert Gräf's avatar
    bd7682b8
    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
    History
    Add document generation for ReadMe.html and Welcome.html.
    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.