Gallery macro
=============

[[Parent]]: available_macros.txt

The Gallery macro generates an image gallery. The supported image formats 
are PNG, JPEG, GIF, SVG, and SVGZ. These image formats are the ones that 
are [well-supported][ImageFormats] in browsers (as of October 2012).
Thumbnails are automatically generated for images with filename 
extensions .png, .gif, .jpeg, .jpg. The Gallery macro uses the Pillow
library to generate the thumbnails. If the Pillow library is not installed,
then the Gallery macro will still run, but thumbnails will not be generated
(a warning is given in this case).

[ImageFormats]: http://en.wikipedia.org/wiki/Comparison_of_browsers

Properties
----------

### Output type

Html

### Output expansion default

Disabled.

### Parameters

A list of the following form:

	image1.png
	- Caption for the first image.
	- More caption for the first image.
	image2.jpg
	- Caption for the second image.
	image4.gif
	image5.svg
	...

Specification of captions is not required.

### Variables

Gallery.thumbnail_max_width 
: 	A maximum for the width of a thumbnail in pixels.
	Default 300.

Gallery.thumbnail_max_height
: 	A maximum for the height of a thumbnail in pixels.
	Default 300.

The pixel-count defines the resolution of the thumbnail image
for the pixel-based images; if the number of pixels is too low 
compared to the presentation size (defined by the CSS), the 
thumbnail image will look blurry.

### Multiple image formats

If an image file has multiple formats in the same directory,
say `lookaheads.png` and `lookaheads.svg`, then they are assumed
to be the same image in different formats. If there is an image 
file for which thumbnails can be generated, then that image file 
is used to generate the thumbnail. In particular, this covers for 
the fact that, as of October 2012, there aren't any good 
open-source libraries for converting SVG to a pixel-based image.

### Width and height of thumbnails

To set the maximum allowed presentation width and height for
the image thumbnails, modify the `max-width` and `max-height`
properties of the `.highslide img` selector in `highslide.css`.
The defaults for these are 45% and 20% (of the containing element), 
respectively.

### Thumbnail naming

The thumbnails will be stored at the `remark_files/thumbnails` 
directory of the output root-directory. A thumbnail is named
such that it starts with the image filename without the extension,
and is then followed by (a dash - and) a hash of the relative-path 
in hex-form which disambiguates images with equal filenames. 

Using hashing for disambiguation means that images with _equal_ filenames 
may sometimes collide (they will then have the same thumbnail image). 
The probability of this happening is governed by the 
[birthday paradox][Birthday]. Given the current implementation, which
uses a 64-bit hash, over 6 million files with equal filenames need
to be generated to get a collision with a one-in-a-million probability.

[Birthday]: http://en.wikipedia.org/wiki/Birthday_paradox

Warnings
--------

vector-thumbnail
:	This warning is generated when an SVG file is used as its
	own thumbnail.  Depending on the complexity of the SVG file
	this might cut out unnecessary amount of performance from
	the browsing of the webpage. To fix this, provide a	pixel-based 
	alternative image to create the thumbnail from.

thumbnail-failed
:	This warning is generated when the creation of a thumbnail
	fails for a reason or another.

Example
-------

[[Example]]:
	[[Gallery]]:
		hsv.png
		- A visualization of the HSV color space (with full saturation).
		- This text is appended to the caption.
		lookaheads.svg
		- Lookahead-sets in LC(1)-parsing

See also
--------

[[Link]]: file_searching_algorithm.txt
