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