document album v3, based on trail v3

4 files changed, 187 insertions, 105 deletions

diff --git a/doc/plugins/contrib/album.mdwn b/doc/plugins/contrib/album.mdwn
index dde533e76..836a98f33 100644
--- a/doc/plugins/contrib/album.mdwn
+++ b/doc/plugins/contrib/album.mdwn
@@ -1,147 +1,118 @@
 [[!template id=plugin name=album author="[[Simon_McVittie|smcv]]"]]
-[[!template id=gitbranch branch=smcv/album2 author="[[Simon_McVittie|smcv]]"]]
 [[!tag type/chrome]]
 
-Available from [[smcv]]'s git repository, in the `album2` branch.
-Older (pre-rebase) versions in `album`, `album-live` (the latter
-was used on an actual website and didn't explode too much).
+This plugin provides the [[ikiwiki/directive/album]] [[ikiwiki/directive]],
+which turns a page into a photo album or image gallery, containing all
+images attached to the album or its subpages. It also provides the
+[[ikiwiki/directive/albumsection]] and [[ikiwiki/directive/albumimage]]
+directives.
 
-[The version currently available hasn't been modified to work with the
-November 2011 version of [[trail]]. -[[smcv]]]
+This plugin automatically enables the [[filecheck]], [[img]], [[inline]],
+[[trail]] and [[transient]] plugins. The [[meta]] plugin is also
+recommended.
 
-This plugin formats a collection of images into a photo album,
-in the same way as many websites: good examples include the
-PHP application [Gallery](http://gallery.menalto.com/), Flickr,
-and Facebook's Photos "application".
+## Changing the templates
 
-I've called it `album` to distinguish it from
-[[contrib/gallery|plugins/contrib/gallery]], although `gallery` might well be
-a better name for this functionality.
+When a viewer page is generated or inlined into an album, the template can
+contain these extra variables:
 
-The web UI I'm trying to achieve consists of one
-[HTML page of thumbnails](http://ikialbum.hosted.pseudorandom.co.uk/album/)
-as an entry point to the album, where each thumbnail links to
-[a "viewer" HTML page](http://ikialbum.hosted.pseudorandom.co.uk/album/img_0120/)
-with a full size image, next/previous thumbnail links, and
-[[plugins/comments]].
+* `<TMPL_VAR ALBUM>` - page name of the album
+* `<TMPL_VAR ALBUMURL>` - relative URL to the album
+* `<TMPL_VAR ALBUMTITLE>` - title of the album, usually taken from
+  a [[ikiwiki/directive/meta]] directive
+* `<TMPL_VAR CAPTION>` - caption for the image
+* `<TMPL_VAR THUMBNAIL>` - a small [[ikiwiki/directive/img]] for the image
+* `<TMPL_VAR IMAGEWIDTH>` - width of the full-size image in pixels
+* `<TMPL_VAR IMAGEHEIGHT>` - height of the full-size image in pixels
+* `<TMPL_VAR IMAGEFILESIZE>` - size of the image, e.g. `1.2 MiB`
+* `<TMPL_VAR IMAGEFORMAT>` - format of the image, typically `JPEG`
 
-(The Summer of Code [[plugins/contrib/gallery]] plugin does the
-next/previous UI in Javascript using Lightbox, which means that
-individual photos can't be bookmarked in a meaningful way, and
-the best it can do as a fallback for non-Javascript browsers
-is to provide a direct link to the image.)
+The template for the viewer page can also contain:
 
-<h2 id="album"><code>album</code> directive</h2>
+* `<TMPL_VAR IMG>` - a large [[ikiwiki/directive/img]] to display the image
+* `<TMPL_VAR PREV>` - a link to the previous viewer, typically with a
+  thumbnail
+* `<TMPL_VAR NEXT>` - a link to the next viewer, typically with a
+  thumbnail
 
-Each page containing an `album` directive is treated as a photo album.
+## Including album entries elsewhere
 
-Every image attached to an album or its subpages is considered to be part of
-the album. A "viewer" page, with the wiki's default page extension, will be
-generated in the [[transient underlay|todo/transient_pages]] to display the
-image, if there isn't already a page of the same name as the image: for
-instance, if `debconf` is an album and `debconf/tuesday/p100.jpg` exists,
-then `debconf/tuesday/p100.mdwn` might be created.
+To display images from elsewhere in the wiki with the same appearance as
+an [[ikiwiki/directive/album]] or [[ikiwiki/directive/albumsection]],
+you can use an [[ikiwiki/directive/inline]] with the `albumitem`
+template:
 
-There's currently a hard-coded list of extensions that are treated as images:
-`png`, `gif`, `jpg`, `jpeg` or `mov` files. More image and video types could
-be added in future. Videos aren't currently handled very well;
-ideally, something like totem-video-thumbnailer would be used.
+	\[[!inline pages="..." sort="-age" template="albumitem"]]
 
-The `album` directive also produces an [[ikiwiki/directive/inline]] which
-automatically includes all the viewers for this album, except those that
-will appear in an <a href="#albumsection">albumsection</a> (if every image
-is in a section, then the `album` directive won't have any visible effect).
+----
 
-The `inline` is in `archive` and `quick` mode, but can include some
-extra information about the images, including file size and a thumbnail made
-using [[ikiwiki/directive/img]]). The default template is `albumitem.tmpl`,
-which takes advantage of these things.
+[[!template id=gitbranch branch=smcv/album3 author="[[Simon_McVittie|smcv]]"]]
 
-<h2 id="albumsection"><code>albumsection</code> directive</h2>
-
-The `albumsection` directive is used to split an album into sections. It can
-only appear on a page that also has the <a href="#album">album</a> directive.
-
-The `filter` parameter is a [[ikiwiki/PageSpec]] against which viewer pages
-are matched. The `albumsection` directive displays all the images that match
-the filter, and the `album` directive displays any leftover images, like
-this:
-
-    # Holiday photos
-
-    \[[!album]]
-    <!-- replaced with a list of any uncategorized photos, which might be
-         empty -->
-
-    ## People
-
-    \[[!albumsection filter="tagged(people)"]]
-    <!-- replaced with a list of photos tagged 'people', including
-         any that are also tagged 'landscapes' -->
+Available from [[smcv]]'s git repository, in the `album3` branch.
+I've called it `album` to distinguish it from
+[[contrib/gallery|plugins/contrib/gallery]], although `gallery` might well be
+a better name for this functionality.
 
-    ## Landscapes
+(The Summer of Code [[plugins/contrib/gallery]] plugin does the
+next/previous UI in Javascript using Lightbox, which means that
+individual photos can't be bookmarked in a meaningful way, and
+the best it can do as a fallback for non-Javascript browsers
+is to provide a direct link to the image.)
 
-    \[[!albumsection filter="tagged(landscapes)"]]
-    <!-- replaced with a list of photos tagged 'landscapes', including
-         any that are also tagged 'people' -->
+Updated, November 2011: rebased onto [[trail]] v3, CSS adjusted.
 
-<h2 id="albumimage"><code>albumimage</code> directive</h2>
+## Manual installation
 
-Each viewer page produced by the <a href="#album">album</a> directive
-contains an `albumimage` directive, which is replaced by an
-[[ikiwiki/directive/img]], wrapped in some formatting using a
-template (by default it's `albumviewer.tmpl`). That template can also include
-links to the next photo, the previous photo and the album it's in; the default
-template has all of these.
+If you don't want to use a branch of ikiwiki, manual installation requires
+these files (use the "raw" link in gitweb to download), in addition to the
+ones needed by [[trail]]:
 
-The next/previous links are themselves implemented by evaluating a template,
-either `albumnext.tmpl` or `albumprev.tmpl` by default.
+* [album.pm](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album3:/IkiWiki/Plugin/album.pm)
+  in an `IkiWiki/Plugin` subdirectory of your configured `plugindir`
+* [albumviewer.tmpl](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album3:/templates/albumviewer.tmpl),
+  [albumitem.tmpl](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album3:/templates/albumitem.tmpl),
+  [albumnext.tmpl](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album3:/templates/albumnext.tmpl) and
+  [albumprev.tmpl](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album3:/templates/albumprev.tmpl),
+   in your configured `templatedir`, or a `templates` subdirectory of your wiki repository
+* the album-related bits from the end of the
+  [stylesheet](http://git.pseudorandom.co.uk/smcv/ikiwiki.git/blob/album3:/doc/style.css)
+  (put them in your local.css)
 
-The directive can also have parameters:
+## Demo
 
-* `title`, `copyright` and `date` are short-cuts for the corresponding
-  [[ikiwiki/directive/meta]] directives
+* [HTML page of thumbnails](http://ikialbum.hosted.pseudorandom.co.uk/album/)
+  as an entry point to the album
+* Each thumbnail links to
+  [a "viewer" HTML page](http://ikialbum.hosted.pseudorandom.co.uk/album/img_0120/)
+  with a full size image, optional next/previous thumbnail links, and
+  optional [[plugins/comments]]
 
-* `caption` sets a caption which is displayed in the album and viewer
-  pages
+## Bugs
 
-The viewer page can also have other contents before or after the actual
-image viewer.
+* There's currently a hard-coded list of extensions that are treated as
+  images: `png`, `gif`, `jpg`, `jpeg` or `mov` files. More image and video
+  types could be added in future.
 
-## Bugs
+* Videos aren't currently handled very well; ideally, something like
+  totem-video-thumbnailer would be used.
 
 * The plugin doesn't do anything special to handle albums that are subpages
   of each other. If, say, `debconf` and `debconf/monday` are both albums,
   then `debconf/monday/p100.jpg` will currently be assigned to one or the
   other, arbitrarily. It should probably pick the closest (longest) album name.
+  (I'm not sure that it can do this reliably, though, since the scan stage
+  runs in an undefined order.)
 
 * The plugin doesn't do anything special to handle photos with similar names.
   If you have `p100.jpg` and `p100.png`, one will get a viewer page called
-  `p100` and the other will be ignored.
+  `p100` and the other will be ignored. (I'm not sure what we could do better,
+  though.)
 
 * If there's no `albumimage` in a viewer page, one should probably be appended
   automatically.
 
-* When editing a viewer page, rebuilding it seems to fail at the moment.
-  Probably related to:
-
-* Integration with [[plugins/contrib/trail]] is new, untested and not
-  very well implemented. In particular, the prev/up/next links are
-  redundant with the ones from `trail`.
-
 ## TODO
 
-* The documentation should mention how to replicate the appearance of
-  `album` and `albumsection` using an `inline` of viewer pages,
-  elsewhere on the site.
-
-* The documentation should mention all the template variables and
-  all the parameters.
-
-* The generated viewer page should include most or all of the possible
-  parameters to the `albumimage` directive, with empty values, as a
-  template for editing.
-
 * The generated viewer page should extract as much metadata as possible from
   the photo's EXIF tags (creation/modification dates, author, title, caption,
   copyright). [[smcv]] has a half-written implementation which runs
diff --git a/doc/plugins/contrib/ikiwiki/directive/album.mdwn b/doc/plugins/contrib/ikiwiki/directive/album.mdwn
new file mode 100644
index 000000000..433eec8bd
--- /dev/null
+++ b/doc/plugins/contrib/ikiwiki/directive/album.mdwn
@@ -0,0 +1,56 @@
+The `album` directive is supplied by the [[!iki plugins/contrib/album desc=album]] plugin.
+
+Each page containing an `album` directive is treated as a photo album
+or image gallery. Example usage is as simple as:
+
+    \[[!album]]
+
+Every image attached to an album or its [[subpages|ikiwiki/subpage]] is
+considered to be part of the album. A "viewer" page, with the wiki's default
+page extension, will be generated in the
+[[transient underlay|plugins/transient]] to display the
+image, if there isn't already a page of the same name as the image: for
+instance, if `debconf` is an album and `debconf/tuesday/p100.jpg` exists,
+then `debconf/tuesday/p100.mdwn` might be created.
+
+The album is treated as a [[!iki plugins/contrib/trail desc=trail]], which
+gives each viewer page a link back to the album, and a link to the previous
+and next viewer in the album.
+
+The `album` directive also produces an [[ikiwiki/directive/inline]] which
+automatically includes all the viewers for this album, except those that
+will appear in an [[albumsection]]. If every image in the album is in a
+section, then the `album` directive is still required, but won't produce
+any output in the page.
+
+The `inline` can include some extra information about the images, including
+file size and a thumbnail made using [[ikiwiki/directive/img]]). The
+default template is `albumitem.tmpl`, which takes advantage of these things.
+
+## Options
+
+The directive can have some options for the entire album. The defaults are:
+
+    \[[!album
+      sort="-age"
+      size="full"
+      thumbnailsize="96x96"
+      viewertemplate="albumviewer"
+      prevtemplate="albumprev"
+      nexttemplate="albumnext"
+
+* `sort` - sets the order in which images appear, defaulting to earliest
+  creation date first
+* `size` - if not `full`, the [[ikiwiki/directive/img]] in the viewer page
+  will be resized to be no larger than this
+* `thumbnailsize` - the [[ikiwiki/directive/img]] in the album page,
+  which can also be used in the previous/next links, will be no larger than
+  this
+* `viewertemplate` - the template used for the [[albumimage]] in each
+  viewer page
+* `prevtemplate` - the template used to replace `<TMPL_VAR PREV>` if used in
+  the viewer page
+* `nexttemplate` - the template used to replace `<TMPL_VAR NEXT>` if used in
+  the viewer page
+
+[[!meta robots="noindex, follow"]]
diff --git a/doc/plugins/contrib/ikiwiki/directive/albumimage.mdwn b/doc/plugins/contrib/ikiwiki/directive/albumimage.mdwn
new file mode 100644
index 000000000..2385bb535
--- /dev/null
+++ b/doc/plugins/contrib/ikiwiki/directive/albumimage.mdwn
@@ -0,0 +1,26 @@
+The `albumimage` directive is supplied by the [[!iki plugins/contrib/album desc=album]] plugin.
+
+Each viewer page produced by the [[album]] directive
+contains an `albumimage` directive, which is replaced by an
+[[ikiwiki/directive/img]], wrapped in some formatting using a
+template (by default it's `albumviewer.tmpl`). That template can also include
+links to the next and previous photos, in addition to those provided by the
+[[!iki plugins/contrib/trail desc=trail]] plugin.
+
+The next/previous links are themselves implemented by evaluating a template,
+either `albumnext.tmpl` or `albumprev.tmpl` by default.
+
+The directive can also have parameters:
+
+* `title`, `date`, `updated`, `author`, `authorurl`, `copyright`, `license`
+  and `description` are short-cuts for the corresponding
+  [[ikiwiki/directive/meta]] directives
+
+* `caption` sets a caption which is displayed near this image in the album
+  and viewer pages
+
+The viewer page can also contain any text and markup before or after the
+`albumimage` directive, which will appear before or after the image in the
+viewer page.
+
+[[!meta robots="noindex, follow"]]
diff --git a/doc/plugins/contrib/ikiwiki/directive/albumsection.mdwn b/doc/plugins/contrib/ikiwiki/directive/albumsection.mdwn
new file mode 100644
index 000000000..7e5749e05
--- /dev/null
+++ b/doc/plugins/contrib/ikiwiki/directive/albumsection.mdwn
@@ -0,0 +1,29 @@
+The `albumsection` directive is supplied by the [[!iki plugins/contrib/album desc=album]] plugin.
+
+The `albumsection` directive is used to split an album into sections. It can
+only appear on a page that also has the [[album]] directive.
+
+The `filter` parameter is a [[ikiwiki/PageSpec]] against which viewer pages
+are matched. The `albumsection` directive displays all the images that match
+the filter, and the `album` directive displays any leftover images, like
+this:
+
+    # Holiday photos
+
+    \[[!album]]
+    <!-- replaced with a list of any uncategorized photos; it will be
+         empty if they're all tagged as 'people' and/or 'landscapes' -->
+
+    ## People
+
+    \[[!albumsection filter="tagged(people)"]]
+    <!-- replaced with a list of photos tagged 'people', including
+         any that are also tagged 'landscapes' -->
+
+    ## Landscapes
+
+    \[[!albumsection filter="tagged(landscapes)"]]
+    <!-- replaced with a list of photos tagged 'landscapes', including
+         any that are also tagged 'people' -->
+
+[[!meta robots="noindex, follow"]]