WHAT'S GUASH?
	Guash (Gimp Users' Another SHell) is a visual shell for loading,
	deleting, copying, moving and mapping a command on image files
	within The GIMP-1.[12] .

IMPORTANT CHANGES FROM THE PREVIOUS REGISTERED VERSION:
	(for 2.3.0)
	o guash now uses idle renderer (any exposure event won't be lost!).
	o works on win32 well ???
	o the entry box for page number works now
	(for 2.2.4)
	o I18N. Guash now use "gimp-libgimp" adn "gimp-std-plugins" as
	its textdomain
	(for 2.2.3)
	o wheelmouse support
	(for 2.2.2)
	o fix rubber band bug
	o fix redraw bug
	(for 2.2.0)
	o Guash uses gtk_drawing_area instead of gtk_preview for the
	  thumbnail_panel. This change would cause the drastic speed up of
	  drawing the panel.
	o During drag-and-drop between two guashes, staying on a directory
	  icon for a while is interpreted as a trigger to change directory.
	o rubber band(hand?) selector was implemented
	(for 2.1.2)
	o fix a bug on generating jpeg-thumbnail without comment string
	(for 2.1.1)
	o fix a bug on displaying comment
	(for 2.1.0)
	o guash can generate index.html w/ images' thumbnails.
	o Some directory operations are added.
	(for 2.0.7)
	o works only on (upcoming) gimp-1.1.10
	(for 2.0.7)
	o Two serious bugs were fixed.
	(for 2.0.6)
	o fix a serious bug on DnD file movement.
	o Selection is held after DnD file operations.
	(for 2.0.5)
	o Guash now works only on gimp-1.0.4 and later.
	o Guash can cope with The GIMP and Gnu Midnight Commander through
	  DnD protocol. Drag'em! Drop'em!
	o You can terminate guash immediately, even if it starts a (long)
	  directory scan.
	(for 2.0.4)
	o Guash should work again on glib-1.0/gtk-1.0/gimp-1.0
	o The secret feature since 2.0.0, 16bit thumbnail format becomes
	  official. This 16bit format is compatible to the original XV
	  thumbnail format (XV can read it). But it doubles the size of
	  thumbnail file. And it requires more memory (x3) and computational
	  power (in loading/saving). And the quality as 8bit thumbnail
	  would degrade. Are you ready? Try:
	       (guash-option-string "***G**")
	  On the other hand, 8bit mode uses error distribution method since
	  this version. (The code was stoled from gimp/app/fileops.c.)
	  NOTE for good eyes:-): the mnemonic was changed to 'G' from 'C'.
	o Code for resizing was changed. It works on CVS gimp and gtk (Tue
	  Mar 16 23:14:42 1999). Please let me know if it does not work on
	  another version. Mainly this modification fixes the bug on remote
	  execution (or timing problem on very slow machines).
	(for 2.0.3)
	o Guash copes with gimp-1.1.2
	(for 2.0.2)
	o [On gimp-1.1] Now the default of the 2nd button is changed to
	  "Move" from "Update". You can move files without keyboard.
	o "gimp-comment" parasite is used to build info field. And this
	   tarball contains a script-fu to add a comment parasite into an
	   image with minimal feature. See script-for-gimp1.2/add-comment.scm.
	o All cursor keys can be used to change focus in the preview pane.
	o "Map script-fu" was re-implemented and works on gimp-1.1, however,
	  with badly interface: you must input a script filename in the
	  script-fu dialog.
	(for 2.0.[01])
	o Guash has overhauled as follows! In short, x6 speed & 1/3 memory
	  for thumbnail loading, compared with the previous version 1.1.1.
	o Guash loads thumbnail files without any interaction with the gimp.
	  The speed of scanning a directory with thumbnails is much much
	  improved. See the PERFORMANCE section. And as a side-effect, the
	  speed is not affected by layer-channel dialog.
	o Guash requires much less memory, by changing to conservative
	  policy, and using indexed image representation.
	o Guash becomes more consistent and robust (in various meanings).
	  o directory_monitor is invoked carefully to avoid the interfere to
	    gimp (file plug-in for saving). 1.1.1 was very dangerous. Some
	    dagerous specifications were eliminated.
	  o guash stops directory_monitor immediately if the directory is
	    not writable.
	  o guash remembers the last displayed page of old visiting
	    directories.
	  o directory history is managed in LRU order.
	  o sudden jump to the first page after file deletion was fixed.
	  o check the existence of the selected image files before file
	    operations on selection.
	o Selection becomes a part of directory information. Changing
	  current directory, copying/moving file(s), and making a new
	  directory don't reset selection. And all directories'
	  information is updated synchronously, whenever a file operation
	  (in guash) is done.
	o Semantics of display-mode was changed. There are two mode:
	  o display_image_mode "display only images" (no change): to show
	    only image files, and
	  o display_file_mode "display all files" (modified): list all files
	    with "?" icon. But if a file has its thumbnail file, it is used.
	o script-fu mapper is invoked much efficiently: no need to rescan.
	  NOTE: map-on-guash-selection.scm has been updated.
	  NOTE: the behavior of "Map script on..." was modified temporally.
	o I found guash can handle filename with NON-ASCII characters after
	  some preparation (fontset in gtkrc, LC_CTYPE), by chance :-)
	o You can change to the nth subdirectory (0 <= n <= 9) by typing the
	  correspoding numeric key (0 means the parent directory whenever).

INSTALL:
	I think (hope) compilation is easy. Check the definitions
	(especially HAVE_UNISTD_H and THUMBNAIL_FONT_SIZE, and LOCALEDIR if
	you want to use gettext) in guash-config.h,
	then do:

	gimptool --install guash.c

	(gimptool is included in gimp-1.X and should be installed with gimp.)

	But Guash is depended on file operation library or platform
	heavily. Since only Linux (debian 2.0) is available to me, if
	you had to modify the source, please send your patch to me.

	Some reported problems in compilation/execution time and misc
	important information are summarized in file BUGS. PLEASE CHECK IT
	NOW, EVEN IF YOU HAVE ALREADY READ IT IN THE OLD GUASH.

	If you success to compilation, gimptool installs guash into
	~/.gimp/plug-in/ automatically.

	Then copy map-on-guash-selection.scm in a subdirectory to your (or
	site) script-fu directory as:

	gimptool --install-script script-for-gimp1.X/map-on-guash-selection.scm

	Note: map-on-guash-selection.scm has also been updated. Please
	delete the old version(the above command overwrites the old script).

	guash-mapper-sample.scm is a sample file. Copy it if you think it's
	useful.
	(The directory: script-for-gimp1.X contains some other scripts.
	Check it out.)

WHEN GUASH CRASHED:
	Check the BUGS file. Doesn't it help you? OK. Please recompile
	guash.c with DEBUG (in guash-config.h). Now the new guash dumps long
	log on console, during its execution. Send a bug-report to
	<narazaki@gimp.org> with the log. Patch is better:-)

CUSTOMIZATION:
	The initial size (# of columns/rows) of thumbnail panel can be
	changed by inserting following declarations to your ~/.gimp/gimprc

	(guash-ncol "5")	# default.	valid range: [4:10]
	(guash-nrow "3")	# default.	valid range: [1:10]
	----------------
	If guash crashes after reading a directory which has a lot of image,
	Try:

	(guash-max-images-in-dir "1024") # default.	valid range: [1:2000]
	--------------------------------
	With this setting, only the first 1024 files in a directory are
	checked. (Thus 1024 - (# of dirs + # of non-image files) images are
	shown in the panel.)

	For speed up, during a directory scan, guash skips files which have
	one of specific suffixes. You can change the file types by the
	following declaration:

	(guash-inhibit-suffix "core:.mpeg:.mpg:.tar:.tar.gz:.tgz:.tar.bz2:.h")
	----------------------------------------------------------------------
	This is the default value. And, as you see, a colon is used as the
	delimiter.
	(If you want to skip ps/pdf image, add ":.pdf:.eps.gz:.eps:.ps.gz:.ps"
	to guash-inhibit-suffix.)

	Note: a period is NOT added before the each pattern automatically now.
	Thus "ps" in the list matches to "*.ps", "*.eps", and further "*ps".
	If you don't like it, use ".ps" instead of "ps". Usually ".eps:.ps"
	would be better. ".eps:.eps.gz:.ps:.ps.gz" would be further better.

	If you want to traverse on MS-Windows directories. I recommend to
	add ".exe:.dll"

	If your machine does not have enough physical memory, you might want
	to set the upper boundary of memory that guash uses. The following
	would help you:

	(guash-directory-history-length "M")	# M is an integer in [1:32]
	------------------------------------
	It defines how long history of directory traverse must be held.
	Since each thumbnail for an image file requires 80x60x1 byte = 4.8KB,
	guash requires at least:
		total_memory = M * N * 4.8 [KB],
	where N is the average number of image files in a directory.
	If no declaration, 6 is used as the default. (2.0.0 scans a directory
	enough quickly. So memory consumption is crucial now. Thus you can
	choose 1. It would be a good choice. Since, however, 2.0.0 releases
	unused memories willingly, 6 is also an appropriate value. In this
	case, guash on Linux (glib2.0) seems requiring usually about 5-6MB.)

	The scan interval of automatic directory monitor (which updates the
	panel if the directory has been updated) is set by:

	(guash-directory-monitor-interval "10")	# 10 is default value.
	---------------------------------------
	In this case, guash scans directories it visits for each 10
	seconds. See the next paragraph how to activate automatic directory
	monitor. 

	The other options are now collected into a string guash-option-string:

	(guash-option-string "CKDSSU")	; Warning: "CKDSSU" is invalid str.
	------------------------------
	Each character in the string holds a value of an option as follows:

	nth	Category	Values	Description
	1st	Confirmation	[CN]	do Confirm or Not on file operations
	2nd	Keybindings	[GE]	Gimp or Emacs
	3rd	Display_type	[IF]	only Images or all Files
	4th	Save_type	[GXU]	Guash(16bit XV), Xv thumbnail or Unsave
	5th	Sort_type	[ND]	by Name or by Date
	6th	Thumb. Update	[AM]	update Automatically or Manually

	The default is "CGIXNM", that means with confirmor, gimp-ish
	keybindings, and sort by name, show only image files (loadable files),
	then save thumbnail as xvpict and you must update thumbnail-panel by
	hand.

	NOTE: lower-cased strings are acceptable from 2.0.0.

MAP A SCRIPT ON SELECTED IMAGE FILE:
	The most important feature of guash (or the reason why I decided to
	write guash) is not providing GUI for file operations but mapping a
	script on selected files.

	By typing `!' (or selecting the command from menu), you can do.
	It is done by:

	1. write a temporally file in gimp_dir which includes a form
	   defining a list of the selected image files
	2. then start <toolbox>/Xtns/Script-Fu/Misc/Map on guash selection,
	   BY YOURSELF
	3. this script maps the procedure given on the list
	4. delete the temporally file if you want.

	A short summary (and code) about the protocol between mapper and the
	mapped function is in map-on-guash-selection.scm.
	As samples of mapped function, guash-mapper-sample.scm defines the
	following commands:

	gm-thumbnail	creates thumbnail files and an html fragment
	gm-to-jpg	converts to JPEG format
	gm-to-gif	converts to GIF format
	gm-to-png	converts to PNG format
	gm-collect	collects files into a new multi-layered image
	gm-mgp		creates a mgp (http://www.mew.org/mgp/) script

PERFORMANCE:
	Environment:
		PentiumII-300MHz, Memory 256MB
		Debian 2.0, XFree86 3.3.2 ViRGE (xserver-S3V)
		glib-1.1.0/gtk+-1.1.0 or latest snapshot(s) (shared lib)
		gimp-SNAP-1.1.0 (tile-cache-size 32MB)
		xv-3.10a

	Test directory:
		827 JPGs (720x480) (about 90MB, but cached into file buffer)
	Panel size of xv is the default. That of guash is 5x3.

	RESULT:				    g  u  a  s	h
				 xv	1.0.3	1.1.0	2.0.0
	thumbnail generation	126sec	622sec	618sec	625sec
	open dir. w/ thumb.	1.3-1.8	 19sec	  9sec	1.5sec
	(by embedded timer)		1850ms	880ms	138ms

	Evaluations of 1.0.3 and 1.1.1 were done without layer-channel
	dialog, which made guash slow down drastically. But it does not
	affect 2.0.0 anymore.

IMPLEMENTATION MEMO:
	o Guash is a GPLed free/open ware. All files/directories under this
	  directory should be distributed as a part of guash.
	o Now guash is being developed not for gimp-1.0 but for the latest
	  snapshot of gimp-1.1. Though I try to keep compatibility, some
	  descriptions in files would not be suitable for gimp-1.0.
	o [On gimp-1.1] Guash can handle drag-and-drop protocol. But the
	  ugly "Copy/Move" button is left for compatibility and for
	  convenience. (During the development, I frequently opened a lot of
	  images. Ghaaa! I inteaded to copy them!)
	o Resizable preview widget in guash is a bogus implementation.

-- 
Fri Sep  8 18:04:08 2000
Shuji Narazaki
      Email: narazaki@gimp.org
      (My old address <narazaki@InetQ.or.jp> is not reachable now.)
      URL: http://www.gimp.org/~narazaki/
      Developer's snapshot is http://www.gimp.org/~narazaki/guash.tar.bz2
