Render graphics in the manual

[fricklerhandwerk]

Problem

We want to add graphs and illustrations to the manual to better explain concepts and mechanisms.
Make a setup to declare and maintain graphics to be displayed in the manual.

Requirements

• The manual is rendered for the web and the terminal from the same source
  • There must either be a terminal representation for the graphics, or a transparent way of not displaying them (without artifacts such as "The following diagram shows...")
  • The web representation should be static, i.e. not require JavaScript to display correctly
• The setup must allow displaying diffs and previews conveniently
  • The interface should ideally be text-based and declarative, or require additional tools that are well-supported and easy to learn and use
• The number of required manipulations outside making the actual changes to the graphics should me minimal, ideally zero
• The closure size for building the manual should be considered and kept minimal

Based on prior discussion by the Nix team..

Alternatives considered

• Graphviz
  • (+) well-known and supported
  • (+) text-based declarative input format
  • (+) outputs SVG and other image formats
  • (+) support for ASCII output via GraphEasy (example on StackOverflow) (Perl)
  • (+) C/C++ (Python in nativeBuildInputs)
• Mermaid
  • (+) good preview support in modern tooling
    • (+) automatically renders on GitHub markdown
  • (+) well-documented
  • (-) requires JavaScript to display output without pre-processing
    • (+) image output possible
  • (-) requires JavaScript in the build closure
  • (-) no ASCII output
• PlantUML
  • (+) well-documented and supported
  • (+) text-based
  • (+/-) supports ASCII output, but only for sequence diagrams
• Plain SVG
  • (+) text-based format
    • (-) diffs are unreadable for all but the most trivial graphics
  • (-) very cumbersome to get right manually
  • (-) external tooling usually produces verbose output
• Plain ASCII
  • (+) WYSIWYG, everywhere
  • (+) diffs are obvious
  • (-) tedious to get right manually
  • (-) looks clunky on the web
    • (+) can be converted to SVG with svgbob
      • (-) requires abiding to a bespoke, largely undocumented syntax

        It's like markdown brought to its bitter conclusion.

      • (-) requires Rust in the build closure

Priorities

Add 👍 to issues you find important.