Fri Nov 24 21:37:01 2006 John Ellis <johne@verizon.net>
[geeqie.git] / README
1 ###################################################################
2 ##                          GQview 2.1.4      (November 4, 2006) ##
3 ##                                                               ##
4 ##              Copyright (C) 1999 - 2006 John Ellis.            ##
5 ##                                                               ##
6 ##                      Use at your own risk!                    ##
7 ##                                                               ##
8 ##  This software released under the GNU General Public License. ##
9 ##       Please read the COPYING file for more information.      ##
10 ###################################################################
11
12 Author: John Ellis <johne@verizon.net>
13 e-mail: gqview@users.sourceforge.net
14 homepage: http://gqview.sourceforge.net
15
16
17  BETA! BETA! BETA! BETA! BETA! BETA! BETA! BETA! BETA! BETA! BETA!
18
19  The 2.1.x series are all development releases, and as such may
20  contain incredible bugs. Only use if interested in the new features.
21
22  The stable release as of this writing is 2.0.0.
23
24  BETA! BETA! BETA! BETA! BETA! BETA! BETA! BETA! BETA! BETA! BETA!
25
26
27 ======== README contents:
28
29     * Requirements
30     * Notes and changes for this release
31     * Installation
32     * Description / Features
33     * Documentation (keyboard shortcuts)
34     * Editor command macros
35     * Additional comments
36     * Translation status
37     * Credits
38
39 ======== Requirements
40
41   Required libraries:
42     GTK+ 2.4.x: ftp://ftp.gtk.org/pub/gtk
43
44   Optional libraries:
45     lcms, for color management support: http://www.littlecms.com
46         (disable with configure option: '--without-lcms')
47
48 ======== Notes and changes for this release            [section:release_notes]
49
50   Changes:
51
52    2.1.4: (quick bug fix release)
53     * Fix Pan View scrolling to top left or center when the
54       canvas size is recalculated.
55
56    2.1.3:
57     + Add translations eo, eu; updated translation be.
58     + Add command to view image as grayscale with [Shift]+[G].
59     - Make [F11] also toggle fullscreen.
60     - Make [Shift]+[P] show print dialog in additional places.
61     - Make [Control]+[V] display current image in a new window.
62     - Use new window icons, and include original svg images with source.
63     - Add --geometry command line option.
64     - In Pan View, make [Control]+[F] show search bar,
65       and [Control]+[G] repeat last search.
66     - Add Pan View option to display EXIF data with info popup.
67     - Add Pan View option to display full size image with info popup.
68     * Fix Pan View inability to scroll to popups that are offscreen.
69     * Fix Pan View shortcuts to work regardless of widget focus.
70     * Fix command line parsing when given multiple folders.
71     * Use correct folder name (.thumblocal) to store local thumbnails
72       as described in the freedesktop thumbnail managing standard.
73     * Fix auto rename utility to allow counting from zero.
74     * Fix [Shift]+[R] from also activating refresh when in fullscreen.
75     * Fix [Shift]+[F] from also deactivating fullscreen, then crashing.
76     * Fix long standing bug of partially obscured window not properly
77       redrawing when panning the image.
78     * Fix using [Escape] key to close image windows from eventually
79       leading to crash.
80     * Fix very slow re-sort in the file list.
81     * Fix warning when attempting to draw zero length string onto pixbuf.
82
83   Notes:
84
85     For translation status list, see further below.
86
87     Version in perenthesis indicates first appearance of feature or change.
88
89     (2.1.5) Add support for color profiles when lcms is installed. To
90     disable color profiles and use of lcms, run configure
91     with '--without-lcms'.
92
93     (2.1.1) Add support for viewing jpeg images and EXIF embedded within
94     raw files for Canon (.crw, .cr2) Fujifilm (.raf), and Nikon (.nef).
95     Note that not all cameras that support a raw format will necessarily
96     save a usable jpeg in the raw file (for example some Nikon cameras only
97     store a tiny thumbnail within the raw .nef file).
98
99     (1.5.6) The "shared thumbnail cache" is a proposal to unify the method
100     of storing thumbnails, so that they are compatible between different
101     applications. Using this option will allow GQview to share it's
102     thumbnails with, and use thumbnails from, other applications. Current
103     releases of GNOME (through nautilus and gthumb) and the gimp use this
104     new thumbnailing system. The latest draft of the thumbnail standard
105     is located on freedesktop.org in the standards section, and links to:
106
107       http://triq.net/~jens/thumbnail-spec/index.html
108
109     The shared thumbnail standard and GQview's classic mechanism can
110     not be used at the same time, enabling the "use shared thumbnail cache"
111     option will disable the use of classic thumbnails and use the new
112     shared thumbnails.
113
114     (1.5.6) Collections contained in $HOME/.gqview/collections are now
115     updated when moving or renaming files, even if the collection is not
116     open at the time.
117
118     (1.5.6) The new option to the keep the full screen window above other
119     windows is only available when using at least GTK+ 2.4.0
120
121     (1.5.5) Dialog buttons are now ordered as recommended by the GNOME HIG.
122     The GNOME Human Interface Guidelines live at:
123        http://developer.gnome.org/projects/gup/hig/
124     To restore the old button order you must be using GTK 2.6 and set
125     the "gtk-alternative-button-order" key to TRUE in the gtkrc file:
126        $HOME/.gtkrc-2.0
127     by changing or adding this line:
128        gtk-alternative-button-order = 1
129
130     (1.5.5) The dithering option is now a hidden option, to change it
131     please refer to section 10.7 of the manual (help -> contents).
132
133     (1.5.0) Keywords and comments can now be entered for a file. Two places
134     allow keyword and comment entry. The first is via the new image details
135     sidebar accessed with (Ctrl-K), and the second is a details tab in the
136     properties dialog. If multiple files are selected, two buttons are
137     available: One allows adding the keywords to the selected files, the
138     other replaces existing keywords with the new keywords.
139
140     Keyword and comment metadata is stored in $(HOME)/.gqview/metadata, and
141     mirrors the existing filesystem tree. Metadata filenames have a suffix
142     of .meta appended. If 'cache into .thumbnails' is enabled, metadata is
143     stored locally to the original file in a hidden subfolder ".metadata".
144     If write permissions do not allow local saving of metadata, GQview falls
145     back to the default $(HOME)/.gqview/metadata location.
146
147     (1.5.0) Search dialog (F3 key) types:
148        Path       searches files in the entered folder.
149        Comments   searches all file metadata stored in ~/.gqview/metadata.
150        Results    searches the current list of results, allowing refinement.
151
152     (1.3.6) Drag and drop has been significantly improved, with a few
153     changes. Button 1 will now initiate a drag, button 2 will still work
154     for this, the difference is button 2 will not change the selection.
155
156     (1.3.6) A middle button click will now toggle selection of clicked item.
157
158     (1.3.5) UTF-8 and filenames: GQview works fine if your filenames
159     correctly match the prefered locale encoding (LANG environment
160     variable), and prints errors on the console when they do not.
161
162     (1.3.3) Safe delete does not include undo, you will need to go to the
163     trash folder and retrieve the file(s) manually. The files can be viewed
164     by clicking the view button near the safe delete option in the preferences
165     window. Files moved to the trash folder are prefixed with a 6 digit
166     number. Lower numbers are older, and deleted (permanently) first when the
167     trash size limit is reached.
168
169     (1.3.2) New in 1.3.2 are sidebars for exif data display and a sort
170     manager. Exif (ctrl + E) should be self explanatory. The Sort manager is a
171     directory list that allows copying or moving the displayed image to that
172     destination with one click of the button - very helpful when visually
173     sorting many images into subdirectories. To edit, reorder, or remove items
174     in the sort list, use the right click menu. The keyboard can also be used
175     by moving the focus to the desired button, then pressing menu/ctrl+f10 key
176     to display the popup menu, or shift+up/shift+down keys to change the
177     button location in the list. Items can also be added to the list by
178     dragging a directory onto the list.
179
180   Code hackers:
181
182     If you plan on making any major changes to the code that will be offered
183     for inclusion to the main source, please contact me first - so that we
184     can avoid duplication of effort. A good example is porting any part of
185     GQview that uses deprecated widgets to GTK2 widgets, there are already
186     several such patches floating around. This is especially true if the
187     change is listed in the TODO!
188                                              -John ( johne@verizon.net )
189
190   Known bugs:
191
192     see the TODO file.
193
194 ======== Installation
195
196   Compilation: ./configure ; make
197   General install: make install
198   Removal: make uninstall
199
200     - To build an RPM binary:
201
202          on RedHat 6.x, 7.x use 'rpm -tb gqview-x.x.x.tar.gz'.
203          on RedHat 8 and 9 use 'rpmbuild -tb gqview-x.x.x.tar.gz'.
204          on other rpm distros, it depends on which version of rpm is used, if
205          the option fails with the rpm command, try rpmbuild.
206
207       Where the resulting package is placed is distribution specific, for
208       example in RedHat it is placed in /usr/src/redhat/RPMS/{architecture}/
209
210 ======== Description / Features
211
212   GQview is a graphics file viewer. Basic features:
213
214     - Single click image viewing / navigation.
215     - Zoom functions.
216     - Thumbnails, with optional caching and .xvpics support.
217     - Multiple file selection for move, copy, delete, rename, drag and drop.
218     - Drag and drop.
219     - Slideshow.
220     - Full screen.
221     - Ability to open images in external editors (configurable).
222     - Collections.
223     - Comparison of images to find duplicates by name, size, date,
224       dimensions, or image content similarity.
225     - EXIF support.
226
227 ======== Documentation (brief)                         [section:documentation]
228
229   Keyboard commands:
230     [PageDown], [Keypad PageDown]      next image
231     [PageUp], [Keypad PageUp]          previous image
232     [Home], [Keypad Home]              first image in list
233     [End], [Keypad End]                last image in list
234     [Tab]                              tab completion in path entry window
235     [Escape]                           cancel completion in path entry window
236
237   Keyboard commands valid when image has focus (image has black rectangle)
238     arrow keys, [Keypad arrows]        pan image
239     [Shift] - arrow keys               pan image faster
240     [Space]                            next image
241     [Backspace] , B                    previous image
242
243   File menu related:
244     [Ctrl] - N                         new window
245     C                                  new empty collection
246     O                                  open collection
247     D                                  open a Find Duplicates window
248     [Shift]- P                         open Print dialog
249     [Ctrl] - F                         new folder
250     [Ctrl] - C                         copy file
251     [Ctrl] - M                         move file
252     [Ctrl] - R                         rename file
253     [Ctrl] - D, [Delete]               delete file
254     [Ctrl] - W                         close window
255     [Ctrl] - Q                         exit GQview
256
257   Edit menu related:
258     [Ctrl] - 1 .. 0                    run external editor
259     [Ctrl] - A                         select all files
260     [Ctrl] - [Shift] - A               unselect all files
261     [Ctrl] - P                         display image properties window
262     [Ctrl] - O                         configure Options
263     ]                                  rotate image clockwise
264     [                                  rotate image counterclockwise
265     [Shift] - R                        rotate image 180 degrees
266     [Shift] - M                        mirror image (horizontal)
267     [Shift] - F                        flip image (verticle)
268     [Shift] - G                        grayscale image
269
270   View menu related:
271     +, =, [Keypad +]                   zoom in
272     -, [Keypad -]                      zoom out
273     Z, [Keypad /]                      zoom to original size
274     X, [Keypad *]                      zoom to fit within window
275     W                                  zoom to fit width of window
276     H                                  zoom to fit height of window
277     1, 2, 3, 4                         zoom to Nx (3 = 3x)
278     9, 8, 7                            zoom to -2, -3, -4, respectively
279     T                                  toggle thumbnails in list view
280     [Ctrl] - L                         display files as list view
281     [Ctrl] - I                         display files as icon view
282     [Ctrl] - T                         toggle tree view of directories
283     R                                  refresh list
284     L                                  (Un)float file selection area
285     [ctrl] - H                         (Un)hide file selection area
286     [Ctrl] - K                         toggle Keywords sidebar
287     [Ctrl] - E                         toggle EXIF sidebar
288     [Ctrl] - S                         toggle sort manager sidebar
289     F, V                               toggle full screen
290     S                                  toggle slide show
291     P                                  (Un)pause slideshow
292     [Ctrl] - V                         display current image in new window
293
294   Collection windows:
295
296     arrows, [Keypad arrows]            move selection
297     [Shift] + arrows                   select multiple images
298     [Ctrl] + arrows                    move without changing selection
299     [Space]                            select only image with focus
300     [Ctrl] + [Space]                   toggle selection of image with focus
301     [Home], [Keypad Home]              move focus to top of images
302     [End], [Keypad End]                move focus to end of images
303       (shift and ctrl work with Home, End, PageUp/Down as with arrows)
304     [Ctrl] - A                         select all images
305     [Ctrl] - [Shift] - A               unselect all images
306
307     [Delete], [Keypad Delete]          remove selected images from collection
308                                        (does not delete file)
309     [Ctrl] - L                         add images from main window file list
310
311     [Ctrl] - T                         toggle display of icon filename text
312
313     N                                  sort collection by name
314     D                                  sort collection by date
315     B                                  sort collection by size (bytes)
316     P                                  sort collection by location (path)
317     I (*)                              sort collection by name numerically
318                                    (file1 file10 file2 -> file1 file2 file10)
319
320     [Enter], [Keypad Enter]            view image with focus in main window
321     V                                  view image with focus in new window
322     [Ctrl] - 1 .. 0                    open selected image(s) in editor
323
324     S                                  save collection
325     [Ctrl] - S                         save collection as...
326     A                                  append to collection...
327
328     [Shift] - P                        print selected images...
329
330     [Ctrl] - C                         copy selected files...
331     [Ctrl] - M                         move selected files...
332     [Ctrl] - R                         rename selected files...
333     [Ctrl] - D                         delete selected files
334
335     [Ctrl] - P                         display image properties window
336
337     [Ctrl] - W                         close window
338
339   Find Duplicates window:
340
341     [Ctrl] - A                         select all images
342     [Ctrl] - [Shift] - A               unselect all images
343     1                                  select group 1 duplicates
344     2                                  select group 2 duplicates
345
346     [Ctrl] - L                         add images from main window file list
347     C                                  add selected images to new collection
348
349     [Delete], [Keypad Delete]          remove selected images from list
350     [Ctrl] - [Delete]                  clear window
351
352     [Enter], [Keypad Enter]            view image with focus in main window
353     V                                  view image with focus in new window
354     [Ctrl] - 1 .. 0                    open selected image(s) in editor
355
356     [Ctrl] - C                         copy selected files...
357     [Ctrl] - M                         move selected files...
358     [Ctrl] - R                         rename selected files...
359     [Ctrl] - D                         delete selected files
360
361     [Ctrl] - P                         display image properties window
362
363     [Ctrl] - W                         close window
364
365   Pan View:
366
367     [Ctrl] - F, /                      show search bar
368     [Ctrl] - G                         repeat previous search
369
370   (*) This is a compile time option enabled when strverscmp is found.
371
372   Mouse image control:
373
374     Button 1                           view next image
375     Button 2                           view previous image
376     Button 3                           context menu
377
378     Button 1 drag                      scroll/pan image
379     Button 2 drag                      initiate drag and drop
380
381     Wheel up/down                      change to previous/next image
382     Wheel up/down + [Shift]            scroll image up/down
383     Wheel up/down + [Control]          zoom image in/out
384
385 ======== Editor command macros                               [section:editors]
386
387  Any one of the following filename markers may be used:
388
389     %f  Replaced with list of selected files, may occur once.
390     %p  Command is run once for each selected file, may occur multiple times.
391    none When neither %f or %p exist, list of files is appended to command.
392
393  Use of the following to display output window for the command:
394
395     %v  Display result of command in output window, must occur as first two
396         characters in the command, or immediately after the "%w" macro.
397     %V  Like v above, but when used with %p, only displays output window for
398         multiple files. The output of a single file is suppressed.
399
400  Additional macros:
401
402     %w  Prevent full screen from deactivating when command is executed,
403         must occur as the first two characters.
404
405 ======== Additional comments:
406
407   Advanced options:
408     These options are not adjustable in the preferences window, to change
409     them edit $(HOME)/.gqview/gqviewrc while GQview is not running. An option
410     becomes 'advanced' when it is removed from the user's visibility, and
411     only remains so that those few users that really want it will not complain
412     about it's removal :)
413
414   lazy_image_sync: false
415     Set true to enable the old behavior of lazy image updates when changing
416     directories. (viewed image will remain until a new file is selected)
417
418   display_dialogs_under_mouse: false
419     Set true to force dialogs to display under the current mouse position,
420     note that this goes against the preference set for the window manager.
421
422 ======== Translation status:
423
424  (as of 2.1.3)
425
426    Please send po files/patches in gzipped form to ensure data integrity.
427
428    Note: completion % in the chart below may not be quite correct when fuzzy
429          translations exist but do not appear in the source.
430          comp % = trans / (trans + fuzzy + untrans)
431
432 Language     Comp (%)  Trans   Fuzzy Untrans  Warn
433 --------------------------------------------------
434 ar                62     449     175      93
435 be                99     712       1       4
436 bg                93     667      27      23
437 ca                93     667      27      23
438 cs                93     667      27      23
439 da                19     138     310     269
440 de                93     667      27      23
441 eo                98     707       6       4
442 es                93     667      27      23
443 et                28     204     307     206
444 eu                99     712       1       4
445 fi                93     669      25      23
446 fr                98     706       4       7
447 hu                52     374     211     132
448 id                29     208     308     201
449 it                98     704       6       7
450 ja                93     667      27      23
451 ko                15     114      10     593
452 nl                93     669      25      23
453 no                23     169     320     228
454 pl                88     631       6      80
455 pt_BR             98     704       6       7
456 ro                54     388     213     116
457 ru                93     667      27      23
458 sk                96     690       7      20
459 sl                21     155     326     236
460 sv                92     665      28      24
461 th                22     161     318     238
462 tr                 9      71     309     337
463 uk                25     180     316     221
464 vi                98     705       5       7
465 zh_CN.GB2312      23     169     320     228
466 zh_TW             96     695       6      16
467 --------------------------------------------------
468
469
470 ======== Credits                                             [section:credits]
471
472
473   Translations:
474
475      Grzegorz Kowal <g_kowal@poczta.onet.pl>
476      Zbigniew Chyla <cyba@gnome.pl>
477      Emil Nowak <emil5@go2.pl>
478      Wit Wilinski <wit.wilinski@gmail.com>
479          for Polish translation
480
481      Christopher R. Gabriel <cgabriel@pluto.linux.it>
482      Di Maggio Salvatore <Salvatore.Dimaggio@bologna.marelli.it>
483      Costantino <inverness1ATvirgilio.it>
484          for Italian translation
485
486      Sandokan <cortex@nextra.sk>
487      Ivan Priesol <priesol@iris-sk.sk>
488      Mgr. Peter Tuharsky <tuharsky@misbb.sk>
489          for Slovak translation
490
491      Rodrigo Sancho Senosiain <ruy_ikari@bigfoot.com>
492      Ariel Fermani <the_end@bbs.frc.utn.edu.ar>
493          for Spanish translation
494
495      Eric Lassauge <lassauge@users.sf.net>
496      Jean-Pierre Pedron <jppedron@club-internet.fr>
497      Pascal Bleser <pascal.bleser@atosorigin.com>
498      Nicolas Boos <nicolas.boos@wanadoo.fr>
499      Nicolas Bonifas <nicolas_bonifas@users.sf.net>
500          for French translation
501
502      Fâtih Demir <kabalak@gmx.net>
503          for Turkish translation
504
505      Kam Tik <kamtik@hongkong.com>
506      Abel Cheung <deaddog@deaddog.ws>
507      S.J. Luo <crystal@mickey.ee.nctu.edu.tw>
508          for Traditional Chinese (Big5) translation
509
510      Junichi Uekawa <dancer@debian.org>
511      Oleg Andrjushenko <oandr@itec.cn.ua>
512      Michael Bravo <mbravo@tag-ltd.spb.ru>
513      Sergey Pinaev <dfo@antex.ru>
514          for Russian translation
515
516      Guilherme M. Schroeder <slump@ieg.com.br>
517      Vitor Fernandes <vitor_fernandes@SoftHome.net>
518      Herval Ribeiro de Azevêdo <heraze@gmail.com>
519          for Brazilian Portuguese translation
520
521      Shingo Akagaki <akagaki@ece.numazu-ct.ac.jp>
522      Yuuki Ninomiya <gm@debian.or.jp>
523      Sato Satoru <ss@gnome.gr.jp>
524      Takeshi AIHANA <aihana@gnome.gr.jp>
525          for Japanese translation
526
527      Matthias Warkus <mawarkus@t-online.de>
528      Thomas Klausner <wiz@danbala.ifoer.tuwien.ac.at>
529      Danny Milosavljevic <danny_milo@yahoo.com>
530      Ronny Steiner <Post@SIRSteiner.de>
531          for German translation
532
533      Matej Erman <matej.erman@guest.arnes.si>
534          for Slovene translation
535
536      MÃtyÃs Tibor <templar@tempi.scene.hu>
537      Koblinger Egmont <egmont@uhulinux.hu>
538      Sári Gábor <saga@externet.hu>
539          for Hungarian translation
540
541      Wu Yulun <migr@operamail.com>
542      Charles Wang <charlesw1234cn@yahoo.com.cn>
543          for simplified Chinese translation
544
545      H.J.Visser <H.J.Visser@harrie.mine.nu>
546      Tino Meinen <a.t.meinen@chello.nl>
547          for Dutch translation
548
549      Lauri Nurmi <lanurmi@iki.fi>
550          for Finnish translation
551
552      Ilmar Kerm <ikerm@hot.ee>
553          for Estonian translation
554
555      Volodymyr M. Lisivka <lvm@mystery.lviv.net>
556          for Ukrainian translation
557
558      Birger Langkjer <birger.langkjer@image.dk>
559          for Danish translation
560
561      Torgeir Ness Sundli <torgeir@mp3bil.no>
562          for Norwegian translation
563
564      Jan Raska <jan.raska@tiscali.cz>
565      Michal Bukovjan <bukm@centrum.cz>
566          for Czech translation
567
568      Phanumas Thanyaboon <maskung@hotmail.com>
569          for Thai translation
570
571      Harald Ersch <hersch@romatsa.ro>
572          for Romanian translation
573
574      pclouds <pclouds@vnlinux.org>
575          for Vietnamese translation
576
577      Tedi Heriyanto <tedi_h@gmx.net>
578          for Indonesian translation
579
580      Vladimir Petrov <vladux@mail.bg>
581          for Bulgarian translation
582
583      Hans Öfverbeck <hans.ofverbeck@home.se>
584          for Swedish translation
585
586      Youssef Assad <youssef@devcabal.org>
587          for Arabic translation
588
589      catux.org <mecatxis@ya.com>
590          for Catalan translation
591
592      Hyun-Jin Moon <moonhyunjin@gmail.com
593          for Korean translation
594
595      Pavel Piatruk <berserker@neolocation.com>
596          for Belarusion translation
597
598      Piarres Beobide <pi@beobide.net>
599          for Basque translation
600
601      Antonio C. Codazzi <f_sophia@libero.it>
602          for Esperanto translation
603
604  Fixes, additions, and patches:
605
606      Eric Swalens
607      Quy Tonthat
608          for initial Exif support.
609
610      Daniel M. German <dmgerman at uvic.ca>
611          for Canon raw image support.
612
613      Lars Ellenberg
614          for Fujifilm raw image support.
615
616      Diederen Damien <D.Diederen@student.ulg.ac.be>
617          for .xvpics thumbnail reading support.
618
619      Nick Rusnov <nick@grawk.net>
620      Ryan Murray <rmurray@debian.org>
621          for man page.
622
623      Martin Pool <mbp@samba.org>
624          for sort by number, misc. improvements.
625
626      Jörg Mensmann <joerg.mensmann@gmx.de>
627          for Xinerama support patch.
628
629      Vadim Shliakhov
630          for miscellaneous fixes.
631
632
633      And...
634          Thanks to the users for finding GQview useful.
635
636
637 ========
638