generators: Use single function for all templates

This commit makes use of a common function for all template parsing and page
writing. The behaviour is controlled by the "item" argument passed in. This
allows us to have a single code that generates code for list of items as well
as for a single item. In the future, this can be used for e.g. combining
thumbnails and large images on the same page.

Other than that this commit also brings several other changes:
 - further clarification of theming setup XML file
 - <protected_thumbnail> tag has been moved out of the <album> structure into
   the <index> structure where it functionally belongs. Only whole albums can
   be protected and the substitute thumbnail is displayed on index pages.
 - position marker format has been broken out to a constant
 - added few more FIXMEs to mark places that will change soon
 - some template variables have been renamed

1 files changed, 19 insertions, 14 deletions

diff --git a/templates/default.xml b/templates/default.xml
index 9197519..c903a4b 100644
--- a/templates/default.xml
+++ b/templates/default.xml
@@ -9,10 +9,11 @@
          the "preview" size will be used instead.  -->
 
     <!-- Meaning of "original" is shifted here from previous versions;
-         it's considered more like a bigger preview size for large screens now. -->
+         it's considered more like a bigger preview size for large screens now.
+         However it still serves the purpose of supplying metadata (EXIF etc.). -->
     <!-- 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. -->
+         this image size availability on the page. -->
     <size name="original">
       <landscape w="1200" h="800" />
       <portrait w="1024" h="1024" />
@@ -72,31 +73,34 @@
 
   <!--  particular design setup  -->
   <theme enabled="yes">
-    <!-- When the <index> structure is missing, album design will be used for
-         both list of albums and list of pictures. -->
+    <!-- Index pages may only contain thumbnails. When the <index> structure is
+         missing, album design will be used for both list of albums and list
+         of pictures. -->
     <index>
       <template>template_index.html</template>
       <target_filename>index.html</target_filename>
       <!-- specify thumbnail image size to be used here. -->
       <thumbnail_size>thumbnail</thumbnail_size>
+      <!--  In case of a protected album, show special thumbnail (must be included
+            in supplemental_files). Comment out to use real thumbnail.  -->
+      <protected_thumbnail>emblems-readonly_120.png</protected_thumbnail>
     </index>
 
-    <!-- This is mandatory. -->
+    <!-- Album definition is mandatory. -->
     <album>
       <template>template_album.html</template>
       <target_filename>index.html</target_filename>
-      <!--  which picture size to use for XXX tags (TODO)  -->
-      <picture_size>preview</picture_size>
-      <!--  thumbnail_size is optional when thumbnails are not used on album pages  -->
+      <!--  thumbnail_size is optional, omit it when thumbnails are not used on
+            album pages (will skip some tags substitution).  -->
       <thumbnail_size>thumbnail</thumbnail_size>
-      <!--  In case of a protected album, show special thumbnail (must be included
-            in supplemental_files). Comment out to use real thumbnail  -->
-      <protected_thumbnail>emblems-readonly_120.png</protected_thumbnail>
+      <!--  Just like thumbnail_size, also picture_size is optional, omit it
+            when images in their full sizes are not used on album pages.  -->
+      <picture_size>preview</picture_size>
     </album>
 
     <!-- When the <picture> structure is missing, no pages for the particular
-         images will be generated. Images are processed in either case, for use
-         with album alone. -->
+         images will be generated. Images are processed in either case, for
+         potential use within album pages. -->
     <picture>
       <template>template_picture.html</template>
       <!--  '%s' will be replaced with actual picture filename  -->
@@ -120,7 +124,7 @@
          or as a value constant (specify "value(DEFINE_NAME)" to retrieve the value).
          For "ifdef" negation, use "ifndef" or "else". -->
     <!-- Some defines are added during runtime and take priority over custom defines
-         here. This way you can define default values here which would get eventually
+         here. This way you can define default values which would get eventually
          overriden by the generator. -->
 
     <!--  image border style, overriden by <border style> tags from the album source file  -->
@@ -141,3 +145,4 @@
        filenames to avoid conflicts.  -->
 
 </design_setup>
+