README

   1 Introduction
   2 ------------
   3 bpgallery is a small static gallery generator, it generates an index file and
   4 thumbnails of your images. The index file is generated in the image folder,
   5 icons in a subfolder called icons.
   6
   7 Requirements
   8 ------------
   9 The ImageMagick tools (convert and identify)
  10 bash
  11 GNU find
  12 GNU xargs
  13 sed
  14
  15 Installation
  16 ------------
  17 Copy the file bpgallery.sh to a directory in your PATH.
  18
  19 Usage
  20 -----
  21 bpgallery.sh /path/to/image/files
  22
  23 Also, the following files, if placed in the images directory, will be used to
  24 generate part of the index page:
  25         description.txt
  26             a simple text file containing paragraphs to go at the beginnings of
  27             the index page
  28         captions.txt
  29             filename<tab>caption style file, it'll add a caption to the images
  30             on the index page.
  31
  32 If both width and height are specified then it'll be resized to the bounding
  33 box that contains it.
  34
  35 If height is specified without width then the bounding box will be 100xHEIGHT
  36 for icons and 400xMEDIUMHEIGHT for the medium sized image pages
  37
  38 The following environment variables can also be used:
  39         TITLE
  40             the title of the gallery
  41
  42         WIDTH
  43             the width to make the icons
  44
  45         HEIGHT
  46             the height to make the icons
  47
  48         MEDIUMWIDTH
  49             set the width of images in the medium size pages
  50
  51         MEDIUMHEIGHT
  52             the height to make images in the medium size pages
  53
  54         BPGALLERY_THEME
  55             set the theme to use (described below)
  56
  57         BPGALLERY_THEME_DIR
  58             set an extra location to look for themes
  59
  60         OUTPUTHTML
  61             sets the script output to be wrapped in a <pre> block
  62
  63         GENERATEPAGESFORMEDIUMSIZE
  64             generate medium sized images and pages
  65
  66         GENERATEPAGESFORFULLSIZE
  67             decide wether to generate pages for the full size images or not
  68
  69         INDEXDOCUMENT
  70             name of the index page (e.g. index.html)
  71
  72         PAGESDIRECTORY
  73             name of the directory in which to put the pages for fullsized and
  74             mediumsized images. Defaults to the image directory. This is
  75             relative to the images directory, so, for example,
  76             PAGESDIRECTORY=pages would create /path/to/image/files/pages
  77
  78         MEDIUMDIRECTORY
  79             directory to generate medium sized images in, defaults to medium,
  80             works the same as the PAGESDIRECTORY variable
  81
  82         ICONSDIRECTORY
  83             directory to generate thumbnails in, defaults to icons, works the
  84             same as MEDIUMDIRECTORY and PAGESDIRECTORY
  85
  86 Example Usage:
  87         TITLE="My Funky Gallery" bpgallery.sh /path/to/image/files
  88
  89 Themes
  90 ------
  91 Theme support is very rudimentary, basically you create functions for each of
  92 the parts of the template, and put them in a file named the same as the theme.
  93 The functions that you need to declare are as follows:
  94
  95         Available in all templates:
  96             ${BASEURL}
  97                 Base directory (will generate ../ when making pages in a
  98                 subdirectory for getting to the generated stylesheet or to the
  99                 index page)
 100
 101         bpgallery_ThemeName_head()
 102                 what's it for?:
 103                         This sets up the header for the page, generally
 104                         everything until the first picture. So, the title bar
 105                         and any menus you would like to use
 106                 available variables:
 107                         $TITLE       - the title for the index page
 108         bpgallery_ThemeName_tail()
 109                 what's it for?:
 110                         Closes the page, is the last thing to be printed.
 111                 available variables:
 112                         None
 113         bpgallery_ThemeName_description()
 114                 what's it for?:
 115                         if there's a description set up (i.e. a description.txt
 116                         file) then this is what it'll be wrapped in. It comes
 117                         just after the _head.
 118                 available variables:
 119                         $DESCRIPTION - the content of description.txt
 120         bpgallery_ThemeName_stylesheet()
 121                 what's if for?:
 122                         It generates the stylesheet for the page.
 123                 available variables:
 124                         $WIDTH       - the width of the images
 125                         $MAXWIDTH    - the maximum width of the images
 126                         $MAXHEIGHT   - the maximum height of the images
 127         bpgallery_ThemeName_thumbsline()
 128                 what's it for?:
 129                         Whatever is in here is generated per thumbnail.
 130                 available variables:
 131                         $link        - the page/image to link to
 132                         $filename    - the name of the file
 133                         $caption     - the caption as got from captions.txt
 134         bpgallery_ThemeName_page()
 135                 what's it for?:
 136                         It generates the pages for fullsize image pages
 137                 available variables:
 138                         $filename    - the name of the image
 139                         $previouspage - the URL for the previous page
 140                         $currentpage - the url for the current page
 141                         $nextpage    - the url for the next page
 142                         $caption     - the image caption
 143
 144 If any of the functions are not defined in a theme then the default theme
 145 function will be used instead. The default theme is clean and simplistic, this
 146 is deliberate!
 147
 148 Author
 149 ------
 150 Brett Parker:
 151         e-mail: <iDunno@sommitrealweird.co.uk>
 152         www:    http://www.sommitrealweird.co.uk/