--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/bins.1	Wed Oct 15 23:28:56 2008 +0200
@@ -0,0 +1,622 @@
+.TH "BINS" "1" 
+.SH "NAME" 
+bins \(em Generate a static HTML photo albums using XML and EXIF tags 
+.SH "SYNOPSIS" 
+.PP 
+\fBbins\fR [\fB-f \fIconfig_file\fR\fP]  [\fB-o \fISTR\fR\fP]  [\fB-d \fISTR\fR\fP]  [\fB-c \fIcolor_style\fR\fP]  [\fB-s \fIstyle\fR\fP]  [\fB-t \fItemplate_dir\fR\fP]  [\fB-p\fP]  [\fB-e\fP]  [\fB-i \fIiKey,iKey...\fR\fP]  [\fB-v \fIX\fR\fP]  [\fB-h\fP] \fIsource_dir\fR \fItarget_dir\fR  
+.SH "DESCRIPTION" 
+.PP 
+This manual page documents briefly the 
+\fBbins\fR command. 
+.PP 
+This manual page was written for the \fBDebian\fP distribution 
+because the original program does not have a manual page. 
+Instead, it has documentation in HTML in 
+\fB/usr/share/doc/bins/index.html\fP as well as a 
+\fB-h\fP option. 
+.PP 
+\fBbins\fR is a program that takes a 
+collection of directories and files containing 
+JPEG images and XML       descriptions, combines them with a set of 
+HTML templates, and produces a complete photo 
+gallery of static HTML files, rescaled images 
+at three sizes, and thumbnails. 
+.SH "OPTIONS" 
+.IP "\fB-f \fIconfig_file\fR\fP" 10 
+use an alternative configuration file, instead of 
+\fB~/.bins/binsrc.\fP. 
+.IP "\fB-o \fISTR\fR\fP" 10 
+Tells script to use only one copy of image using 
+HTML size specs (height, width specs in the image 
+tag) for scaled versions (instead of generating 
+several images, one for each size). 
+.IP "" 10 
+Default is false. 
+.IP "" 10 
+\fISTR\fR is an optional argument 
+to set how the one image is generated. Possible values: 
+ 
+.RS 
+.IP "scaled" 10 
+(make scaled copy of orig in target_dir 
+hierarchy, sized to max size). Default. 
+.IP "copied" 10 
+(copy orig to web dir) 
+.IP "custom" 10 
+(use copy if filesize < 1meg 
+resize, resave, if bigger than 1 meg) 
+.RE 
+ 
+.IP "\fB-d \fISTR\fR\fP" 10 
+Determine if tags found in EXIF structure are 
+added in desc files. 
+.IP "" 10 
+\fISTR\fR is one of "always", "never" or "exist" 
+("exist" only adds if the desc file already exist.) 
+Default is always. 
+.IP "\fB-c \fIcolor_style\fR\fP" 10 
+Color style to use. Can be \fBblue\fP 	    (default one), \fBgreen\fP, 
+\fBivory\fP and \fBpink\fP or 
+any other one defined in configuration/description files.  
+This option is deprecated (and thus, not supported by all 
+templates), in favor of alternate stylesheets and the 
+\fBcustomStyleSheet\fP parameter. 
+.IP "\fB-s \fIstyle\fR\fP" 10 
+Template style to use (styles provided for now are 
+\fBjoi\fP, \fBmarc\fP, 
+\fBmartin\fP, \fBmwolson\fP 	  \fBpetrus\fP, \fBsatyap\fP and 
+\fBswigs\fP). 
+.IP "\fB-t \fItemplate_dir\fR\fP" 10 
+Specify location of html templates. 
+.IP "" 10 
+Default is \fB~/.bins\fP, falling back 
+to default versions in 
+\fB/etc/bins/templates.\fIstyle\fR\fP. 
+.IP "\fB-p\fP         " 10 
+Numbers preceding the album title, followed by  
+an underscore are stripped. 
+If this option is given, then prefix ordering 
+numbers on directories are removed.  For example, 
+if one has directories \fBmay\fP, 
+\fBjune\fP, and \fBaugust\fP, they 
+can be renamed \fB0_may\fP, 
+\fB1_june\fP, and \fB2_august\fP and 
+they will appear in the album in the correct 
+order. 
+.IP "\fB-e\fP" 10 
+Tells the script to generate an editable version of 
+the album.  If set, some more links and icons are added to 
+directly access the \fB.xml\fP files for 
+editing. This is for editing purposes, not for a final 
+album. 
+.IP "\fB-i \fIiKey,iKey...\fR\fP" 10 
+Sets "ignore" keywords which will be compared against 
+the contents of the \fBignore\fP field of the 
+album's XML file, in the \fBignore\fP field in 
+\fBdescription\fP section.  If any of the 
+\fIiKeys\fR match those in the album's 
+"ignore" field, that album will not be processed.  See also 
+the \fBignore\fP parameter. 
+.IP "\fB-n \fIiKey,iKey...\fR\fP" 10 
+Sets "hidden" keywords which will be compared against 
+the contents of the \fBignore\fP field of the 
+album's XML file, in the \fBignore\fP field in 
+\fBdescription\fP section.  If any of the 
+\fIiKeys\fR match those in the album's 
+"ignore" field, that album will be hidden: it will not be 
+linked anywhere. See also the \fBhidden\fP 	  parameter. 
+.IP "\fB-v \fIX\fR\fP         " 10 
+\fIX\fR is the verbosity level (between 0 and 3) 
+.IP "\fB-h\fP         " 10 
+Show the help string this man page was originally based on. 
+.SH "SETTINGS" 
+.PP 
+bins is also controlled by other files. 
+.IP "\fB/etc/bins/binsrc\fP" 10 
+.IP "\fB~/.bins/binsrc\fP" 10 
+The \fBbinsrc\fP files are 
+XML files with a top level 
+\fBbins\fP tag.  There are three element 
+names with \fBbins\fP: \fBparameter\fP, 
+\fBcolors\fP, and \fBsizes\fP. 
+Each of these has a \fBname\fP attribute 
+which names the data in the element content. 
+.IP "" 10 
+The \fBcolors\fP element has a 
+\fBstyle\fP attribute, that can be used with 
+the \fBcolorStyle\fP parameter or the 
+\fB-c\fP command line option. It contains 
+\fBcolor\fP elements. The 
+\fBcolor\fP elements name has one of the 
+following values which is substituted into the template 
+files. This tag is deprecated, in favor of alternate 
+stylesheets and the \fBcustomStyleSheet\fP 	  parameter. 
+.RS 
+.IP "" 10 
+PAGE_BACK 
+.IP "" 10 
+PAGE_TITLE 
+.IP "" 10 
+MAINBAR_BACK 
+.IP "" 10 
+MAINBAR_TITLE 
+.IP "" 10 
+MAINBAR_LINK 
+.IP "" 10 
+MAINBAR_CURRENTPAGE 
+.IP "" 10 
+SUBBAR_BACK 
+.IP "" 10 
+SUBBAR_LINK 
+.IP "" 10 
+SUBBAR_CURRENTPAGE 
+.IP "" 10 
+SUBBAR_TITLE 
+.RE 
+.IP "" 10 
+The \fBsizes\fP element contains 
+\fBsize\fP elements which each have a 
+\fBname\fP attribute, a 
+\fBshortname\fP attribute, a 
+\fBheight\fP attribute, and a 
+\fBwidth\fP attribute.  These default to 
+.RS 
+.IP "" 10 
+Small, Sm, 40%, 40% 
+.IP "" 10 
+Medium, Med, 64%, 64% 
+.IP "" 10 
+Large, Lg, 100%, 100% 
+.RE 
+.IP "" 10 
+\fBname\fP and 
+\fBshortname\fP are used in the output 
+HTML and in generated filenames.  The 
+default values listed above are passed through 
+\fBgettext\fP for localization; overrides 
+in \fBbinsrc\fP files are not, and should 
+be in the desired language. 
+.IP "" 10 
+For the \fBparameter\fP elements the 
+\fBname\fP attribute names one of the 
+following parameters. 
+.RS 
+.IP "addExifToDescFile" 10 
+If set to 1 (the default), write EXIF data found in 
+the image file to the image desc file (but see also 
+the \fB-d\fP flag). 
+.IP "albumThumbInSubAlbumPage" 10 
+If set to 1 (the default), display the current 
+album thumbnail in sub-albums page 
+if it has pictures, with links to 
+the thumbnails page. 
+.IP "allThumbnailsPage" 10 
+If set to \fB1\fP, generate a page with all 
+thumbnails in the album and 
+sub-albums. This is deactivated 
+because it is an alpha feature which 
+seems to not work properly. 
+.IP "backgroundImage" 10 
+Set this to the image that should be displayed 
+as the background of the album pages.  The Image will 
+be copied to the static files directory. This works 
+only with joi, marc, martin and petrus templates for now. 
+ 
+.IP "borderOnThumbnails" 10 
+Width of the border of the thumbnail's image in 
+the thumbnails page, in pixels. \fB0\fP 		means no border. 
+ 
+.IP "colorStyle" 10 
+Name of the color style to use. Default is 
+\fBblue\fP. See also the 
+\fB-c\fP option which takes precedence.  
+This option is deprecated (and thus, not supported by 
+all templates), in favor of alternate stylesheets and 
+the \fBcustomStyleSheet\fP 		parameter. 
+.IP "compactHTML" 10 
+If set to \fB1\fP, generated 
+HTML code is cleaned up to reduce 
+the size of pages and thus, speed up browsing. This 
+reduces the size of HTML BINS files 
+by about 30%. See \fBHTML::Clean(3)\fR to 
+know how optimizations are performed. 
+.IP "configFileName" 10 
+Can be set in the global config file, but only 
+influences the basename of the local user config 
+file.  Defaults to \fB.binsrc\fP. 
+.IP "createEmptyDescFields" 10 
+If set to 1 (the default), add empty description 
+fields in the \fBdescription\fP section 
+when the image description file is created to ease 
+later manual editing. 
+.IP "createHtaccess" 10 
+If \fB1\fP, create an Apache 
+\fB.htaccess\fP file in the root dir of 
+the album with the encoding charset bound to 
+\fBhtml\fP and \fBhtm\fP 		files. This is a parameter global for the album, it 
+can't be set in album.xml. 
+.IP "customStyleSheet" 10 
+Set this to the CSS file that should be used as 
+the stylesheet for the album pages.  The CSS file will 
+be copied to the static files directory. This works 
+only with joi, marc, martin and petrus templates for now. 
+ 
+.IP "dateString" 10 
+Specify the format of date strings.  This variable 
+accepts all formats supported by \fBdate(1)\fR. 
+ 
+.IP "defaultSize" 10 
+Size to use when user clicks directly on the 
+thumbnail in the thumbnails page instead of one of 
+the size name. 0 is the first size 
+(\fBSmall\fP in the default config), 1 
+the second (\fBMedium\fP), and so 
+on. Set this variable to \-1 if you don't want the 
+thumbnail to be clickable. 
+.IP "deExifyImages" 10 
+If set to 1, do NOT copy exif data found in the 
+source images to any of the generated resized images. 
+Setting this option can yield significant space 
+savings, especially for thumbnail and imagelist 
+pages. 
+.IP "emptyAlbumDesc" 10 
+If set to 1, and album desciption is not set, no 
+message will be displayed (instead of the "No 
+long/short description available" one). 
+.IP "enlarge" 10 
+If set to 1, small images are enlarged 
+in the "med" and "large" series.  (defaults to 0). 
+.IP "excludeBackgroundImage" 10 
+If set to 1, the image with the name given in 
+\fBbackgroundImage\fP will be excluded from the 
+current directory. 
+ 
+.IP "excludeDirs" 10 
+Exclude directories that match this regexp (if 
+set). Set to  
+CVS$ in default config, so that CVS 
+subdirs aren't processed by bins. 
+ 
+.IP "excludeFiles" 10 
+Exclude image files that match this regexp (if 
+set). No image files are excluded in default config. 
+ 
+.IP "globalConfigDir" 10 
+Can't usefully be set, since it has already been 
+used when the first config file is read.  Defaults 
+to \fB/etc/bins\fP. 
+.IP "hidden" 10 
+Put here a comma separated list of keyword. If 
+one on this keyword is found in the 
+\fBignore\fP field in the 
+\fBdescription\fP section of an 
+\fBalbum.xml\fP, then this sub-album 
+will be hidden, i.e. it will be generated but not 
+linked anywhere. You can also use the 
+\fB-n\fP command line option. 
+.IP "homeURL" 10 
+Set this to your home page's 
+URL. This is used for the leave button 
+in some templates. 
+.IP "htmlEncoding" 10 
+HTML pages charset encoding. 
+.IP "ignore" 10 
+Put here a comma separated list of keyword. If 
+one on this keyword is found in the 
+\fBignore\fP field in the 
+\fBdescription\fP section of an 
+\fBalbum.xml\fP, then this sub-album 
+will be ignored, i.e. it will not be processed. You 
+can also use the \fB-i\fP command line 
+option. 
+.IP "imagePageCycling" 10 
+If set to 0 next/prev-Links will be hidden if 
+the actual page is the last/first Image page. 
+.IP "javaScriptPreloadImage" 10 
+If set to \fB1\fP, add some 
+javascript code in image pages to preload the next 
+image of the same size when current one is loaded, to 
+speed up the album browsing. 
+.IP "javaScriptPreloadThumbs" 10 
+If set to \fB1\fP, add some 
+javascript code in thumbnails pages to preload 
+thumbnails of the next page when current one is 
+loaded, to speed up the album browsing. 
+.IP "jpegQuality" 10 
+Quality of scaled jpegs (lower number = more 
+compression, lower quality) in 1-100 range (default 
+of 75).  See imagemagick docs for more details. 
+.IP "linkInsteadOfCopy" 10 
+If set to 1, we link the picture instead of 
+copying it if possible (i.e. scaleIfSameSize is set to 
+\fB0\fP and destination image doesn't 
+have to be rotated: \fBrotateImages\fP is 
+set to \fBoriginal\fP or 
+\fBnone\fP, or orientation is already 
+correct). Warning : if whenSrcSmaller is set 
+to enlarge, original image can be modified. 
+.IP "linkRelative" 10 
+If set to 1, we use a relative path for the link if 
+\fBlinkInsteadOfCopy\fP is set to 1. 
+ 
+.IP "maxAlbumsForLongSubAlbum" 10 
+If the number of sub albums is greater (than 
+this value which defaults to 20), 
+generate a short sub album page 
+instead of the long one. (Short sub album pages 
+appear to be unsupported at the moment; this option 
+is disabled.) 
+.IP "noRotation" 10 
+Don't perform rotation on files matching this 
+regexp. This can used in conjunction with 
+\fBscaleIfSameSize=0\fP and a scaled size of 
+\fB100%x100%\fP to keep original pictures in 
+your album. 
+.IP "numThumbsPerPage" 10 
+Number of thumbnails (default of 16) displayed 
+in each page in an album. 
+.IP "pathImgNum" 10 
+If set to 1 the path in the imageview contains 
+the number of the current image. 
+.IP "pathShowIcon" 10 
+If set to 1 the path contains icons. 
+.IP "previewMaxWidth" 10 
+.IP "previewMaxHeight" 10 
+Max thumbnail width and height (default 150x150). 
+.IP "jpegProgressify" 10 
+whether to convert generated jpegs to 
+progressive using jpegtran (if available).  can be 
+\fBnever\fP, \fBalways\fP, or 
+\fBsmaller\fP (if the progressified file 
+is smaller than the baseline). 
+.IP "reverseOrder" 10 
+Are we reversing sorting order for pictures or 
+directories ? 0=none, 1=dirs, 2=pix, 3=both. See 
+also \fB-r\fP command line option. 
+ 
+.IP "rotateImages" 10 
+Do we rotate images if the 
+\fBOrientation\fP EXIF 		tag is found? If set to \fBoriginal\fP 		(the default), the original image is rotated the first 
+time, and then it is left untouched. If set to 
+\fBdestination\fP, this is all the scaled 
+images and thumbnails that are rotated. This is less 
+efficient, but the original images are preserved (and 
+is useful if the original images are read-only). If 
+set to \fBnone\fP, no rotation is 
+performed. 
+.IP "rotateWithJpegtran" 10 
+If set to \fB1\fP, 
+\fBbins\fP try to use the 
+\fBjpegtran\fP program to rotate 
+JPEG images if it is 
+available. \fBjpegtran\fP is faster and 
+lossless, but some versions fail to perform rotation 
+correctly, so it is deactivated in default config. If 
+set to \fB0\fP or if 
+\fBjpegtran\fP is not found, 
+\fBmogrify\fP (from ImageMagick) is 
+used. 
+.IP "scaleIfSameSize" 10 
+If set to 1, we scale the picture even 
+if destination size is the same as the 
+original picture, if set to 0 (the default), the 
+original image is just copied if the 
+size is correct. 
+.IP "scaleMethod" 10 
+What method should be used to create scaled 
+pictures and thumbnails ? Can be either 
+\fBscale\fP or 
+\fBsample\fP. \fBsample\fP 		is \fBfaster\fP, scale is better. 
+ 
+.IP "searchEngine" 10 
+If 1, generate a search page. Images can be searched 
+on description fields set in the 
+\fBsearchFields\fP parameter.  
+ 
+.IP "searchFields" 10 
+Space separated list of description field names used 
+by the search engine, if 
+\fBsearchEngine\fP is set to 1. 
+ 
+.IP "searchLimit" 10 
+Maximum results returned by the search engine, if 
+\fBsearchEngine\fP is set to 1. Note 
+that if this number is too high, it can hang the 
+browser. 
+ 
+.IP "stripDirPrefix" 10 
+If \fB1\fP, numbers preceding the 
+album title, followed by an underscore, are 
+stripped. If this parameter is set, then prefix 
+ordering numbers on directories are removed.  For 
+example, if one has directories may, june, and august, 
+they can be renamed \fB0_may\fP, 
+\fB1_june\fP, and 
+\fB2_august\fP and they will appear in 
+the album in the correct order. This can be overridden 
+by the \fB-p\fP command line option. 
+.IP "templateStyle" 10 
+Name of the template style to use. Default is 
+\fBswigs\fP. Other templates provided 
+with BINS are \fBjoi\fP, 
+\fBmarc\fP, \fBmartin\fP, 
+\fBpetrus\fP and 
+\fBsatyap\fP. Several templates can be 
+used for different sub-album of an album, by using 
+this parameter in the \fBbins\fP section 
+of the \fBalbum.xml\fP files. See also 
+the \fB-s\fP option which takes precedence 
+over binsrc (but not album.xml). 
+.IP "thumbnailBackground" 10 
+If set to 1, add a background colour 
+(SUBBAR_BACK) to the thumbnail's cell in the 
+thumbnails page so that if the top and bottom borders 
+are wider than the image (for example, if it is in 
+portrait mode), instead of spilling over, there is a 
+border around the whole picture.  By default, use the 
+PAGE_BACK color. 
+.IP "thumbnailInImageList" 10 
+Display thumbnails on the Image List page, set 
+to 1 by default. 
+.IP "thumbnailPageCycling" 10 
+If set to 0 next/prev-Links will be hidden if 
+the actual page is the last/first 
+Thumbnail page. 
+.IP "thumbPrevNext" 10 
+If set to 1 (the default), display thumbnails close 
+to the previous and next link at the 
+bottom of the image page. 
+.IP "thumbsPerRow" 10 
+Number of thumbnails (default of 4) displayed in each 
+row in an album. 
+.IP "titleOnThumbnail" 10 
+Should the title be displayed on top on the 
+thumbnail in the thumbnails page? (defaults to 1.) 
+.IP "treePreview" 10 
+If set to 1, preview thumbnails will be showed 
+in the album tree page. This works only with joi, 
+marc and petrus templates for now. 
+ 
+.IP "updateOriginalPerms" 10 
+If set to 1, read permissions on images will be 
+set, to ensure http deamon will be able to read 
+them. 
+ 
+.IP "userConfigDir" 10 
+Can be set in the global config file (since 
+after the user one is read, it is too late). 
+Defaults to \fB~/.bins\fP and is 
+processed by \fBbsd_glob\fP (see 
+\fBFile::Glob\fP for details.) 
+ 
+.IP "xmlEncoding" 10 
+XML files charset encoding. 
+.RE 
+.IP "\fB\fIimage.jpg\fR\fP" 10 
+The EXIF tags are extracted from 
+the image.  Currently only the 
+\fBOrientation\fP tag influences the 
+processing, but a variety of settings are copied into the 
+HTML file generated via the 
+\fBdetails.html\fP template. 
+.IP "\fB\fIimage.jpg\fR.xml\fP" 10 
+The XML file contains an 
+\fBimage\fP element, which contains three child 
+elements: 
+.RS 
+.IP "\fBdescription\fP" 10 
+which has \fBfield\fP children that 
+contain per-image data.  The \fBname\fP 		  attribute names the tag (allowing simple 
+extensibility, see the 
+\fBbins_edit\fP 		  \fB\-\-generic\fP flag) but 
+\fBbins\fP itself currently only 
+makes use of 
+.RS 
+.IP "" 10 
+title 
+.IP "" 10 
+description 
+.IP "" 10 
+people 
+.IP "" 10 
+location 
+.IP "" 10 
+date 
+.IP "" 10 
+event 
+.RE 
+.IP "\fBbins\fP" 10 
+which works as described with the 
+\fBbinsrc\fP file settings, except 
+that many of the settings are not meaningful in the 
+context of a single picture. 
+.IP "\fBexif\fP" 10 
+which has a cache of values copied from the 
+EXIF tags in the image, to allow 
+simpler processing by other tools. 
+.IP "" 10 
+If a user wants to override the 
+EXIF values and provide a 
+replacement (such as a corrected 
+\fBOrientation\fP or an 
+\fBOwner\fP setting that reflects who 
+you loaned the camera to) adding a 
+\fBpriority\fP attribute with a value 
+of "1" will prevent \fBbins\fP from 
+replacing it with the value in the image. 
+.RE 
+.IP "\fBalbum.xml\fP" 10 
+This file contains an 
+\fBalbum\fP element, which contains 
+\fBdescription\fP and \fBbins\fP 	    stanza as described for an image.  The are extensible in 
+the same manner, but \fBbins\fP only makes 
+use of 
+.RS 
+.IP "" 10 
+dirname 
+.IP "" 10 
+descFileName 
+.IP "" 10 
+shortdesc 
+.IP "" 10 
+title 
+.IP "" 10 
+sampleimage 
+.IP "" 10 
+longdesc 
+.RE 
+.IP "\fBinclude_images.txt\fP" 10 
+includes image filenames (relative to the current 
+album, i.e. the directory where the 
+\fBinclude_images.txt\fP file is stored.) 
+Each filename appears on a line by itself; a line 
+beginning with a \fB#\fP is a comment, and 
+lines composed entirely of whitespace are ignored. 
+Otherwise, the line is exactly the filename.  These images 
+are included in the order listed, and added after any that 
+actually appear in the directory. 
+.IP "\fB\fItemplate\fR.html\fP" 10 
+There are a number of template 
+HTMLfiles which are used to generate 
+the actual images.  The base names of these are 
+.RS 
+.IP "" 10 
+tree 
+.IP "" 10 
+imagelist 
+.IP "" 10 
+subalbum 
+.IP "" 10 
+thumbnail 
+.IP "" 10 
+details 
+.IP "" 10 
+image 
+.RE 
+.IP "" 10 
+The default versions of these files in 
+\fB/etc/bins/templates.default\fP should 
+show how they work, as does the 
+\fBHTML::Template\fP documentation.  Aside 
+from the \fBCOLOR\fP substitutions described 
+above, a template can also reference 
+.RS 
+.IP "" 10 
+BINS_VERSION 
+.IP "" 10 
+ENCODING 
+.IP "" 10 
+GENERATED_DATE 
+.IP "" 10 
+BINS_ID 
+.RE 
+.SH "SEE ALSO" 
+.PP 
+bins_edit (1), jpegtran (1), File::Glob, HTML::Template, imagemagick. 
+.SH "AUTHOR" 
+.PP 
+This manual page was written by Mark W. Eichin eichin@thok.org for 
+the \fBDebian\fP system (but may be used by others).  As it is 
+mostly derived from the \fBbins\fP program 
+itself, it is covered by the GNU General Public License. 
+.\" created by instant / docbook-to-man, Wed 24 Aug 2005, 23:31