From 4f4df42ca9cc8b93ce21cc55f29619abad8600a3 Mon Sep 17 00:00:00 2001 From: Kenny Levinsen Date: Wed, 24 Jun 2020 01:12:41 +0200 Subject: thumbnails: Clarify shared thumbnail URIs --- thumbnail/thumbnail-spec.sgml | 92 ++++++++++++++++++++++++++++--------------- 1 file changed, 60 insertions(+), 32 deletions(-) diff --git a/thumbnail/thumbnail-spec.sgml b/thumbnail/thumbnail-spec.sgml index bbdbe5b..e5bf4e7 100644 --- a/thumbnail/thumbnail-spec.sgml +++ b/thumbnail/thumbnail-spec.sgml @@ -277,11 +277,12 @@ $XDG_CACHE_HOME/thumbnails/fail/ Beside the png format there is another internet standard which is important in this context: the URI - mechanism. 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. - + url="https://www.ietf.org/rfc/rfc2396.txt">URI mechanism. It + is used to specify the location of the original file. For the global + thumbnail repository, canonical absolute URIs (including the scheme) + are used to determine the original uniquely. In shared thumbnail + repositories, URIs are relative to the repository used. + 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 @@ -297,8 +298,11 @@ $XDG_CACHE_HOME/thumbnails/fail/ - Thumb::URI The absolute canonical uri for - the original file. (eg file:///home/jens/photo/me.jpg) + Thumb::URI The URI for the original file. + For global thumbnails, this is an absolute canonical URI (e.g. + file:///home/jens/photo/me.jpg). For shared thumbnail + repositories, the URI is relative to the repository prefixed with + ./ (e.g. ./picture.jpg). Thumb::MTimeThe modification time of the @@ -438,11 +442,14 @@ $XDG_CACHE_HOME/thumbnails/fail/ - You need the absolute canonical URI for the original file, as stated - in URI RFC - 2396. In particular this defines to use three '/' for local 'file:' - resources (see example below). + For global thumbnails, you need the absolute canonical URI for the + original file, as stated in + URI RFC 2396. In particular this defines to use three '/' for local 'file:' + resources (see example below). For shared thumbnails, you need a canonical URI relative + to the shared thumbnail repository, comprised of a single "./"-prefixed and properly + encoded path segment for the filename, e.g. "./picture.png". The "./" prefix is required + to simplify encoding, and use of the canonical, minimally encoded form of the URI is + required to avoid mismatches between thumbnail generator and thumbnail reader. Calculate the MD5 hash for this URI. Not for the file it points to! @@ -460,7 +467,7 @@ $XDG_CACHE_HOME/thumbnails/fail/ An example will illustrate this: - Saving a thumbnail + Saving a global thumbnail 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 @@ -472,6 +479,21 @@ $XDG_CACHE_HOME/thumbnails/fail/ results in the following final thumbnail path: /home/jens/.cache/thumbnails/normal/c6ee772d9e49320e97ec29a7eb5b1697.png + + + Saving a shared thumbnail + + Consider we have a file /mnt/pictures/picture.png. We want to create a thumbnail with + a size of 128x128 pixel for it, which means it will be stored in the + /mnt/pictures/.sh_thumbnails/normal directory. The relative canonical URI for the file in + this example is ./picture.png. + + + The MD5 hash for the uri as a hex string is + 7fd0e41c1612f860427a76c4100745a3. Following the steps above this + results in the following final thumbnail path: + +/mnt/pictures/.sh_thumbnails/normal/7fd0e41c1612f860427a76c4100745a3.png @@ -696,7 +718,7 @@ if (file.mtime != thumb.MTime) { - + Shared Thumbnail repositories In some situations it is desirable to have a shared thumbnail repository. This @@ -707,29 +729,35 @@ if (file.mtime != thumb.MTime) { - 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. - - - - The location for shared thumbnails will be + A shared thumbnail repository is stored in the directory whose files it should contain + thumbnails for. The location for a shared thumbnail repository inside such a directory will be: .sh_thumbnails/ Within this directory are the same subdirectories as in the global thumbnail directory. - .sh_thumbnails/ - .sh_thumbnails/normal/ - .sh_thumbnails/large/ - .sh_thumbnails/x-large/ - .sh_thumbnails/xx-large/ - .sh_thumbnails/fail/ + +.sh_thumbnails/ +.sh_thumbnails/normal/ +.sh_thumbnails/large/ +.sh_thumbnails/x-large/ +.sh_thumbnails/xx-large/ +.sh_thumbnails/fail/ The meaning of these directories is identical to their meaning in the global directory. - - 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. + + + Shared thumbnails use URIs relative to the thumbnail respository instead of absolute canonical + URIs. This applies both to the URI used when generating the thumbnail filename using md5sum, as + well as the Thumb::URI property. This is due to absolute paths not necessarily being consistent + across different users of the shared thumbnail repository. + + + + Given an original file at "/mnt/pictures/picture.png", the shared thumbnail repository would be + located at "/mnt/pictures/.sh_thumbnails/". The repository would contain an entry for the URI + "./picture.png". A relative thumbnail URI must be comprised "./" followed by a single path segment + for the filename with canonical URI encoding applied. + Creating thumbnails in a shared thumbnail repository @@ -737,7 +765,7 @@ if (file.mtime != thumb.MTime) { 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. + thumbnail repository. -- cgit v1.2.3