================================================================================
		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, Ubuntu
	9		License
	10		Contacts, mailing lists, URLs
================================================================================
	1		Overview
================================================================================

FIM (Fbi IMproved) is a highly customizable and scriptable image viewer targeted
at the users who are comfortable with software like the Vim text editor or the
Mutt mail user agent, or keyboard oriented, full screen programs.
FIM aims to be a "Swiss Army knife" for viewing images.

FIM is multidevice: it has X support (via the SDL and the Imlib2 libraries),
it supports ASCII art output (via the aalib library), and since it derives from
the Fbi image viewer (by Gerd Hoffmann), it can display images in the Linux
framebuffer console, too.

FIM is free software; it ships under the GPL software license.

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

FIM is documented in `man fim' (doc/fim.man.html), describing its invocation,
and `man fimrc' (doc/fimrc.man.html), describing the language: commands,
internal variable and key bindings.

FIM offers many options for scaling, orienting, listing and rearranging the
ordering of images.
FIM is capable of regular expressions based (on filename) vim-like autocommands,
comment-based search and filtering, EXIF tags display, custom font usage.
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.
Each documentation item is also accessible via the internal 'help' command.

================================================================================
	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
 - 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
 - image descriptions display (expando sequences)
 - regular expressions on image descriptions
 - configuration (initialization) file support (~/.fimrc)
 - usable built-in 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 height 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 and mipmaps
 - image prefetching
 - 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
 - support for AAlib (Ascii Art rendering) (-o aa)
 - support for SDLlib (Simple Directmedia Layer) (-o sdl) (X!)
 - experimental support for Imlib2 (-o imlib2) (X!)
 - experimental PDF, PS, DJVU file support
 - viewing any file as a binary/RGB pixelmap
 - viewing any file as (rendered) text
 - opening files at a specified file offset
 - image list limiting
 - comments / captions / description files
 - search and reordering based on descriptions and internal variables
 - decode files based on magic number, not file extension
 - recursive loading from directories
 - sorting files list on file size, name date
 - text font control (size and consolefont selection)
 - dump to stdout list of selected images 
 - one-key based jump between last two images

 Follows a comparison of popular image viewers available on Linux, focusing on
 the peculiar FIM features.
 We take in consideration free software.
 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                                    X		    ?
 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                                             *                    *
 ...

Other nice command line picture viewers:  pv (http://www.trashmail.net/pv/),
 zgv, feh, sxiv, mirage...

 ______________________________________________________________________________
 

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

 - the GNU readline library ( https://www.gnu.org/software/readline/ )
 - GNU flex  (NOT any lex ) ( https://www.gnu.org/software/flex/  )
 - GNU bison (NOT any yacc) ( https://www.gnu.org/software/bison/)
 - the GCC ( GNU Compiler Collection ) ( http://gcc.gnu.org/ )
 - optionally, header files for:
	libpng		  ( http://directory.fsf.org/libpng.html )
	libjpeg		  ( http://www.ijg.org/ )
 	giflib		  ( http://sourceforge.net/projects/giflib/ )
	libtiff 	  ( http://www.libtiff.org/ )
	libdjvulibre	  ( http://sourceforge.net/projects/djvu/  )
	libsdl   	  ( http://libsdl.org/ )

You find all of these on any decent Linux distribution.

 Libraries originally required by Fbi but not by FIM:
 	libFS, libCURL, libLIRC

--------------------------------------------------------------------------------
	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 (requires png and gif support).
 make tests

--------------------------------------------------------------------------------
	4.6		Example: compiling FIM from repository on Ubuntu/Debian:

 sudo apt-get install subversion
 sudo apt-get install automake autoconf libtool
 sudo apt-get install libreadline-dev libexif-dev
 sudo apt-get install libjpeg-dev libpng-dev libtiff-dev libgif-dev
 sudo apt-get install libsdl1.2-dev libaa1-dev 
 # experimental, not recommended:
 sudo apt-get install libpoppler-dev libdjvulibre-dev libspectre-dev
 sudo apt-get install libarchive-dev
 svn co http://svn.savannah.nongnu.org/svn/fbi-improved/trunk/ fim
 sh autogen.sh
 cd fim
 ./configure --enable-poppler --enable-aa --enable-sdl
 make
 
================================================================================
	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, libgif, libtiff, libreadline,
   libexif

================================================================================
	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'
back in 2005.

The code was applied as a patch on the existing fbi source tree, but was 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 single keyboard input handler.

================================================================================
	7		Technical overview (important for patch writers,but old)
================================================================================

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/
 giflib   : http://sourceforge.net/projects/giflib/
 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 started as a fork of 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/
http://cppreference.com/
man console_codes
man fb.modes
man fbi
man console_ioctl
man resizecons

Further useful documents:
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

Earlier tested platforms (fim-0.3...):
 - 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).

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

--------------------------------------------------------------------------------
	8.1		Debian, Ubuntu
 
 You should find fim in Debian and Ubuntu,  and install it with:

 sudo apt-get install fim

 But beware: the deb packages are very likely to be outdated.
 

 In order to build from svn sources, you are advised to install packages from
 the following (overly complete) list:
  
 autoconf autoconf-archive autoheader automake autotools-dev bison ctags
 flex groff g++ libaa1-dev libdjvulibre-dev libgif4 libgif-dev libimlib2-dev
 libjpeg-dev libncurses5-dev libpng-dev libpoppler-cpp-dev libpoppler-dev
 libreadline-dev libsdl-dev libspectre-dev libtiff-dev libtool m4 make svn
 txt2html libexif-dev

 The above list was valid on a Debian Jessie installation; it's fair to expect
 these packages names to change a little with time..
 
================================================================================
	9		License
================================================================================

 FIM is free software, and is licensed under the GPLv2 or later.
 FIM has been written by Michele Martone.

 FIM started as a fork of fbi-1.31 by Gerd Hoffmann, which is "GPLv2 or later".
 FIM uses the PCX reading code contributed by Mohammed Isam.
 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 scripts shipped with the Vim text editor (http://www.vim.org),
which is licensed compatibly with the GPL.
 The FIM source code package includes the Lat15-Terminus16.psf file, originally
from the GPL licensed Terminus Font package, version 4.30 authored by
Dimitar Toshkov Zhekov.

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

FIM is (C) 2007-2018 Michele Martone.

 Email: "dezperado_FOobAr_autistici_Baz_org", just care replacing
         _FOobAr_ with a '@' and _Baz_ with a '.'.
 GPG Key: 0xE0E669C8EF1258B8

If it is for a bug report or installation help, be sure of reading the
documentation and the BUGS file first.
FIM is not perfect: a number of weaknesses are summarized in TODO and BUGS.


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

Announcements: http://freecode.com/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://svn.savannah.nongnu.org/svn/fbi-improved

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

ChangeLog    : http://svn.savannah.nongnu.org/svn/fbi-improved/trunk/ChangeLog

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

 $Id: README 1576 2018-01-28 22:33:17Z dezperado $
 vim:tw=78:fo=tcq2:isk=!-~,^*,^\|,^\":ts=8:ft=help:norl: