summaryrefslogtreecommitdiffstats
path: root/thumbnail
diff options
context:
space:
mode:
authorVincent Untz <vuntz@gnome.org>2012-04-26 10:12:58 +0200
committerVincent Untz <vuntz@gnome.org>2012-05-11 14:05:48 +0200
commit27347f5fe2c06fe95f19a041941036a9f7413a08 (patch)
tree3feb507892e4777236182897a410e86d8749eb3b /thumbnail
parente5ddf8a14a46f0ae6bcf0775b4a1c54cc5ccde2d (diff)
downloadxdg-specs-27347f5fe2c06fe95f19a041941036a9f7413a08.tar.xz
thumbnail: Import thumbnail spec (version 0.7.0)
Diffstat (limited to 'thumbnail')
-rw-r--r--thumbnail/thumbnail-spec.sgml775
1 files changed, 775 insertions, 0 deletions
diff --git a/thumbnail/thumbnail-spec.sgml b/thumbnail/thumbnail-spec.sgml
new file mode 100644
index 0000000..576ffaf
--- /dev/null
+++ b/thumbnail/thumbnail-spec.sgml
@@ -0,0 +1,775 @@
+<!doctype article PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
+]>
+<article id="index">
+ <artheader>
+ <title>Thumbnail Managing Standard</title>
+ <releaseinfo>Version 0.7.0</releaseinfo>
+ <date>September 2004</date>
+ <authorgroup>
+ <author>
+ <firstname>Jens</firstname>
+ <surname>Finke</surname>
+ <affiliation>
+ <address>
+ <email>jens@gnome.org</email>
+ </address>
+ </affiliation>
+ </author>
+ <author>
+ <firstname>Olivier</firstname>
+ <surname>Sessink</surname>
+ <affiliation>
+ <address>
+ <email>olivier@lx.student.wau.nl</email>
+ </address>
+ </affiliation>
+ </author>
+ </authorgroup>
+ </artheader>
+
+ <sect1 id="history">
+ <title>History</title>
+ <itemizedlist>
+ <listitem><para>September 2004, Version 0.7.0</para>
+ <itemizedlist>
+ <listitem><para>Added readonly support for shared thumbnail repositories</para></listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem><para>September 2002, Version 0.6.1</para>
+ <itemizedlist>
+ <listitem><para>The subdirectories weren't a good idea. Removed them from
+ this version.</para></listitem>
+ <listitem><para>Updated link to the MD5 implementation.</para></listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem><para>September 2002, Version 0.6</para>
+ <itemizedlist>
+ <listitem><para>Added another sub directory level within the cache base
+ directories to avoid too much clutter.</para></listitem>
+ <listitem><para>State not to create thumbnails for files within the
+ thumbnail cache directory.</para></listitem>
+ <listitem><para>State when it's allowed to use thumbnails which haven't
+ been checked for validity.</para></listitem>
+ <listitem><para>Some typo fixes.</para></listitem>
+ <listitem><para>Introduction and conclusion rewrite.</para></listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem><para>Janurary 2002, Version 0.5</para>
+ <itemizedlist>
+ <listitem><para>Changed handling of different thumbnail sizes.</para></listitem>
+ <listitem><para>Renamed directories.</para></listitem>
+ <listitem><para>Propose using temporary filenames to avoid problems with
+ concurrent access.</para></listitem>
+ <listitem><para>Save thumbnails directly in the size dir without subdirs.</para></listitem>
+ <listitem><para>Added optional Thumb::Mimetype key</para></listitem>
+ <listitem><para>Give some more implementation notes.</para></listitem>
+ <listitem><para>Added "Thanks" section.</para></listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem><para>December 2001, Version 0.4</para>
+ <itemizedlist>
+ <listitem><para>Destinction between required and optional thumbnail attributes.
+ </para></listitem>
+ <listitem><para>Dropped distinction between global/local .thumbnail
+ directories.</para></listitem>
+ <listitem><para>Use MD5 hashes as thumbnail filename.</para></listitem>
+ <listitem><para>Initial attempt to handle concurrent accesses by different programs.
+ </para></listitem>
+ <listitem><para>Rewrote the "Deleting Thumbnails" section.
+ </para></listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem><para>August 2001, Version 0.3</para>
+ <itemizedlist>
+ <listitem><para>Rewrote this paper.</para></listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem><para>July 2001, Version 0.2</para>
+ <itemizedlist>
+ <listitem><para>Removed distinction between low/high quality thumbnails.</para></listitem>
+ <listitem><para>Seperate directory for failures.</para></listitem>
+ <listitem><para>Consider permission settings.</para></listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem><para>July 2001, Version 0.1</para>
+ <itemizedlist>
+ <listitem><para>First public release.</para></listitem>
+ </itemizedlist></listitem>
+ </itemizedlist>
+ </sect1>
+
+ <sect1 id="introduction">
+ <title>Introduction</title>
+ <para>
+ This paper deals with the permanent storage of previews for file
+ content. In particular, it tries to define a general and widely accepted
+ standard for this task. That way, it will be possible to share these so
+ called thumbnails across a large number of applications.</para>
+
+ <para>The current situation is, that nearly every program introdues a new
+ way of dealing with thumbnails. This results in the fact, that if the user
+ uses 4 or 5 different programs, he will end up with 4 or 5 thumbnails for
+ the same file. It's obvious that this is not only a waste of the users disc
+ space, but also makes the managing of large collections harder.
+ </para>
+
+ <para>But why does a program use thumbnails? Often these are presented in
+ file operation dialogs to give the user a hint what a certain file is
+ about. This can be seen as information in additon to the plain filename
+ which helps to identify the desired file faster and more easily. But the
+ idea isn't limited to images and file operation dialogs. The additional
+ value of previews is also applyable to other file types, like text
+ documents, pdf files, spreadsheets and so on. The reason why this isn't
+ deployed widely so far is, that it requires a lot of effort and is only of
+ little use for a single program (for example, if only the spreadsheet
+ program can create and view it's previews). But imagine if your filemanager
+ could display all these previews too, while you are browsing through your
+ filesystem.
+ </para>
+
+ <para>If there is a general accepted, file type independent way how to
+ deal with previews, the above sketched vision can come true. Everytime an
+ application saves a file it creates also a preview thumbnail for it. Other
+ programs can check if there is a thumbnail for a specific file and can
+ present it. This proposal tries to unifiy the thumbnail managing and
+ constitutes the first step to a better graphical desktop.
+ </para>
+ </sect1>
+ <sect1 id="issues">
+ <title>Issues To Solve</title>
+ <para>
+ There are some issues to solve to make this work correctly. Specifically
+ these are:
+ <itemizedlist>
+ <listitem>
+ <para>Find a place for permanent storing.</para>
+ </listitem>
+ <listitem>
+ <para>Preserve information about original image and make them easily
+ accessible without touching the original.</para>
+ </listitem>
+ <listitem>
+ <para>Provide the ability to handle different thumbnail sizes.</para>
+ </listitem>
+ <listitem>
+ <para>Take care of thumbnail generation failures.</para>
+ </listitem>
+ <listitem>
+ <para>Find a way to access thumbnails concurrently with different
+ programs.</para>
+ </listitem>
+ </itemizedlist>
+ All these things will be discussed in the next chapters and solutions
+ will be presented.
+ </para>
+ </sect1>
+ <sect1 id="directory">
+ <title>Thumbnail Directory</title>
+
+ <para> There exists exactly one place where all generated thumbnails will
+ be stored. This is the .thumbnails directory located in the users
+ home. </para>
+
+ <sect2 id="dirstructure"><title>Directory Structure</title>
+
+ <para> Within this dir there are living some other subdirectories showing
+ in the following listing:
+ </para>
+ <programlisting>
+~/.thumbnails/
+~/.thumbnails/normal
+~/.thumbnails/large/
+~/.thumbnails/fail/
+ </programlisting>
+ <para> The meaning of the directories are as follows:</para>
+ <itemizedlist>
+ <listitem>
+ <para>Normal: The default place for storing thumbnails. The image
+ size must not exceed 128x128 pixel. Programs which need smaller
+ resolutions should read and write the 128x128 thumbnails and
+ downscale them afterwards to the desired dimension. See <link
+ linkend="creation">Thumbnail Creation</link> for more details.</para>
+ </listitem>
+ <listitem>
+ <para>Large: The previous notes apply to this directory too, except
+ that the thumbnail size must be 256x256 pixel. </para>
+ </listitem>
+ <listitem>
+ <para>Fail: This directory is used to store information about files
+ where a thumbnail couldn't be generated. See <link
+ linkend="failures">Thumbnail Generation Failure</link> for more
+ details.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <note>
+ <para>
+ You must not create/save thumbnails for any files you will find in these
+ directories. Instead load and use these files directly.
+ </para>
+ </note>
+ </sect2>
+ </sect1>
+
+ <sect1 id="creation"> <title>Thumbnail Creation</title>
+
+ <sect2><title>Fileformat</title>
+
+ <para> The image format for thumbnails is the <ulink
+ url="http://www.w3.org/TR/REC-png">PNG format</ulink>, regardless in
+ which format the original file was saved. To be more specific it must
+ be a 8bit, non-interlaced PNG image with full alpha transparency (means
+ 255 possible alpha values). However, every program should use the best
+ possible quality when creating the thumbnail. The exact meaning of this
+ is left to the specific program but it should consider applying
+ antialising.</para>
+ </sect2>
+
+ <sect2 id="addinfos"><title>Thumbnail Attributes</title>
+
+ <para>Beside the storage of the raw graphic data its often useful to
+ provide further information about a file in its thumbnail. Especially
+ file size, image dimension or image type are often used in graphic
+ programs. If the thumbnail provides such information it avoids any need
+ to access the original file and thus makes the loading faster.</para>
+
+ <para> The PNG format provides a mechanism to store arbitrary text strings
+ together with the image. It uses a simple key/value scheme, where some
+ keys are already predefined like Title, Author and so on (see <ulink
+ url="http://www.w3.org/TR/REC-png#C.tEXt">section 4.2.7</ulink> of the
+ PNG standard). This mechanism is used to store additional
+ thumbnail attributes.</para>
+
+ <para> Beside the png format there is another internet standard which is
+ important in this context: the <ulink
+ url="http://community.roxen.com/developers/idocs/rfc/rfc2396.html">URI
+ mechanism</ulink>. It is used to specify the location of the original
+ file. Only canonical absolute URIs (including the scheme) are used to
+ determine the original uniquely.</para>
+
+ <para>The following keys and their appropriate values must be provided by
+ every program which supports this standard. All the keys are defined in
+ the "Thumb::" namespace or if already defined by the PNG standard
+ without any namespace.</para>
+ <para>
+ <table>
+ <title>Required attributes.</title>
+ <tgroup cols="2" align="left">
+ <thead>
+ <row>
+ <entry>Key</entry><entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>Thumb::URI</entry> <entry>The absolute canonical uri for
+ the original file. (eg file:///home/jens/photo/me.jpg)</entry>
+ </row>
+ <row>
+ <entry>Thumb::MTime</entry><entry>The modification time of the
+ original file (as indicated by stat, which is represented as
+ seconds since January 1st, 1970).</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+
+ <para>If it's not possible to obtain the modification time of the
+ original then you shouldn't store a thumbnail for it at all. The
+ mtime is needed to check if the thumbnail is valid yet (see <link
+ linkend="modifications">Detect modifications</link>). Otherwise we
+ can't guarantee the content corresponds to the original and must
+ regenerate a thumb every time anyway.</para>
+
+ <para>
+ <table>
+ <title>Additional attributes.</title>
+ <tgroup cols="2" align="left">
+ <thead>
+ <row>
+ <entry>Key</entry><entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>Thumb::Size</entry><entry>File size in bytes of the original
+ file.</entry>
+ </row>
+ <row>
+ <entry>Thumb::Mimetype</entry><entry>The file mimetype. </entry>
+ </row>
+ <row>
+ <entry>Description</entry><entry>This key is predefined by the PNG
+ standard. It provides a general description about the thumbnail
+ content and can be used eg. for accessability needs.</entry>
+ </row>
+ <row>
+ <entry>Software</entry><entry>This key is predefined by the PNG
+ standard. It stores the name of the program which generated
+ the thumbnail.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+
+ <para>There are surely some situations where further information are
+ desired. Eg. the Gimp could save the number of layers an image has or
+ something like this. So if an application wants to save more
+ information it is free to do so. It should use a key in its own
+ namespace (to avoid clashes) prefixed by X- to indicate that this is an
+ extension. Eg. Gimp could save the layer info in the key
+ X-GIMP::Layers.</para>
+
+ <para> However, regarding to the filetype there are some keys which are
+ generally useful. If a program can obtain information for the following
+ keys it should provide them.</para>
+ <para>
+ <table>
+ <title>Filetype specific attributes.</title>
+ <tgroup cols="2" align="left">
+ <thead>
+ <row>
+ <entry>Key</entry><entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>Thumb::Image::Width</entry><entry>The width of the original
+ image in pixel.</entry>
+ </row>
+ <row>
+ <entry>Thumb::Image::Height</entry><entry>The height of the original
+ image in pixel.</entry>
+ </row>
+ <row>
+ <entry>Thumb::Document::Pages</entry><entry>The number of pages
+ the original document has.</entry>
+ </row>
+ <row>
+ <entry>Thumb::Movie::Length</entry><entry>The length of the movie
+ in seconds.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+
+
+ <para>With this approach a program doesn't have the guarantee that certain
+ keys are stored in a thumbnail, because it may have been created by
+ another application. If possible, a program should cope with the lack
+ of information in such a case instead of recreating the thumbnail and
+ the missing information.
+ </para>
+ </sect2>
+
+ <sect2 id="thumbsize"><title>Thumbnail Size</title>
+ <para>
+ As already mentionend in the <link linkend="directory">Thumbnail
+ Directory</link> section there exists two suggested sizes you can use
+ for your thumbnails: 128x128 and 256x256 pixel. The idea is that if a
+ program uses another size for it's previews it loads one of the two
+ versions and scales them down to the desired size. Similar, when
+ creating a thumbnail it scales the file down to 128x128 first (or
+ 256x256), saves it to disk and then reduce the size further. This
+ mechanism enables all programs to obtain their desired previews in an
+ easy and fast way. </para>
+
+ <para> However, these are suggestions. Implementations should cope also
+ with images that are smaller than the suggested size for the normal and
+ large subdirectories. Depending on the difference between the actual
+ and the desired size, they can either use the smaller one found in the
+ cache and scale it down or recreate a thumbnail with the proposed size
+ for this directory.</para>
+
+ <para> If a program needs a thumbnail for an image file which is
+ smaller than 128x128 pixel it doesn't need to save it at all.</para>
+
+ <note>
+ <para> All sizes define just a rectangle area where the thumbnail must
+ fit in. Don't scale every image to a rectangular thumbnail but preserve
+ the ratio instead!</para></note>
+ </sect2>
+ </sect1>
+
+ <sect1 id="thumbsave"><title>Thumbnail Saving</title>
+
+ <para>The thumbnail filename is determined by a hashfunction. This proposal
+ utilizes <ulink
+ url="http://community.roxen.com/developers/idocs/rfc/rfc1321.html">MD5</ulink>
+ as hash mechanism in the following way.
+ </para>
+ <orderedlist>
+ <listitem>
+ <para>You need the absolute canonical URI for the original file, as stated
+ in <ulink
+ url="http://community.roxen.com/developers/idocs/rfc/rfc2396.html">URI RFC
+ 2396</ulink>. In particular this defines to use three '/' for local 'file:'
+ resources (see example below).</para>
+ </listitem>
+ <listitem>
+ <para>Calculate the MD5 hash for this URI. Not for the file it points to!
+ This results in a 128bit hash, which is representable by a hexadecimal
+ number in a 32 character long string.</para>
+ </listitem>
+ <listitem>
+ <para>To get the final filename for the thumbnail just append a '.png' to
+ the hash string. According to the dimension of the thumbnail you must store
+ the result either in ~/.thumbnails/normal or ~/.thumbnails/large.
+ </para>
+ </listitem>
+ </orderedlist>
+ <para>
+ An example will illustrate this:
+ </para>
+ <example><title>Saving a thumbnail</title>
+ <para>
+ Consider we have a file ~/photos/me.png. We want to create a thumbnail with
+ a size of 128x128 pixel for it, which means it will be stored in the
+ ~/.thumbnails/normal directory. The absolute canonical URI for the file in
+ this example is file:///home/jens/photos/me.png.
+ </para>
+ <para>The MD5 hash for the uri as a hex string is
+ c6ee772d9e49320e97ec29a7eb5b1697. Following the steps above this
+ results in the following final thumbnail path:</para>
+<programlisting>
+/home/jens/.thumbnails/normal/c6ee772d9e49320e97ec29a7eb5b1697.png
+</programlisting>
+ </example>
+
+ <sect2><title>Permissions</title> <para>A few words regarding permissions:
+ All the directories including the ~/.thumbnails directory must have set
+ their permissions to 700 (this means only the owner has read, write and
+ execute permissions, see "man chmod" for details). Similar, all the files
+ in the thumbnail directories should have set their permissions to 600. This
+ way we assure that if a user creates a thumbnail for a file where only he
+ has read-permissions no other user can take a glance on it through the
+ backdoor with the thumbnails.</para>
+ </sect2>
+
+ <sect2><title>Concurrent Thumbnail Creation</title> <para>An important goal
+ of this paper is to enable programs to share their thumbnails. This
+ includes the occurences of concurrent accesses to the cache by different
+ programs. Problems arise if two programs try to create a thumbnail for the
+ same file at the same time. Because of this the following procedure is
+ suggested: </para>
+ <orderedlist>
+ <listitem><para>Check if the thumbnail already exists and if it's valid.</para>
+ </listitem>
+ <listitem><para>If the above conditions are not fulfiled create the
+ thumbnail and write it under a temporary filename onto the disk.</para>
+ </listitem>
+ <listitem><para>Rename the temporary file to the thumbnail filename. Since
+ this is an atomic operation the new thumbnail is either completely written
+ or not.</para>
+ </listitem>
+ </orderedlist>
+ <para>
+ This way the worst case is that a thumbnail will be written twice. However,
+ the thumbnail is in a sane state at any time. </para>
+ <note>
+ <para> The temporary file should be placed into the same directory as the
+ final thumbnail, because then you are sure that they lay on the same
+ filesystem. This guarantees a fast renaming of the temporary file. Using a
+ combination of programname, process id and eg. first characters from the
+ hash string should give a fairly unique temporary name.</para></note>
+ </sect2>
+
+ <sect2><title>Advantages Of This Approach</title>
+
+ <para>Previously versions of this standard used a very different
+ mechanism for storing thumbnails. But this one has some very important
+ advantages:</para>
+ <orderedlist>
+ <listitem>
+ <para>Works for all kinds of possible file locations, since its based
+ only on the textual URI representation of a file. This way files that are
+ located on the locale filesystem or a samba, http, ftp or WebDAV server
+ can be treated equally.</para>
+ </listitem>
+ <listitem>
+ <para>It results in a flat directory hierarchy which assures fast
+ access. Since the hash is always 32 characters long the thumbnail
+ filename is exactly 36 characters long for every possible file (including
+ the '.png' suffix).</para>
+ </listitem>
+ <listitem>
+ <para>Due to the usage of the MD5 hash its unlikely that there occur
+ clashes between two different thumbnails, even if it's theoretically
+ possible. But the probability is very low and can be ignored in this
+ context. The worst case would be that a thumbnail overwrites another
+ valid one. Ok, if they have exactly the same modification time it is
+ theoretically possible too that a wrong thumbnail for a file will be
+ displayed (see <link linkend="modifications">Detect
+ Modifications</link>).
+ </para>
+ </listitem>
+ <listitem>
+ <para>It's very easy to implement.</para>
+ </listitem>
+ </orderedlist>
+ <note><para>There do exist a lot of different library implementations for
+ the MD5 hash algorithm. If you don't want to add yet another library
+ dependency to support thumbnailing in your program you can eg. use the
+ <ulink url="ftp://mirror.cs.wisc.edu/pub/mirrors/ghost/packages/md5.tar.gz">RFC 1321
+ implementation</ulink> by L. Peter Deutsch. It adds only 1.5kb sourcecode
+ in two files to your project and can be used without much
+ restrictions.</para>
+ </note>
+ </sect2>
+ </sect1>
+
+ <sect1 id="modifications"><title>Detect Modifications</title>
+
+ <para> One important thing is to assure that the thumbnail image displays
+ the same information than the original, only in a downscaled
+ version. To make this possible we use the modification time stored in
+ the required <link linkend="addinfos">'Thumb::MTime' key</link> and
+ check if it's equal the current modification time of the
+ original. If not we must recreate the thumbnail. <example><title>Algorithm
+ to check for modification.</title>
+ <programlisting>
+if (file.mtime != thumb.MTime) {
+ recreate_thumbnail ();
+}
+ </programlisting>
+ </example></para>
+
+ <note><para> It is not sufficient to do a <prompt>file.mtime >
+ thumb.MTime</prompt> check. If the user moves another file
+ over the original, where the mtime changes but is in fact lower than
+ the thumbnail stored mtime, we won't recognize this modification.
+ </para></note>
+
+ <para> If for some reason the thumbnail doesn't have the 'Thumb::MTime'
+ key (although it's required) it should be recreated in any
+ case.</para>
+
+ <note>
+ <para>There are certain circumstances where a program can't or don't want
+ to update a thumbnail (eg. within a history view of your recently edited
+ files). This is legally but it should be indicated to the user that an
+ thumbnail is maybe outdated or not even checked for modifications.</para>
+ </note>
+ </sect1>
+
+
+ <sect1 id="failures"><title>Thumbnail Creation Failures</title>
+ <para>Due to several reasons its possible that the generation of a thumbnail fails:
+ <itemizedlist>
+ <listitem>
+ <para>The file format is unknown and cannot be loaded by the program.</para>
+ </listitem>
+ <listitem>
+ <para>The file format is known but the file is somehow broken and
+ thus cannot be read.</para>
+ </listitem>
+ <listitem>
+ <para> The generation of a thumbnail would take too long, due to the
+ large size of the file.</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>Under some circumstances a program want to preserve the information
+ that the creation failed. Eg to avoid trying it again and again in the
+ future. The problem is that the above mentioned issues are often program
+ specific. Eg Nautilus can't read the native Gimp format xcf but of
+ course Gimp can and could create thumbnails for them. Or one program
+ uses a broken TIFF implementation which refuses to load an TIFF image
+ but another one uses a correct implementation.</para>
+
+ <para> Because of this, its best to save these failure information per
+ program. In the <link linkend="dirstructure">Directory Structure</link>
+ section there is already a 'fail' directory mentioned, which should be
+ used for this. Every program must create a directory of it's own there
+ with the name of the program appended by the version number
+ (eg. <prompt>~/.thumbnails/fail/nautilus-1.0</prompt>).</para>
+
+ <para> For every thumbnail generation failure the program creates an empty
+ PNG file. If it's possible to obtain some additional information from
+ the image (see <link linkend="addinfos">Store Additional
+ Information</link>) they should be stored together with the thumbnail
+ too, at least the required 'Thumb::MTime' and 'Thumb::URI' keys must be
+ set. The procedure for the saving of such a fail image is the same as
+ described in <link linkend="thumbsave">Thumbnail Saving</link>. You must
+ only use the application specific directory within
+ <prompt>~./thumbnails/fail</prompt> instead of the size specific ones.
+ </para>
+ <para>This approach has the advantage that a program can access information
+ about a thumbnail creation failure the same way as it does with
+ successfully generated ones.</para>
+ </sect1>
+
+ <sect1 id="delete"><title>Deleting Thumbnails</title>
+
+ <para> The deletion of a thumbnail is somehow tricky. A general rule is
+ that a thumbnail should be deleted if the orginial file doesn't exist
+ anymore (Note: If it was only modified the thumbnail should be recreated
+ instead). There are different ways how this can be achieved:</para>
+ <orderedlist>
+ <listitem>
+ <para>If a filemanger is aware of this standard and deletes a file it
+ could take care of deleting the thumbnail too.</para>
+ </listitem>
+ <listitem>
+ <para>A daemon runs in the background which cleans up the cache in certain
+ intervalls.</para>
+ </listitem>
+ <listitem>
+ <para>The user can call a managing tool which lists all the thumbnails
+ together with their original file paths. From there he can delete single
+ images, all images where the orignial doesn't exist anymore or all
+ images older than eg. 30 days.</para>
+ </listitem>
+ </orderedlist>
+ <para>Another problem is that there are some URI schemes where it isn't
+ directly possible to determine if the file exists or not. Eg. this applies
+ to all the internet related schemes like http:, ftp: and so on when you
+ don't have an internet connection. The same applies to removable media
+ eg. a cdrom. </para>
+
+ <para>The above mentioned managing tools should therefore consider
+ the following rules:</para>
+ <orderedlist>
+ <listitem>
+ <para>If the URI scheme specifies a local file (like the file: scheme)
+ then it should check if the original file exists. If it doesn't exist
+ anymore the program should delete the thumbnail.</para>
+ </listitem>
+ <listitem>
+ <para>For all internet related schemes (like http: or ftp:) delete the
+ thumbnail if it hasn't been accessed within a certain user defined
+ time period (can default to 30 days).</para>
+ </listitem>
+ <listitem>
+ <para>Removable medias should be considered too. Although this can't
+ work for all systems in all cases reliable there are some heuristics
+ which can be used. Eg. checking the fstab configuration file and look
+ for the mount point of /dev/fd0 (floppy disk) or check if the CD-Rom
+ drive is mounted under /cdrom. Thumbnails for removable media files
+ should be handled as in the previous point.</para>
+ </listitem>
+ </orderedlist>
+ </sect1>
+
+ <sect1 id="shared"><title>Shared Thumbnail repositories</title>
+ <para>
+ In some situations it is desirable to have a shared thumbnail repository. This
+ is a read-only collection of thumbnails that is shared among different users or different
+ computers. For example a CD-ROM with images, could include the thumbnails for
+ these images such that they do not need to be generated for every user or computer
+ accessing this CD-ROM.
+ </para>
+
+ <para>
+ Because the URI of such an image is not constant (a CD-ROM for example can be mounted
+ at different locations) the thumbnails should be in a relative path from the original
+ image.
+ </para>
+
+ <para>
+ The location for shared thumbnails will be
+ </para>
+ <programlisting>.sh_thumbnails/</programlisting>
+
+ <para>Within this directory are the same subdirectories as in the global thumbnail directory.</para>
+ <programlisting>.sh_thumbnails/
+ .sh_thumbnails/normal/
+ .sh_thumbnails/large/
+ .sh_thumbnails/fail/
+ </programlisting>
+ <para>The meaning of these directories is identical to their meaning in the global directory.</para>
+
+ <para>The filename of the thumbnail is also in the shared thumbnail repository the md5sum
+ of the URI. But, because the URI is possibly not constant, only the filename part of the
+ URI should be used, no directory parts.</para>
+
+ <sect2><title>Creating thumbnails in a shared thumbnail repository</title>
+ <para>
+ A shared thumbnail repository should be considered read-only. A program should never
+ add or update a thumbnail in the shared thumbnail repository. Such a repository should only
+ be created on special request by the user. If a thumbnail is outdated or corrupt, a program
+ should create a new thumbnail in the personal thubmnail repository, and not update the shared
+ thumbnail repository.
+ </para>
+
+ <para>
+ If the user specific requested the creation of a shared thumbnail repository, the thumbnails
+ can be created. Because the URI for shared images is possibly not constant, this means that
+ the full URI can not be stored in the thumbnail. The URI field should, therefore, contain only
+ the filename, and no directory parts. All other properties, however, should be the
+ same as in the personal repository, including the size. The permissions for shared thumbnails
+ should be the same as their original images.</para>
+
+ </sect2>
+ <sect2><title>Loading thumbnails from a shared thumbnail repository</title>
+ <para>
+ When loading thumbnails from a shared thumbnail repository, the personal repository
+ has a higher priority. If a thumbnail exists in the personal thumbnail repository, this
+ thumbnail should be used, and not the thumbnail from the shared repository.
+ </para>
+ <para>
+ There is one exception to this rule. If the thumbnail in the personal thumbnail repository
+ is outdated or corrupt, the thumbnail from the shared repository should be checked. If this
+ thumbnail is correct, the thumbnail in the personal repository can be deleted and the thumbnail
+ from the shared collection can be used.
+ </para>
+ </sect2>
+
+ </sect1>
+
+ <sect1 id="conclusion"><title>Conclusion</title>
+
+ <para> The proposed way of dealing with file previews fulfiles the
+ requirements of a file type independent preview cache. It is relative
+ easy to use, understand and implement. All these are important facts to
+ allow it's wide spread.</para>
+
+ <para>The next step will be to take these ideas to the applications. If a
+ lot of users, coders and maintainers will cooperate on this, we can reach a
+ new level of usability.</para>
+ </sect1>
+
+ <sect1 id="thanks"><title>Thanks</title>
+
+ <para>The following people helped me to write this paper with a lot of
+ suggestions, good ideas and constructive critism. They found serious bugs
+ and problems in previous versions or helped me in another way. Thank you
+ very much:
+ </para>
+ <para>
+ Darin Adler (Gnome/Nautilus),
+ Alexander Larsson (Gnome/Nautilus),
+ Thomas Leonard (Rox Desktop),
+ Sven Neumann (Gimp),
+ Havoc Pennington (Gnome/freedesktop.org),
+ Malte Starostik (KDE),
+ Owen Taylor (GTK),
+ and all I forgot to mention here.
+ </para>
+ </sect1>
+
+ <sect1 id="links"><title>Links</title>
+ <itemizedlist>
+ <listitem>
+ <para>URI standard: <ulink
+ url="http://community.roxen.com/developers/idocs/rfc/rfc2396.html">http://community.roxen.com/developers/idocs/rfc/rfc2396.html</ulink></para>
+ </listitem>
+ <listitem>
+ <para>PNG standard: <ulink
+ url="http://www.w3.org/TR/REC-png">http://www.w3.org/TR/REC-png</ulink></para>
+ </listitem>
+ <listitem>
+ <para>MD5 hash algorithm: <ulink
+ url="http://community.roxen.com/developers/idocs/rfc/rfc1321.html">http://community.roxen.com/developers/idocs/rfc/rfc1321.html</ulink>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </sect1>
+</article>
+
+
+