always mark dirty when changing version
[booh] / THEMES
diff --git a/THEMES b/THEMES
index 23fbaf136e074ca61876e141f60bc6b9e68df03f..c7917b569905e93c5dd31a4eb5cfb33f4c064d13 100644 (file)
--- a/THEMES
+++ b/THEMES
@@ -1,15 +1,96 @@
-                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
+
+If you want to create a new theme, or make local modifications to a
+theme, just have them in your ~/.booh-themes directory. For example,
+to hack off "dark":
+
+# mkdir ~/.booh-themes
+# cp -a /usr/share/booh/themes/dark ~/.booh-themes/mine
+
+Use a different name than original theme names (here I picked the
+dummy name "mine", choose a better one).
+
+
+                  [[ 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
-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.
-