README
1Next Generation Pretty README.
2
3WARNING: Please read BUGS for important information before using npretty!
4
5npretty is a perl script which generates image galleries.
6It can generate thumbnail and preview pages based on a template,
7convert videos to gif89a(via mplayer), remove EXIF thumbnails and auto-rotate
8images (via jhead), scale images with many different filters and much more.
9
10Requirements
11============
12- Anything but Windows (fork won't work)
13- Kernel threading support
14- perl > 5.8.x (untested on anything lower)
15- perl fork module
16- Image::ExifTool perl module
17- Image::Magic
18- Getopt::Long
19
20Suggested dependencies
21======================
22mplayer with many codecs and gif89a output support (http://mplayerhq.hu)
23display (comes with imagemagick) (http://www.imagemagick.org)
24jhead (http://www.sentex.net/~mwandel/jhead/)
25
26Install
27=======
28If you don't have the required perl modules, the 'quick and dirty' way to
29install them is to start up cpan and then:
30cpan> force install forks
31cpan> force install Image::ExifTool
32cpan> force install Image::Magick
33
34Agree to all dependencies cpan wants to get.
35Assuming you have ImageMagick and forking support, this should work even
36though it will spawn a lot of warnings and errors.
37
38create /etc/npretty/ and copy novideo.gif, npretty_template.tpl and npretty.conf
39to it.
40
41Then place npretty.pl in a fitting directory and make it executable:
42as root,
43 chmod +x npretty.pl
44 cp npretty.pl /usr/local/bin
45
46You should now be ready to go!
47
48Usage
49=====
50
51There are too many ways to use npretty for me to describe them all here.
52Usually, something like
53 npretty.pl --image-path=/path/to/images/ --destination=/my/destination/
54should be a good start.
55
56Options
57=======
58
59--video-preview-dimensions= video preview dimensions XxY
60--image-quality= image quality in percent (JPEG/MIFF/PNG only)
61--resize-algorithm= resizing algorithm, set to 'help' for list
62--keep-thumb-ratio keep aspect ratio of thumbnails
63--keep-preview-ratio keep aspect ratio of previews
64--use-video use video converter
65--use-preprocessor use pre-processor
66--pre-remove-cthumbs remove cam thumbs with pre-processor
67--pre-auto-rotate auto-rotate images with pre-processor
68--jobs= jobs to run simultaneously
69--mplayer-path= path to 'mplayer' binary
70--image-path= path to images
71--image-dest= destination path for images
72--thumb-dest= destination path for thumbs
73--destination= destination prefix for archive
74--preview-dest= destination path for previews
75--thumb-dimensions= thumbnail dimensions, XxY
76--preview-dimensions= preview dimensions XxY
77--thumbs-per-page= max thumbs per page
78--pages= max number of pages
79--sloppy-files= be sloppy on page calculation
80--title= text to prepend to title tag
81--config= use config instead of config hierarchy
82--sidepad= string to pad thumb/preview lists with
83--delete-originals delete original images
84--overwrite-images overwrite images
85--overwrite-previews overwrite previews
86--overwrite-thumbs overwrite thumbnails
87--overwrite-all overwrite everything
88--overwrite-nothing overwrite nothing
89--template template file to use
90--skip-images skip image creation
91--skip-pages skip page creation
92--recursive recursively look for images
93--maxdepth traversal depth if recursive
94--comments ask for comment on each image
95--preview show preview before comment
96--sloppy enable sloppiness
97--help this text
98--version version
99
100Template
101========
102The template file consists of blocks, subblocks and tags.
103
104Blocks
105------
106There are three major blocks:
107 [NPRETTY_BLOCK_THUMB]
108 [NPRETTY_BLOCK_BODY] and
109 [NPRETTY_BLOCK_PREVIEW]
110The THUMB block contains all initial and final HTML for thumbnail pages.
111The BODY block contains HTML code containing and surrounding each thumbnail
112image.
113The PREVIEW block contains all HTML for preview pages.
114Each BLOCK is closed by an identical block tag with a \/ prepended before the
115bracket. For example,
116 [NPRETTY_BLOCK_BODY] HTML here [/NPRETTY_BLOCK_BODY]
117
118Subblocks
119---------
120The major blocks contain subblocks and tags.
121Subblocks work the same as the major blocks, but are
122mostly formed on a 'if exists'-basis.
123
124The subblocks are:
125 In THUMB block:
126 [NPRETTY_LIST]
127 [NPRETTY_LIST_IFSEL]
128 [NPRETTY_PREV_EXIST]
129 [NPRETTY_PREV_NOEXIST]
130 [NPRETTY_NEXT_EXIST]
131 [NPRETTY_NEXT_NOEXIST]
132 [NPRETTY_COMMENT_EXIST]
133 [NPRETTY_TITLE_EXIST]
134 [NPRETTY_TITLE_NOEXIST]
135 In BODY block:
136 [NPRETTY_DEL<_n>]
137 [NPRETTY_PAD_DEL]
138 In PREVIEW block:
139 [NPRETTY_PREV_LIST]
140 [NPRETTY_PREV_LIST_IFSEL]
141 [NPRETTY_PREV_IMG_EXIST]
142 [NPRETTY_PREV_IMG_NOEXIST]
143 [NPRETTY_NEXT_IMG_EXIST]
144 [NPRETTY_NEXT_IMG_NOEXIST]
145 [NPRETTY_COMMENT_EXIST]
146 [NPRETTY_TITLE_EXIST]
147 [NPRETTY_TITLE_NOEXIST]
148
149Most of these should be self-explanatory, but there are a few odd ones.
150
151The [NPRETTY_LIST] subblock specifies where and how you want to insert links to
152thumbnail pages. If you have five thumbnail pages, the code inserted in this
153subblock will be repeated five times, with the internal variables updated each
154iteration. This allows you to design the layout for your link menu.
155
156The [NPRETTY_PREV_LIST] is the same as [NPRETTY_LIST], but for preview pages.
157
158The [NPRETTY_DEL<_n>] subblock specifies code to be inserted between every <n>
159images. [NPRETTY_DEL_4] Hello! [/NPRETTY_DEL] would insert "Hello!" between
160every 4 images, unless the last image is the 4th.
161
162The [NPRETTY_PAD_DEL] subblock specifies code to be inserted as padding when
163there are no more images on the page, but the delimiter count is uneven.
164This is handy for properly ending a table, for example.
165
166Tags
167----
168Tags are internal variables which will be replaced with dynamic data based on
169the block and subblock in which the variable lies. There are several
170inconsistencies here which I blame on my sloppy coding, but for the mostpart
171it should work alright.
172
173Tags Replaced with
174[NPRETTY_BODY] contents of BODY block
175[NPRETTY_TITLE] set title
176[NPRETTY_COMMENT] set comment for current image
177[NPRETTY_LIST_PAGE] current page in iterator
178[NPRETTY_LIST_NUM] current page number in iterator
179[NPRETTY_PREV_PAGE] previous page (if possible)
180[NPRETTY_PREV_PAGE_NUM] previous page number (if possible)
181[NPRETTY_NEXT_PAGE] next page (if possible)
182[NPRETTY_NEXT_PAGE_NUM] next page number (if possible)
183[NPRETTY_PREVIEW_PAGE] preview page for image
184[NPRETTY_THUMB] thumbnail for image
185[NPRETTY_SIZE] filesize of original image
186[NPRETTY_PAGE] current page
187[NPRETTY_PREV_LIST_PAGE] current preview page in iterator
188[NPRETTY_PREV_LIST_PAGE_NUM] current preview page number in iterator
189[NPRETTY_PREV_IMG] current preview image
190[NPRETTY_PREV_IMG_NAME] current preview image name
191[NPRETTY_NEXT_IMG] next image (if possible)
192[NPRETTY_NEXT_IMG_NAME] next image name (if possible)
193[NPRETTY_FILENAME] current image filename
194[NPRETTY_PREVIEW] current preview image
195[NPRETTY_EXIF_<element>] EXIF-element <element>
196
197How to use these would be a mess to document, and I'm not good at writing.
198Have a look at the default template file to see a good example of how it
199all works.
200
201Other
202=====
203npretty is licenced under the GPLv2.
204For contact, check https://github.com/gammy
205
