================================================================================
		FIM - Fbi IMproved    README document.
================================================================================
	1		Overview
	2		Description
	3		Features, comparison to other image viewers
	4		Compilation Requirements
	4.5		Testing
	5		Run Time Requirements
	5.5		Hacking, maintenance guidelines
	6		Original Idea
	7		Technical overview (important for patch writers)
	8		Availability in Linux distributions
	8.1		Debian
	8.2		Gentoo Installation Tips
	9		License
	10		Contacts, mailing lists, URLs
================================================================================
	1		Overview
================================================================================

FIM is a highly customizable and scriptable image viewer targeted at the
users who are confortable with software like the Vim text editor or the Mutt
mail user agent (it aims to be a swiss army knife for viewing images).

It is based on the Fbi image viewer (by Gerd Hoffmann), and works primarily in
the Linux framebuffer console.
It is multidevice : it has X support, too (via the SDL library) and it supports
ascii art output (via the aalib library).

FIM is free software, and it ships under the GPL software license, complete with
documentation, in form of a doc/FIM.TXT documentation file, a man page, lots
of comments in the code, and some text files.

================================================================================
	2		Description
================================================================================

FIM is a highly customizable and scriptable image viewer targeted at the
users who are confortable with software like the Vim text editor or the Mutt
mail user agent (it aims to be a swiss army knife for viewing images).

It is based on the Fbi image viewer (by Gerd Hoffmann), and works primarily in
the Linux framebuffer console.
It is multidevice : it has X support, too (via the SDL library) and it supports
ascii art output (via the aalib library).

It is capable of regular expressions based (on filename) image viewing,vim-like
autocommands, it offers GNU readline command line autocompletion and history,
completely customizable key bindings, external/internal (if-while based)
scriptability (through return codes, standard input/output, and commands given
at invocation time, initialization file), internal filename-based image search,
and much more features.

FIM is free software, and it ships under the GPL software license, complete with
documentation, in form of a doc/FIM.TXT documentation file, a man page, lots
of comments in the (sometimes still dirty) code, and some text files.

================================================================================
	3		Features, comparison to other image viewers
================================================================================

Implemented features: 

 - interactive (default) and command line modes
 - all of the functionality is scripted in an internal domain specific language
 - on-screen debug and information console in command mode
 - multiple internal windows with indipendent images displayed at once
 - per-image variables (e.g.: i:var="value")
 - regular expression filename searches (/*.png) and viewing
 - command line history (enter the console with ':', then use arrows with arrows)
 - command line tab-based command autocompletion (thanks to the GNU/readline)
 - command line command autocompletion
 - command line history file saving/loading upport (~/.fim_history)
 - key-action binding, with Shift and Control key combinations for interactive mode
 - simple if-while scriptability, with integer/float/string variables and arithmetic evaluation
 - command aliases support (macros)
 - event autocommands (in Vim's 'autocmd' style)
 - regular expressions on filenames to enrich autocommand behaviour
 - configuration (initialization) file support (~/.fimrc)
 - usable builtin default configuration
 - wrapper script to convert pdf,ps,eps,dvi,cbr(rar),cbz(zip),tar,tar.gz,tgz,http://...
   contents into images and display with Fim
 - embedded piping through 'convert','inkscape','xcftopnm','dia'... for a wider file formats compatibility
 - index based goto in Vim's style (:<number>)
 - regular expressions (on filename) based goto and image search
 - stuff     usual for an image viewer (scale, pan, etc..)
 - stuff (un)usual for an image viewer (setting scale factor, auto width scale, 
   auto heigth scale, marking of 'interesting' files, sorting of files in the
   list, recording/replaying of sessions, repeat last action )
 - image flipping, mirroring, rotation, stretching (asymmetric scaling)
 - command iteration ( in the [n]<command key> form )
 - external script file execution
 - system call support
 - image caching (optional)
 - image prefetching (optional)
 - pipe commands from some input program
 - many of these features could be enabled or disabled at compile time editing the Makefile
 - runs under screen
 - standard input file list read
 - standard input whole file read
 - standard input script file read
 - history file
 - full         support for AAlib (Ascii Art rendering) (-o aa)
 - experimental support for SDLlib (Simple Directmedia Layer) (-o sdl) (X!)
 - experimental PDF, PS, DJVU file support
 - viewing any file as a binary/RGB pixelmap

Yet unimplemented features :

 - autodocumentation, in gdb style!
 - mutt-like patterns ~p, ~r ...
 - advanced pattern selection of images on other criterias ?


 Follows a comparison of popular image viewers available on Linux, focusing on
 the peculiar Fim features (so, Fim have no competitors because it is not in any
 competition! ). We take in consideration free software only, of course.
 Note also that no all of the feature could ever exist in all of the mentioned
 programs, by their very nature.

 ______________________________________________________________________________

 \ Program :            kuickshow eog [xz]gv    fbi   FIM GQview dfbsee	pv qiv
 ______________________________________________________________________________
 Features :

 status:(a)lpha/(m)ature   m       m   m         a     m     m    m	m   m
 environment(f=framebuffer)X      X  X,svga      f     f     X    f	X   X
 linux specific                        ?         *     *          *	*   ?
 key rebindings            *                           *     *		    ?
 external scriptability(bash,..)                 ~     *		~   ?
 internal scriptability                                *		    ?
 internal scriptability minilanguage                   * 		    ? 
 printing support          *       *   ?                     *		    ?
 slideshow                 *       *             *     *     *    *	*   *
 caching                   *       ?                   *     *		    ?
 preview browser           *                                 *		    ?
 EXIF tag display          *                     *           *		    ?
 internal windowing                                    *		    ?
 internal image search                                 *		    ?
 external image search                                       *		    ?
 'pan views' ('rich' views)                                  *		    ?
 system interaction        *                           *     *		    ?
 system interaction safe   *						    ?
 remote commands                                             *		    ?
 saves last folder         *                                 *		    ?
 runs under screen                                     *		    ?
 standard input interaction                            *		    ?
 rotation		   *	?    ?           ?     *     ?    ?     *   *
 history                                               *		  
 multi-device (X/SDL, framebuffer, aalib)              *                   
 mirroring                                             *                    *
 ....

Some nice command line picture viewers :  pv (http://www.trashmail.net/pv/) ...

 ______________________________________________________________________________
 

================================================================================
	4		Compilation Requirements
================================================================================

 - fbi, with curl and exif support disabled
 - the GNU readline library ( http://directory.fsf.org/readline.html )
 - GNU flex  (NOT any lex ) ( http://directory.fsf.org/flex.html  )
 - GNU bison (NOT any yacc) ( http://directory.fsf.org/bison.html )
 - the GCC ( Gnu Compiler Collection ) ( http://directory.fsf.org/gcc.html )
 - optionally, header files for :
	libpng		  ( http://directory.fsf.org/libpng.html )
	libjpeg		  ( http://www.ijg.org/ )
 	libungif	  ( http://sourceforge.net/projects/libungif/ )
	libtiff 	  ( http://www.libtiff.org/ )
	libdjvulibre	  ( http://sourceforge.net/projects/djvu/  )

 Libraries originally required by Fbi but removed from Fim :
 	libFS, libCURL, libLIRC


   GNU Flex version prior to 2.5.4a and GNU Bison version prior 1.875d" are
   known to give compilation problems, so make sure you have newer versions of
   these. Note that Flex 2.5.4a comes after Flex-2.5.4.
   This note is especially precious for Debian/Ubuntu users.

--------------------------------------------------------------------------------
	4.5		Testing

 Just after the  './configure'  and 'make' steps, you should:
 
 # test if fim works at all on this machine/user
 make test

 # test if fim works at all on this machine/user (if you compiled aa support)
 make aatest
 
 # run a pool of test scripts, which should validate most fim functionalities
 # for common usage.
 make tests

 # if you are a fim developer/hacker, test thoroughly all configure options 
 # (a long test)
 make tests-all

 
================================================================================
	5		Run Time Requirements
================================================================================

 - A Linux (not sure if it is necessary for it to be an x86; i think not) box
 - The framebuffer device ( e.g.: /dev/fb0 or /dev/fb/0 ) enabled in the kernel
   ( and usually found in "/usr/src/linux/Documentation/fb" in the kernel source
    code tree ).
 - shared library files for : libpng, libjpeg, libungif, libtiff, libreadline

================================================================================
	5.5		Hacking, maintenance guidelines
================================================================================

If you hack fim in an interesting way, consider submitting your changes as a
patch.

There is a number of informal rules to follow when maintaining or hacking and
contributing to Fim.

 - If you intend to support a new file format, remember that `fim -V` should 
   list the supported file types list. So you should update it.
 - If you intend to support a new output device, remember that `fim -V` should 
   list the supported output devices. So you should update it.
 - Fim should continue passing the tests after your patch, and your patch should
   be robust, too. Consider writing a new test case.

================================================================================
	6		Original Idea
================================================================================

The original architecture of Fim is based on the wonderful fbi-1.31, written by
Gerd Hoffmann/Knorr: ( Fbi can be obtained at http://linux.bytesex.org/fbida/ ).

The idea was to enrich Fbi with a command line and configurability features.

An idea of the concept was settled when developing a small 'vim-like fbi patch'
for fbi back in 2005:
http://dezperado.altervista.org/coding.html#vim-like-fbi,%20and%20the%20wrapper%20fbgs.sh%20script%20modified%20for%20handling%20of%20ps,dvi%20and%20pdf%20files

The code is applied as a patch an the existing fbi source tree, but it is not by
any means near to what is Fim today.

Fim aims at a complete reorganization of the Fbi code, and ideally towards an
implementation of the most scriptable and configurable image viewer ever - not
tied to the framebuffer device and to a sole keyboard input.

================================================================================
	7		Technical overview (important for patch writers)
================================================================================

To run Fim requires a Linux box with the framebuffer device enabled in the 
kernel, and some popular image file decoding libraries.

Information about the framebuffer can be found under the directory
 "./Documentation/fb"
 inside the kernel tree 
 (usually "/usr/src/linux/Documentation/fb" ).

The libraries can be found on their sites (as of 20070312):

 libpng   : http://www.libpng.org/
 libjpeg  : http://www.ijg.org/
 libungif : http://sourceforge.net/projects/libungif/
 libtiff  : http://www.libtiff.org/
 libdjvulibre : http://sourceforge.net/projects/djvu/

Tested and working with library SDL-1.2.12.

Note that it is highly likely that you already have these libraries on your
system, especially on Gentoo Linux.

From the original README, it reads that Gerd himself built FBI hacking
"a svgalib PhotoCD viewer", so regard this software as a big, dirty code
potpourri :) .
For the sake of completeness, Fim is based on the version 1.31 of fbi,
available from http://dl.bytesex.org/releases/fbida/fbi_1.31.tar.gz .

Useful documents I've read and consulted during the coding of Fim, and 
useful for hacking it :

Thomas Niemann's tutorial to yacc & lex
The yacc & lex HOWTO
GNU readline manual
Ray Lischner, STL Pocket Reference, O'Reilly, 2004 
Herbert Schildt, C++- Complete Reference, Third Edition, Osborne McGraw-Hill, 1999
http://www.gnu.org/software/m4/manual/
http://www.gnu.org/software/autoconf/manual/
http://www.gnu.org/software/automake/manual/
http://www.gnu.org/software/make/manual/
http://www.gnu.org/software/bash/manual/
http://www.gnu.org/software/bison/manual/
flex manual ?
man console_codes
man fb.modes
man fbi
man console_ioctl
man resizecons

Useful documents I could read later on:
vim -c ':help'
man 3 history
man readline
http://www.gnu.org/prep/standards/

Useful URLs:
http://www.tldp.org/HOWTO/Framebuffer-HOWTO.html
and mirrors
http://www.linux.org/docs/ldp/howto/Framebuffer-HOWTO.html
http://www.pluto.it/files/ildp/HOWTO/Framebuffer-HOWTO/Framebuffer-HOWTO.html

and
http://bisqwit.iki.fi/source/fbmodes.html
http://asm.sourceforge.net/articles/fb.html
http://www.linuxjournal.com/article/2783

Tested platforms :
 - 2.6.25-2-686 Linux Kernel, GCC-4.3.1, flex 2.5.35, bison 2.3, Debian Lenny, x86
 - 2.6.17 Linux Kernel, GCC-3.4.6, gentoo, x86
 - 2.6.17 Linux Kernel, GCC-4.1.1, gentoo, x86
 - 2.6.17 Linux Kernel, GCC-3.3.6, flex 2.5.4, bison 1.875d, gentoo, x86
 - 2.6.17 Linux Kernel, GCC-3.3.6, flex 2.5.4, bison 2.2   , gentoo, x86
 - 2.6.17 Linux Kernel, GCC-3.3.6, flex 2.5.33,bison 2.2   , gentoo, x86
 - 2.6.19 Linux Kernel, GCC-4.1.1, flex 2.5.33,bison 2.2   , gentoo, powerpc
 - other ones, but non documented here.

 -- 

 If you intend to write patches or contribute to the code, be sure of reading 
 all of the documentation and _write me an email first_ (i will give you some
 advice).

 The code is much complicated and is very susceptible.

================================================================================
	8		Availability in Linux distributions
================================================================================

--------------------------------------------------------------------------------
	8.1		Debian
 
 You should find fim in debian, and install it like:

 apt-get install fim
 
--------------------------------------------------------------------------------
	8.2		Gentoo Installation Tips (obsolete)

On the Gentoo Linux distribution , you should not have problems building Fim by
first installing some libraries :

 $ emerge media-libs/giflib media-libs/jpeg media-libs/libpng media-libs/tiff
and Bison (from 1.875d on) and Flex :
 $ emerge flex bison

This should suffice.
Once these requirements are satisfied, you could proceed with the 
	./configure ; make ; make install
sequence.
Standard installation details are in the INSTALL file.

BEWARE : THERE COULD BE PROBLEMS WITH FLEX/BISON! 

WARNING : the gentoo linux fim package version (<=0.2) is obsolete!

"flex version 2.5.4" and "bison (GNU Bison) 1.875d" are known to work.

================================================================================
	9		License
================================================================================

 Fim is free software, and is licensed under the GPLv2 or later.

 Fim extends the Fbi program by Gerd Hoffmann, which is "GPLv2 or later".
 Fim also uses a regex.c file from the GNU Regular Expressions library, 
distributed on http://directory.fsf.org/regex.html, in the version shipped with
the Mutt mail user agent (http://www.mutt.org).
 It also uses some scripts shipped with the Vim text editor (http://www.vim.org),
which is licensed compatibly with the GPL.

================================================================================
	10		Contacts, URLs
================================================================================

Fim is (C) 2007-2009 Michele Martone.

You can contact me via email: "dezperado_FOobAr_autistici_Baz_org", after
replacing _FOobAr_ with a '@' and _Baz_ with a '.'.

If it is for a bug report or installation help, be sure of reading the
documentation and the BUGS file first, and then you're welcome.
If it is for other suggestions or ideas, you are welcome, too (and don't miss
the TODO file, too)!
Fim is not perfect : a number of weaknesses are summarized in TODO and BUGS.


Web Page     : http://savannah.nongnu.org/projects/fbi-improved/

Mailing List : http://savannah.nongnu.org/mail/?group=fbi-improved
	(or http://lists.nongnu.org/mailman/listinfo/fbi-improved-devel)

Releases     : http://download.savannah.nongnu.org/releases/fbi-improved

Repository   : http://code.autistici.org/svn/fim/

Off.  Mirror : http://www.autistici.org/dezperado/fim/

ChangeLog    : http://code.autistici.org/svn/fim/trunk/ChangeLog

Bugs(unofficial): http://code.autistici.org/trac/fim/report

Bugs (official) : http://savannah.nongnu.org/bugs/?group=fbi-improved

 $Id: README 265 2009-10-14 21:05:40Z dezperado $
 vim:tw=78:fo=tcq2:isk=!-~,^*,^\|,^\":ts=8:ft=help:norl: