README: add one.

diff --git a/README b/README
new file mode 100644 (file)
index 0000000..7df72d2
--- /dev/null
+++ b/README
@@ -0,0 +1,90 @@
+== Overview ==
+
+This package builds a GDK Pixbuf Loader for the SVG format that uses
+libsvgtiny:
+
+  https://www.netsurf-browser.org/projects/libsvgtiny/
+
+Why? I'm glad you asked!
+
+GTK (https://www.gtk.org/) is a toolkit that powers many modern
+desktop environments and applications. GTK uses an abstraction called
+a GdkPixbuf for all of its images. When GTK wants to display an icon,
+it first loads that icon into a GdkPixbuf before displaying the result
+on the screen. GTK itself knows how to import many common formats like
+PNG and JPEG into a GdkPixbuf and can handle those formats
+out-of-the-box. The programs that handle the importing of the various
+formats are called "pixbuf loaders."
+
+Problem: GTK doesn't know the size of your screen, but it needs to
+display icons and images at an appropriate size. How big is that? Good
+question: nobody knows. For that reason, GTK makes heavy use of
+Scalable Vector Graphics (SVGs). It's much wiser to store one SVG and
+scale it to the desired size -- once you know what that is -- than it
+would be to store multiple copies of a non-scalable image at each of
+the sizes you might need. But, as you may have guessed, GTK itself
+doesn't know how to import an SVG into a GdkPixbuf. It doesn't come
+with the corresponding pixbuf loader.
+
+The blessed solution to this problem is to use librsvg:
+
+  https://wiki.gnome.org/Projects/LibRsvg
+
+That package builds a pixbuf loader that can be plugged into GTK,
+allowing it to import SVG files into a GdkPixbuf, and everything is
+great. Until January 3rd, 2017. On that day, librsvg-2.41.0 became the
+only dependency of GTK that requires Rust, which in turn requires
+LLVM. The rest of GTK (and its dependencies) are written in C or
+C++. This has several downsides:
+
+  * Rust is big and slow to compile
+  * LLVM is big and slow to compile
+  * Rust is far less portable than C; it doesn't run on as many CPUs
+  * The Rust ecosystem ironically burdens you with easily-avoidable
+    security vulnerabilities [0].
+
+It's not feasible to keep the old librsvg around forever, because that
+will *also* result in security vulnerabilities. Which brings us to...
+
+== Why ==
+
+Because if you have a problem with any of the bullet points above,
+then you need to replace librsvg if you want to keep using GTK. And,
+
+  * libsvgtiny is written in portable C
+  * libsvgtiny is actively maintained
+  * libsvgtiny is already packaged on a few distributions as part of the
+    netsurf browser
+
+== Caveats ==
+
+This is a REPLACEMENT for librsvg, and cannot be used alongside it
+(the filenames and mimetypes clash).
+
+The main downside is that libsvgtiny isn't as robust as librsvg. It
+renders some things wrong, or a bit uglier than its counterpart. These
+are in theory all fixable upstream however, and you will help the
+netsurf browser by doing so. Regardless, it more or less works.
+
+== Components ==
+
+This package builds three things:
+
+ 1. The pixbuf loader, libpixbufloader-svg.so. It's a shared library
+    that should be installed in your GDK_PIXBUF_MODULEDIR. Afterwards,
+    you have to run "gdk-pixbuf-query-loaders --update-cache" to tell
+    GTK about it.
+
+  2. A GTK thumbnailer entry, libsvgtiny.thumbnailer, that tells GTK
+     how to create thumbnails of SVG images. (Spoiler: we just run
+     gdk-pixbuf-thumbnailer.)
+
+  3. A test program, svg2png, that converts an SVG to a PNG. It does
+     this by loading an SVG into a pixbuf, and then saving that pixbuf
+     as a PNG. **It uses the pixbuf loaders from the live filesystem**
+     so you have to install libpixbufloader-svg.so and update the
+     loader cache before svg2png will use it.
+
+== References ==
+
+  [0] https://blogs.gentoo.org/mgorny/2021/02/19/the-modern-packagers-security-nightmare/