[librsvg/wip/rust-api] Add toplevel docs for librsvg_crate

[Federico Mena Quintero <federico src gnome org>]

commit ff0c33f4e7a0fae061a1c4630a8a4e90de60d786
Author: Federico Mena Quintero <federico gnome org>
Date:   Mon Feb 18 12:57:13 2019 -0600

    Add toplevel docs for librsvg_crate

 librsvg/rsvg-handle.c    | 20 +++++++----
 librsvg_crate/src/lib.rs | 88 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 101 insertions(+), 7 deletions(-)
---
diff --git a/librsvg/rsvg-handle.c b/librsvg/rsvg-handle.c
index 336d522e..faf34352 100644
--- a/librsvg/rsvg-handle.c
+++ b/librsvg/rsvg-handle.c
@@ -30,11 +30,16 @@
  * RsvgHandle from an SVG file, or from a memory buffer that contains SVG data,
  * or in the most general form, from a #GInputStream that will provide SVG data.
  *
+ * Librsvg can load SVG images and render them to Cairo surfaces,
+ * using a mixture of SVG's [static mode] and [secure static mode].
+ * Librsvg does not do animation nor scripting, and can load
+ * references to external data only in some situations; see below.
+ *
  * Librsvg supports reading <link
  * href="https://www.w3.org/TR/SVG11/";>SVG 1.1</link> data, and is
  * gradually adding support for features in <link
  * href="https://www.w3.org/TR/SVG2/";>SVG 2</link>.  Librsvg also supports
- * SVGZ files, which is just an SVG stream compressed with the GZIP algorithm.
+ * SVGZ files, which are just an SVG stream compressed with the GZIP algorithm.
  *
  * # The "base file" and resolving references to external files
  *
@@ -56,11 +61,12 @@
  * When processing an SVG, librsvg will only load referenced files if they are
  * in the same directory as the base file, or in a subdirectory of it.  That is,
  * if the base file is <filename>/foo/bar/baz.svg</filename>, then librsvg will
- * only try to load referenced files (from SVG's "image" element, for example,
- * or from content included through XML entities) if those files are in
- * <filename>/foo/bar/<!-- -->*</filename> or in
- * <filename>/foo/bar/<!-- -->*<!-- -->/.../<!-- -->*</filename>.  This is so that malicious
- * SVG files cannot include files that are in a directory above.
+ * only try to load referenced files (from SVG's
+ * <literal>&lt;image&gt;</literal> element, for example, or from content
+ * included through XML entities) if those files are in <filename>/foo/bar/<!--
+ * -->*</filename> or in <filename>/foo/bar/<!-- -->*<!-- -->/.../<!--
+ * -->*</filename>.  This is so that malicious SVG files cannot include files
+ * that are in a directory above.
  *
  * The full set of rules for deciding which URLs may be loaded is as follows;
  * they are applied in order.  A referenced URL will not be loaded as soon as
@@ -81,7 +87,7 @@
  *   </listitem>
  *
  *   <listitem>
- *     If referenced URLs are absolute, rathen than relative, then they must
+ *     If referenced URLs are absolute, rather than relative, then they must
  *     have the same scheme as the base URL.  For example, if the base URL has a
  *     "<literal>file</literal>" scheme, then all URL references inside the SVG must
  *     also have the "<literal>file</literal>" scheme, or be relative references which
diff --git a/librsvg_crate/src/lib.rs b/librsvg_crate/src/lib.rs
index 508aa53a..7d462729 100644
--- a/librsvg_crate/src/lib.rs
+++ b/librsvg_crate/src/lib.rs
@@ -1,3 +1,91 @@
+//! Load and render SVG images into Cairo surfaces.
+//!
+//! This crate can load SVG images and render them to Cairo surfaces,
+//! using a mixture of SVG's [static mode] and [secure static mode].
+//! Librsvg does not do animation nor scripting, and can load
+//! references to external data only in some situations; see below.
+//!
+//! Librsvg supports reading [SVG 1.1] data, and is gradually adding
+//! support for features in [SVG 2].  Librsvg also supports SVGZ
+//! files, which are just an SVG stream compressed with the GZIP
+//! algorithm.
+//!
+//! # Basic usage
+//!
+//! * Create a [`LoadOptions`] struct.
+//! * Get an [`SvgHandle`] from the [`LoadOptions`].
+//! * Get a [`CairoRenderer`] from the [`SvgHandle`] and render to a Cairo context.
+//!
+//! [`LoadOptions`]: struct.LoadOptions.html
+//! [`SvgHandle`]: struct.SvgHandle.html
+//! [`CairoRenderer`]: struct.CairoRenderer.html
+//!
+//! # The "base file" and resolving references to external files
+//!
+//! When you load an SVG, librsvg needs to know the location of the "base file"
+//! for it.  This is so that librsvg can determine the location of referenced
+//! entities.  For example, say you have an SVG in <filename>/foo/bar/foo.svg</filename>
+//! and that it has an image element like this:
+//!
+//! ```ignore
+//! <image href="resources/foo.png" .../>
+//! ```
+//!
+//! In this case, librsvg needs to know the location of the toplevel
+//! `/foo/bar/foo.svg` so that it can generate the appropriate
+//! reference to `/foo/bar/resources/foo.png`.
+//!
+//! ## Security and locations of referenced files
+//!
+//! When processing an SVG, librsvg will only load referenced files if
+//! they are in the same directory as the base file, or in a
+//! subdirectory of it.  That is, if the base file is
+//! `/foo/bar/baz.svg`, then librsvg will only try to load referenced
+//! files (from SVG's `<image>` element, for example, or from content
+//! included through XML entities) if those files are in `/foo/bar/*`
+//! or in `/foo/bar/*/.../*`.  This is so that malicious SVG files
+//! cannot include files that are in a directory above.
+//!
+//! The full set of rules for deciding which URLs may be loaded is as follows;
+//! they are applied in order.  A referenced URL will not be loaded as soon as
+//! one of these rules fails:
+//!
+//! 1. All `data:` URLs may be loaded.  These are sometimes used to
+//! include raster image data, encoded as base-64, directly in an SVG
+//! file.
+//!
+//! 2. All other URL schemes in references require a base URL.  For
+//! example, this means that if you load an SVG with
+//! [`LoadOptions.read`](struct.LoadOptions.html#method.read) without
+//! providing a `base_url`, then any referenced files will not be
+//! allowed (e.g. raster images to be loaded from other files will not
+//! work).
+//!
+//! 3. If referenced URLs are absolute, rather than relative, then
+//! they must have the same scheme as the base URL.  For example, if
+//! the base URL has a "`file`" scheme, then all URL references inside
+//! the SVG must also have the "`file`" scheme, or be relative
+//! references which will be resolved against the base URL.
+//!
+//! 4. If referenced URLs have a "`resource`" scheme, that is, if they
+//! are included into your binary program with GLib's resource
+//! mechanism, they are allowed to be loaded (provided that the base
+//! URL is also a "`resource`", per the previous rule).
+//!
+//! 5. Otherwise, non-`file` schemes are not allowed.  For example,
+//! librsvg will not load `http` resources, to keep malicious SVG data
+//! from "phoning home".
+//!
+//! 6. A relative URL must resolve to the same directory as the base
+//! URL, or to one of its subdirectories.  Librsvg will canonicalize
+//! filenames, by removing "`..`" path components and resolving symbolic
+//! links, to decide whether files meet these conditions.
+//!
+//! [static mode]: https://www.w3.org/TR/SVG2/conform.html#static-mode
+//! [secure static mode]: https://www.w3.org/TR/SVG2/conform.html#secure-static-mode
+//! [SVG 1.1]: https://www.w3.org/TR/SVG11/
+//! [SVG 2]: https://www.w3.org/TR/SVG2/
+
 #![warn(unused)]
 extern crate cairo;
 extern crate gio;