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:

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


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



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

--

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.html,v 1.16 2018/01/29 21:41:41 dezperado Exp $ vim:tw=78:fo=tcq2:isk=!-~,^*,^\|,^\":ts=8:ft=help:norl: