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
        8.2             Gentoo Installation Tips
        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.
FIM aims to be a "Swiss Army knife" for viewing images.

It derives from the Fbi image viewer (by Gerd Hoffmann), and works primarily in the Linux frame buffer console.
FIM is multidevice: it has X support (via the SDL and the Imlib2 libraries) 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 comfortable with software like the Vim text editor or the Mutt mail user agent.
FIM aims to be a swiss army knife for viewing images.

It derives from the Fbi image viewer (by Gerd Hoffmann), and works primarily in the Linux frame buffer console.
FIM is multidevice: it has X support (via the SDL and the Imlib2 libraries) and it supports ASCII art output (via the aalib library).

FIM is capable of regular expressions based (on filename) vim-like autocommands, comment-based search, EXIF tags display. 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.
Each user available command and variable is documented.

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:

Yet unimplemented features:

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=frame buffer)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, frame buffer, aalib)             *                   
 mirroring                                             *                    *

...

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



4 Compilation Requirements


Libraries originally required by Fbi but not by 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


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



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


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 an 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 frame buffer device and to a single keyboard input.


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


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

Information about the frame buffer 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/ 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:

--

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, 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..


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 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 some 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 by Dimitar Toshkov Zhekov.


10 Contacts, URLs


FIM is (C) 2007-2015 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/

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.html,v 1.15 2016/01/31 08:35:38 dezperado Exp $ vim:tw=78:fo=tcq2:isk=!-~,^*,^\|,^\":ts=8:ft=help:norl: