================================================================================
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:
- 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
- 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 (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
- 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
Yet unimplemented features:
- autodocumentation, like gdb or vim
- 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.
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
================================================================================
- 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/ )
giflib ( http://sourceforge.net/projects/giflib/ )
libtiff ( http://www.libtiff.org/ )
libdjvulibre ( http://sourceforge.net/projects/djvu/ )
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
================================================================================
- A Linux (not sure if it is necessary for it to be an x86; i think not) box
- The frame buffer 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 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:
- 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, 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 900 2015-12-20 19:40:16Z dezperado $
vim:tw=78:fo=tcq2:isk=!-~,^*,^\|,^\":ts=8:ft=help:norl: