Debian Codegraph @

README

raw
1 -==============================================================================-
2 FIM - Fbi IMproved README document.
3 ================================================================================
4 - 1 Overview
5 - 2 Description
6 - 3 Features, comparison to other image viewers
7 - 4 Build, test, example
8 - 5 Run time requirements
9 - 6 Original Idea
10 - 7 Notes for patch writers
11 - 8 Availability in Linux distributions
12 - 9 License
13 - 10 Contacts, mailing lists, URLs
14 -==============================================================================-
15 1 Overview
16 ================================================================================
17
18 FIM (Fbi IMproved) is a highly customizable and scriptable image viewer targeted
19 at the users who are comfortable with software like the Vim text editor or the
20 Mutt mail user agent, or keyboard oriented, full screen programs.
21 FIM aims to be a "Swiss Army knife" for viewing images.
22
23 FIM is multidevice: it has X11/Wayland support (via the SDL and GTK libraries),
24 it supports ASCII art output (via the aalib and libcaca libraries), and because
25 it derives from the Fbi image viewer (by Gerd Hoffmann), it can display images
26 in the Linux framebuffer console, too.
27
28 FIM is free software, distributed under the terms of the GPL software license.
29
30 -==============================================================================-
31 2 Description
32 ================================================================================
33
34 FIM invocation is documented in `man fim` (doc/fim.man.html).
35 The FIM language (syntax, commands, variables, key bindings) is documented in
36 `man fimrc` (doc/fimrc.man.html).
37
38 FIM offers many ways for scaling, orienting, listing or rearranging the
39 ordering of images.
40 FIM is capable of regular expressions based (on filename) vim-like autocommands,
41 comment-based search and filtering, display of EXIF tags, customizable command
42 lines, and use a custom font (from console fonts).
43 FIM offers GNU `readline` command line autocompletion and history,
44 completely customizable key bindings, internal/external scriptability
45 (through return codes, standard input/output, commands given at invocation time,
46 and an initialization file), internal filename-based image search, and more.
47 Each documentation item is accessible via the internal `help` command.
48
49 -==============================================================================-
50 3 Features, comparison to other image viewers
51 ================================================================================
52
53 Features:
54
55 * modes: interactive (default), and command line
56 * lots of the functionality is scripted in an internal domain specific language
57 * on-screen debug and information console in command mode
58 * per-image variables (e.g.: `i:var="value"`)
59 * regular expression filename search (`/*.png`) and view
60 * command line history (enter the console with `':'`, then use arrows)
61 * command line Tab-based command autocompletion (thanks to the GNU readline)
62 * command line history file save/load support (`~/.fim_history`)
63 * key-action bindings, with Shift (uppercase and Control ('C-') key combinations
64 * simple `if/while` scriptability, with integer/float/string variables and arithmetic evaluation
65 * command aliases support (macros)
66 * event autocommands (styled after Vim's `autocmd` )
67 * regular expressions on filenames to enrich autocommand behaviour
68 * image descriptions display ('expando' sequences)
69 * regular expressions on image descriptions
70 * configuration (initialization) file support (`~/.fimrc`)
71 * usable built-in default configuration
72 * wrapper script (`fimgs`) to convert pdf,ps,eps,dvi,cbr(rar),cbz(zip),tar,tar.gz,tgz,http://...
73 contents into images that can be displayed
74 * embedded piping through `convert`,`inkscape`,`xcftopnm`,`dia`... to visualize further file formats
75 * view a Matrix Market file rendering via librsb
76 * index-based `goto` styled after Vim (`:<number>`)
77 * image search with regular expressions on filenames (`goto` command)
78 * other stuff usual for an image viewer (`scale`, `pan,` etc..)
79 * other stuff unusual for an image viewer (setting scale factor, auto width scale,
80 auto height scale, marking of 'interesting' files, sorting of files in the
81 list, recording/replaying of sessions, repeat last action )
82 * image flip, mirror, rotation, stretch (asymmetric scaling)
83 * command iteration (with the `[n]<command key>` syntax
84 * external script file execution
85 * system call support
86 * image cache and mipmaps
87 * image prefetch
88 * pipe commands from an input program
89 * many features could be enabled or disabled at compile time editing the Makefile
90 * run under screen or ssh
91 * read files list via standard input
92 * read image file via standard input
93 * read commands script via standard input
94 * support for GTK (`-o gtk`) (X11/Wayland)
95 * support for SDLlib (Simple Directmedia Layer) (`-o sdl`) (X11/Wayland)
96 * support for AAlib (ASCII Art rendering) (`-o aa`)
97 * support for libcaca (Colour ASCII Art rendering) (`-o ca`)
98 * experimental (incomplete, discontinued) support for Imlib2 (`-o imlib2`)
99 * experimental support for file formats: PDF, PS, DJVU
100 * view any file as a binary/RGB pixelmap
101 * view any file as (rendered) text
102 * open files at a specified byte offset
103 * image list limiting (temporary list shrinking)
104 * comments / captions / description files
105 * search and reordering based on descriptions and internal variables
106 * decode files based on magic number (contents), not file extension
107 * recursive load from directory
108 * sort files list on file name, file size or name date
109 * text font control (selection of size and consolefont)
110 * dump list of selected images to `stdout`
111 * jump between last two images repeatedly with one key
112
113 The next table is a comparison (very outdated...) of popular image viewers
114 available on Linux, focusing on FIM-like free software ones.
115
116 | Program: |kuickshow|eog|xz|gv|fbi|FIM|GQview|dfbsee|pv|qiv|
117 |--------------------------------|-----|---|--|--|---|---|------|------|--|---|
118 |status:(a)lpha/(m)ature | m | m | m| | a | m| m | |m | m |
119 |X=X,f=framebuffer,s=SVGA,a=ascii| X | X |Xs| X| f |fXa| X | ? |f | X |
120 |linux specific | | | ?| | * | *| | |* | ? |
121 |key rebindings | * | | | | | *| * | | | ? |
122 |external scriptability | | | | | ~ | *| | | | ? |
123 |internal scriptability | | | | | | *| | | | ? |
124 |internal scriptability | | | | | | *| | | | ? |
125 |printing support | * | * | ?| | | | * | | | ? |
126 |slideshow | * | * | | | * | *| * | |* | * |
127 |caching | * | ? | | | | *| * | | | ? |
128 |preview browser | * | | | | | | * | | | ? |
129 |EXIF tag display | * | | | | * | *| * | | | ? |
130 |internal windowing | | | | | | X| | | | ? |
131 |internal image search | | | | | | *| | | | ? |
132 |external image search | | | | | | | * | | | ? |
133 |'pan views' ('rich' views) | | | | | | | * | | | ? |
134 |system interaction | * | | | | | *| * | | | ? |
135 |system interaction safe | * | | | | | | | | | ? |
136 |remote commands | | | | | | | * | | | ? |
137 |saves last folder | * | | | | | | * | | | ? |
138 |runs under screen | | | | | | *| | | | ? |
139 |standard input interaction | | | | | | *| | | | ? |
140 |rotation | * | ? | ?| | ? | *| ? | ? |* | * |
141 |history | | | | | | *| | | | |
142 |multi-device | | | | | | *| | | | |
143 |mirroring | | | | | | *| | | | * |
144 |description files | | | | | | *| | | | |
145
146
147 Other nice command line picture viewers: pv (http://www.trashmail.net/pv/),
148 zgv, feh, sxiv, mirage...
149
150 ______________________________________________________________________________
151
152
153 -==============================================================================-
154 4 Build, test, example
155 ================================================================================
156
157
158 Requirements are:
159
160 * the GNU readline library ( https://www.gnu.org/software/readline/ )
161 * GNU flex (NOT any lex ) ( https://www.gnu.org/software/flex/ )
162 (some systems need also 'libfl-dev' to find `FlexLexer.h`)
163 * GNU bison (NOT any yacc) ( https://www.gnu.org/software/bison/)
164 * the GCC ( GNU Compiler Collection ) ( http://gcc.gnu.org/ )
165 or clang ( https://clang.llvm.org/ )
166 * and optionally:
167 * GTK-3 ( https://gtk.org/ )
168 * libsdl-1.2 ( https://libsdl.org/ )
169 * libsdl-2.0 ( https://libsdl.org/ )
170 * libexif ( https://libexif.github.io/ )
171 * libjpeg ( https://www.ijg.org/ )
172 * libpng ( http://www.libpng.org/ )
173 * giflib ( https://sourceforge.net/projects/giflib/ )
174 * libtiff ( http://www.libtiff.org/ )
175 * libdjvulibre ( https://djvu.sourceforge.net/ )
176 * libwebp ( https://github.com/webmproject/libwebp/ )
177 * libavif ( https://github.com/AOMediaCodec/libavif/ )
178 * libqoi ( https://qoiformat.org/ )
179 * ...
180
181
182 Libraries originally required by Fbi-1.31 but not by FIM:
183 libFS, libCURL, libLIRC
184
185
186 Usually, building and installing FIM proceeds like:
187
188 ./configure --help # get options you may pass to configure
189 ./configure
190 make
191 make test
192 sudo make install
193
194 If you wish to run `./configure` again with different options, it is
195 recommended to `make clean` before that.
196
197 --------------------------------------------------------------------------------
198 4.1 Test
199
200
201 # run fim in interactive mode (press q to quit)
202 make test
203
204 # run the test suite
205 make tests
206
207
208 You can also run separately parts of `make tests`:
209
210 # run only -o fbdev tests (if disabled, fail)
211 make fbtests
212
213 # run only -o gtk tests (if disabled, fail)
214 make gtktests
215
216 # run only -o sdl tests (if disabled, fail)
217 make sdltests
218
219 # run only -o aa tests (if disabled, fail)
220 make aatests
221
222 # run only -o ca tests (if disabled, fail)
223 make cacatests
224
225 --------------------------------------------------------------------------------
226 4.2 Example on Debian
227
228 sudo apt install subversion
229 sudo apt install flex libfl-dev bison
230 sudo apt install automake autoconf libtool # to generate configure, etc
231 sudo apt install pkg-config # to generate configure
232 sudo apt install libreadline-dev libexif-dev
233 sudo apt install libjpeg-dev libpng-dev libtiff-dev libgif-dev
234 sudo apt install libsdl2-dev libaa1-dev libcaca-dev libgtk-3-dev
235 # the following are experimental, less recommended:
236 sudo apt install libpoppler-cpp-dev libpoppler-dev libpoppler-private-dev
237 sudo apt install libdjvulibre-dev libspectre-dev
238 sudo apt install libqoi-dev libwebp-dev libavif-dev
239 sudo apt install libarchive-dev
240 svn co http://svn.savannah.nongnu.org/svn/fbi-improved/trunk/ fim
241 cd fim
242 autoreconf -i
243 ./configure --enable-aa --enable-caca --enable-sdl --enable-gtk
244 make
245 sudo make install
246
247 -==============================================================================-
248 5 Run time requirements
249 ================================================================================
250
251 * Linux (not sure if it is necessary for it to be an x86; i think not)
252 * The framebuffer device ( e.g.: `/dev/fb0` or `/dev/fb/0` ) enabled in the kernel
253 ( and usually found in `"/usr/src/linux/Documentation/fb"` in the kernel source
254 code tree ).
255 * unless disabled, FIM will create a history (`~/.fim_history`) file in the
256 `${HOME}` directory when leaving (so it assumes ${HOME} to exist)
257 * shared library files for e.g.: libpng, libjpeg, libgif, libtiff, libreadline,
258 libexif, ...
259
260 -==============================================================================-
261 6 Original Idea
262 ================================================================================
263
264 FIM derives from the wonderful fbi-1.31, written by Gerd Hoffmann/Knorr:
265 ( Fbi can be obtained at https://www.kraxel.org/blog/linux/fbida/ ).
266
267 It all started in 2005, developing a small 'vim-like fbi patch', and following
268 features to enrich Fbi with a command line and more customizations.
269
270 FIM is a significant reorganization and expansion of the Fbi code, and aims at
271 obtaining the most scriptable and configurable image viewer ever.
272
273 -==============================================================================-
274 7 Notes for patch writers
275 ================================================================================
276
277 To run, FIM requires a Linux box with X, or the framebuffer device enabled in
278 the kernel, and some popular image file decoding libraries.
279
280 Information about the framebuffer can be found under the directory
281 "./Documentation/fb"
282 inside the kernel tree
283 (usually "/usr/src/linux/Documentation/fb" ).
284
285 The file decoding libraries are listed in an earlier section.
286 Tested and working with library SDL-1.2.12 through SDL-1.2.15.
287 Experimental support for SDL-2.0 and GTK-3.0.
288
289 From the original Fbi README, it reads that Gerd himself wrote FBI hacking
290 "a svgalib PhotoCD viewer", so regard this software as a big, dirty code
291 potpourri :) .
292 For the sake of completeness, FIM started as a fork of version 1.31 of fbi,
293 available from http://dl.bytesex.org/releases/fbida/fbi_1.31.tar.gz .
294
295 Useful documents I've read and consulted during the coding of Fim, and
296 useful for hacking it:
297
298 * Thomas Niemann's tutorial to yacc & lex
299 * The yacc & lex HOWTO
300 * GNU readline manual
301 * Ray Lischner, STL Pocket Reference, O'Reilly, 2004
302 * Herbert Schildt "C++ - Complete Reference" Third Edition, Osborne McGraw-Hill, 1999
303 * http://www.gnu.org/software/m4/manual/
304 * http://www.gnu.org/software/autoconf/manual/
305 * http://www.gnu.org/software/automake/manual/
306 * http://www.gnu.org/software/make/manual/
307 * http://www.gnu.org/software/bash/manual/
308 * http://www.gnu.org/software/bison/manual/
309 * http://cppreference.com/
310 * `man console_codes`
311 * `man fb.modes`
312 * `man fbi`
313 * `man console_ioctl`
314 * `man resizecons`
315
316 Further useful documents:
317 * `vim -c ':help'`
318 * `man 3 history`
319 * `man readline`
320 * http://www.gnu.org/prep/standards/
321
322 Useful URLs:
323 * http://www.tldp.org/HOWTO/Framebuffer-HOWTO.html
324 and mirrors
325 * http://www.linux.org/docs/ldp/howto/Framebuffer-HOWTO.html
326 * http://www.pluto.it/files/ildp/HOWTO/Framebuffer-HOWTO/Framebuffer-HOWTO.html
327 and
328 * http://bisqwit.iki.fi/source/fbmodes.html
329 * http://asm.sourceforge.net/articles/fb.html
330 * http://www.linuxjournal.com/article/2783
331
332 Platforms tested in the past versions (fim-0.3...):
333 * 2.6.25-2-686 Linux Kernel, GCC-4.3.1, flex 2.5.35, bison 2.3, Debian Lenny, x86
334 * 2.6.17 Linux Kernel, GCC-3.4.6, gentoo, x86
335 * 2.6.17 Linux Kernel, GCC-4.1.1, gentoo, x86
336 * 2.6.17 Linux Kernel, GCC-3.3.6, flex 2.5.4, bison 1.875d, gentoo, x86
337 * 2.6.17 Linux Kernel, GCC-3.3.6, flex 2.5.4, bison 2.2 , gentoo, x86
338 * 2.6.17 Linux Kernel, GCC-3.3.6, flex 2.5.33,bison 2.2 , gentoo, x86
339 * 2.6.19 Linux Kernel, GCC-4.1.1, flex 2.5.33,bison 2.2 , gentoo, powerpc
340 * other ones, but non documented here.
341
342
343 If you intend to write patches or contribute to the code, be sure of reading
344 all of the documentation and _write me an email first_ (I will give you some
345 advice).
346
347
348 --------------------------------------------------------------------------------
349 7.1 Hacking, maintenance guidelines
350
351 If you hack FIM in an interesting way, consider submitting your changes as a
352 patch.
353
354 * If you introduce support for a new file format: `fim -V` should list the
355 your new format, too (so you should update it).
356 * Same for a new output device.
357 * FIM should continue passing the tests after your patch, and your patch should
358 be robust, too. Consider writing a new test case.
359 * In particular, the developer tests should pass:
360 `make devtests dist dist-tests`.
361 * If you're experimenting on Android's Termux, for gtk3 you may need
362 'xorgproto' to provide you 'xproto' (applies to Termux version 0.118.0).
363
364 -==============================================================================-
365 8 Availability in Linux distributions
366 ================================================================================
367
368 --------------------------------------------------------------------------------
369 8.1 Debian, Ubuntu
370
371 You should find fim in Debian and Ubuntu, and install it with:
372
373 sudo apt install fim
374
375 But beware: the deb packages may be outdated.
376
377
378 In order to build from repository, you are advised to install packages from
379 the following (overly complete) list:
380
381 autoconf autoconf-archive autoheader automake autotools-dev bison ctags
382 flex groff g++ libaa1-dev libcaca-dev libdjvulibre-dev libgif4 libgif-dev
383 libjpeg-dev libncurses5-dev libpng-dev libtiff-dev libexif-dev
384 libpoppler-cpp-dev libpoppler-dev libpoppler-private-dev libreadline-dev
385 libsdl2-dev libspectre-dev libtool m4 make svn txt2html
386
387 The above list was valid on a Debian Jessie installation; it's possible that
388 these packages names change with time.
389
390 -==============================================================================-
391 9 License
392 ================================================================================
393
394 FIM is free software, and is licensed under the GPLv2 or later.
395 FIM has been written by Michele Martone.
396
397 FIM started as a fork of fbi-1.31 by Gerd Hoffmann, which is "GPLv2 or later".
398 FIM uses the PCX reading code contributed by Mohammed Isam.
399 FIM also uses a regex.c file from the GNU Regular Expressions library,
400 distributed on http://directory.fsf.org/regex.html, in the version shipped with
401 the Mutt mail user agent ( http://www.mutt.org ).
402 It also uses scripts shipped with the Vim text editor (http://www.vim.org),
403 which is licensed compatibly with the GPL.
404 The FIM source code package includes the Lat15-Terminus16.psf file, originally
405 from the GPL licensed Terminus Font package, version 4.30 authored by
406 Dimitar Toshkov Zhekov.
407
408 -==============================================================================-
409 10 Contacts, mailing lists, URLs
410 ================================================================================
411
412 FIM is (C) 2007-2024 Michele Martone.
413
414 Email: "dezperado_FOobAr_autistici_Baz_org", just care replacing
415 _FOobAr_ with a '@' and _Baz_ with a '.'.
416 GPG Key: 0xE0E669C8EF1258B8
417 GitHub: https://github.com/michelemartone
418
419 If it is for a bug report or installation help, be sure of reading the
420 documentation and the BUGS file first.
421 FIM is not perfect: a number of weaknesses are summarized in the man pages,
422 the TODO file, and the BUGS file.
423
424
425 Homepage : https://www.nongnu.org/fbi-improved/
426
427 Savannah Page: http://savannah.nongnu.org/projects/fbi-improved/
428
429 Announcements: http://freecode.com/projects/fbi-improved/
430
431 Mailing List : http://savannah.nongnu.org/mail/?group=fbi-improved
432 (or http://lists.nongnu.org/mailman/listinfo/fbi-improved-devel)
433
434 Releases : http://download.savannah.nongnu.org/releases/fbi-improved
435
436 Repository : http://svn.savannah.nongnu.org/svn/fbi-improved
437
438 Off. Mirror : http://www.autistici.org/dezperado/fim/
439
440 ChangeLog : http://svn.savannah.nongnu.org/svn/fbi-improved/trunk/ChangeLog
441
442 Bugs (official) : http://savannah.nongnu.org/bugs/?group=fbi-improved
443
444 $Id: README 2233 2024-05-01 11:01:21Z dezperado $
445 vim:tw=78:fo=tcq2:isk=!-~,^*,^\|,^\":ts=8:ft=markdown:norl: