diff options
Diffstat (limited to 'thumbnail')
| -rw-r--r-- | thumbnail/thumbnail-spec.sgml | 775 |
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> + + + |