From efa3be408a2420f177c2e7cf798f92f3efdad36b Mon Sep 17 00:00:00 2001
From: Tomas Bzatek <tbzatek@users.sourceforge.net>
Date: Sun, 14 Sep 2014 23:28:04 +0200
Subject: theming: Clarify image size rules

Adding notes mostly about legacy features.
---
 templates/default.xml | 17 +++++++++++++----
 1 file changed, 13 insertions(+), 4 deletions(-)

(limited to 'templates')

diff --git a/templates/default.xml b/templates/default.xml
index 4bbbb6c..d2b0b63 100644
--- a/templates/default.xml
+++ b/templates/default.xml
@@ -10,26 +10,35 @@
 
     <!-- Meaning of "original" is shifted here from previous versions;
          it's considered more like a bigger preview size for large screens now. -->
-    <!--  corresponds with mandatory <item src> tag in album source file  -->
+    <!-- Corresponds with mandatory <item src> tag in album source file.  -->
+    <!-- Note that the series of legacy <nofullsize> and <fullsize> tags control
+         this image size availability. -->
     <size name="original">
       <landscape w="1200" h="800" />
       <portrait w="1024" h="1024" />
       <quality value="97" />
-      <!-- With presence of the "no_resize" tag, no resizing will be done and
+      <!-- With the presence of the "no_resize" tag, no resizing will be done and
            image file will be copied as is (this is a default for backwards
            compatibility). -->
       <no_resize />
     </size>
 
-    <!--  corresponds with optional <item preview> tag in album source file  -->
+    <!-- The "preview" size is considered default and should be displayed
+         on a first visit.  -->
+    <!-- Corresponds with optional <item preview="..."> tag in album source file.
+         No resizing is made when the attribute is present (legacy behaviour).  -->
     <size name="preview">
+      <!-- Note that "preview" sizes can be further overriden by album legacy
+           <images> tag and also per-image by "width"/"height" <item> tag
+           attributes. Same goes for quality. -->
       <landscape w="1067" h="600" />
       <portrait w="800" h="800" />
       <quality value="95" />
     </size>
 
     <!-- Thumbnail section is mandatory. -->
-    <!--  corresponds with optional <item thumbnail> tag in album source file  -->
+    <!-- Corresponds with optional <item thumbnail> tag in album source file.
+         Note that thumbnail images are always resized even for custom supplied files.  -->
     <size name="thumbnail">
       <landscape w="180" h="120" />
       <portrait w="120" h="180" />
-- 
cgit v1.2.3