update
[booh] / THEMES
diff --git a/THEMES b/THEMES
index 23fbaf136e074ca61876e141f60bc6b9e68df03f..bf463fba337a3fa5a95462b3ba70dbc2cb4781a5 100644 (file)
--- a/THEMES
+++ b/THEMES
@@ -1,15 +1,86 @@
-                Screenshots
+                   [[ Themes in booh ]]
+
+Each theme is made of:
+
+- one index.html skeleton, used for the "index" page, the page
+  showing the available subalbums (no such page in the generated
+  album, if you don't have any subalbum)
+
+- one thumbnails.html skeleton, used for the thumbnails page
+
+- one image.html skeleton, used for fullscreen images
+
+- any number of resource files these html pages depend on
+  (images, css..), normally they should all go in the 'root'
+  subdirectory, so that they are only copied in the root
+  directory of the final webalbum and avoid wasting too much
+  hosting space; they can be referred from the skeleton by
+  prepending ~~pathtobase~~, which will be the relative path
+  to the root directory of the final webalbum
+
+- a metadata/parameters.rb file holding information about images
+  sizes that will fit the best the html pages layout
+
+- three metadata/screenshot-?.png files used to select theme in
+  the GUI
+
+
+                  [[ Skeleton files ]]
+
+The skeleton files contain keywords used in the backend to fill
+them up with images. There is no precise documentation about
+them, the best is to look at the 'simple' theme and learn from it
+directly. Most of them are just a simple replace, and there are
+two special cases:
+
+- conditionals:
+
+    ~~iffoo?~~bar~~fi~~
+
+  indicates that if foo is true, put bar at this position, else
+  put nothing; there are a few existing conditions tested, have a
+  look in skeletons of the 'simple' theme
+
+- loops:
+
+   ~~iterate1_open~~
+     foo
+     ~~image_iteration~~
+     bar
+   ~~iterate1_close~~
+
+   is used to put "foo" before each image (index and thumbnails
+   pages only), and bar after each image
+
+   It can be nested:
+
+   ~~iterate1_open~~
+      foo
+       ~~iterate2_open_max4~~
+         bar
+         ~~image_iteration~~
+         baz
+       ~~iterate2_close~~
+      qux
+   ~~iterate1_close~~
+
+   The character after "max" can be hardcoded, or can be "N" to
+   represent the configurable number of images per rows in the
+   thumbnails page. It indicates the amount of times iterate2
+   will be performed before another iterate1 is needed.
+
+
+                     [[ Screenshots ]]
 
 Each theme must export three screenshots, used to select theme in
 the GUI. First screenshot demonstrates the "index" page, second
 
 Each theme must export three screenshots, used to select theme in
 the GUI. First screenshot demonstrates the "index" page, second
-one the "thumbnails" page, and thirs one the "image" page.
+one the "thumbnails" page, and third one the "image" page.
 
 
-To keep a correct ratio between themes, to do your screenshot,
-first resize your browser so that the webpage will use a
-rectangular area of 800x600, and use appropriate images sizes
-(most probable "small"); then resize it to 192x144.
+To keep a correct ratio between themes, to do your screenshot, be
+sure to use the correct images sizes for your resolution; then
+take the screenshot, crop for 1.55 aspect ratio and resize to 192
+of width (thus 124 of height).
 
 It would be best if the screenshots would show the same contents,
 so just send me your theme if you create a new one and I'll do
 the screenshots.
 
 It would be best if the screenshots would show the same contents,
 so just send me your theme if you create a new one and I'll do
 the screenshots.
-