================================================================================
		FIM - Fbi IMproved    README document.
================================================================================
	1		Overview
	2		Description
	3		Features, comparison to other image viewers
	4		Compilation Requirements
	5		Run Time Requirements
	6		Original Idea
	7		Technical overview (important for patch writers)
	8		Gentoo Installation Tips
	9		License
	10		Contacts, mailing lists, URLs
================================================================================
	1		Overview
================================================================================

FIM aims to be 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 is based on the Fbi image viewer, by Gerd Hoffmann, and works in the 
 Linux framebuffer console ( so, it is not an X program! ).

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 aims to be 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 is based on the Fbi image viewer, by Gerd Hoffmann, and works in the Linux
framebuffer console ( so, it is not an X program! ).

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), 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 language
 - on-screen debug and information console in command mode
 - multiple internal windows with indipendent images displayed at once
 - per-image variables
 - regular expression filename searches
 - command line history
 - command line tab-based command autocompletion (thanks to the GNU/readline)
 - command line command autocompletion
 - 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 to enrich autocommand behaviour
 - configuration (initialization) file support
 - 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
 - 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

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
 ______________________________________________________________________________
 Features :

 status:(a)lpha/(m)ature   m       m   m         a     m     m    m
 environment(f=framebuffer)X      X  X,svga      f     f     X    f
 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 file list read                         *
 mirroring                 ....

 ______________________________________________________________________________
 

================================================================================
	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 )
 - 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/ )

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

================================================================================
	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

================================================================================
	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 by 
any means near to what is now Fim.

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/

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 read during the coding of this patch:

- Thomas Niemann's tutorial to yacc & lex
- The yacc & lex HOWTO
- GNU readline manual
- Ray Lischner, STL Pocket Reference, O'Reilly, 2004 
- Herbert Schildt's C++, Complete Reference, Third Edition, Osborne McGraw-Hill, 1999
man console_codes
man fb.modes
man fbi

Useful documents I could read later on:
vim -c ':help'
man 3 history
man readline

Tested platforms :
 - 2.6.17 Linux Kernel, GCC-3.4.6, gentoo
 - 2.6.17 Linux Kernel, GCC-4.1.1, gentoo
 - 2.6.17 Linux Kernel, GCC-3.3.6, flex 2.5.4, bison 1.875d, gentoo
 - 2.6.17 Linux Kernel, GCC-3.3.6, flex 2.5.4, bison 2.2   , gentoo
 - 2.6.17 Linux Kernel, GCC-3.3.6, flex 2.5.33,bison 2.2   , gentoo
 - 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		Gentoo Installation Tips
================================================================================

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.
Installation details are in the INSTALL file.

BEWARE : THERE COULD BE PROBLEMS WITH FLEX/BISON! 

"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
================================================================================

You can contact the Fim author via email: dezperado_FOobAr_autistici_Baz_org, by
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)!


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/ChangeLog

 $Id: README 122 2008-02-20 17:50:08Z dezperado $
 vim:tw=78:fo=tcq2:isk=!-~,^*,^\|,^\":ts=8:ft=help:norl:
