git.defcon.no Git - plsgen/blob - README

   1 Perl Simple Gallery Generator v 0.3
   2 ==============================================
   3
   4 Requirements
   5 ------------------------
   6
   7 Perl modules
   8  * Image::ExifTool
   9    http://search.cpan.org/~exiftool/Image-ExifTool-8.15/
  10  * AppConfig
  11    http://search.cpan.org/~abw/AppConfig/
  12  * Getopt::Long (shipped with perl5->)
  13    http://search.cpan.org/~jv/Getopt-Long-2.38/
  14
  15 Programs:
  16  * convert from ImageMagick
  17    http://www.imagemagick.org/
  18  * jhead
  19    http://www.sentex.net/~mwandel/jhead/
  20
  21 And, of course you probably want to publish whis on
  22 a Web server. The generated result is static HTML,
  23 so no requirements at all exist in regard to type
  24 and functionality of HTTP daemon.
  25
  26
  27 Installation
  28 -------------------------
  29
  30 * Place the navigation JavaScript and the CSS file
  31 somewhere convenient on your Web server.
  32
  33 * Place the template files (index.tpl, full.tpl)
  34 where You want, I prefer having them located in
  35 /usr/local/share/plsgen
  36
  37 * Place the executable script so that execution
  38 is practical. I place it as /usr/local/bin/plsgen so
  39 that I have it in my search path.
  40
  41 * Take a look at the shipped configuration file.
  42 plsgen looks for a config file as /etc/plsgen.cfg,
  43 as ./plsgen.cfg or ../plgen.cfg relative to where
  44 it is executed. Alternatively, the --config option
  45 allows you to override the default locations.
  46 The shipped config lists all configuration options,
  47 along with their default values (used if no config present).
  48
  49
  50 Execution / Use
  51 -------------------------
  52
  53 plsgen is written to be ececuted in a directory filled
  54 with image files, and will create all its data
  55 in this directory. The resulting album will list
  56 all present image files of types JPG, PNG and GIF.
  57 A display-size and thumbnail image will be created
  58 for each image, and will be stored in the sub-directories
  59 view and thumbs (respectively).
  60
  61 Recognized commandline options are:
  62     --title='Your album title'
  63         Sets the album title. Title will be stored in .title
  64         If no title is given, it will be read from .title, if present
  65     --htmlonly
  66         Add this option to only generate HTML files
  67         No image operations will be performed with this option
  68     --noexif
  69         Forces EXIF data block not to be written to HTML output
  70     --config=/path/to/config
  71         Overrides default config file location.
  72         Default is to look for ./plsgen.cfg, then ../plsgen.cfg
  73         and finally /etc/plsgen.cfg.
  74      --help
  75         Displays a list of available commandline options
  76
  77
  78 File overrides: comments, title, index image.
  79 ------------------------------------------------------
  80 plsgen supports static gallery- and image comments. To get descriptive
  81 text or author comments on a gallery, add a file with the name 'comment.txt'
  82 to the directory before generating the album. The file is read, and injected
  83 verbatim, into all index* files generated, pre- and post-padded with the
  84 content of the comment-{pre,post} configuration variables.
  85
  86 To add an image comment, create a text file named identically to the image
  87 filename, plus the suffix .txt. So, if an image is named 'AnImage.JPG', the
  88 corresponding comment file should be named 'AnImage.JPG.txt'
  89
  90 If you wish to pre-seed the gallery title, you may do so by putting the
  91 gallery title on a single line in a file named '.title'. The title is read
  92 from this file if no title is given on the command line, and it is present.
  93 Note that if a title is given on the command line, that title will be used,
  94 and also will overwrite any content in the .title file.
  95
  96 A reference to an "index image", simply the first image in the set,
  97 is saved in the file '.indeximage', if this file does not previously exist.
  98 To override the chosen index image, simply put the filename you would
  99 rather have used in this file. The index image is used bu the included
 100 example index.php and rss.php
 101
 102
 103 Index front-end and RSS support
 104 -------------------------
 105 Included is a sample front-end index, and an accompanying RSS
 106 generator written using PHP. To use these, take a look at the PHP
 107 source, make personal adaptation (at least change references to my site
 108 to your own), and place both php files, plus indexstyle.css in a
 109 directory where you keep your albums as sub-directories.
 110
 111 E.g.:
 112   Web Root
 113   |-- galleryset1
 114   |   |-- image1.jpg
 115   |   |-- image1.jpg.txt
 116   |   |-- image2.jpg
 117   |   |-- comment.txt
 118   |    `- .title
 119   |-- galleryset2
 120   .     ...
 121   |-- nav.js
 122   |-- style.css
 123   |-- index.php
 124   |-- indexstyle.css
 125    `- rss.php
 126
 127 Changelog
 128 -------------------------
 129 * 0.3 -> 0.4
 130 # DONE: Removed some default values in config, allowing empty options
 131 # DONE: Added latest.php, a hybrid between index.php and rss.php ..
 132 # DONE: Gathered all user-related data in php-files as variables on top.
 133 # BUGFIX: Added missing alt-tags to img-tags generated
 134 # BUGFIX: Shipped templates and config now give validating HTML
 135 # BUGFIX: Prepped up index.php to validate aswell
 136 # REMOVED: Will not use perlmagick et. al, removed TODO.
 137
 138 * 0.2 -> 0.3
 139 # DONE: Config option for size of view/thumbnail
 140 # DONE: Config option to disable arrow-up navigation
 141 # DONE: Config option to disable image rescaling ?
 142 # DONE: Multithreaded resizing, multiple resizes at the same time
 143 # BUGFIX: Version number now gets updated between versions :P
 144
 145 * 0.1 -> 0.2
 146 # DONE: filename.txt for file comments
 147 # DONE: comment.txt for album comments
 148 # DONE: Save reference to main-index thumbnail.
 149 # DONE: Add command line option to disable EXIF block output
 150 # BUGFIX: Now generates for all images, including the last in set.
 151 # BUGFIX: Performs rotation according to EXIF
 152
 153 Todo-list
 154 -------------------------
 155 # TODO: Stripping of image suffix for HTML file w/config option?
 156 # TODO: Clear old generated files and meta on regen
 157 # TODO: Image title from EXIF for a title-template-tag.
 158 # TODO: Possibility for hide/show EXIF
 159 # TODO: Templating of EXIF
 160 # TODO: Priority/sorting of EXIF tags
 161 # BUG:  The naive handling of filenames breaks on special characters
 162
 163 Lisencing
 164 -------------------------
 165 Copyright (c) 2010, Jon Langseth
 166 All rights reserved.
 167
 168 Redistribution and use in source and binary forms, with or without
 169 modification, are permitted provided that the following conditions are met:
 170     * Redistributions of source code must retain the above copyright
 171       notice, this list of conditions and the following disclaimer.
 172     * Redistributions in binary form must reproduce the above copyright
 173       notice, this list of conditions and the following disclaimer in the
 174       documentation and/or other materials provided with the distribution.
 175
 176 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
 177 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 178 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 179 DISCLAIMED. IN NO EVENT SHALL JON LANGSETH BE LIABLE FOR ANY
 180 DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 181 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 182 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 183 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 184 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 185 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.