Merge branch 'docs-to-devel-guide' into 'main'

Move most of the Markdown documents to the development guide

See merge request GNOME/librsvg!783

12 files changed, 1434 insertions, 1022 deletions

diff --git a/COMPILING.md b/COMPILING.md
deleted file mode 100644
index bee25518..00000000
--- a/COMPILING.md
+++ /dev/null
@@ -1,352 +0,0 @@
-Compiling librsvg
-=================
-
-**For the impatient:**
-
-First, install librsvg's dependencies; see ["Installing dependencies for
-building"](#installing-dependencies-for-building) below for
-instructions for various operating systems.
-
-For everyday hacking, librsvg looks like a regular Rust project.  You
-can `cargo build` to compile the main user-visible artifact for the
-`rsvg-convert` program:
-
-* `cargo build --release` - will compile `rsvg-convert` and put it in
-  `./target/release/rsvg-convert`.  You can use that binary directly.
-  If you need a debug build, use `cargo build --debug` instead; note
-  that debug binaries run *much* slower!
-
-* `cargo test` - this runs almost all of librsvg's test suite, which
-  includes the Rust API and `rsvg-convert`, and is enough for regular
-  hacking.  The full test suite includes tests for the C API; see the
-  section "Compiling the C API" below.
-
-* `cargo doc` - will produce the documentation for the Rust crate.
-
-# Installing dependencies for building
-
-To compile librsvg, you need the following packages installed.  The
-minimum version is listed here; you may use a newer version instead.
-
-**Compilers:**
-
-* a C compiler and `make` tool; we recommend GNU `make`.
-* rust 1.63 or later
-* cargo
-
-**Mandatory dependencies:**
-
-* Cairo 1.16.0 with PNG support
-* Freetype2 2.8.0
-* Gdk-pixbuf 2.20.0
-* GIO 2.24.0
-* GObject-Introspection 0.10.8
-* gi-docgen
-* python3-docutils
-* Libxml2 2.9.0
-* Pango 1.46.0
-
-The following sections describe how to install these dependencies on
-several systems.
-
-### Debian based systems
-
-As of 2018/Feb/22, librsvg cannot be built in `debian stable` and
-`ubuntu 18.04`, as they have packages that are too old.
-
-**Build dependencies on Debian Testing or Ubuntu 18.10:**
-
-```sh
-apt-get install -y gcc make rustc cargo \
-automake autoconf libtool gi-docgen python3-docutils git \
-libgdk-pixbuf2.0-dev libgirepository1.0-dev \
-libxml2-dev libcairo2-dev libpango1.0-dev
-```
-
-Additionally, as of September 2018 you need to add `gdk-pixbuf` utilities to your path, see #331 for more.
-
-```sh
-PATH="$PATH:/usr/lib/x86_64-linux-gnu/gdk-pixbuf-2.0"
-```
-
-### Fedora based systems
-
-```sh
-dnf install -y gcc rust rust-std-static cargo make \
-automake autoconf libtool gi-docgen python3-docutils git redhat-rpm-config \
-gdk-pixbuf2-devel gobject-introspection-devel \
-libxml2-devel cairo-devel cairo-gobject-devel pango-devel
-```
-
-### openSUSE based systems
-
-```sh
-zypper install -y gcc rust rust-std cargo make \
-automake autoconf libtool python3-gi-docgen python38-docutils git \
-gdk-pixbuf-devel gobject-introspection-devel \
-libxml2-devel cairo-devel pango-devel
-```
-
-### macOS systems
-
-Dependencies may be installed using [Homebrew](https://brew.sh) or another
-package manager.
-
-```sh
-brew install automake gi-docgen pkgconfig libtool gobject-introspection gdk-pixbuf pango
-```
-
-# Detailed compilation instructions
-
-A full build of librsvg requires [autotools].  A full build will produce these:
-
-* `rsvg-convert` binary.
-* librsvg shared library with the GObject-based API.
-* Gdk-pixbuf loader for SVG files.
-* HTML documentation for the GObject-based API, with `gi-docgen`.
-* GObject-introspection information for language bindings.
-* Vala language bindings.
-
-Librsvg uses a mostly normal [autotools] setup.  The details of how
-librsvg integrates Cargo and Rust into its autotools setup are
-described in [this blog post][blog], although hopefully you will not
-need to refer to it.
-
-It is perfectly fine to [ask the maintainer][maintainer] if you have
-questions about the Autotools setup; it's a tricky bit of machinery,
-and we are glad to help.
-
-There are generic compilation/installation instructions in the
-[`INSTALL`][install] file, which comes from Autotools.  The following
-explains librsvg's peculiarities.
-
-* [Basic compilation instructions](#basic-compilation-instructions)
-* [Verbosity](#verbosity)
-* [Debug or release builds](#debug-or-release-builds)
-* [Selecting a Rust toolchain](#selecting-a-rust-toolchain)
-* [Cross-compilation](#cross-compilation)
-* [Building with no network access](#building-with-no-network-access)
-* [Running `make distcheck`](#running-make-distcheck)
-
-# Basic compilation instructions
-
-If you are compiling a tarball:
-
-```sh
-./configure --enable-vala
-make
-make install
-```
-
-See the [`INSTALL`][install] file for details on options you can pass
-to the `configure` script to select where to install the compiled
-library.
-
-If you are compiling from a git checkout:
-
-```sh
-./autogen.sh --enable-vala
-make
-make install
-```
-
-The `--enable-vala` argument is optional.  It will check that you have
-the Vala compiler installed.
-
-# Verbosity
-
-By default the compilation process is quiet, and it just tells you
-which files it is compiling.
-
-If you wish to see the full compilation command lines, use "`make V=1`"
-instead of plain "`make`".
-
-# Debug or release builds
-
-Librsvg's artifacts have code both in C and Rust, and each language
-has a different way of specifying compilation options to select
-compiler optimizations, or whether debug information should be
-included.
-
-* **Rust code:** the librsvg shared library, and the `rsvg-convert`
-  binary.  See below.
-
-* **C code:** the gdk-pixbuf loader; you should set the `CFLAGS`
-  environment variable with compiler flags that you want to pass to
-  the C compiler.
-
-## Controlling debug or release mode for Rust
-
-* With a `configure` option: `--enable-debug` or `--disable-debug`
-* With an environment variable: `LIBRSVG_DEBUG=yes` or `LIBRSVG_DEBUG=no`
-
-For the Rust part of librsvg, we have a flag that
-you can pass at `configure` time.  When enabled, the Rust
-sub-library will have debugging information and no compiler
-optimizations.  **This flag is off by default:** if the flag is not
-specified, the Rust sub-library will be built in release mode (no
-debug information, full compiler optimizations).
-
-The rationale is that people who already had scripts in place to build
-binary packages for librsvg, generally from release tarballs, are
-already using conventional machinery to specify C compiler options,
-such as that in RPM specfiles or Debian source packages.  However,
-they may not contemplate Rust libraries and they will certainly
-not want to modify their existing packaging scripts too much.
-
-So, by default, the Rust library builds in **release mode**, to make
-life easier to binary distributions.  Librsvg's build scripts will add
-`--release` to the Cargo command line by default.
-
-Developers can request a debug build of the Rust code by
-passing `--enable-debug` to the `configure` script, or by setting the
-`LIBRSVG_DEBUG=yes` environment variable before calling `configure`.
-This will omit the `--release` option from Cargo, so that it will
-build the Rust sub-library in debug mode.
-
-In case both the environment variable and the command-line option are
-specified, the command-line option overrides the env var.
-
-# Selecting a Rust toolchain
-
-By default, the configure/make steps will use the `cargo` binary that
-is found in your `$PATH`.  If you have a system installation of Rust
-and one in your home directory, or for special build systems, you may
-need to override the locations of `cargo` and/or `rustc`.  In this
-case, you can set any of these environment variables before running
-`configure` or `autogen.sh`:
-
-* `RUSTC` - path to the `rustc` compiler
-* `CARGO` - path to `cargo`
-
-Note that `$RUSTC` only gets used in the `configure` script to ensure
-that there is a Rust compiler installed with an appropriate version.
-The actual compilation process just uses `$CARGO`, and assumes that
-that `cargo` binary will use the same Rust compiler as the other
-variable.
-
-# Cross-compilation
-
-If you need to cross-compile librsvg, specify the `--host=TRIPLE` to
-the `configure` script as usual with Autotools.  This will cause
-librsvg's build scripts to automatically pass `--target=TRIPLE` to
-`cargo`.
-
-Note, however, that Rust may support different targets than the C
-compiler on your system.  Rust's supported targets can be found in the
-[rustc manual](https://doc.rust-lang.org/nightly/rustc/platform-support.html)
-
-You can check Jorge Aparicio's [guide on cross-compilation for
-Rust][rust-cross] for more details.
-
-## Overriding the Rust target name
-
-If you need `cargo --target=FOO` to obtain a different value from the
-one you specified for `--host=TRIPLE`, you can use the `RUST_TARGET`
-variable, and this will be passed to `cargo`.  For example,
-
-```sh
-RUST_TARGET=aarch64-unknown-linux-gnu ./configure --host=aarch64-buildroot-linux-gnu
-# will run "cargo --target=aarch64-unknown-linux-gnu" for the Rust part
-```
-
-## Cross-compiling to a target not supported by Rust out of the box
-
-When building with a target that is not supported out of the box by
-Rust, you have to do this:
-
-1. Create a [target JSON definition file][target-json].
-
-2. Set the environment variable `RUST_TARGET_PATH` to its directory
-   for the `make` command.
-
-Example:
-
-```sh
-cd /my/target/definition
-echo "JSON goes here" > MYMACHINE-VENDOR-OS.json
-cd /source/tree/for/librsvg
-./configure --host=MYMACHINE-VENDOR-OS
-make RUST_TARGET_PATH=/my/target/definition
-```
-
-## Cross-compiling for win32 target
-
-You can also cross-compile to win32 (Microsoft Windows) target by using
-[MinGW-w64][mingw-w64]. You need to specify the appropriate target in the same way
-as usual:
-
-* Set an appropriate target via the `--host` configure option:
-    * `i686-w64-mingw32` for 32-bit target
-    * `x86_64-w64-mingw32` for 64-bit target
-* Set an appropriate RUST_TARGET:
-    * `i686-pc-windows-gnu` for 32-bit target
-    * `x86_64-pc-windows-gnu` for 64-bit target
-
-In addition you may need to link with some win32 specific libraries like
-`LIBS="-lws2_32 -luserenv"`.
-
-Example:
-
-```sh
-./configure \
-  --host=x86_64-w64-mingw32 \
-  RUST_TARGET=x86_64-pc-windows-gnu \
-  LIBS="-lws2_32 -luserenv"
-make
-```
-
-The most painful aspect of this way of building is preparing a win32
-build for each of librsvg's dependencies. [MXE][mxe] may help you on
-this work.
-
-
-
-# Building with no network access
-
-Automated build systems generally avoid network access so that they
-can compile from known-good sources, instead of pulling random updates
-from the net every time.  However, normally Cargo likes to download
-dependencies when it first compiles a Rust project.
-
-We use [`cargo vendor`][cargo-vendor] to ship librsvg release tarballs
-with the source code for Rust dependencies **embedded within the
-tarball**.  If you unpack a librsvg tarball, these sources will appear
-in the `vendor/` subdirectory.  If you build librsvg from a
-tarball, instead of git, it should not need to access the network to
-download extra sources at all.
-
-Build systems can use [Cargo's source replacement
-mechanism][cargo-source-replacement] to override the location of the
-source code for the Rust dependencies, for example, in order to patch
-one of the Rust crates that librsvg uses internally.
-
-The source replacement information is in `rust/.cargo/config` in the
-unpacked tarball.  Your build system can patch this file as needed.
-
-# Running `make distcheck`
-
-The `make distcheck` command will built a release tarball, extract it,
-compile it and test it.  However, part of the `make install` process
-within that command will try to install the gdk-pixbuf loader in your
-system location, and it will fail.
-
-Please run `make distcheck` like this:
-
-```
-$ make distcheck DESTDIR=/tmp/foo
-```
-
-That `DESTDIR` will keep the gdk-pixbuf loader installation from
-trying to modify your system locations.
-
-[autotools]: https://autotools.io/index.html
-[blog]: https://people.gnome.org/~federico/blog/librsvg-build-infrastructure.html
-[maintainer]: README.md#maintainers
-[install]: INSTALL
-[cargo-vendor]: https://crates.io/crates/cargo-vendor
-[cargo-source-replacement]: http://doc.crates.io/source-replacement.html
-[rust-cross]: https://github.com/japaric/rust-cross
-[target-json]: https://github.com/japaric/rust-cross#target-specification-files
-[mingw-w64]: https://mingw-w64.org/
-[mxe]: https://mxe.cc/
diff --git a/FEATURES.md b/FEATURES.md
deleted file mode 100644
index 9e9570ea..00000000
--- a/FEATURES.md
+++ /dev/null
@@ -1,449 +0,0 @@
-# SVG and CSS features that librsvg supports
-
-Table of contents:
-
-[[_TOC_]]
-
-Librsvg tries to be a mostly complete renderer for SVG1.1 and SVG2.
-
-In terms of processing external references, librsvg is a bit more
-strict than SVG's "static mode" and a bit more lenient than "secure
-static mode".  See "Security and locations of referenced files" in the
-reference documentation for details.
-
-Animation, interactivity, and scripting are not supported.
-
-The SVG1.2 specification never made it past draft status in the W3C's
-process, and librsvg does not support it.  Note that SVG2 removed some
-of the features proposed for SVG1.2.
-
-Generally, librsvg tries to keep up with features in the SVG2
-Candidate Recommendation spec.  It ignores features in the SVG2
-drafts that are not finalized yet.
-
-Alternative versions of SVG (SVG Tiny, SVG Basic, [SVG
-Native](https://gitlab.gnome.org/GNOME/librsvg/-/issues/689)) are not
-explicitly supported.  Their features which are a subset of SVG1.1 or
-SVG2 are supported if they are equivalent to the ones listed below.
-
-SVG2 offloads many of its features to the family of CSS3
-specifications.  Librsvg does not try to support them exhaustively
-(there are too many features in CSS!).  Instead, we try to prioritize
-new features based on the needs which people express in librsvg's bug
-tracker.  Do you want a feature?  [File an
-issue](https://gitlab.gnome.org/GNOME/librsvg/issues)!
-
-# Attributes supported by all elements
-
-| Attribute          | Notes                                                                               |
-| ---                | ---                                                                                 |
-| class              |                                                                                     |
-| id                 |                                                                                     |
-| requiredExtensions | Used in children of the `switch` element.                                           |
-| requiredFeatures   | Used in children of the `switch` element.                                           |
-| systemLanguage     | Used in children of the `switch` element.                                           |
-| style              |                                                                                     |
-| transform          | The `transform` attribute has a different syntax than the CSS `transform` property. |
-| xml:lang           |                                                                                     |
-| xml:space          |                                                                                     |
-
-# Elements and their specific attributes
-
-| Element             | Attributes          | Notes                                                              |
-| ---                 | ---                 | ---                                                                |
-| a                   |                     |                                                                    |
-|                     | xlink:href          | Needs xlink namespace                                              |
-|                     | href                | SVG2                                                               |
-| circle              |                     |                                                                    |
-|                     | cx                  |                                                                    |
-|                     | cy                  |                                                                    |
-|                     | r                   |                                                                    |
-| clipPath            |                     |                                                                    |
-|                     | clipPathUnits       |                                                                    |
-| defs                |                     |                                                                    |
-| ellipse             |                     |                                                                    |
-|                     | cx                  |                                                                    |
-|                     | cy                  |                                                                    |
-|                     | rx                  |                                                                    |
-|                     | ry                  |                                                                    |
-| feBlend             |                     | See "Filter effects"                                               |
-|                     | in                  |                                                                    |
-|                     | in2                 |                                                                    |
-|                     | mode                |                                                                    |
-| feColorMatrix       |                     | See "Filter effects"                                               |
-|                     | in                  |                                                                    |
-|                     | type                |                                                                    |
-|                     | values              |                                                                    |
-| feComponentTransfer |                     | See "Filter effects"                                               |
-|                     | in                  |                                                                    |
-| feComposite         |                     | See "Filter effects"                                               |
-|                     | in                  |                                                                    |
-|                     | in2                 |                                                                    |
-|                     | operator            |                                                                    |
-|                     | k1                  |                                                                    |
-|                     | k2                  |                                                                    |
-|                     | k3                  |                                                                    |
-|                     | k4                  |                                                                    |
-| feConvolveMatrix    |                     | See "Filter effects"                                               |
-|                     | in                  |                                                                    |
-|                     | order               |                                                                    |
-|                     | divisor             |                                                                    |
-|                     | bias                |                                                                    |
-|                     | targetX             |                                                                    |
-|                     | targetY             |                                                                    |
-|                     | edgeMode            |                                                                    |
-|                     | kernelMatrix        |                                                                    |
-|                     | kernelUnitLength    |                                                                    |
-|                     | preserveAlpha       |                                                                    |
-| feDiffuseLighting   |                     | See "Filter effects"                                               |
-|                     | in                  |                                                                    |
-|                     | surfaceScale        |                                                                    |
-|                     | kernelUnitLength    |                                                                    |
-|                     | diffuseConstant     |                                                                    |
-| feDisplacementMap   |                     | See "Filter effects"                                               |
-|                     | in                  |                                                                    |
-|                     | in2                 |                                                                    |
-|                     | scale               |                                                                    |
-|                     | xChannelSelector    |                                                                    |
-|                     | yChannelSelector    |                                                                    |
-| feDistantLight      |                     |                                                                    |
-|                     | azimuth             |                                                                    |
-|                     | elevation           |                                                                    |
-| feFuncA             |                     | See "Filter effect feComponentTransfer"                            |
-| feFuncB             |                     | See "Filter effect feComponentTransfer"                            |
-| feFuncG             |                     | See "Filter effect feComponentTransfer"                            |
-| feFuncR             |                     | See "Filter effect feComponentTransfer"                            |
-| feFlood             |                     | See "Filter effects"                                               |
-|                     |                     | Parameters come from the flood-color and flood-opacity properties. |
-| feGaussianBlur      |                     | See "Filter effects"                                               |
-|                     | in                  |                                                                    |
-|                     | stdDeviation        |                                                                    |
-| feImage             |                     | See "Filter effects"                                               |
-|                     | xlink:href          | Needs xlink namespace                                              |
-|                     | href                | SVG2                                                               |
-|                     | path                | Non-standard; used by old Adobe Illustrator versions.              |
-|                     | preserveAspectRatio |                                                                    |
-| feMerge             |                     | See "Filter effects"                                               |
-| feMergeNode         |                     |                                                                    |
-|                     | in                  |                                                                    |
-| feMorphology        |                     | See "Filter effects"                                               |
-|                     | in                  |                                                                    |
-|                     | operator            |                                                                    |
-|                     | radius              |                                                                    |
-| feOffset            |                     | See "Filter effects"                                               |
-|                     | in                  |                                                                    |
-|                     | dx                  |                                                                    |
-|                     | dy                  |                                                                    |
-| fePointLight        |                     |                                                                    |
-|                     | x                   |                                                                    |
-|                     | y                   |                                                                    |
-|                     | z                   |                                                                    |
-| feSpecularLighting  |                     | See "Filter effects"                                               |
-|                     | in                  |                                                                    |
-|                     | surfaceScale        |                                                                    |
-|                     | kernelUnitLength    |                                                                    |
-|                     | specularConstant    |                                                                    |
-|                     | specularExponent    |                                                                    |
-| feSpotLight         |                     |                                                                    |
-|                     | x                   |                                                                    |
-|                     | y                   |                                                                    |
-|                     | z                   |                                                                    |
-|                     | pointsAtX           |                                                                    |
-|                     | pointsAtY           |                                                                    |
-|                     | pointsAtZ           |                                                                    |
-|                     | specularExponent    |                                                                    |
-|                     | limitingConeAngle   |                                                                    |
-| feTile              |                     | See "Filter effects"                                               |
-|                     | in                  |                                                                    |
-| feTurbulence        |                     | See "Filter effects"                                               |
-|                     | baseFrequency       |                                                                    |
-|                     | numOctaves          |                                                                    |
-|                     | seed                |                                                                    |
-|                     | stitchTiles         |                                                                    |
-|                     | type                |                                                                    |
-| filter              |                     |                                                                    |
-|                     | filterUnits         |                                                                    |
-|                     | primitiveUnits      |                                                                    |
-|                     | x                   |                                                                    |
-|                     | y                   |                                                                    |
-|                     | width               |                                                                    |
-|                     | height              |                                                                    |
-| g                   |                     |                                                                    |
-| image               |                     |                                                                    |
-|                     | xlink:href          | Needs xlink namespace                                              |
-|                     | href                | SVG2                                                               |
-|                     | path                | Non-standard; used by old Adobe Illustrator versions.              |
-|                     | x                   |                                                                    |
-|                     | y                   |                                                                    |
-|                     | width               |                                                                    |
-|                     | height              |                                                                    |
-|                     | preserveAspectRatio |                                                                    |
-| line                |                     |                                                                    |
-|                     | x1                  |                                                                    |
-|                     | y1                  |                                                                    |
-|                     | x2                  |                                                                    |
-|                     | y2                  |                                                                    |
-| linearGradient      |                     |                                                                    |
-|                     | gradientUnits       |                                                                    |
-|                     | gradientTransform   |                                                                    |
-|                     | spreadMethod        |                                                                    |
-|                     | x1                  |                                                                    |
-|                     | y1                  |                                                                    |
-|                     | x2                  |                                                                    |
-|                     | y2                  |                                                                    |
-| marker              |                     |                                                                    |
-|                     | markerUnits         |                                                                    |
-|                     | refX                |                                                                    |
-|                     | refY                |                                                                    |
-|                     | markerWidth         |                                                                    |
-|                     | markerHeight        |                                                                    |
-|                     | orient              |                                                                    |
-|                     | preserveAspectRatio |                                                                    |
-|                     | viewBox             |                                                                    |
-| mask                |                     |                                                                    |
-|                     | x                   |                                                                    |
-|                     | y                   |                                                                    |
-|                     | width               |                                                                    |
-|                     | height              |                                                                    |
-|                     | maskUnits           |                                                                    |
-|                     | maskContentUnits    |                                                                    |
-| path                |                     |                                                                    |
-|                     | d                   |                                                                    |
-| pattern             |                     |                                                                    |
-|                     | xlink:href          | Needs xlink namespace                                              |
-|                     | href                | SVG2                                                               |
-|                     | patternUnits        |                                                                    |
-|                     | patternContentUnits |                                                                    |
-|                     | patternTransform    |                                                                    |
-|                     | preserveAspectRatio |                                                                    |
-|                     | viewBox             |                                                                    |
-|                     | x                   |                                                                    |
-|                     | y                   |                                                                    |
-|                     | width               |                                                                    |
-|                     | height              |                                                                    |
-| polygon             |                     |                                                                    |
-|                     | points              |                                                                    |
-| polyline            |                     |                                                                    |
-|                     | points              |                                                                    |
-| radialGradient      |                     |                                                                    |
-|                     | gradientUnits       |                                                                    |
-|                     | gradientTransform   |                                                                    |
-|                     | spreadMethod        |                                                                    |
-|                     | cx                  |                                                                    |
-|                     | cy                  |                                                                    |
-|                     | r                   |                                                                    |
-|                     | fx                  |                                                                    |
-|                     | fx                  |                                                                    |
-|                     | fr                  |                                                                    |
-| rect                |                     |                                                                    |
-|                     | x                   |                                                                    |
-|                     | y                   |                                                                    |
-|                     | width               |                                                                    |
-|                     | height              |                                                                    |
-|                     | rx                  |                                                                    |
-|                     | ry                  |                                                                    |
-| stop                |                     |                                                                    |
-|                     | offset              |                                                                    |
-| style               |                     |                                                                    |
-|                     | type                |                                                                    |
-| svg                 |                     |                                                                    |
-|                     | x                   |                                                                    |
-|                     | y                   |                                                                    |
-|                     | width               |                                                                    |
-|                     | height              |                                                                    |
-|                     | viewBox             |                                                                    |
-|                     | preserveAspectRatio |                                                                    |
-| switch              |                     |                                                                    |
-| symbol              |                     |                                                                    |
-|                     | preserveAspectRatio |                                                                    |
-|                     | viewBox             |                                                                    |
-| text                |                     |                                                                    |
-|                     | x                   |                                                                    |
-|                     | y                   |                                                                    |
-|                     | dx                  |                                                                    |
-|                     | dy                  |                                                                    |
-| tref                |                     |                                                                    |
-|                     | xlink:href          | Needs xlink namespace                                              |
-| tspan               |                     |                                                                    |
-|                     | x                   |                                                                    |
-|                     | y                   |                                                                    |
-|                     | dx                  |                                                                    |
-|                     | dy                  |                                                                    |
-| use                 |                     |                                                                    |
-|                     | xlink:href          | Needs xlink namespace                                              |
-|                     | href                | SVG2                                                               |
-|                     | x                   |                                                                    |
-|                     | y                   |                                                                    |
-|                     | width               |                                                                    |
-|                     | height              |                                                                    |
-
-# CSS properties
-
-The following are shorthand properties.  They are not available as
-presentation attributes, only as style properties, so for example you have to use
-`<path style="marker: url(#foo);"/>`, since there is no `marker` attribute.
-
-| Property                   | Notes                                                              |
-|----------------------------|--------------------------------------------------------------------|
-| font                       |                                                                    |
-| glyph-orientation-vertical | Supports only CSS Writing Modes 3 values: auto, 0, 90, 0deg, 90deg |
-| marker                     |                                                                    |
-
-The following are longhand properties.  Most of them are available as
-presentation attributes, e.g. you can use `<rect fill="blue"/>` as
-well as `<rect style="fill: blue;"/>`.  The Notes column indicates
-which properties are not available as presentation attributes.
-
-| Property                    | Notes                                                  |
-|-----------------------------|--------------------------------------------------------|
-| baseline-shift              |                                                        |
-| clip-path                   |                                                        |
-| clip-rule                   |                                                        |
-| color                       |                                                        |
-| color-interpolation-filters |                                                        |
-| direction                   |                                                        |
-| display                     |                                                        |
-| enable-background           |                                                        |
-| fill                        |                                                        |
-| fill-opacity                |                                                        |
-| fill-rule                   |                                                        |
-| filter                      |                                                        |
-| flood-color                 |                                                        |
-| flood-opacity               |                                                        |
-| font-family                 |                                                        |
-| font-size                   |                                                        |
-| font-stretch                |                                                        |
-| font-style                  |                                                        |
-| font-variant                |                                                        |
-| font-weight                 |                                                        |
-| isolation                   | Not available as a presentation attribute.             |
-| letter-spacing              |                                                        |
-| lighting-color              |                                                        |
-| line-height                 | Not available as a presentation attribute.             |
-| marker-end                  |                                                        |
-| marker-mid                  |                                                        |
-| marker-start                |                                                        |
-| mask                        |                                                        |
-| mask-type                   |                                                        |
-| mix-blend-mode              | Not available as a presentation attribute.             |
-| opacity                     |                                                        |
-| overflow                    |                                                        |
-| paint-order                 |                                                        |
-| shape-rendering             |                                                        |
-| stop-color                  |                                                        |
-| stop-opacity                |                                                        |
-| stroke                      |                                                        |
-| stroke-dasharray            |                                                        |
-| stroke-dashoffset           |                                                        |
-| stroke-linecap              |                                                        |
-| stroke-linejoin             |                                                        |
-| stroke-miterlimit           |                                                        |
-| stroke-opacity              |                                                        |
-| stroke-width                |                                                        |
-| text-anchor                 |                                                        |
-| text-decoration             |                                                        |
-| text-orientation            | Not available as a presentation attribute.             |
-| text-rendering              |                                                        |
-| transform                   | SVG2; different syntax from the `transform` attribute. |
-| unicode-bidi                |                                                        |
-| vector-effect               | Only `non-scaling-stroke` is supported for paths.      |
-| visibility                  |                                                        |
-| writing-mode                |                                                        |
-
-## Filter effects
-
-The following elements are filter effects:
-
-* feBlend
-* feColorMatrix
-* feComponentTransfer
-* feComposite
-* feConvolveMatrix
-* feDiffuseLighting
-* feDisplacementMap
-* feFlood
-* feGaussianBlur
-* feImage
-* feMerge
-* feMorphology
-* feOffset
-* feSpecularLighting
-* feTile
-* feTurbulence
-
-All of those elements for filter effects support these attributes:
-
-| Attribute | Notes |
-| ---       | ---   |
-| x         |       |
-| y         |       |
-| width     |       |
-| height    |       |
-| result    |       |
-
-Some filter effect elements take one input in the `in` attribute, and
-some others take two inputs in the `in`, `in2` attributes.  See the
-table of elements above for details.
-
-## Filter effect feComponentTransfer
-
-The `feComponentTransfer` element can contain children `feFuncA`,
-`feFuncR`, `feFuncG`, `feFuncB`, and those all support these
-attributes:
-
-| Attribute   | Notes |
-| ---         | ---   |
-| type        |       |
-| tableValues |       |
-| slope       |       |
-| intercept   |       |
-| amplitude   |       |
-| exponent    |       |
-| offset      |       |
-
-# CSS features
-
-## Pseudo-classes
-
-| Pseudo-class        | Notes                                                                                |
-| ---                 | ---                                                                                  |
-| :link               |                                                                                      |
-| :visited            | Because librsvg does not maintain browser history, this is parsed, but never matches |
-| :lang()             |                                                                                      |
-| :not()              | [^1]                                                                                 |
-| :first-child        | [^1]                                                                                 |
-| :last-child         | [^1]                                                                                 |
-| :only-child         | [^1]                                                                                 |
-| :root               | [^1]                                                                                 |
-| :empty              | [^1]                                                                                 |
-| :nth-child()        | [^1]                                                                                 |
-| :nth-last-child()   | [^1]                                                                                 |
-| :nth-of-type()      | [^1]                                                                                 |
-| :nth-last-of-type() | [^1]                                                                                 |
-| :first-of-type      | [^1]                                                                                 |
-| :last-of-type       | [^1]                                                                                 |
-| :only-of-type       | [^1]                                                                                 |
-
-[^1]: These structural pseudo-classes are implemented in rust-selectors, which librsvg uses.
-
-FIXME: which selectors, combinators, at-rules.
-
-# XML features
-
-FIXME: `<xi:include href= parse= encoding=>`
-
-FIXME: `<xi:fallback>`
-
-FIXME: `xml:lang` attribute
-
-FIXME: `xml:space` attribute
-
-# Explicitly Unsupported features
-
-* `flowRoot` element and its children - Inkscape, SVG 1.2 only., #13
-
-* `glyph-orientation-horizontal` property - SVG1.1 only, removed in SVG2
-
-* The pseudo-classes `:is()` and `:where()` are part of Selectors Level 4, which is still a working draft.
-
-# Footnotes
diff --git a/Makefile.am b/Makefile.am
index 3c6388c9..af2e6514 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -243,7 +243,6 @@ CLEANFILES += rsvg-convert.1
 endif
 
 dist_doc_DATA =				\
-	COMPILING.md			\
 	CONTRIBUTING.md			\
 	README.md			\
 	code-of-conduct.md
@@ -255,7 +254,6 @@ EXTRA_DIST =				\
 	AUTHORS				\
 	COPYING.LIB 			\
 	NEWS				\
-	SECURITY.md			\
 	Rsvg-2.0-custom.vala		\
 	Rsvg-2.0.metadata		\
 	glib-tap.mk			\
diff --git a/README.md b/README.md
index 2e9a76e7..c6445d58 100644
--- a/README.md
+++ b/README.md
@@ -9,7 +9,9 @@ generate output for printing.
 Do you want to render non-animated SVGs to a Cairo surface with a
 minimal API?  Librsvg may be adequate for you.
 
-**Supported SVG/CSS features:** Please see the [FEATURES.md](FEATURES.md) file.
+**Supported SVG/CSS features:** Please see the chapter for [supported
+features](https://gnome.pages.gitlab.gnome.org/librsvg/devel-docs/features.html)
+in the development guide.
 
 ***PLEASE DO NOT SEND PULL REQUESTS TO GITHUB.***  We use
 [`gitlab.gnome.org`](https://gitlab.gnome.org/GNOME/librsvg) instead.
@@ -47,7 +49,7 @@ may run into some peculiarities due to the Rust internals library if
 you are **cross-compiling** or if you are in a **build system with no
 network access**, or if you are **building binary packages from a
 librsvg tarball**.  In those cases, please refer to the
-[`COMPILING.md`][compiling] file.
+[Detailed compilation instructions][compiling] in the development guide.
 
 **Documentation:** You can read the documentation for librsvg's [C
 API][c-docs] or the [Rust API][rust-docs].  Please [file an
@@ -67,6 +69,11 @@ Introspection][gi].  This way, it is available in many programming
 languages other than C.  Please see your language binding's
 documentation for information on how to load the `Rsvg` namespace.
 
+**Security:** For a list of releases with security issues,
+instructions on reporting security-related bugs, and the security
+considerations for librsvg's dependencies, see the [Security
+chapter][security] in the development guide.
+
 [c-docs]: https://gnome.pages.gitlab.gnome.org/librsvg/Rsvg-2.0/index.html
 [rust-docs]: https://gnome.pages.gitlab.gnome.org/librsvg/doc/librsvg/index.html
 
@@ -75,10 +82,9 @@ documentation for information on how to load the `Rsvg` namespace.
 There is a code of conduct for contributors to librsvg; please see the
 file [`code-of-conduct.md`][coc].
 
-Please see the [Development guide for
-librsvg](https://gnome.pages.gitlab.gnome.org/librsvg/devel-docs/index.html)
-on how to contribute to librsvg, how set up your development
-environment, and for a description of librsvg's architecture.
+Please see the [Development guide for librsvg][devel-guide] on how to
+contribute to librsvg, how set up your development environment, and
+for a description of librsvg's architecture.
 
 For information on how to report bugs, or how to contribute to librsvg
 in general, please see the file [`CONTRIBUTING.md`][contributing].
@@ -179,18 +185,19 @@ ways:
 
 * [Mail me][mail] at federico@gnome.org.
 
-* IRC: I am `federico` on `irc.gnome.org` in the `#rust` or
-  `#gnome-hackers` channels.  I'm there most weekdays (Mon-Fri)
-  starting at about UTC 14:00 (that's 08:00 my time; I am in the UTC-6
-  timezone).  If this is not a convenient time for you, feel free to
-  [mail me][mail] and we can arrange a time.
+* Matrix: I am `@federico` on the [GNOME Hackers][gnome-hackers] and
+  [Rust ❤️ GNOME][gnome-rust] channels on gnome.org's Matrix.  I'm
+  there most weekdays (Mon-Fri) starting at about UTC 14:00 (that's
+  08:00 my time; I am in the UTC-6 timezone).  If this is not a
+  convenient time for you, feel free to [mail me][mail] and we can
+  arrange a time.
 
 [svg]: https://en.wikipedia.org/wiki/Scalable_Vector_Graphics
 [gnome]: https://www.gnome.org/
 [cairo]: https://www.cairographics.org/
 [coc]: code-of-conduct.md
 [autotools]: https://autotools.io/index.html
-[compiling]: COMPILING.md
+[compiling]: https://gnome.pages.gitlab.gnome.org/librsvg/devel-docs/compiling.html
 [mail]: mailto:federico@gnome.org
 [bugs]: https://gitlab.gnome.org/GNOME/librsvg/issues
 [gi]: https://wiki.gnome.org/Projects/GObjectIntrospection
@@ -201,3 +208,7 @@ ways:
 [platform]: https://developer.gnome.org/
 [guadec-presentation-1]: https://viruta.org/docs/fmq-porting-c-to-rust.pdf
 [guadec-presentation-2]: https://viruta.org/docs/fmq-refactoring-c-to-rust.pdf
+[gnome-hackers]: https://matrix.to/#/#gnome-hackers:gnome.org
+[gnome-rust]: https://matrix.to/#/#rust:gnome.org
+[devel-guide]: https://gnome.pages.gitlab.gnome.org/librsvg/devel-docs/index.html
+[security]: https://gnome.pages.gitlab.gnome.org/librsvg/devel-docs/security.html
diff --git a/SECURITY.md b/SECURITY.md
deleted file mode 100644
index f9ae8781..00000000
--- a/SECURITY.md
+++ /dev/null
@@ -1,195 +0,0 @@
-# Reporting security bugs
-
-Please mail the maintainer at federico@gnome.org.  You can use the GPG
-public key from https://viruta.org/docs/fmq-gpg.asc to send encrypted
-mail.
-
-# Librsvg releases with security fixes
-
-Librsvg releases have a version number like major.minor.micro. Note
-that releases with an odd minor number (e.g. 2.47.x since 47 is odd)
-are considered development releases and should not be used in
-production systems.
-
-The following list is only for stable release streams, where the minor
-number is even (e.g. 2.50.x).
-
-### 2.50.4
-
-RUSTSEC-2020-0146 - lifetime erasure in generic-array.
-
-### 2.48.10
-
-CVE-2020-35905 - RUSTSEC-2020-0059 - data race in futures-util.
-
-CVE-2020-35906 - RUSTSEC-2020-0060 - use-after-free in futures-task.
-
-CVE-2021-25900 - RUSTSEC-2021-0003 - buffer overflow in smallvec.
-
-RUSTSEC-2020-0146 - lifetime erasure in generic-array.
-
-### 2.48.0
-
-CVE-2019-20446 - guard against exponential growth of CPU time
-from malicious SVGs.
-
-### 2.46.5
-
-RUSTSEC-2020-0146 - lifetime erasure in generic-array.
-
-CVE-2021-25900 - RUSTSEC-2021-0003 - buffer overflow in smallvec.
-
-See notes below on libcroco.
-
-### 2.44.17
-
-RUSTSEC-2020-0146 - lifetime erasure in generic-array.
-
-CVE-2019-15554 - RUSTSEC-2019-0012 - memory corruption in smallvec.
-
-CVE-2019-15551 - RUSTSEC-2019-0009 - double-free and use-after-free in smallvec.
-
-CVE-2021-25900 - RUSTSEC-2021-0003 - buffer overflow in smallvec.
-
-See notes below on libcroco.
-
-### 2.44.16
-
-CVE-2019-20446 - guard against exponential growth of CPU time
-from malicious SVGs.
-
-See notes below on libcroco.
-
-### 2.42.8
-
-CVE-2019-20446 - guard against exponential growth of CPU time
-from malicious SVGs.
-
-See notes below on libcroco.
-
-### 2.42.9
-
-CVE-2018-20991 - RUSTSEC-2018-0003 - double-free in smallvec.
-
-See notes below on libcroco.
-
-### 2.40.21
-
-CVE-2019-20446 - guard against exponential growth of CPU time
-from malicious SVGs.
-
-See notes below on libcroco.
-
-### 2.40.18
-
-CVE-2017-11464 - Fix division-by-zero in the Gaussian blur code.
-
-See notes below on libcroco.
-
-### Earlier releases should be avoided and are not listed here.
-
-**Important note on libcroco:** Note that librsvg 2.46.x and earlier use
-[libcroco](https://gitlab.gnome.org/Archive/libcroco/) for parsing
-CSS, but that library is deprecated, unmaintained, and has open CVEs as
-of May 2021.
-
-If your application processes untrusted data, please avoid using
-librsvg 2.46.x or earlier.  The first release of librsvg that does not
-use libcroco is 2.48.0.
-
-# Librsvg's dependencies
-
-Librsvg depends on the following libraries implemented in memory-unsafe languages:
-
-* **libxml2** - loading XML data.
-* **cairo** - 2D rendering engine.
-* **gdk-pixbuf** - decoding raster images like JPEG/PNG.
-* **freetype2** - font renderer.
-* **harfbuzz** - text shaping engine.
-
-And of course, their recursive dependencies as well, such as **glib/gio**.
-
-## Security considerations for libxml2
-
-Librsvg uses the following configuration for the SAX2 parser in libxml2:
-
- * `XML_PARSE_NONET` - forbid network access.
- * `XML_PARSE_BIG_LINES` - store big line numbers.
-
-As a special case, librsvg enables `replaceEntities` in the
-`_xmlParserCtxtPtr` struct so that libxml2 will expand references only
-to internal entities declared in the DTD subset.  External entities
-are disabled.
-
-For example, the following document renders two rectangles that are
-expanded from internal entities:
-
-```
-<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1 Basic//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11-basic.dtd" [
-  <!ENTITY Rect1 "<rect x='15' y='10' width='20' height='30' fill='blue'/>">
-  <!ENTITY Rect2 "<rect x='10' y='5' width='10' height='20' fill='green'/>">
-]>
-<svg xmlns="http://www.w3.org/2000/svg" width="60" height="60">
-  &Rect1;
-  &Rect2;
-</svg>
-```
-
-However, an external entity like
-
-```
-  <!ENTITY foo SYSTEM "foo.xml">
-```
-
-will generate an XML parse error and the document will not be loaded.
-
-## Security considerations for Cairo
-
-Cairo is easy to crash if given coordinates that fall outside the
-range of its 24.8 fixed-point numbers.  Librsvg is working on
-mitigating this.
-
-## Security considerations for gdk-pixbuf
-
-Gdk-pixbuf depends on **libpng**, **libjpeg**, and other libraries for
-different image formats.
-
-# Security considerations for librsvg
-
-**Built-in limits:** Librsvg has built-in limits for the following:
-
-* Limit on the maximum number of loaded XML elements, set to 1,000,000
-  (one million).  SVG documents with more than this number of elements
-  will fail to load.  This is a mitigation for malicious documents
-  that would otherwise consume large amounts of memory, for example by
-  including a huge number of `<g/>` elements with no useful content.
-  This is set in the file `src/limits.rs` in the `MAX_LOADED_ELEMENTS`
-  constant.
-
-* Limit on the maximum number of referenced elements while rendering.
-  The `<use>` element in SVG and others like `<pattern>` can reference
-  other elements in the document.  Malicious documents can cause an
-  exponential number of references to be resolved, so librsvg places a
-  limit of 500,000 references (half a million) to avoid unbounded
-  consumption of CPU time.  This is set in the file `src/limits.rs` in
-  the `MAX_REFERENCED_ELEMENTS` constant.
-
-Librsvg has no built-in limits on the total amount of memory or CPU
-time consumed to process a document.  Your application may want to
-place limits on this, especially if it processes untrusted SVG
-documents.
-
-**Processing external files:** Librsvg processes references to
-external files by itself: XML XInclude, `xlink:href` attributes, etc.
-Please see the section "Security and locations of referenced files" in
-the [developer's
-documentation](https://developer-old.gnome.org/rsvg/unstable/RsvgHandle.html)
-to see what criteria is used to accept or reject a file based on its
-location.  If your application has more stringent requirements, it may
-need to sandbox its use of librsvg.
-
-**SVG features:** Librsvg ignores animations, scripts, and events
-declared in SVG documents.  It always handles referenced images,
-similar to SVG's [static processing
-mode](https://www.w3.org/TR/SVG2/conform.html#static-mode).
-
diff --git a/configure.ac b/configure.ac
index 7e30c50d..2760ffdd 100644
--- a/configure.ac
+++ b/configure.ac
@@ -106,7 +106,7 @@ AS_IF(test x$RUSTC = xno,
 )
 
 dnl MSRV - Minimum Supported Rust Version
-dnl If you change this, please update COMPILING.md
+dnl If you change this, please update the "_manual_setup" section of devel-docs/devel_environment.rst
 MINIMUM_RUST_VER=1.63
 rust_version=`$RUSTC --version | sed -e 's/^rustc //g'`
 AX_COMPARE_VERSION([$rust_version],[lt],[$MINIMUM_RUST_VER], [
diff --git a/devel-docs/compiling.rst b/devel-docs/compiling.rst
new file mode 100644
index 00000000..07ba2e62
--- /dev/null
+++ b/devel-docs/compiling.rst
@@ -0,0 +1,260 @@
+Detailed compilation instructions
+=================================
+
+A full build of librsvg requires
+`autotools <https://autotools.io/index.html>`__. A full build will
+produce these (see :doc:`product` for details):
+
+-  ``rsvg-convert`` binary and its ``man`` page.
+-  librsvg shared library with the GObject-based API.
+-  Gdk-pixbuf loader for SVG files.
+-  HTML documentation for the GObject-based API, with ``gi-docgen``.
+-  GObject-introspection information for language bindings.
+-  Vala language bindings.
+
+Librsvg uses a mostly normal `autotools
+<https://autotools.io/index.html>`__ setup. The historical details of
+how librsvg integrates Cargo and Rust into its autotools setup are
+described in `this blog post
+<https://viruta.org/librsvgs-build-infrastructure-autotools-and-rust.html>`__,
+although hopefully you will not need to refer to it.
+
+It is perfectly fine to `ask the maintainer
+<https://gitlab.gnome.org/GNOME/librsvg/#maintainers>`__ if you have
+questions about the Autotools setup; it’s a tricky bit of machinery, and
+we are glad to help.
+
+The rest of this document explains librsvg’s peculiarities apart from
+the usual way of compiling Autotools projects:
+
+-  `Basic compilation instructions <#basic-compilation-instructions>`__
+-  `Verbosity <#verbosity>`__
+-  `Debug or release builds <#debug-or-release-builds>`__
+-  `Selecting a Rust toolchain <#selecting-a-rust-toolchain>`__
+-  `Cross-compilation <#cross-compilation>`__
+-  `Building with no network
+   access <#building-with-no-network-access>`__
+-  `Running "make distcheck" <#running-make-distcheck>`__
+
+Basic compilation instructions
+------------------------------
+
+If you are compiling a tarball:
+
+.. code:: sh
+
+   ./configure --enable-gtk-doc --enable-vala
+   make
+   make install
+
+See the ``INSTALL`` file for details on options you can
+pass to the ``configure`` script to select where to install the compiled
+library.
+
+If you are compiling from a git checkout:
+
+.. code:: sh
+
+   ./autogen.sh --enable-gtk-doc --enable-vala
+   make
+   make install
+
+The ``--enable-gtk-doc`` and ``--enable-vala`` arguments are
+optional. They will check that you have gi-docgen and the Vala compiler
+installed, respectively.
+
+Verbosity
+---------
+
+By default the compilation process is quiet, and it just tells you which
+files it is compiling.
+
+If you wish to see the full compilation command lines, use
+“``make V=1``” instead of plain “``make``”.
+
+Debug or release builds
+-----------------------
+
+Librsvg’s artifacts have code both in C and Rust, and each language has
+a different way of specifying compilation options to select compiler
+optimizations, or whether debug information should be included.
+
+-  **Rust code:** the librsvg shared library, and the ``rsvg-convert``
+   binary. See below.
+
+-  **C code:** the gdk-pixbuf loader; you should set the ``CFLAGS``
+   environment variable with compiler flags that you want to pass to the
+   C compiler.
+
+Controlling debug or release mode for Rust
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+-  With a ``configure`` option: ``--enable-debug`` or
+   ``--disable-debug``
+-  With an environment variable: ``LIBRSVG_DEBUG=yes`` or
+   ``LIBRSVG_DEBUG=no``
+
+For the Rust part of librsvg, we have a flag that you can pass at
+``configure`` time. When enabled, the Rust sub-library will have
+debugging information and no compiler optimizations. **This flag is off
+by default:** if the flag is not specified, the Rust sub-library will be
+built in release mode (no debug information, full compiler
+optimizations).
+
+The rationale is that people who already had scripts in place to build
+binary packages for librsvg, generally from release tarballs, are
+already using conventional machinery to specify C compiler options, such
+as that in RPM specfiles or Debian source packages. However, they may
+not contemplate Rust libraries and they will certainly not want to
+modify their existing packaging scripts too much.
+
+So, by default, the Rust library builds in **release mode**, to make
+life easier to binary distributions. Librsvg’s build scripts will add
+``--release`` to the Cargo command line by default.
+
+Developers can request a debug build of the Rust code by passing
+``--enable-debug`` to the ``configure`` script, or by setting the
+``LIBRSVG_DEBUG=yes`` environment variable before calling ``configure``.
+This will omit the ``--release`` option from Cargo, so that it will
+build the Rust sub-library in debug mode.
+
+In case both the environment variable and the command-line option are
+specified, the command-line option overrides the env var.
+
+Selecting a Rust toolchain
+--------------------------
+
+By default, the configure/make steps will use the ``cargo`` binary that
+is found in your ``$PATH``. If you have a system installation of Rust
+and one in your home directory, or for special build systems, you may
+need to override the locations of ``cargo`` and/or ``rustc``. In this
+case, you can set any of these environment variables before running
+``configure`` or ``autogen.sh``:
+
+-  ``RUSTC`` - path to the ``rustc`` compiler
+-  ``CARGO`` - path to ``cargo``
+
+Note that ``$RUSTC`` only gets used in the ``configure`` script to
+ensure that there is a Rust compiler installed with an appropriate
+version. The actual compilation process just uses ``$CARGO``, and
+assumes that that ``cargo`` binary will use the same Rust compiler as
+the other variable.
+
+Cross-compilation
+-----------------
+
+If you need to cross-compile librsvg, specify the ``--host=TRIPLE`` to
+the ``configure`` script as usual with Autotools. This will cause
+librsvg’s build scripts to automatically pass ``--target=TRIPLE`` to
+``cargo``.
+
+Note, however, that Rust may support different targets than the C
+compiler on your system. Rust’s supported targets can be found in the
+`rustc
+manual <https://doc.rust-lang.org/nightly/rustc/platform-support.html>`__
+
+You can check Jorge Aparicio’s `guide on cross-compilation for
+Rust <https://github.com/japaric/rust-cross>`__ for more details.
+
+Overriding the Rust target name
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you need ``cargo --target=FOO`` to obtain a different value from the
+one you specified for ``--host=TRIPLE``, you can use the ``RUST_TARGET``
+variable, and this will be passed to ``cargo``. For example,
+
+.. code:: sh
+
+   RUST_TARGET=aarch64-unknown-linux-gnu ./configure --host=aarch64-buildroot-linux-gnu
+   # will run "cargo --target=aarch64-unknown-linux-gnu" for the Rust part
+
+Cross-compiling to a target not supported by Rust out of the box
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When building with a target that is not supported out of the box by
+Rust, you have to do this:
+
+1. Create a `target JSON definition
+   file <https://github.com/japaric/rust-cross#target-specification-files>`__.
+
+2. Set the environment variable ``RUST_TARGET_PATH`` to its directory
+   for the ``make`` command.
+
+Example:
+
+.. code:: sh
+
+   cd /my/target/definition
+   echo "JSON goes here" > MYMACHINE-VENDOR-OS.json
+   cd /source/tree/for/librsvg
+   ./configure --host=MYMACHINE-VENDOR-OS
+   make RUST_TARGET_PATH=/my/target/definition
+
+Cross-compiling for win32 target
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can also cross-compile to win32 (Microsoft Windows) target by using
+`MinGW-w64 <https://mingw-w64.org/>`__. You need to specify the
+appropriate target in the same way as usual:
+
+-  Set an appropriate target via the ``--host`` configure option:
+
+   -  ``i686-w64-mingw32`` for 32-bit target
+   -  ``x86_64-w64-mingw32`` for 64-bit target
+
+-  Set an appropriate RUST_TARGET:
+
+   -  ``i686-pc-windows-gnu`` for 32-bit target
+   -  ``x86_64-pc-windows-gnu`` for 64-bit target
+
+In addition you may need to link with some win32 specific libraries like
+``LIBS="-lws2_32 -luserenv"``.
+
+Example:
+
+.. code:: sh
+
+   ./configure \
+     --host=x86_64-w64-mingw32 \
+     RUST_TARGET=x86_64-pc-windows-gnu \
+     LIBS="-lws2_32 -luserenv"
+   make
+
+The most painful aspect of this way of building is preparing a win32
+build for each of librsvg’s dependencies. `MXE <https://mxe.cc/>`__ may
+help you on this work.
+
+Building with no network access
+-------------------------------
+
+Automated build systems generally avoid network access so that they can
+compile from known-good sources, instead of pulling random updates from
+the net every time. However, normally Cargo likes to download
+dependencies when it first compiles a Rust project.
+
+You can use `cargo vendor
+<https://doc.rust-lang.org/cargo/commands/cargo-vendor.html>`_ to
+download librsvg's Rust dependencies ahead of time, so that subsequent
+compilation don't require network access.
+
+Build systems can use `Cargo’s source replacement
+mechanism <https://doc.rust-lang.org/cargo/reference/source-replacement.html>`_ to override
+the location of the source code for the Rust dependencies, for example,
+in order to patch one of the Rust crates that librsvg uses internally.
+
+Running ``make distcheck``
+--------------------------
+
+The ``make distcheck`` command will built a release tarball, extract it,
+compile it and test it. However, part of the ``make install`` process
+within that command will try to install the gdk-pixbuf loader in your
+system location, and it will fail.
+
+Please run ``make distcheck`` like this:
+
+::
+
+   $ make distcheck DESTDIR=/tmp/foo
+
+That ``DESTDIR`` will keep the gdk-pixbuf loader installation from
+trying to modify your system locations.
diff --git a/devel-docs/devel_environment.rst b/devel-docs/devel_environment.rst
index d03b5b1f..9facbd1f 100644
--- a/devel-docs/devel_environment.rst
+++ b/devel-docs/devel_environment.rst
@@ -13,7 +13,7 @@ System requirements
 
 - Around 10 GB free of hard disk space.
 
-- You can either use `podman`_ to work in a
+- You can either use `podman <https://podman.io/>`_ to work in a
   containerized setup (this chapter will show you how), or you can
   install librsvg's dependencies by hand.
 
@@ -34,9 +34,10 @@ Downloading the source code
 Setting up with podman
 ----------------------
 
-An easy way to set up a development environment is to use `podman`_ to
-download and run a container image.  This is similar to having a
-``chroot`` with all of librsvg's dependencies already set up.
+An easy way to set up a development environment is to use `podman
+<https://podman.io/>`_ to download and run a container image.  This is
+similar to having a ``chroot`` with all of librsvg's dependencies
+already set up.
 
 Install ``podman`` on your distro, and then:
 
@@ -96,7 +97,84 @@ You can now skip to :ref:`build`.
 Setting up dependencies manually
 --------------------------------
 
-FIXME.
+To compile librsvg, you need the following packages installed.  The
+minimum version is listed here; you may use a newer version instead.
+
+**Compilers and build tools:**
+
+* a C compiler and `make` tool; we recommend GNU `make`.
+* rust 1.63 or later
+* cargo
+* autoconf, automake, libtool, itstool
+* vala (optional)
+
+**Mandatory dependencies:**
+
+* Cairo 1.16.0 with PNG support
+* Freetype2 2.8.0
+* Gdk-pixbuf 2.20.0
+* GIO 2.24.0
+* GObject-Introspection 0.10.8
+* gi-docgen
+* python3-docutils
+* Libxml2 2.9.0
+* Pango 1.46.0
+
+The following sections describe how to install these dependencies on
+several systems.
+
+Debian based systems
+~~~~~~~~~~~~~~~~~~~~
+
+As of 2018/Feb/22, librsvg cannot be built in `debian stable` and
+`ubuntu 18.04`, as they have packages that are too old.
+
+**Build dependencies on Debian Testing or Ubuntu 18.10:**
+
+.. code-block:: sh
+
+   apt-get install -y gcc make rustc cargo \
+   automake autoconf libtool gi-docgen python3-docutils git \
+   libgdk-pixbuf2.0-dev libgirepository1.0-dev \
+   libxml2-dev libcairo2-dev libpango1.0-dev
+
+Additionally, as of September 2018 you need to add `gdk-pixbuf`
+utilities to your path, see `#331
+<https://gitlab.gnome.org/GNOME/librsvg/-/issues/331>`_ for details:
+
+.. code-block:: sh
+
+   PATH="$PATH:/usr/lib/x86_64-linux-gnu/gdk-pixbuf-2.0"
+
+Fedora based systems
+~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: sh
+
+   dnf install -y gcc rust rust-std-static cargo make \
+   automake autoconf libtool gi-docgen python3-docutils git redhat-rpm-config \
+   gdk-pixbuf2-devel gobject-introspection-devel \
+   libxml2-devel cairo-devel cairo-gobject-devel pango-devel
+
+openSUSE based systems
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: sh
+
+   zypper install -y gcc rust rust-std cargo make \
+   automake autoconf libtool python3-gi-docgen python38-docutils git \
+   gdk-pixbuf-devel gobject-introspection-devel \
+   libxml2-devel cairo-devel pango-devel
+
+macOS systems
+~~~~~~~~~~~~~
+
+Dependencies may be installed using `Homebrew <https://brew.sh>`_ or another
+package manager.
+
+.. code-block:: sh
+
+   brew install automake gi-docgen pkgconfig libtool gobject-introspection gdk-pixbuf pango
 
 .. _build:
 
@@ -112,6 +190,14 @@ time during regular development.  If you are using the podman
 container as per above, you should do this in the ``/srv/project``
 directory most of the time.
 
+To casually test rendering, for example, for a feature you are
+developing, you can run `target/debug/rsvg-convert -o output.png
+my_test_file.svg`.
+
+If you do a release build with `carto build --release`, which includes
+optimizations, the binary will be in `target/release/rsvg-convert`.
+This version is *much* faster than the debug version.
+
 **Doing a full build:** You can use the following:
 
 .. code-block:: sh
@@ -126,4 +212,6 @@ You should only have to do that if you need to run the full test
 suite, for the C API tests and the tests for limiting memory
 consumption.
 
+
+
 .. _podman: https://podman.io/
diff --git a/devel-docs/features.rst b/devel-docs/features.rst
new file mode 100644
index 00000000..d21cd07d
--- /dev/null
+++ b/devel-docs/features.rst
@@ -0,0 +1,804 @@
+SVG and CSS features that librsvg supports
+==========================================
+
+Librsvg tries to be a mostly complete renderer for `SVG1.1
+<https://www.w3.org/TR/SVG11/>`_ and `SVG2
+<https://www.w3.org/TR/SVG2/>`_.
+
+In terms of processing external references, librsvg is a bit more
+strict than SVG’s “static mode” and a bit more lenient than “secure
+static mode”. See "`Security and locations of referenced files
+<https://gnome.pages.gitlab.gnome.org/librsvg/Rsvg-2.0/class.Handle.html#security-and-locations-of-referenced-files>`_"
+in the reference documentation for details.
+
+Animation, interactivity, and scripting are not supported.
+
+The SVG1.2 specification never made it past draft status in the W3C’s
+process, and librsvg does not support it. Note that SVG2 removed some of
+the features proposed for SVG1.2.
+
+Generally, librsvg tries to keep up with features in the SVG2 Candidate
+Recommendation spec. It ignores features in the SVG2 drafts that are not
+finalized yet.
+
+Alternative versions of SVG (SVG Tiny, SVG Basic, `SVG
+Native <https://gitlab.gnome.org/GNOME/librsvg/-/issues/689>`__) are not
+explicitly supported. Their features which are a subset of SVG1.1 or
+SVG2 are supported if they are equivalent to the ones listed below.
+
+SVG2 offloads many of its features to the family of CSS3 specifications.
+Librsvg does not try to support them exhaustively (there are too many
+features in CSS!). Instead, we try to prioritize new features based on
+the needs which people express in librsvg’s bug tracker. Do you want a
+feature? `File an
+issue <https://gitlab.gnome.org/GNOME/librsvg/issues>`__!
+
+Attributes supported by all elements
+------------------------------------
+
++-----------------------------------+-----------------------------------+
+| Attribute                         | Notes                             |
++===================================+===================================+
+| class                             |                                   |
++-----------------------------------+-----------------------------------+
+| id                                |                                   |
++-----------------------------------+-----------------------------------+
+| requiredExtensions                | Used in children of the           |
+|                                   | ``switch`` element.               |
++-----------------------------------+-----------------------------------+
+| requiredFeatures                  | Used in children of the           |
+|                                   | ``switch`` element.               |
++-----------------------------------+-----------------------------------+
+| systemLanguage                    | Used in children of the           |
+|                                   | ``switch`` element.               |
++-----------------------------------+-----------------------------------+
+| style                             |                                   |
++-----------------------------------+-----------------------------------+
+| transform                         | The ``transform`` attribute has a |
+|                                   | different syntax than the CSS     |
+|                                   | ``transform`` property.           |
++-----------------------------------+-----------------------------------+
+| xml:lang                          |                                   |
++-----------------------------------+-----------------------------------+
+| xml:space                         |                                   |
++-----------------------------------+-----------------------------------+
+
+Elements and their specific attributes
+--------------------------------------
+
++-----------------------+-----------------------+-----------------------+
+| Element               | Attributes            | Notes                 |
++=======================+=======================+=======================+
+| a                     |                       |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | xlink:href            | Needs xlink namespace |
++-----------------------+-----------------------+-----------------------+
+|                       | href                  | SVG2                  |
++-----------------------+-----------------------+-----------------------+
+| circle                |                       |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | cx                    |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | cy                    |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | r                     |                       |
++-----------------------+-----------------------+-----------------------+
+| clipPath              |                       |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | clipPathUnits         |                       |
++-----------------------+-----------------------+-----------------------+
+| defs                  |                       |                       |
++-----------------------+-----------------------+-----------------------+
+| ellipse               |                       |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | cx                    |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | cy                    |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | rx                    |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | ry                    |                       |
++-----------------------+-----------------------+-----------------------+
+| feBlend               |                       | See “Filter effects”  |
++-----------------------+-----------------------+-----------------------+
+|                       | in                    |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | in2                   |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | mode                  |                       |
++-----------------------+-----------------------+-----------------------+
+| feColorMatrix         |                       | See “Filter effects”  |
++-----------------------+-----------------------+-----------------------+
+|                       | in                    |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | type                  |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | values                |                       |
++-----------------------+-----------------------+-----------------------+
+| feComponentTransfer   |                       | See “Filter effects”  |
++-----------------------+-----------------------+-----------------------+
+|                       | in                    |                       |
++-----------------------+-----------------------+-----------------------+
+| feComposite           |                       | See “Filter effects”  |
++-----------------------+-----------------------+-----------------------+
+|                       | in                    |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | in2                   |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | operator              |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | k1                    |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | k2                    |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | k3                    |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | k4                    |                       |
++-----------------------+-----------------------+-----------------------+
+| feConvolveMatrix      |                       | See “Filter effects”  |
++-----------------------+-----------------------+-----------------------+
+|                       | in                    |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | order                 |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | divisor               |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | bias                  |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | targetX               |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | targetY               |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | edgeMode              |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | kernelMatrix          |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | kernelUnitLength      |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | preserveAlpha         |                       |
++-----------------------+-----------------------+-----------------------+
+| feDiffuseLighting     |                       | See “Filter effects”  |
++-----------------------+-----------------------+-----------------------+
+|                       | in                    |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | surfaceScale          |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | kernelUnitLength      |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | diffuseConstant       |                       |
++-----------------------+-----------------------+-----------------------+
+| feDisplacementMap     |                       | See “Filter effects”  |
++-----------------------+-----------------------+-----------------------+
+|                       | in                    |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | in2                   |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | scale                 |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | xChannelSelector      |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | yChannelSelector      |                       |
++-----------------------+-----------------------+-----------------------+
+| feDistantLight        |                       |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | azimuth               |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | elevation             |                       |
++-----------------------+-----------------------+-----------------------+
+| feFuncA               |                       | See “Filter effect    |
+|                       |                       | feComponentTransfer”  |
++-----------------------+-----------------------+-----------------------+
+| feFuncB               |                       | See “Filter effect    |
+|                       |                       | feComponentTransfer”  |
++-----------------------+-----------------------+-----------------------+
+| feFuncG               |                       | See “Filter effect    |
+|                       |                       | feComponentTransfer”  |
++-----------------------+-----------------------+-----------------------+
+| feFuncR               |                       | See “Filter effect    |
+|                       |                       | feComponentTransfer”  |
++-----------------------+-----------------------+-----------------------+
+| feFlood               |                       | See “Filter effects”  |
++-----------------------+-----------------------+-----------------------+
+|                       |                       | Parameters come from  |
+|                       |                       | the flood-color and   |
+|                       |                       | flood-opacity         |
+|                       |                       | properties.           |
++-----------------------+-----------------------+-----------------------+
+| feGaussianBlur        |                       | See “Filter effects”  |
++-----------------------+-----------------------+-----------------------+
+|                       | in                    |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | stdDeviation          |                       |
++-----------------------+-----------------------+-----------------------+
+| feImage               |                       | See “Filter effects”  |
++-----------------------+-----------------------+-----------------------+
+|                       | xlink:href            | Needs xlink namespace |
++-----------------------+-----------------------+-----------------------+
+|                       | href                  | SVG2                  |
++-----------------------+-----------------------+-----------------------+
+|                       | path                  | Non-standard; used by |
+|                       |                       | old Adobe Illustrator |
+|                       |                       | versions.             |
++-----------------------+-----------------------+-----------------------+
+|                       | preserveAspectRatio   |                       |
++-----------------------+-----------------------+-----------------------+
+| feMerge               |                       | See “Filter effects”  |
++-----------------------+-----------------------+-----------------------+
+| feMergeNode           |                       |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | in                    |                       |
++-----------------------+-----------------------+-----------------------+
+| feMorphology          |                       | See “Filter effects”  |
++-----------------------+-----------------------+-----------------------+
+|                       | in                    |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | operator              |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | radius                |                       |
++-----------------------+-----------------------+-----------------------+
+| feOffset              |                       | See “Filter effects”  |
++-----------------------+-----------------------+-----------------------+
+|                       | in                    |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | dx                    |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | dy                    |                       |
++-----------------------+-----------------------+-----------------------+
+| fePointLight          |                       |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | x                     |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | y                     |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | z                     |                       |
++-----------------------+-----------------------+-----------------------+
+| feSpecularLighting    |                       | See “Filter effects”  |
++-----------------------+-----------------------+-----------------------+
+|                       | in                    |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | surfaceScale          |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | kernelUnitLength      |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | specularConstant      |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | specularExponent      |                       |
++-----------------------+-----------------------+-----------------------+
+| feSpotLight           |                       |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | x                     |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | y                     |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | z                     |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | pointsAtX             |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | pointsAtY             |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | pointsAtZ             |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | specularExponent      |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | limitingConeAngle     |                       |
++-----------------------+-----------------------+-----------------------+
+| feTile                |                       | See “Filter effects”  |
++-----------------------+-----------------------+-----------------------+
+|                       | in                    |                       |
++-----------------------+-----------------------+-----------------------+
+| feTurbulence          |                       | See “Filter effects”  |
++-----------------------+-----------------------+-----------------------+
+|                       | baseFrequency         |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | numOctaves            |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | seed                  |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | stitchTiles           |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | type                  |                       |
++-----------------------+-----------------------+-----------------------+
+| filter                |                       |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | filterUnits           |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | primitiveUnits        |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | x                     |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | y                     |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | width                 |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | height                |                       |
++-----------------------+-----------------------+-----------------------+
+| g                     |                       |                       |
++-----------------------+-----------------------+-----------------------+
+| image                 |                       |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | xlink:href            | Needs xlink namespace |
++-----------------------+-----------------------+-----------------------+
+|                       | href                  | SVG2                  |
++-----------------------+-----------------------+-----------------------+
+|                       | path                  | Non-standard; used by |
+|                       |                       | old Adobe Illustrator |
+|                       |                       | versions.             |
++-----------------------+-----------------------+-----------------------+
+|                       | x                     |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | y                     |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | width                 |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | height                |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | preserveAspectRatio   |                       |
++-----------------------+-----------------------+-----------------------+
+| line                  |                       |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | x1                    |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | y1                    |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | x2                    |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | y2                    |                       |
++-----------------------+-----------------------+-----------------------+
+| linearGradient        |                       |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | gradientUnits         |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | gradientTransform     |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | spreadMethod          |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | x1                    |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | y1                    |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | x2                    |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | y2                    |                       |
++-----------------------+-----------------------+-----------------------+
+| marker                |                       |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | markerUnits           |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | refX                  |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | refY                  |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | markerWidth           |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | markerHeight          |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | orient                |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | preserveAspectRatio   |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | viewBox               |                       |
++-----------------------+-----------------------+-----------------------+
+| mask                  |                       |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | x                     |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | y                     |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | width                 |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | height                |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | maskUnits             |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | maskContentUnits      |                       |
++-----------------------+-----------------------+-----------------------+
+| path                  |                       |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | d                     |                       |
++-----------------------+-----------------------+-----------------------+
+| pattern               |                       |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | xlink:href            | Needs xlink namespace |
++-----------------------+-----------------------+-----------------------+
+|                       | href                  | SVG2                  |
++-----------------------+-----------------------+-----------------------+
+|                       | patternUnits          |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | patternContentUnits   |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | patternTransform      |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | preserveAspectRatio   |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | viewBox               |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | x                     |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | y                     |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | width                 |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | height                |                       |
++-----------------------+-----------------------+-----------------------+
+| polygon               |                       |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | points                |                       |
++-----------------------+-----------------------+-----------------------+
+| polyline              |                       |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | points                |                       |
++-----------------------+-----------------------+-----------------------+
+| radialGradient        |                       |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | gradientUnits         |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | gradientTransform     |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | spreadMethod          |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | cx                    |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | cy                    |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | r                     |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | fx                    |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | fx                    |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | fr                    |                       |
++-----------------------+-----------------------+-----------------------+
+| rect                  |                       |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | x                     |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | y                     |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | width                 |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | height                |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | rx                    |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | ry                    |                       |
++-----------------------+-----------------------+-----------------------+
+| stop                  |                       |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | offset                |                       |
++-----------------------+-----------------------+-----------------------+
+| style                 |                       |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | type                  |                       |
++-----------------------+-----------------------+-----------------------+
+| svg                   |                       |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | x                     |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | y                     |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | width                 |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | height                |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | viewBox               |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | preserveAspectRatio   |                       |
++-----------------------+-----------------------+-----------------------+
+| switch                |                       |                       |
++-----------------------+-----------------------+-----------------------+
+| symbol                |                       |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | preserveAspectRatio   |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | viewBox               |                       |
++-----------------------+-----------------------+-----------------------+
+| text                  |                       |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | x                     |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | y                     |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | dx                    |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | dy                    |                       |
++-----------------------+-----------------------+-----------------------+
+| tref                  |                       |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | xlink:href            | Needs xlink namespace |
++-----------------------+-----------------------+-----------------------+
+| tspan                 |                       |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | x                     |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | y                     |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | dx                    |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | dy                    |                       |
++-----------------------+-----------------------+-----------------------+
+| use                   |                       |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | xlink:href            | Needs xlink namespace |
++-----------------------+-----------------------+-----------------------+
+|                       | href                  | SVG2                  |
++-----------------------+-----------------------+-----------------------+
+|                       | x                     |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | y                     |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | width                 |                       |
++-----------------------+-----------------------+-----------------------+
+|                       | height                |                       |
++-----------------------+-----------------------+-----------------------+
+
+CSS properties
+--------------
+
+The following are shorthand properties. They are not available as
+presentation attributes, only as style properties, so for example you
+have to use ``<path style="marker: url(#foo);"/>``, since there is no
+``marker`` attribute.
+
++----------------------------+--------------------------------------------------------------------+
+| Property                   | Notes                                                              |
++============================+====================================================================+
+| font                       |                                                                    |
++----------------------------+--------------------------------------------------------------------+
+| glyph-orientation-vertical | Supports only CSS Writing Modes 3 values: auto, 0, 90, 0deg, 90deg |
++----------------------------+--------------------------------------------------------------------+
+| marker                     |                                                                    |
++----------------------------+--------------------------------------------------------------------+
+
+The following are longhand properties. Most of them are available as
+presentation attributes, e.g. you can use ``<rect fill="blue"/>`` as
+well as ``<rect style="fill: blue;"/>``. The Notes column indicates
+which properties are not available as presentation attributes.
+
++-----------------------+----------------------------------------------+
+| Property              | Notes                                        |
++=======================+==============================================+
+| baseline-shift        |                                              |
++-----------------------+----------------------------------------------+
+| clip-path             |                                              |
++-----------------------+----------------------------------------------+
+| clip-rule             |                                              |
++-----------------------+----------------------------------------------+
+| color                 |                                              |
++-----------------------+----------------------------------------------+
+| color-                |                                              |
+| interpolation-filters |                                              |
++-----------------------+----------------------------------------------+
+| direction             |                                              |
++-----------------------+----------------------------------------------+
+| display               |                                              |
++-----------------------+----------------------------------------------+
+| enable-background     |                                              |
++-----------------------+----------------------------------------------+
+| fill                  |                                              |
++-----------------------+----------------------------------------------+
+| fill-opacity          |                                              |
++-----------------------+----------------------------------------------+
+| fill-rule             |                                              |
++-----------------------+----------------------------------------------+
+| filter                |                                              |
++-----------------------+----------------------------------------------+
+| flood-color           |                                              |
++-----------------------+----------------------------------------------+
+| flood-opacity         |                                              |
++-----------------------+----------------------------------------------+
+| font-family           |                                              |
++-----------------------+----------------------------------------------+
+| font-size             |                                              |
++-----------------------+----------------------------------------------+
+| font-stretch          |                                              |
++-----------------------+----------------------------------------------+
+| font-style            |                                              |
++-----------------------+----------------------------------------------+
+| font-variant          |                                              |
++-----------------------+----------------------------------------------+
+| font-weight           |                                              |
++-----------------------+----------------------------------------------+
+| isolation             | Not available as a presentation attribute.   |
++-----------------------+----------------------------------------------+
+| letter-spacing        |                                              |
++-----------------------+----------------------------------------------+
+| lighting-color        |                                              |
++-----------------------+----------------------------------------------+
+| line-height           | Not available as a presentation attribute.   |
++-----------------------+----------------------------------------------+
+| marker-end            |                                              |
++-----------------------+----------------------------------------------+
+| marker-mid            |                                              |
++-----------------------+----------------------------------------------+
+| marker-start          |                                              |
++-----------------------+----------------------------------------------+
+| mask                  |                                              |
++-----------------------+----------------------------------------------+
+| mask-type             |                                              |
++-----------------------+----------------------------------------------+
+| mix-blend-mode        | Not available as a presentation attribute.   |
++-----------------------+----------------------------------------------+
+| opacity               |                                              |
++-----------------------+----------------------------------------------+
+| overflow              |                                              |
++-----------------------+----------------------------------------------+
+| paint-order           |                                              |
++-----------------------+----------------------------------------------+
+| shape-rendering       |                                              |
++-----------------------+----------------------------------------------+
+| stop-color            |                                              |
++-----------------------+----------------------------------------------+
+| stop-opacity          |                                              |
++-----------------------+----------------------------------------------+
+| stroke                |                                              |
++-----------------------+----------------------------------------------+
+| stroke-dasharray      |                                              |
++-----------------------+----------------------------------------------+
+| stroke-dashoffset     |                                              |
++-----------------------+----------------------------------------------+
+| stroke-linecap        |                                              |
++-----------------------+----------------------------------------------+
+| stroke-linejoin       |                                              |
++-----------------------+----------------------------------------------+
+| stroke-miterlimit     |                                              |
++-----------------------+----------------------------------------------+
+| stroke-opacity        |                                              |
++-----------------------+----------------------------------------------+
+| stroke-width          |                                              |
++-----------------------+----------------------------------------------+
+| text-anchor           |                                              |
++-----------------------+----------------------------------------------+
+| text-decoration       |                                              |
++-----------------------+----------------------------------------------+
+| text-orientation      | Not available as a presentation attribute.   |
++-----------------------+----------------------------------------------+
+| text-rendering        |                                              |
++-----------------------+----------------------------------------------+
+| transform             | SVG2; different syntax from the              |
+|                       | ``transform`` attribute.                     |
++-----------------------+----------------------------------------------+
+| unicode-bidi          |                                              |
++-----------------------+----------------------------------------------+
+| vector-effect         | Only ``non-scaling-stroke`` is supported for |
+|                       | paths.                                       |
++-----------------------+----------------------------------------------+
+| visibility            |                                              |
++-----------------------+----------------------------------------------+
+| writing-mode          |                                              |
++-----------------------+----------------------------------------------+
+
+Filter effects
+--------------
+
+The following elements are filter effects:
+
+- feBlend
+- feColorMatrix
+- feComponentTransfer
+- feComposite
+- feConvolveMatrix
+- feDiffuseLighting
+- feDisplacementMap
+- feFlood
+- feGaussianBlur
+- feImage
+- feMerge
+- feMorphology
+- feOffset
+- feSpecularLighting
+- feTile
+- feTurbulence
+
+All of those elements for filter effects support these attributes:
+
++-----------------------------------+-----------------------------------+
+| Attribute                         | Notes                             |
++===================================+===================================+
+| x                                 |                                   |
++-----------------------------------+-----------------------------------+
+| y                                 |                                   |
++-----------------------------------+-----------------------------------+
+| width                             |                                   |
++-----------------------------------+-----------------------------------+
+| height                            |                                   |
++-----------------------------------+-----------------------------------+
+| result                            |                                   |
++-----------------------------------+-----------------------------------+
+
+Some filter effect elements take one input in the ``in`` attribute, and
+some others take two inputs in the ``in``, ``in2`` attributes. See the
+table of elements above for details.
+
+Filter effect feComponentTransfer
+---------------------------------
+
+The ``feComponentTransfer`` element can contain children ``feFuncA``,
+``feFuncR``, ``feFuncG``, ``feFuncB``, and those all support these
+attributes:
+
+=========== =====
+Attribute   Notes
+=========== =====
+type        
+tableValues 
+slope       
+intercept   
+amplitude   
+exponent    
+offset      
+=========== =====
+
+CSS features
+------------
+
+Pseudo-classes
+~~~~~~~~~~~~~~
+
++-----------------------------------+-----------------------------------+
+| Pseudo-class                      | Notes                             |
++===================================+===================================+
+| :link                             |                                   |
++-----------------------------------+-----------------------------------+
+| :visited                          | Because librsvg does not maintain |
+|                                   | browser history, this is parsed,  |
+|                                   | but never matches                 |
++-----------------------------------+-----------------------------------+
+| :lang()                           |                                   |
++-----------------------------------+-----------------------------------+
+| :not()                            |  [1]_                             |
++-----------------------------------+-----------------------------------+
+| :first-child                      |  [1]_                             |
++-----------------------------------+-----------------------------------+
+| :last-child                       |  [1]_                             |
++-----------------------------------+-----------------------------------+
+| :only-child                       |  [1]_                             |
++-----------------------------------+-----------------------------------+
+| :root                             |  [1]_                             |
++-----------------------------------+-----------------------------------+
+| :empty                            |  [1]_                             |
++-----------------------------------+-----------------------------------+
+| :nth-child()                      |  [1]_                             |
++-----------------------------------+-----------------------------------+
+| :nth-last-child()                 |  [1]_                             |
++-----------------------------------+-----------------------------------+
+| :nth-of-type()                    |  [1]_                             |
++-----------------------------------+-----------------------------------+
+| :nth-last-of-type()               |  [1]_                             |
++-----------------------------------+-----------------------------------+
+| :first-of-type                    |  [1]_                             |
++-----------------------------------+-----------------------------------+
+| :last-of-type                     |  [1]_                             |
++-----------------------------------+-----------------------------------+
+| :only-of-type                     |  [1]_                             |
++-----------------------------------+-----------------------------------+
+
+FIXME: which selectors, combinators, at-rules.
+
+XML features
+------------
+
+FIXME: ``<xi:include href= parse= encoding=>``
+
+FIXME: ``<xi:fallback>``
+
+FIXME: ``xml:lang`` attribute
+
+FIXME: ``xml:space`` attribute
+
+Explicitly Unsupported features
+-------------------------------
+
+-  ``flowRoot`` element and its children - Inkscape, SVG 1.2 only.
+
+-  ``glyph-orientation-horizontal`` property - SVG1.1 only, removed in
+   SVG2
+
+-  The pseudo-classes ``:is()`` and ``:where()`` are part of Selectors
+   Level 4, which is still a working draft.
+
+Footnotes
+---------
+
+.. [1]
+   These structural pseudo-classes are implemented in rust-selectors,
+   which librsvg uses.
diff --git a/devel-docs/index.rst b/devel-docs/index.rst
index 34625c15..856a3920 100644
--- a/devel-docs/index.rst
+++ b/devel-docs/index.rst
@@ -2,21 +2,45 @@ Development guide for librsvg
 =============================
 
 .. toctree::
+   :caption: For Distributors and End Users
+   :maxdepth: 1
+
    product
+   features
    roadmap
+   compiling
+   security
+
+.. toctree::
+   :caption: Getting Started as a Contributor
+   :maxdepth: 1
+
    devel_environment
+   contributing
+
+.. toctree::
+   :caption: Understand the Code
+   :maxdepth: 1
+
    architecture
    adding_a_property
    memory_leaks
-   contributing
-   ci
+
+.. toctree::
+   :caption: Design Documents
+   :maxdepth: 1
+
    text_layout
    render_tree
    api_observability
    performance_tracking
-   releasing
+
+.. toctree::
+   :caption: Info for Maintainers
    :maxdepth: 1
-   :caption: Contents:
+
+   releasing
+   Continuous Integration <ci>
 
 Welcome to the developer's guide for librsvg.  This is for people who
 want to work on the development of librsvg itself, not for users of
@@ -34,8 +58,12 @@ icons and other graphical assets on the desktop.  Since then, it has
 evolved into a few different tools.
 
 - :doc:`product` - What comes out of this repository once it is compiled?
+- :doc:`features` - Supported elements, attributes, and properties.
 - :doc:`roadmap` - Ever-changing list of priorities for the
   maintainers; check this often!
+- :doc:`compiling` - Cross compilation, debug/release builds, special options.
+- :doc:`security` - Reporting security bugs, releases with security
+  fixes, security of dependencies.
 
 Getting started
 ---------------
@@ -49,8 +77,6 @@ Add basic info on cloning the repo, getting a gitlab account, forking.
 Understand the code
 -------------------
 
-Tour of the code - load a file, render it.
-
 Test suite - move tests/readme here?
 
 - `Documentation of the library's internals <https://gnome.pages.gitlab.gnome.org/librsvg/internals/librsvg/index.html>`_
@@ -80,6 +106,7 @@ Information for maintainers
 ---------------------------
 
 - :doc:`releasing`
+- :doc:`ci`
 
 Overview of the maintainer's workflow.
 
diff --git a/devel-docs/product.rst b/devel-docs/product.rst
index 4c9d4d3e..092284c7 100644
--- a/devel-docs/product.rst
+++ b/devel-docs/product.rst
@@ -95,3 +95,7 @@ Other artifacts
   <https://gnome.pages.gitlab.gnome.org/librsvg/doc/librsvg/index.html>`_,
   published online.  This is not built from the normal `make` process,
   but independently as part of the :doc:`ci` pipeline.
+
+- The rendered HTML version of this development guide.  This is not
+  built from the normal `make` process, but independently as part of
+  the :doc:`ci` pipeline.
diff --git a/devel-docs/security.rst b/devel-docs/security.rst
new file mode 100644
index 00000000..95b2f749
--- /dev/null
+++ b/devel-docs/security.rst
@@ -0,0 +1,216 @@
+Security
+========
+
+Reporting security bugs
+-----------------------
+
+Please mail the maintainer at federico@gnome.org. You can use the GPG
+public key from https://viruta.org/docs/fmq-gpg.asc to send encrypted
+mail.
+
+Librsvg releases with security fixes
+------------------------------------
+
+Librsvg releases have a version number like major.minor.micro. Note that
+releases with an odd minor number (e.g. 2.47.x since 47 is odd) are
+considered development releases and should not be used in production
+systems.
+
+The following list is only for stable release streams, where the minor
+number is even (e.g. 2.50.x).
+
+2.50.4
+~~~~~~
+
+RUSTSEC-2020-0146 - lifetime erasure in generic-array.
+
+2.48.10
+~~~~~~~
+
+CVE-2020-35905 - RUSTSEC-2020-0059 - data race in futures-util.
+
+CVE-2020-35906 - RUSTSEC-2020-0060 - use-after-free in futures-task.
+
+CVE-2021-25900 - RUSTSEC-2021-0003 - buffer overflow in smallvec.
+
+RUSTSEC-2020-0146 - lifetime erasure in generic-array.
+
+2.48.0
+~~~~~~
+
+CVE-2019-20446 - guard against exponential growth of CPU time from
+malicious SVGs.
+
+2.46.5
+~~~~~~
+
+RUSTSEC-2020-0146 - lifetime erasure in generic-array.
+
+CVE-2021-25900 - RUSTSEC-2021-0003 - buffer overflow in smallvec.
+
+See notes below on libcroco.
+
+2.44.17
+~~~~~~~
+
+RUSTSEC-2020-0146 - lifetime erasure in generic-array.
+
+CVE-2019-15554 - RUSTSEC-2019-0012 - memory corruption in smallvec.
+
+CVE-2019-15551 - RUSTSEC-2019-0009 - double-free and use-after-free in
+smallvec.
+
+CVE-2021-25900 - RUSTSEC-2021-0003 - buffer overflow in smallvec.
+
+See notes below on libcroco.
+
+2.44.16
+~~~~~~~
+
+CVE-2019-20446 - guard against exponential growth of CPU time from
+malicious SVGs.
+
+See notes below on libcroco.
+
+2.42.8
+~~~~~~
+
+CVE-2019-20446 - guard against exponential growth of CPU time from
+malicious SVGs.
+
+See notes below on libcroco.
+
+2.42.9
+~~~~~~
+
+CVE-2018-20991 - RUSTSEC-2018-0003 - double-free in smallvec.
+
+See notes below on libcroco.
+
+2.40.21
+~~~~~~~
+
+CVE-2019-20446 - guard against exponential growth of CPU time from
+malicious SVGs.
+
+See notes below on libcroco.
+
+2.40.18
+~~~~~~~
+
+CVE-2017-11464 - Fix division-by-zero in the Gaussian blur code.
+
+See notes below on libcroco.
+
+Earlier releases should be avoided and are not listed here.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**Important note on libcroco:** Note that librsvg 2.46.x and earlier use
+`libcroco <https://gitlab.gnome.org/Archive/libcroco/>`__ for parsing
+CSS, but that library is deprecated, unmaintained, and has open CVEs as
+of May 2021.
+
+If your application processes untrusted data, please avoid using librsvg
+2.46.x or earlier. The first release of librsvg that does not use
+libcroco is 2.48.0.
+
+Librsvg’s dependencies
+----------------------
+
+Librsvg depends on the following libraries implemented in memory-unsafe
+languages:
+
+-  **libxml2** - loading XML data.
+-  **cairo** - 2D rendering engine.
+-  **gdk-pixbuf** - decoding raster images like JPEG/PNG.
+-  **freetype2** - font renderer.
+-  **harfbuzz** - text shaping engine.
+
+And of course, their recursive dependencies as well, such as
+**glib/gio**, **libjpeg**, **libpng**.
+
+Security considerations for libxml2
+-----------------------------------
+
+Librsvg uses the following configuration for the SAX2 parser in libxml2:
+
+-  ``XML_PARSE_NONET`` - forbid network access.
+-  ``XML_PARSE_BIG_LINES`` - store big line numbers.
+
+As a special case, librsvg enables ``replaceEntities`` in the
+``_xmlParserCtxtPtr`` struct so that libxml2 will expand references only
+to internal entities declared in the DTD subset. External entities are
+disabled.
+
+For example, the following document renders two rectangles that are
+expanded from internal entities:
+
+::
+
+   <!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1 Basic//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11-basic.dtd" [
+     <!ENTITY Rect1 "<rect x='15' y='10' width='20' height='30' fill='blue'/>">
+     <!ENTITY Rect2 "<rect x='10' y='5' width='10' height='20' fill='green'/>">
+   ]>
+   <svg xmlns="http://www.w3.org/2000/svg" width="60" height="60">
+     &Rect1;
+     &Rect2;
+   </svg>
+
+However, an external entity like
+
+::
+
+     <!ENTITY foo SYSTEM "foo.xml">
+
+will generate an XML parse error and the document will not be loaded.
+
+Security considerations for Cairo
+---------------------------------
+
+Cairo is easy to crash if given coordinates that fall outside the range
+of its 24.8 fixed-point numbers. Librsvg is working on mitigating this.
+
+Security considerations for gdk-pixbuf
+--------------------------------------
+
+Gdk-pixbuf depends on **libpng**, **libjpeg**, and other libraries for
+different image formats.
+
+Security considerations for librsvg
+===================================
+
+**Built-in limits:** Librsvg has built-in limits for the following:
+
+-  Limit on the maximum number of loaded XML elements, set to 1,000,000
+   (one million). SVG documents with more than this number of elements
+   will fail to load. This is a mitigation for malicious documents that
+   would otherwise consume large amounts of memory, for example by
+   including a huge number of ``<g/>`` elements with no useful content.
+   This is set in the file ``src/limits.rs`` in the
+   ``MAX_LOADED_ELEMENTS`` constant.
+
+-  Limit on the maximum number of referenced elements while rendering.
+   The ``<use>`` element in SVG and others like ``<pattern>`` can
+   reference other elements in the document. Malicious documents can
+   cause an exponential number of references to be resolved, so librsvg
+   places a limit of 500,000 references (half a million) to avoid
+   unbounded consumption of CPU time. This is set in the file
+   ``src/limits.rs`` in the ``MAX_REFERENCED_ELEMENTS`` constant.
+
+Librsvg has no built-in limits on the total amount of memory or CPU time
+consumed to process a document. Your application may want to place
+limits on this, especially if it processes untrusted SVG documents.
+
+**Processing external files:** Librsvg processes references to
+external files by itself: XML XInclude, ``xlink:href`` attributes,
+etc. Please see the section "`Security and locations of referenced
+files
+<https://gnome.pages.gitlab.gnome.org/librsvg/Rsvg-2.0/class.Handle.html#security-and-locations-of-referenced-files>`_"
+in the reference documentation to see what criteria are used to accept
+or reject a file based on its location. If your application has more
+stringent requirements, it may need to sandbox its use of librsvg.
+
+**SVG features:** Librsvg ignores animations, scripts, and events
+declared in SVG documents. It always handles referenced images, similar
+to SVG’s `static processing
+mode <https://www.w3.org/TR/SVG2/conform.html#static-mode>`__.