[gnome-desktop] thumbnailer: Add documentation on thumbnailers and .thumbnailer files

[Philip Withnall <pwithnall src gnome org>]

commit f5561d740c26656da7796fdfd3163ce7ce00da31
Author: Philip Withnall <philip withnall collabora co uk>
Date:   Thu Nov 7 12:01:58 2013 +0000

    thumbnailer: Add documentation on thumbnailers and .thumbnailer files
    
    https://bugzilla.gnome.org/show_bug.cgi?id=711604

 libgnome-desktop/gnome-desktop-thumbnail.c |  102 ++++++++++++++++++++++++++++
 1 files changed, 102 insertions(+), 0 deletions(-)
---
diff --git a/libgnome-desktop/gnome-desktop-thumbnail.c b/libgnome-desktop/gnome-desktop-thumbnail.c
index f3cc60e..c9baeac 100644
--- a/libgnome-desktop/gnome-desktop-thumbnail.c
+++ b/libgnome-desktop/gnome-desktop-thumbnail.c
@@ -24,6 +24,108 @@
  * Author: Alexander Larsson <alexl redhat com>
  */
 
+/**
+ * SECTION:gnome-desktop-thumbnail
+ * @short_description: Generates and looks up thumbnails of files and
+ * directories
+ * @stability: Unstable
+ * @include: libgnome-desktop/gnome-desktop-thumbnail.h
+ *
+ * #GnomeDesktopThumbnailFactory allows generation and loading of thumbnails for
+ * local and remote files and directories. It uses a collection of programs
+ * called <firstterm>thumbnailers</firstterm>, each one generating thumbnails
+ * for a specific set of content-types of files. For example,
+ * <application>totem-video-thumbnailer</application> generates thumbnails for
+ * video files using GStreamer; <application>evince-thumbnailer</application>
+ * generates thumbnails for PDFs and other document files. If no specific
+ * thumbnailer exists for a file, or if the thumbnailer fails, gdk-pixbuf is
+ * used as a fallback.
+ *
+ * To generate a thumbnail, an appropriate thumbnailer program is selected then
+ * executed, passing it the URI of the file to thumbnail, plus a path to write
+ * the thumbnail image to. If thumbnailing succeeds, the thumbnailer should have
+ * written the image to disk before terminating; but if thumbnailing fails, no
+ * image should be written, and the thumbnailer should return a non-zero exit
+ * status. #GnomeDesktopThumbnailFactory will then fall back to using gdk-pixbuf
+ * to generate a thumbnail, if possible.
+ *
+ * Thumbnailers are chosen by examining a series of
+ * <filename>.thumbnailer</filename> files in
+ * <filename><replaceable>$PREFIX</replaceable>/share/thumbnailers</filename>.
+ * Each is in a simple key-file format:
+ * <informalexample><programlisting>
+ * [Thumbnailer Entry]
+ * TryExec=evince-thumbnailer
+ * Exec=evince-thumbnailer -s %s %u %o
+ * MimeType=application/pdf;application/x-bzpdf;application/x-gzpdf;
+ * </programlisting></informalexample>
+ *
+ * The <filename>.thumbnailer</filename> format supports three keys:
+ * <variablelist>
+ * <varlistentry><term><code>TryExec</code></term><listitem><para>
+ * Optional. The name of the the thumbnailer program in the current
+ * <envar>$PATH</envar>. This allows the calling code to quickly check whether
+ * the thumbnailer exists before trying to execute it.
+ * </para></listitem></varlistentry>
+ * <varlistentry><term><code>Exec</code></term><listitem><para>
+ * Required. The command to execute the thumbnailer. It supports a few different
+ * parameters which are replaced before calling the thumbnailer:
+ * <replaceable>%u</replaceable> is the URI of the file being thumbnailed;
+ * <replaceable>%i</replaceable> is its path; <replaceable>%o</replaceable>
+ * is the path of the image file to be written to;
+ * <replaceable>%s</replaceable> is the maximum desired size of the thumbnail
+ * image (the maximum width or height, in pixels); and
+ * <replaceable>%%</replaceable> is a literal percent character.
+ * </para></listitem></varlistentry>
+ * <varlistentry><term><code>MimeType</code></term><listitem><para>
+ * Required. A semicolon-separated list of MIME types which the thumbnailer
+ * supports generating thumbnails for.
+ * </para></listitem></varlistentry>
+ * </variablelist>
+ *
+ * So in the example <filename>.thumbnailer</filename> file above, the command
+ * passes the requested thumbnail size, then the input file’s URI, then the
+ * path for the output image file to
+ * <application>evince-thumbnailer</application>.
+ *
+ * The code to examine and call a thumbnailer is contained in
+ * #GnomeDesktopThumbnailFactory, which handles looking up the right thumbnailer
+ * script, building and executing the command for it, and loading the resulting
+ * thumbnail image into a #GdkPixbuf.
+ *
+ * Thumbnail caching is also supported by #GnomeDesktopThumbnailFactory. When
+ * calling a thumbnailer, the path passed for the output image file is in
+ * <filename><envar>$XDG_CACHE_HOME</envar>/thumbnails/
+ * <replaceable>$SIZE</replaceable>/</filename>. The cached image file is given
+ * a (probably) unique filename, generated by hashing the original file’s URI,
+ * so the thumbnail can be looked up in future. #GnomeDesktopThumbnailFactory
+ * supports two sizes of thumbnails: %GNOME_DESKTOP_THUMBNAIL_SIZE_NORMAL and
+ * %GNOME_DESKTOP_THUMBNAIL_SIZE_LARGE. Normal thumbnails are up to 128×128
+ * pixels, whereas large thumbnails are up to 256×256 pixels. Thumbnails which
+ * are larger than this are scaled down before being cached, and non-square
+ * thumbnails are scaled so their largest dimension is at most 128 or 256
+ * pixels.
+ *
+ * #GnomeDesktopThumbnailFactory also handles failed thumbnails. If a
+ * thumbnailer can’t generate a thumbnail for a file (e.g. because the file is
+ * corrupt or because the right video codecs aren’t available), it returns a
+ * non-zero exit status. The thumbnail factory then writes an entry to
+ * <filename><envar>$XDG_CACHE_HOME</envar>/thumbnails/fail/
+ * gnome-thumbnail-factory/</filename> which is named after the hash of the
+ * input file URI (just like a successful cached thumbnail). For future queries
+ * for thumbnails for that file, #GnomeDesktopThumbnailFactory can immediately
+ * return an error after looking up the fail entry.
+ *
+ * If a file changes content, #GnomeDesktopThumbnailFactory will generate a new
+ * thumbnail because each cached image has associated metadata (stored as PNG
+ * tEXt keys) storing the full URI of the thumbnailed file (to check for hash
+ * collisions) and its last modification time at the point of thumbnailing. If
+ * the stored modification time doesn’t match the file’s current one, a new
+ * thumbnail is generated.
+ *
+ * Since: 2.2
+ */
+
 #include <config.h>
 #include <sys/types.h>
 #include <sys/stat.h>