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