Debian Codegraph @

doc/FIM.html

raw
1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2 <html>
3 <head>
4 <title>FIM: FIM</title>
5 <link rel="stylesheet" href="fim-stylesheet.css" type="text/css">
6 </head>
7 <body>
8 <h2>FIM</h2>
9 <pre>
10 </pre><hr><pre><b class="vimtag">*<a name="FIM.TXT">FIM.TXT</a>*</b> Tutorial &amp; Miscellaneous documentation for Fim
11 last updated $Date: 2024-05-10 00:24:27 +0200 (Fri, 10 May 2024) $
12
13 Fim - tutorial &amp; misc documentation
14
15 First of all, please view this text file in Vim with ':set syntax=help'.
16 If you already know Vim, you will know that in this way you can use this
17 documentation as it was a hypertext.
18 ( or add "autocmd BufReadPost FIM.TXT set syntax=help" into your ~/.vimrc ! )
19 If you do not know Vim, you can find it at http://www.vim.org.
20 A hypertextual version of this file (FIM.html) shall be also available
21 with your fim distribution.
22
23 Thank you for using this software; one can regard it as a 'hack',in
24 the sense it is an elaboration of the passionate work of multiple people.
25
26 Please <code class="note">note</code> that this documentation is <b class="vimtag">*<a name="not">not</a>*</b> complete, as Fim is still
27 evolving, and some changes as the exact language specifications are hard to
28 track and document. They will be when a high level of satisfaction of the
29 fim capabilities, usability and overall stability will be achieved.
30 Meanwhile, this file documents Fim commands and functionalities, and gives
31 lots of examples.
32 For a reference of Fim command line flags, see the man pages of Fim:
33
34 <code class="example"> man fim</code>
35 <code class="example"></code>
36 For a reference of Fim internal commands, see
37
38 <code class="example"> man fimrc</code>
39 <code class="example"></code>
40 For the documentation of the 'fimgs' script, see
41
42 <code class="example"> man fimgs</code>
43 <code class="example"></code>
44 The man pages are rich with examples.
45
46
47
48 IMPORTANT <code class="note">NOTE:</code>
49
50 This document will be eliminated/reconverted once all the relevant
51 information will be made available in the man pages, so it may be
52 outdated/obsolete.
53
54 The man pages are the authoritative documentation sources for fim.
55
56 Enjoy!
57
58 </pre><hr><pre>0. Introduction <b class="vimtag">*<a name="intro">intro</a>*</b>
59
60 Fim Startup: to open an image, n framebuffer mode, place yourself in a
61 Linux framebuffer console (that is, outside the X environment -- this
62 is usually achieved by typing <code class="keystroke">CTRL-ALT</code>-F1 from within the X environment)
63 and type:
64
65 <code class="example"> fim image.png</code>
66 <code class="example"></code>
67 You can be sure of being in a Linux framebuffer console by issuing.
68
69 <code class="example"> cat /dev/urandom &gt; /dev/fb0</code>
70 If randomly coloured pixels start appearing on the screen, it means that
71 you are in a framebuffer console and you have proper access rights to it.
72
73 If you have problems here, see the <b class="vimtag">*<a name="framebuffer">framebuffer</a>*</b> section.
74
75
76 Fim Quickstart: to move the image around,
77 use the cursor keys, or "h" to go left, h l
78 "j" to go down, "k" to go up, "l" to go right. j
79 Get out of Fim: Use ":q<code class="special">&lt;Enter&gt;</code>" (press ':', then 'q', then 'enter').
80 Or just press q (or Esc, or whatever you wish, thanks to
81 the <b class="vimtag">*<a name="key-bindings">key-bindings</a>*</b> capabilities.
82
83
84 Fim stands for Fbi IMproved.
85
86 Fbi is a |<a href="./FIM.html#framebuffer">framebuffer</a>| based image viewer by Gerd Hoffmann, and Fim is
87 primarily an interface rework applied roughly as a patch to it, and is an
88 idea and codework of Michele Martone.
89
90 The idea of making Fim came after long usage sessions of Vim and Fbi, and a
91 zest of science fiction inspiration.
92
93 The main purposes of Fim are to power up the features present in Fbi by adding
94 new ones, and achieve higher configurability and flexibility.
95
96 Ease of use and simplicity is a primary concern, too.
97 No programming language knowledge nor reading this manual is needed to use
98 FIM if you have already used Fbi once.
99
100 A basic tenet of configurability the freedom of managing and customize the
101 <b class="vimtag">*<a name="key-bindings">key-bindings</a>*</b> to one's tastes.
102 Fim has a mechanism for the creation of a |<code class="badlink">configuration</code>| file.
103 But Fim tries to go beyond this and propose - in a Vim-ish way - an approach
104 towards complete reconfigurability, and even scriptability of the program.
105 The inspiration for this comes from the use of the nicer software available
106 as free software, often characterized by extreme flexibility, configurability,
107 hackability. This concerns mainly text editors and mail user agents, but why
108 can't this apply to an image viewer, too ?
109
110 </pre><hr><pre>1. Index <b class="vimtag">*<a name="index">index</a>*</b>
111
112 Introduction to Fim <b class="vimtag">*<a name="ref">ref</a>*</b> <b class="vimtag">*<a name="reference">reference</a>*</b>
113
114 0. Introduction |<a href="./FIM.html#intro">intro</a>|
115 1. Index |<a href="./FIM.html#index">index</a>|
116 2. Fim on the Internet |<a href="./FIM.html#internet">internet</a>|
117 2.1. Contact information |<a href="./FIM.html#contact">contact</a>|
118 2.2. Help wanted |<a href="./FIM.html#help-wanted">help-wanted</a>|
119 3. Installation, basic usage |<a href="./FIM.html#basics">basics</a>|
120 3.1. Customization |<a href="./FIM.html#customization">customization</a>|
121 3.2. Keyboard binding |<a href="./FIM.html#keyboard">keyboard</a>|
122 3.3. The fimgs script |<a href="./FIM.html#fimgs">fimgs</a>|
123 3.4. External scripting |<a href="./FIM.html#scripting">scripting</a>|
124 3.5. System integration tips |<a href="./FIM.html#tips">tips</a>|
125 4. Command Line Mode |<a href="./FIM.html#cli">cli</a>|
126 5. Command Line Mode Basics |<a href="./FIM.html#cli-basics">cli-basics</a>|
127 6. Commands Reference |<a href="./FIM.html#commands-reference">commands-reference</a>|
128 6.1. Loading and browsing |<a href="./FIM.html#commands-browsing">commands-browsing</a>|
129 6.2. Scaling, flipping, rotating|<a href="./FIM.html#commands-scaling">commands-scaling</a>|
130 6.3. Panning,moving |<a href="./FIM.html#commands-scroll">commands-scroll</a>|
131 6.4. Recording |<a href="./FIM.html#commands-recording">commands-recording</a>|
132 6.5. Console related commands |<a href="./FIM.html#commands-console">commands-console</a>|
133 6.6. System Interaction |<a href="./FIM.html#commands-system">commands-system</a>|
134 6.7. Variables |<a href="./FIM.html#variables">variables</a>|
135 6.8. Autocommands |<a href="./FIM.html#commands-autocommands">commands-autocommands</a>|
136 7. Command Line,More |<a href="./FIM.html#cli-more">cli-more</a>|
137 7.1. Default configuration |<a href="./FIM.html#default-config">default-config</a>|
138 8. Pattern Matching |<a href="./FIM.html#pattern-matching">pattern-matching</a>|
139 9. Dangers |<a href="./FIM.html#dangers">dangers</a>|
140 10. Technicalia |<a href="./FIM.html#technicalia">technicalia</a>|
141 10.1. Syntax Reference |<a href="./FIM.html#syntax-ref">syntax-ref</a>|
142 10.2. Framebuffer mini how to |<a href="./FIM.html#framebuffer">framebuffer</a>|
143 11. Credits |<a href="./FIM.html#credits">credits</a>|
144 12. FAQs |<a href="./FIM.html#faq">faq</a>|
145 13. License |<a href="./FIM.html#license">license</a>|
146
147 </pre><hr><pre>2. Fim on the Internet <b class="vimtag">*<a name="internet">internet</a>*</b>
148
149 The official Fim page is hosted by the nonGNU project:
150 http://savannah.nongnu.org/projects/fbi-improved/
151
152 The secondary Fim page is:
153 http://www.autistici.org/dezperado/fim/
154
155 Tarball releases are located on
156 http://download.savannah.nongnu.org/releases/fbi-improved/
157
158 The official SVN (subversion) repository is:
159 http://svn.savannah.nongnu.org/svn/fbi-improved/
160
161 The official and secondary web sites contain all the relevant Fim
162 documentation, and the downloadable Fim archives.
163
164 The current SVN repository is kindly hosted by the Savannah
165 project: https://savannah.nongnu.org/projects/fbi-improved
166 You can support Fim by supporting the Savannah project.
167
168 The old SVN repository has been hosted by the Autistici/Inventati
169 past 'code' project for several years.
170 You can support Fim supporting the A/I project as well.
171
172 You could be able to browse the Fim code on the repository, pointing your
173 browser on:
174 http://svn.savannah.nongnu.org/svn/fbi-improved/trunk/
175
176 and get the latest source code tree on:
177 svn export http://svn.savannah.nongnu.org/svn/fbi-improved/trunk/
178
179 This documentation is distributed with the software.
180 See the INSTALL file for installation instructions and issues.
181
182 Although an official bug tracker exists:
183 http://savannah.nongnu.org/bugs/?group=fbi-improved
184 you are rather encouraged to report bugs and/or compilation
185 problems via email to the author directly.
186
187 But before posting anything, read the BUGS file, the |<code class="badlink">bugs</code>| section,
188 and have a look and subscribe to the Fim development mailing list:
189
190 http://lists.nongnu.org/mailman/listinfo/fbi-improved-devel
191
192 </pre><hr><pre>2.1. Contact information <b class="vimtag">*<a name="contact">contact</a>*</b>
193
194 If you want to contribute to the project, it would be appreciated to receive
195 by email a complete report:
196
197 ( make ; make report ) 2&gt;&amp;1 | gzip &gt; fim.`date +%Y%m%d%H%M`.log.gz
198 and please send me the file config.log, generated by running ./configure
199
200 You can report this to dezperado _FOobAr_ autistici _Baz_ org, by replacing
201 _FOobAr_ with a '@' and _Baz_ with a '.'.
202
203 Indications about how to improve this documentation are appreciated, too.
204
205 Ideas on the FIM language and potential use are welcome, too.
206 The current bunch of ideas and inspiration is put in the TODO file.
207 The best place for this discussions is the mailing list, as pointed above.
208
209 p.s.: please read the BUGS file to consult the current bug list, when
210 submitting a bug.
211
212 </pre><hr><pre>2.2. Help appreciated <b class="vimtag">*<a name="help-wanted">help-wanted</a>*</b>
213
214 If you like Fim, you are welcome to do contribute with your help.
215
216 If you have trouble installing Fim, and you think it is Fim's fault, please
217 |<a href="./FIM.html#contact">contact</a>| Fim's author with an email (see Contact Information, above ) and
218 describe carefully the encountered problem.
219
220 If you want to help actively, you are not required to be a programmer; please
221 read on!
222
223 There are the major (P)roblem areas and the possible (C)ontributions:
224
225 P: Keyboard input: panning is somewhat 'slow' or choppy sometimes.
226
227 C: Yes, the input system may be improved.
228 Be sure you have the right video mode and video driver loaded in the kernel.
229 You are welcome to suggest improvements.
230
231 P: Current Fim language and features issues.
232
233 C: If you think the current Fim language is not completely clear or has flaws,
234 you can suggest useful Flex/Bison tips to me.
235 You could suggest Flex/Bison tips also for solving the current language
236 reduce conflicts.
237
238 P: The documentation may be not informative enough.
239
240 C: Describe your personal experience with Fim, providing the pluses
241 and minuses in it, the way you use it, and the ways you would like to.
242 If you have interest in it, your help will contribute to inspire improvements.
243
244 P: Fim sucks: it lacks of feature XXX
245
246 C: You are welcome to send me (|<a href="./FIM.html#contact">contact</a>|) suggestions about the features you
247 would desire Fim to have.
248
249 </pre><hr><pre>3. Installation, basic usage <b class="vimtag">*<a name="basics">basics</a>*</b>
250
251 The installation instructions (a 'make;make install' invocation should suffice)
252 are stated in the INSTALL file, contained in the source archive.
253
254
255 The basic usage of Fim consists of calling it from the Linux console, in a
256 non-X environment, assuming the framebuffer enabled ( if you do not know if
257 your framebuffer is enabled at all, please see the <b class="vimtag">*<a name="framebuffer">framebuffer</a>*</b> section ).
258
259 So, if you have picture.jpg and picture.png in the current directory, issuing
260
261 $ fim picture.jpg picture.png
262
263 should start Fim and display the two specified images.
264
265 Like in Fbi or any other reasonable image viewer, you could be able to view
266 the next or previous image by pressing PageUp or PageDown, or to pan the image
267 around using the arrows.
268 Quitting is triggered by pressing 'q' or <code class="special">&lt;C-c&gt;</code> (holding the control key and
269 then pressing 'c' ).
270
271 In this very basic way, you use the portion of Fim that mimics Fbi.
272
273 You could benefit of Fim features by familiarizing to its command line mode,
274 and reading this carefully written documentation.
275
276 </pre><hr><pre>3.1. Customization <b class="vimtag">*<a name="customization">customization</a>*</b>
277
278 To configure fim, and/or to modify its default behaviour, you could create
279 a .fimrc file in your home directory:
280
281 $ touch ~/.fimrc
282
283 and then edit the file and filling it only with lines you could write live
284 in the fim console or feed to Fim via the -c (pre-execution command) or -F (
285 final command) switches (see man fim).
286
287 If the ~/.fimrc does not exist, the /etc/fimrc file will be sourced, if
288 existent.
289
290 These and other functionality can be activated / deactivated at build time.
291 By executing
292
293 <code class="example"> fim -V</code>
294 <code class="example"></code>
295 you get an output message informative about the compilation details.
296
297 Even if compiled with scripting support, a default configuration has probably
298 built in the program, and all of the interpreting mechanisms are there.
299 Be sure of reading all of the details before asking the author or mailing list.
300
301 </pre><hr><pre>3.2. Keyboard Bindings <b class="vimtag">*<a name="keyboard">keyboard</a>*</b>
302
303 You can assign an arbitrary keyboard key or keys sequence an arbitrary Fim
304 command. See the next two examples:
305
306 <code class="example"> :bind 'n' "next";</code>
307 <code class="example"> :bind 'C-n' "prev";</code>
308 <code class="example"></code>
309 The first command tells Fim that now on, when in interactive mode, pressing 'n'
310 will be equivalent of issuing 'next' in the command line console.
311
312 Likewise, the 'C-n' notation stays for <code class="special">&lt;C-n&gt;</code>, or <code class="special">&lt;Ctrl-n&gt;</code>, or <code class="keystroke">CTRL-n</code>: the
313 act of pressing together the Control and the 'n' keys.
314 The second example assigns 'prev' like an action to be executed when the user
315 will press the Control and the 'n' keys together in interactive mode.
316
317 <code class="note">Note</code> that these commands work inside Fim, and can be written inside the ~/.fimrc
318 configuration file (without the heading ':', though! ).
319
320 When you'll see more commands you'll have a broader range of custom keyboard
321 bindings as your configurability potential.
322 If you are curious, jump to the |<a href="./FIM.html#commands-reference">commands-reference</a>| section right now.
323 Or simply type |<code class="badlink">commands</code>| in Fim.
324
325 Interactive mode offers a way of specifying that an interactive command should
326 be executed more than one time.
327
328 So, typing
329
330 <code class="example"> 10n</code>
331 <code class="example"></code>
332 in interactive mode will tell Fim to execute ten times the action bound by the
333 'n' key, that is, executing 10 times 'next', like typing ':10next'.
334
335 So, the general form of this feature is:
336
337 <code class="example"> [n]<code class="special">&lt;command key&gt;</code></code>
338 <code class="example"></code>
339 Using the dot key:
340
341 <code class="example"> .</code>
342 <code class="example"></code>
343 will repeat the last command. If the previous command was executed multiple times
344 in interactive mode by prepending with a number, it will be repeated the same
345 number of times.
346 If the '_max_iterated_commands' variable is set, the bound action will be repeated
347 no more than '_max_iterated_commands' times.
348
349 </pre><hr><pre>3.3. The fimgs script <b class="vimtag">*<a name="fimgs">fimgs</a>*</b>
350
351 Fim wants to be flexible enough to let you use it directly or through some script.
352 It comes out of the box with one wrapper script, called fimgs (or fimgs.sh)
353 which is capable of converting some file formats in other ones, which fim
354 understands.
355
356 The fimgs script is capable of fetching a file from the web for you, displaying
357 it in the framebuffer using fim, and deleting it from the temporary directory
358 where it has been stored.
359
360 Additionally, the fetched (or local) file could be among the ones directly
361 supported, or one of the following:
362
363 - an Adobe Postscript (.ps, .eps) document
364 - an Adobe Portable Document Format (.pdf) document
365 - a TeX DeVice Indipendent file format (.dvi) document
366
367 - a PKZIP compressed archive (.zip, .cbz)
368 - a RAR compressed archive (.rar, .cbr)
369 - a Tape ARchive archive (.tar)
370 - a g-Zipped Tape ARchive archive (.tgz, .tar.gz)
371
372 If the file is among the first three categories, it is converted through
373 GhostScript ( gs(1) ) in a number of .png files in a temporary directory.
374
375 Otherwise, if the file is among the archives file formats listed, it is
376 decompressed in a temporary directory and displayed file by file with fim.
377
378 </pre><hr><pre>3.4. External scripting <b class="vimtag">*<a name="scripting">scripting</a>*</b>
379
380 Fim is tailored to be as flexible as possible.
381 There are scripts in the "scripts/utilities/" installation directory, which
382 give examples on some uses of fim.
383
384 Take as example the "scripts/utilities/fimscan.sh" shell script: it uses the
385 "scanimage" utility (distributed with the sane-backends package) to scan
386 images at low resolution, ten shows them to the user via fim, asking (inside
387 fim) the user whether to rescan (at higher resolution) the image and save it
388 with a suggested numbered filename scheme.
389
390 </pre><hr><pre>3.5. System integration tips <b class="vimtag">*<a name="tips">tips</a>*</b>
391
392 If you are used to software like mutt, you are likely to use much the console.
393 Often, when using a console without X, it is necessary to view some attachment
394 which is an image or some Adobe Postscript or Adobe PDF attachment.
395 In these cases, Fim could be integrated in the ~/.mailcap file, read by mutt:
396
397 image/*;( [ "$DISPLAY" != "" ] &amp;&amp; kuickshow %s ) ||<code class="badlink"> ( ( ( tty </code>| grep tty ) &amp;&amp; fim %s ) || cacaview %s )
398 image/png;( [ "$DISPLAY" != "" ] &amp;&amp; kuickshow %s ) ||<code class="badlink"> ( ( ( tty </code>| grep tty ) &amp;&amp; fim %s ) || cacaview %s )
399 image/jpeg;( [ "$DISPLAY" != "" ] &amp;&amp; kuickshow %s ) ||<code class="badlink"> ( ( ( tty </code>| grep tty ) &amp;&amp; fim %s ) || cacaview %s )
400 application/pdf;( [ "$DISPLAY" != "" ] &amp;&amp; acroread %s ) ||<code class="badlink"> ( ( ( tty </code>| grep tty ) &amp;&amp; fimgs %s ) )
401
402 This will tell mutt to use kuickshow to display images under the X environment,
403 and Fim otherwise.
404
405 Similarly, the 'acroread' program will be invoked under the X environment,
406 leaving the 'fimgs' script (included in the Fim distribution) as a replacement
407 in all other cases.
408
409
410 But if you built mutt with X (via --enable-sdl) support, you can use:
411
412 image/*; %s
413 image/png; %s
414 image/jpeg; %s
415 application/pdf; fim %s
416
417 to use fim seamlessly as your cross-device picture viewer of choice, inside and outside the framebuffer!
418
419
420 The 'elinks' web browser will use the ~/.mailcap file by default, similarly to mutt.
421
422
423 Separately, you can customize the lynx and links web browsers, too.
424
425
426 For the links (version 2) program, use the menus or edit ~/.links2/links.cfg
427 and add the associations for fim:
428
429 association "fimgs" "application/pdf" "fimgs %" 55 1
430 association "fim" "image/jpeg,image/png,image/pnm,image/ppm" "fim %" 23 1
431
432 and the MIME bindings:
433
434 extension "pnm" "image/x-portable-anymap"
435 extension "ppm" "image/x-portable-pixmap"
436 extension "png" "image/png"
437 extension "jpg,jpeg,jpe" "image/jpeg"
438 extension "pdf" "application/pdf"
439
440 In this way you should be able to view images in the framebuffer via 'fbi'
441 spawned by links !
442
443
444
445 Or the mc ('midinight commander') program, editing ~/.mc/bindings (or configuring
446 via the menus!):
447
448 ### Images ###
449
450 type/^GIF
451 Include=image
452
453 type/^JPEG
454 Include=image
455
456 type/^PC\ bitmap
457 Include=image
458
459 type/^PNG
460 Include=image
461
462 type/^TIFF
463 Include=image
464
465 type/^PBM
466 Include=image
467
468 type/^PGM
469 Include=image
470
471 type/^PPM
472 Include=image
473
474 type/^Netpbm
475 Include=image
476
477 include/image
478 Open=if [ "$DISPLAY" = "" ]; then fim %f; else (kuickshow %f &amp;); fi
479 View=%view<code class="special">{ascii}</code> identify %f
480
481 type/^PostScript
482 Open=if [ "$DISPLAY" = "" ]; then fimgs.sh %f; else (acroread %f &amp;); fi
483
484 type/^PDF
485 Open=if [ "$DISPLAY" = "" ]; then fimgs.sh %f; else (acroread %f &amp;); fi
486 View=%view<code class="special">{ascii}</code> pdftotext %f -
487
488
489 </pre><hr><pre>4. Command Line Mode <b class="vimtag">*<a name="cli">cli</a>*</b>
490
491 The command line mode is activated in Fim by pressing the colon key ( ':' )
492 while standing in interactive mode.
493 A little cursor '_' will appear on the lower left corner of the screen, and
494 more keyboard hits will reveal that text can be written to this command line.
495
496 In this mode, you can issue the internal commands of Fim in an interactive
497 fashion, consult the online help provided with the commands, and experiment
498 with them ( type |<code class="badlink">commands</code>| in Fim to get a list of them).
499
500 The same commands available in this mode are the ones you can use for building
501 your own initialization file ( ~/.fimrc ), which will be read and executed
502 before loading any image and before entering the user input loop.
503
504 If you are familiar already with programming languages, understanding these
505 concepts will be much easier.
506
507 Examples:
508
509 <code class="example"> :20</code>
510 will bring you to the twentieth image in the list (if existing, of course).
511
512 <code class="example"> :$</code>
513 will bring you to the last image in the list
514
515 The same mechanism is achieved with the 'goto' command:
516
517 <code class="example"> :goto "20" ; goto "$"</code>
518 <code class="example"></code>
519 But beware, because
520
521 <code class="example"> :20goto "1"</code>
522 is like jumping on place 20 times, and
523
524 <code class="example"> :$goto</code>
525 <code class="example"></code>
526 does not make sense.
527
528 If these examples sound confusing, please read further or just learn Vim :).
529
530 </pre><hr><pre>5. Commands Line Mode Basics <b class="vimtag">*<a name="cli-basics">cli-basics</a>*</b>
531
532 You can warm up yourself by experimenting with the autocompletion feature.
533 Enter the command line mode hitting ':' one time, then press the Tab key.
534
535 The upper part of the screen will show a text area with information.
536 Fim should have just printed autocompletion information - the text you
537 could type at the keyboard, that is commands and actions.
538
539 Precisely, the displayed list will comprehend the internal commands, the
540 aliases to actions ( not real commands, but groups of commands invokable by
541 some keyboard ), and variables ( which can be assigned or inspected ).
542
543 For singling out the variables, you can also use the 'variables' command.
544 For singling out the aliases, you can also use the 'aliases' command, or
545 'alias' with no argument.
546
547 By invoking 'autocmd' alone, you will ask Fim to show you the list of
548 registered autocommands.
549
550 The autocommand feature is one of the most powerful in Fim, and is explained
551 in detail in the section dedicated to the 'autocmd' command.
552
553 </pre><hr><pre>6. Commands Reference <b class="vimtag">*<a name="commands-reference">commands-reference</a>*</b>
554
555 The internal Fim commands are lightweight enough to be used as parts of bigger
556 macro-commands, that we will call actions.
557 A choice of implementation was to avoid the (re)displaying of the image after
558 every modification to it.
559 For example, issuing 'autoscale;pan_left' would not trigger the displaying of
560 the updated image, until a 'display' command is executed.
561
562 This (default) behaviour allows for particular uses of this software: alas,
563 flexibility and scriptability is enhanced.
564
565 Although, there is a shorthand (enabled by default) which doesn't force the
566 (uninterested) user to issue the 'display' command (by default bound to the
567 interactive key 'd' ) after each minimal command.
568
569 This mechanism is known as |<code class="badlink">auto-commands</code>|, and is enabled in an intuitive way
570 in the default configuration.
571
572 </pre><hr><pre>6.1. Loading and browsing the images <b class="vimtag">*<a name="commands-browsing">commands-browsing</a>*</b>
573
574 If you just invoked Fim, you will notice its behaviour is perfectly similar
575 to that of Fbi: you see the first image loaded in the list.
576 Now you wish to move around.
577
578 If you already know Fbi, you'll try the usual (for an image browser, though)
579 keys combinations: 'PageUp' and 'PageDown' to go to the next or previous
580 image in the list. Also, you'll <code class="note">note</code> that the 'q' key quits the program, and
581 the '+' and '-' keys will scale the image. Quite natural.
582
583 These keys are actually bound to textual commands who truly drive the internal
584 behaviour of Fim. Here are the first ones, essential to start understanding the
585 underneath logic driving the program behaviour:
586
587 'quit' quits the program, optionally executing some action, if specified with
588 the '-F' invocation option, or at run time, or in the configuration file, by
589 the means of some autocommand.
590
591 'sort' sorts the image list alphabetically.
592
593 'prev' jumps to the next image in the list
594 'next' jumps to the previous image in the list
595 'pop' remove the last image from the list
596 'remove' remove the current image from the list
597
598 These commands are quiet, in that they do not directly affect the image
599 displayed on screen; that will be controlled using the autocommands mechanism,
600 triggering 'reload's and 'display's when opportune.
601 These choice was made to not affect the scriptability of Fim, which should
602 be kept maximal.
603 Of course, in the default configuration, in interactive mode, you should not
604 find any unexpected behaviour when issuing 'next' or 'prev' commands;
605 the next (or previous) image filenames will be current, but the actual
606 triggering of 'reload' or 'display' is left to the script or the autocommand.
607
608 'load' loads the current image in the list, if not already loaded
609 'push' 'filename' adds 'filename' to the file list, if not already in
610 'reload' reloads the current image in the list, regardless its load status
611
612 <code class="example"> :push 'image.png'</code>
613 <code class="example"> :f='image.png'; push f</code>
614 <code class="example"> :push 'image.png'</code>
615 <code class="example"></code>
616 As you see, there seems to be some redundancy in the commands, as here specified.
617 The 'load' and 'reload' difference could be useful when programming a script
618 to view images which are refreshed each in a while, like from a camera source.
619
620 'display' displays the current image , if not already displayed
621 'redisplay' displays the current image, regardless its display status
622
623 Difference in 'display' and 'redisplay' arise when thinking about ancillary
624 graphics Fim should load, like status bars or the on-screen console.
625 Moreover, 'redisplay' should display the image as if it was the first time, and
626 this could imply user-defined amenities like rescaling, flipping, or other actions.
627 The 'display' command should be used after such minimal visualization changes
628 as a scroll or a user-triggered rescale, for example.
629
630 A look to the default (or suggested) autocommands of Fim will be a useful
631 explanation for this otherwise exotic features of the program.
632
633 </pre><hr><pre>6.2. Scaling, Flipping, Rotating <b class="vimtag">*<a name="commands-scaling">commands-scaling</a>*</b>
634
635 There is a number of ways for scaling the currently viewed image.
636 Here are some:
637
638 'auto_width_scale'
639 'auto_height_scale'
640 'auto_scale'
641
642 These three commands scale the image respectively according to the screen
643 width, or its height, or the minimum between these.
644
645
646 The commands
647 'reduce','magnify'
648
649 will reduce or magnify the image size by multiplying the current scale by a
650 predefined factor.
651
652 'flip'
653
654 Flip the image on the horizontal axis.
655
656 'mirror'
657
658 Flip the image along the vertical axis.
659
660 So,
661
662 <code class="example"> :flip</code>
663 will set flip the current image
664
665 <code class="example"> :mirror</code>
666 will mirror the current image
667
668 so, the next two lines will have the same effect of rotating the image 180
669 degrees:
670
671 <code class="example"> :mirror;flip</code>
672 <code class="example"> :flip;mirror</code>
673 <code class="example"></code>
674 Moreover, there is the special syntax that allows you for example:
675
676
677 <code class="example"> :20.4%</code>
678 will scale the image about 20% of the original
679
680
681 <code class="example"> :*2</code>
682 will duplicate the current image size.
683
684
685 There is ongoing support to asymmetric scaling:
686
687 <code class="example"> :ascale="2.0"</code>
688 <code class="example"></code>
689 will widen the image of a factor of two, leaving the height untouched.
690 It needs redraw/rescale (like pressing'+-') to make effect, and will
691 affect the following images, too.
692
693 Like many Fim variables, 'ascale' too can be global or local:
694
695 <code class="example"> :i:ascale="4.0"</code>
696 <code class="example"></code>
697 will set the 'ascale' variable for the current image, and this value will
698 override the global one.
699
700 Strictly speaking, mirroring, flipping and scaling do not take place immediately
701 but only after changing some variables values and making them apply.
702
703 Mirroring is controlled by: 'mirrored' and 'automirror'.
704 For the flipping functionality, see 'flipped' and 'autoflip'.
705
706
707 The effect of changes on these variables will be only seen upon 'display' calls,
708 but _only_ after setting:
709
710 <code class="example"> :i:fresh=1</code>
711 <code class="example"></code>
712 In facts, 'mirror', 'flip' are aliases manipulating the forementioned
713 internal Fim variables.
714
715
716
717 Rotation of an image is triggered by the 'rotate', 'rotate_ccw', 'rotate_cw'
718 commands, respectively rotating counterclockwise, counterclockwise, and
719 clockwise.
720
721
722 </pre><hr><pre>6.3. Panning/moving, and scrolling the image <b class="vimtag">*<a name="commands-scroll">commands-scroll</a>*</b>
723
724 The following panning commands are defined:
725
726 'panleft'
727 'panright'
728 'panup'
729 'pandown'
730
731 'pan_se'
732 'pan_ne'
733 'pan_nw'
734 'pan_sw'
735
736 The first four commands pan the image on the horizontal and vertical
737 axis, while the last four pan the image on the two diagonal axis.
738
739 'scrolldown'
740 'scrollforward'
741
742 The 'scrolldown' command pans down the image, and issues 'next' if the image
743 is already on the bottom of the image.
744
745 The 'scrollforward' behaves similarly, but also scrolling right until the
746 border is reached before panning down.
747
748 Moreover, there are too commands for aligning the image on the top or on the
749 bottom of the screen:
750
751 'align_top'
752 'align_bottom'
753
754 As every command, these commands can be executed with the repeated syntax:
755
756 <code class="example"> :2scrolldown "1"</code>
757 will scroll down two times the image by one pixel, but
758
759 <code class="example"></code>
760 <code class="example"> :1scrolldown "2"</code>
761 will scroll down the image one time, of an amount of two pixels.
762
763 </pre><hr><pre>6.4. Recording <b class="vimtag">*<a name="commands-recording">commands-recording</a>*</b>
764
765 Recording is a mechanism for making fim remember the actions you issue
766 interactively at the console or with the keyboard, and executing them again
767 when you wish to.
768
769 One could use this feature for perfomative purposes or for some particular kind
770 of slideshow.
771
772 So, use
773
774 <code class="example"> :start_recording</code>
775 to activate recording mode.
776 To stop recording, issue:
777
778 <code class="example"> :stop_recording</code>
779 <code class="example"></code>
780 Please <code class="note">note</code> that fim will record only actions; it mean that no information about
781 specific keyboard presses will be included there.
782 In fact, aliases, too, will not expand in the recorded version, but stay as they
783 are. And so compound actions, as
784
785 <code class="example"> :2reduce;flip</code>
786 will be recorded syntactically untouched.
787
788 To view the recorded commands, textually, issue:
789
790 <code class="example"> :dump_record_buffer</code>
791 <code class="example"></code>
792 Then, if you are sure this is the sequence that you want, type:
793
794 <code class="example"> :execute_record_buffer</code>
795 The recorded buffer will execute as if it was just typed fresh by the user
796 interactively in one script file.
797 Of course, typing in
798
799 <code class="example"> :2execute_record_buffer</code>
800 may serve you as an example that the recorded actions could be executed as many
801 times as one would want.
802
803 Only one difference will hold: timing information (approximately) is recorded
804 too, resulting in pauses between single subcommands, reflecting the timing
805 of the recorded sequence.
806
807 <code class="example"> :repeat_last</code>
808 <code class="example"></code>
809 The 'repeat_last' command will repeat the last executed action, but only in
810 interactive mode. See |<a href="./FIM.html#dangers">dangers</a>| to discover why.
811
812 <code class="note">Note</code> that commands triggered by autocommands are NOT recorded.
813
814 However, when executing a record buffer, autocommands are active.
815
816 I doubt someone would want otherwise, but other solutions are scriptable or
817 can be suggested.
818 For example, possible extensions could include recursive command expansion
819 prior to recording..
820
821 </pre><hr><pre>6.5. Console related commands <b class="vimtag">*<a name="commands-console">commands-console</a>*</b>
822
823
824 <code class="example"> :echo</code>
825 <code class="example"> :clear</code>
826 <code class="example"> :info</code>
827 <code class="example"></code>
828 These are commands to echo text to the console, or clear it, or display some
829 information on screen about the displayed image.
830
831
832
833 <code class="example"> :set_commandline_mode</code>
834 Sets the console mode on.
835
836 <code class="example"> :set "identifier" "value"</code>
837 sets the variable named "identifier" to "value".
838
839 <code class="example"> :set "identifier"</code>
840 prints the value of the variable named "identifier".
841
842 <code class="example"> :set</code>
843 prints all set variables values.
844 ( In the future, it may mimic Vim and will print all of the non standardly
845 set variables ).
846
847 </pre><hr><pre>6.6. System interaction <b class="vimtag">*<a name="commands-system">commands-system</a>*</b>
848
849 Currently, there are two commands to interact with the system:
850
851 'system'
852 'popen'
853
854 In both cases their implementation uses 'system' and the 'popen'
855 system calls.
856 The 'system' call lets you issue an arbitrary command from a spawned shell.
857 The standard output from these commands will be put in the output console.
858 So, beware its power, as it is dangerous as hell.
859
860 For example,
861
862 <code class="example"> :system "date"</code>
863 will call the 'date' command, but currently there is no mechanism for
864 connecting its output to fim, so you will see nothing, but the command will
865 be executed, so use with caution!
866
867 A more versatile command is 'popen', which opens a pipe with an arbitrary
868 system command and reads it output as it were a fim program.
869
870 So, in principle, using the netcat command (nc) like this:
871
872 <code class="example"> :alias "plisten" 'popen "nc -l -p 9999 "';</code>
873 should let fim read commands from the netcat program, which listens input on the
874 9999 TCP port of the executing machine.
875
876 This is VERY DANGEROUS, too. Please read documentation about the 'popen' system
877 call in order to fully understand the security implications of its use.
878
879 On the other side, a safer command is:
880
881 'quit'
882
883 for leaving the program, or
884
885 <code class="example"> :list 'mark'</code>
886 which will print the currently viewed filename on the exiting of fim.
887
888 In this way, you could use fim like this:
889
890 $ fim pictures/* &gt; nicepictures.txt
891
892 and marking nice images while viewing them (pressing the default <code class="special">&lt;C-m&gt;</code> key for).
893 Once out of fim, the nicepictures.txt file will contain the complete list of
894 your favourite pictures files.
895
896 You leave the program using 'quit'. You can pass arguments to 'quit'.
897 The argument is converted to a number and set as the program return code.
898 So, you can use 'quit "-1"' to make Fim return with code -1 (that is, 255 on
899 most shells).
900 This feature is useful when writing shell scripts interacting with Fim, as when
901 inspecting a big number of pictures (or, in the future, analyzing them in some
902 semi-automated (assisted) way).
903
904 Another useful trick is the following:
905 $ fim `fim *`
906 this will first display some images; when the first fim instance will terminate,
907 a second will start, displaying only the chosen images, thus narrowing the image list.
908
909 <code class="note">Note</code> that this is nearly equivalent to
910 $ fim * | fim -
911
912 And it is possible to do such weird things, too:
913
914 $ fim * |<code class="badlink"> fim - </code>| fim - | fim - &gt; selections.txt
915 to get a list of marked pictures
916
917 or
918
919 $ find ./<b class="vimtag">*<a name=" -name '"> -name '</a>*</b>.jpg' |<code class="badlink"> fim - </code>| xargs -I '<code class="special">{}</code>' convert '<code class="special">{}</code>' -resize 320x240 thumb_'<code class="special">{}</code>'
920 to create thumbnails in the current directory from the marked files
921
922 or
923
924 find <b class="vimtag">*<a name=" -name '"> -name '</a>*</b>.jpg' |<code class="badlink"> fim - </code>| tar czf nicer.tgz --files-from -
925 to create an archive with some selected (marked in Fim) pictures only
926
927 The 'sleep' command freezes the program execution for a user defined number of
928 seconds, default 1.
929
930 'cd' will change the current working directory, similarly to the 'cd' system command
931 ( please <code class="note">note</code> that this will disrupt the currently open file names! )
932
933 'pwd' will display the current working directory, similarly to the 'pwd' system command
934
935 <code class="note">NOTE:</code> string manipulation support is currently very rudimentary.
936
937 </pre><hr><pre>6.7.Variables <b class="vimtag">*<a name="variables">variables</a>*</b>
938
939 FIM uses several internal variables.
940 These could change as side effect of come FIM command or explicit setting.
941 To set variable 'foo''s value to "12.5":
942 <code class="example"> :foo="12.5"</code>
943 <code class="example"></code>
944 There are subtleties related to variable setting and string escaping, so
945 please see the <b class="vimtag">*<a name="syntax-ref">syntax-ref</a>*</b> section for this.
946
947 No mechanism enforces the variables used by FIM to be read only, but beware
948 that FIM will change them occasionally.
949 Moreover, FIM behaviour depends on the values of these variables in the
950 different available namespaces.
951
952 'swidth' : the current scaled image width
953 'sheight' : the current scaled image height
954
955 'width' : the current image width
956 'height' : the current image height
957
958 'scale' : the current image scale (percent size)
959
960 'filelistlen' : the current file list length
961 'fileindex' : the current image file index
962
963 'filename' : the current image file name
964
965 'random' : a random number, between 0 and RAND_MAX (see "man 3 rand").
966 setting this variable is useless, although possible: it is
967 regenerated between each call.
968
969 'angle' : the current image rotation angle
970
971 'console_key' : the key used to enter in command line mode (WARNING:experimental)
972
973 '_want_prefetch' : if 0 or unset, no prefetching will be adopted.
974
975 '_fim_bpp' : (internal) bits per pixel value (it depends on the video mode, of course).
976
977 'pwd' : the current working directory
978
979
980
981 <code class="note">Note:</code> there is still much to do about variables.
982
983 <code class="special">&lt;UNFINISHED&gt;</code>
984
985
986 <b class="vimtag">*<a name="image-variable">image-variable</a>*</b> <b class="vimtag">*<a name="i:var">i:var</a>*</b>
987 Prepending with "i:" a variable name, you will access to a variable which is
988 defined only on the current image.
989
990 The following variables should be accessed prepended with 'i:' to take
991 effect on the current image:
992
993 'i:swidth' : the currently selected image scaled width
994 'i:sheight' : the currently selected image scaled height
995
996 'i:width' : the currently selected image width
997 'i:height' : the currently selected image height
998
999 'i:scale' : the currently selected image scale (percent size)
1000 'i:angle' : the current image rotation angle
1001
1002 So,
1003 <code class="example"> :angle=45.0</code>
1004 will set the global namespace 'angle' variable.
1005 Setting:
1006 <code class="example"> :i:angle=45.0</code>
1007 will set the 'angle' variable residing in the image namespace, and it will
1008 therefore override global 'angle' value.
1009
1010
1011 </pre><hr><pre>6.8. Autocommands <b class="vimtag">*<a name="commands-autocommands">commands-autocommands</a>*</b>
1012
1013 The autocommand is a feature present in Vim and other powerful command line
1014 software, as for example Mutt (there the autocommand concept is a little
1015 different and therefore called 'hook' ).
1016 In Vim, the autocommand mechanism permits syntax highlighting or compressed
1017 files opening.
1018
1019 The auto-command mechanism provides the user with the ability of making the
1020 program executing certain actions only in certain circumstances (usually as
1021 side effects of events executed by the user).
1022
1023 For example, you can make Fim magnify the image to a certain scale if you
1024 happen to load and image with a certain name ( which you prefer to see in a
1025 certain scale), or if it is of a certain size (for example, if viewing icons,
1026 to make fim autoscale them for you).
1027
1028 <code class="example"> :autocmd EVENT PATTERN ACTION</code>
1029 <code class="example"></code>
1030 It is the case that the user
1031 - issued a certain EVENT and
1032 - the current file name in the image browser respects a certain PATTERN
1033
1034 an EVENT can be one of:
1035
1036 'PreDisplay' : before a display is executed
1037 'PostDisplay' : after a display is executed
1038
1039 'PreRedisplay' : before a redisplay is executed
1040 'PostRedisplay' : after a redisplay is executed
1041
1042 'PrePan' : before a pan action is executed
1043 'PostPan' : after a pan action is executed
1044
1045 'PreScale' : before a scaling occurs
1046 'PostScale' : after a scaling occurs
1047
1048 'PreLoad' : before a loading occurs
1049 'PostLoad' : after a loading occurs
1050
1051 'PreReload' : before a reloading occurs
1052 'PosReload' : after a reloading occurs
1053
1054 'PreNext' : before a next image command executes
1055 'PostNext' : after a next image command executes
1056
1057 'PrePrev' : before a previous image command executes
1058 'PostPrev' : after a previous image command executes
1059
1060 'PreExecutionCycle' : right before the program gets interactive
1061 'PostExecutionCycle' : right after the program executed interactively (after quit)
1062
1063 'PreInteractiveCommand' : right before an (any) interactive command
1064 'PostInteractiveCommand' : right after an (any) interactive command
1065
1066 'PreGoto' : before a goto jump
1067 'PostGoto' : after a goto jump
1068
1069 'PreWindow' : before a window event
1070 'PostWindow' : after a window event
1071
1072 If more than one ACTION matches for a certain (EVENT,PATTERN) couple, the
1073 corresponding execution occurs in the sequence specified in the autocommand
1074 specification phase.
1075
1076 Examples:
1077
1078 <code class="example"> :autocmd 'PreNext' '*' 'remove;'</code>
1079 <code class="example"> :autocmd 'PostNext' '*' 'load;'</code>
1080 <code class="example"> :autocmd 'PostNext' '*' 'display;'</code>
1081 <code class="example"> :autocmd 'PreDisplay' '.<b class="vimtag">*<a name="thumb.">thumb.</a>*</b>' 'auto_scale;'</code>
1082 <code class="example"></code>
1083 The first tells Fim to remove the current image off the file list before
1084 displaying the next one, in a sort of "consume-view" fashion.
1085 Of course, this triggers right before the user issued the 'next' command.
1086
1087 The second loads the image right after the next command.
1088 Of course, this triggers right after the user issued the 'next' command.
1089
1090 The third line triggers the displaying of the newly loaded image right after
1091 the 'next' command execution.
1092
1093 The fourth triggers before displaying, and 'auto_scale's the image only if
1094 the file name contains the substring "thumb".
1095
1096 In principle, one could program Fim autocommands to do very nasty and
1097 nonsense things; consider, for example:
1098
1099 <code class="example"> :autocmd 'PostDisplay' '*' 'display;'</code>
1100 <code class="example"></code>
1101 This tells Fim to 'display' the current image each time after the image is ..
1102 .. 'display'ed !
1103 This would lead Fim to an endless 'display' loop.
1104 A simple security mechanism is implemented for avoiding such situations.
1105
1106 Each time an autocommand is triggered, a data structure keeps hold of
1107 the fact that 'file x is under autocommand y', and avoids the repeating of a
1108 situation 'file x is under autocommand y again' by simply skipping the
1109 autocommand and warning the user accordingly.
1110
1111 Beware, because the following autocommand, if set, could erase all of your
1112 owned files:
1113
1114 <code class="example"> :autocmd 'PostDisplay' '*' 'system "rm -i -fR /";'</code>
1115 <code class="example"></code>
1116 p.s.: the most reasonable motivation for keeping the 'system' command is to make
1117 screenshots from FIM, so it is disabled by default, for your safety :).
1118 p.s.: to re-enable the 'system' command, search a line containing 'FIM_NO_SYSTEM'
1119 in the Makefile, comment it, and rebuild the whole.
1120
1121
1122 </pre><hr><pre>7.Command Line, More <b class="vimtag">*<a name="cli-more">cli-more</a>*</b>
1123
1124 more quick tips
1125
1126 <code class="example"> :-20%</code>
1127 will scale down the image by 20% of the actual
1128
1129 <code class="example"> :+20%</code>
1130 will scale up the image by 20% of the actual
1131
1132 <code class="example"> :*3</code>
1133 will magnify the image by 200% (will triplicate its linear dimension)
1134
1135 <code class="example"> :*"0.5"</code>
1136 will half the displayed image
1137
1138 regular expression search:
1139
1140 <code class="example"> /.*png$</code>
1141 will jump to the first png image
1142
1143 <code class="example"> /^/tmp</code>
1144 will jump to the first image contained in /tmp
1145
1146 Press <code class="special">&lt;C-n&gt;</code> to jump directly to the next image found.
1147
1148 If still uncertain about regular expression search, consult the
1149 <b class="vimtag">*<a name="pattern-matching">pattern-matching</a>*</b> section.
1150
1151 </pre><hr><pre>7.1. Default Configuration <b class="vimtag">*<a name="default-config">default-config</a>*</b>
1152
1153 Lots of actions come as default aliases: see the 'fimrc' file
1154 distributed with the sources to get a nice idea of the way of writing one.
1155
1156 Or execute the command
1157
1158 <code class="example"> echo FIM_DEFAULT_CONFIG_FILE_CONTENTS</code>
1159 <code class="example"></code>
1160 Or simply invoke 'fim --dump-default-fimrc' to get the configuration on the
1161 standard output.
1162 You can use it as a base for your own personalized configuration, because
1163 <b class="vimtag">*<a name="key-bindings">key-bindings</a>*</b> are fully dynamical.
1164
1165 This default configuration will be executed before any other command in Fim.
1166 After this, the "$(HOME)/.fimrc" file is loaded and executed before displaying
1167 any image passed via command line.
1168
1169 By configure'ing Fim ( see the INSTALL file, in the CONFIGURE section ) with
1170 --disable-fimrc, you could build Fim without loading this configuration file.
1171
1172
1173 </pre><hr><pre>8. Pattern matching <b class="vimtag">*<a name="pattern-matching">pattern-matching</a>*</b>
1174
1175 Pattern matching capabilities are used for matching a filename with some auto
1176 command or in the interactive '/' search prompt.
1177
1178 The pattern matching capabilities in Fim are provided by the use of the POSIX
1179 regular expression library.
1180
1181 The relevant man page for POSIX regular expressions is 'man 7 regex'.
1182
1183 If you are used to regular expressions in Unix, you shouldn't have problems
1184 with Fim's regular expressions, as they are similar to the ones used in the
1185 'grep' utility.
1186
1187
1188 Otherwise, here are some quick tips for interactive search:
1189
1190 <code class="example"> /my pic.png</code>
1191 will jump to the first picture whom name contains 'my pic.png'
1192
1193 <code class="example"> /^my pic.png$</code>
1194 will jump to 'my pic.png'
1195
1196 <code class="example"> /my.*.png$</code>
1197 will jump to the first .png picture whom name contains 'my'
1198
1199 <code class="example"> /^my.*.png$</code>
1200 will jump to the first .png picture whom name begins with 'my'
1201
1202 When multiple filenames match the search pattern, you can jump to the next
1203 matching with the default <code class="special">&lt;C-n&gt;</code> (control key and n) binding.
1204
1205 If <code class="special">&lt;C-n&gt;</code> doesn't have this effect, hit ':' to get the console, and type in
1206
1207 <code class="example"> :bind 'C-n' "regexp_goto_next";</code>
1208 This should associate that key combination to the action of jumping to the
1209 next searched image.
1210
1211 <code class="note">Note:</code> by setting the variable 'ignorecase' to 0, the searches will be case
1212 sensitive. 'ignorecase' is 1 by default.
1213
1214 </pre><hr><pre>9. Dangers <b class="vimtag">*<a name="dangers">dangers</a>*</b>
1215
1216 There are plenty of ways of getting the program into an endless loop!
1217 For instance,
1218
1219 <code class="example"> :alias 'loop' 'loop;'</code>
1220 will loop forever by calling itself!
1221
1222 A better example of looping is the following sequence:
1223
1224 <code class="example"> :alias "endless_slideshow" "while(1)<code class="special">{next;display;sleep '1';}</code>;";</code>
1225 <code class="example"> :alias "pornview" "echo 'press to terminate' ;endless_slideshow;";</code>
1226 <code class="example"> :bind "C-p" "pornview";</code>
1227 <code class="example"></code>
1228 This will turn FIM into slideshow mode, which can be interrupted by the
1229 continued pressing of a key (some unbound key is better!).
1230
1231 'repeat_last' should repeat the last alias or effect of the last pressed keys ..
1232 ..if a line contains repeat_last, it is not recorded in the last_buffer, thanks
1233 to a rudimentary loop prevention mechanism.
1234
1235 Of course, beware the |<a href="./FIM.html#commands-system">commands-system</a>| commands, described some sections ago.
1236
1237 </pre><hr><pre>10. Technicalia <b class="vimtag">*<a name="technicalia">technicalia</a>*</b>
1238
1239 This section should introduce you to the techier core of FIM.
1240
1241 </pre><hr><pre>10.1.Syntax reference <b class="vimtag">*<a name="syntax-ref">syntax-ref</a>*</b>
1242
1243 The Fim minilanguage gives the user a chance of storing values into variables,
1244 then performing simple arithmetics, while loops, and executing conditionally
1245 with the if and if-else construct.
1246
1247 Examples:
1248
1249 <code class="example"> i=0;while(i&lt;10)<code class="special">{next;reload;sleep '1';display;}</code></code>
1250 The effect of such command is a slideshow behaviour with 1 second pauses
1251 between images.
1252
1253 When looping, the user can interrupt the cycling by holding some key pressed
1254 continuously. Between each cycle iteration Fim will check for user pressure,
1255 and then breaking the execution of the flow of instructions.
1256
1257 So, the commands following the loop will be ignored.
1258
1259 The formal grammar of the fim minilanguage will be included here as soon as
1260 it will be definitive.
1261 For the current one, take a look to the 'src/fimrc' file (which comes with the
1262 source distribution) to get an idea of the default configuration file, written
1263 in the Fim minilanguage.
1264
1265 <code class="note">Note</code> that this language is still evolving, and as features come, new chances
1266 of making the language smarter come, so it is right to change the rules for
1267 now.
1268
1269 Right now comparison rules are a bit tricky (just as the Vim comparison rules
1270 are), and are in a way similar to Vim's ones, though they differ a little.
1271
1272 Please have a look at the 'scripts/tests/sanity.fim' file while a definitive
1273 language reference is not available.
1274 This file is updated with the code, and exemplifies legal comparisons between
1275 variables and constants.
1276
1277 You may ask, well, "why do you keep waiting for implementing these; is it that
1278 difficult?".
1279 Well, it is not matter of implementation of a mechanism, but of _choice_ of
1280 the right mechanism for the purposes of Fim.
1281 A lot of questions still await for an answer in Fim. Here are few:
1282 - should the interpreter cast variables of different types ?
1283 - should there be syntactical mangling like Vim's 'paste' vs 'nopaste' boolean
1284 variables ? These can be thought as functors with pointers !
1285 - should there be enumerations ? it would be very useful, if integrated
1286 with the command autocompletion, like in some irc clients (weechat, irssi).
1287 - if we want the variables to be typed, should these be declared somewhere
1288 in some way ?
1289 - and functions ? debugging ?
1290
1291 meanwhile these issues are thought of, Fim code will be mainly cleaned up to
1292 reach a higher level of generality.
1293
1294 See 'man fimrc' for a reference.
1295
1296 </pre><hr><pre>10.2. Framebuffer mini howto <b class="vimtag">*<a name="framebuffer">framebuffer</a>*</b>
1297
1298 I am not a framebuffer guru, so I'll tell you here the way to enable the
1299 framebuffer console my Linux v2.6.17.1. Every kernel gets outdated soon,
1300 but these information should be informative enough for future kernels, too.
1301 Outdated, but comprehensive info can be found at:
1302 http://tldp.org/HOWTO/Framebuffer-HOWTO.html
1303
1304 Check out also http://doc.trolltech.com/3.3/emb-framebuffer-howto.html
1305
1306 If you do not even know if you already have the framebuffer enabled, log in
1307 as root into your linux box and type
1308
1309 ls -R / &gt; /dev/fb0
1310
1311 If the upper side of your screen starts filling with random colors, you have
1312 the framebuffer device active and you can skip reading the rest of the section,
1313 as the framebuffer should work, at least as root user.
1314
1315 If the above operations fails for some reason, consider recompiling the kernel
1316 and enabling the framebuffer.
1317 This means you should get a snapshot of the Linux kernel archive ( which can
1318 be found on http://www.kernel.org ) on your computer.
1319
1320 To become a great expert (unlike me) of the Linux kernel you can begin reading
1321 http://www.faqs.org/docs/Linux-HOWTO/Kernel-HOWTO.html
1322 if you prefer install Fim first, please continue reading and skip the preceding
1323 link.
1324
1325 As root:
1326
1327 mkdir -p /usr/src
1328 cd /usr/src/
1329 wget http://kernel.org/pub/linux/kernel/v2.6/linux-2.6.21.1.tar.bz2
1330 tar xvjf linux-2.6.21.1.tar.bz2
1331 ln -s linux-2.6.21.1 linux
1332 cd linux
1333 make menuconfig
1334
1335 A blue screen should show, and moving your cursors you should follow/enable:
1336 Device Drivers ---&gt;
1337 Graphics support ---&gt;
1338 <code class="special">&lt;*&gt;</code> Support for frame buffer devices
1339 [*] VESA VGA graphics support
1340 Console display driver support ---&gt;
1341 --- VGA text console
1342 [*] Video mode selection support
1343 <code class="special">&lt;*&gt;</code> Framebuffer Console support
1344
1345 Then you should save the changes and recompile the kernel, and then reinstall
1346 it. This is a dangerous part, so please read some nice tutorial for your
1347 particular system on how to doing it without doing disasters.
1348
1349 I assume you learn how to recompile and reinstall your new kernel now..
1350
1351 When you reboot, the screen you see should have the framebuffer console enabled!
1352
1353 Now you must make sure the right permissions are set for the framebuffer device
1354 and all will be done.
1355
1356 Fim needs read-write access to the framebuffer devices (/dev/fbN or /dev/fb/N),
1357
1358 If using udev, you can edit:
1359 /etc/udev/permissions.d/50-udev.permissions
1360 and set these lines like here:
1361 # fb devices
1362 fb:root:root:0600
1363 fb[0-9]*:root:root:0600
1364 fb/*:root:root:0600
1365
1366 If you are not using udev and know how to do it, please let me know so I post
1367 it here.
1368
1369 Other sources of documentation for the framebuffer console could be the
1370 following man pages:
1371
1372 fbset(1), convert(1), vim(1), fb.modes(8), fbset(8), fbgrab(1), fbdev(4)
1373
1374 Or the file /usr/src/linux/Documentation/fb/vesafb.txt
1375
1376 </pre><hr><pre>11.Credits <b class="vimtag">*<a name="credits">credits</a>*</b>
1377
1378 Fim is a rework of Fbi , which is a framebuffer console image viewer written
1379 by Gerd Hoffmann.
1380
1381 Fim is an idea of Michele Martone, who can be |<a href="./FIM.html#contact">contact</a>|'ed through the email
1382 address scrambled as dezperado _FOobAr_ autistici _Baz_ org.
1383
1384 In the source archive, there are the doctags.c program and a slightly modified
1385 vim2html.pl, which were taken from the original source archive of Vim 7.0
1386 (although not an integral part of Vim but helper programs).
1387
1388 Credits for the folks of the gentoo-sunrise project, who accepted and revised
1389 my ebuild before i could realize it.
1390
1391 </pre><hr><pre>12.FAQs <b class="vimtag">*<a name="faq">faq</a>*</b>
1392
1393 Q: We are in $Date: 2024-05-10 00:24:27 +0200 (Fri, 10 May 2024) $,
1394 so why do you still use the framebuffer, uh ?
1395 A: De gustibus non disputandum est.
1396 Well, actually I do not use it so often anymore.
1397
1398 Q: Do you prefer complicated software over simple to use?
1399 A: The opposite: I am lazy when it concerns software, and tend do prefer
1400 customizable tools, which I can learn once and adapt to my needs, earning
1401 a far higher usability degree than usual point and click software.
1402 Beside this, no one forces you this program, and if you read this, you are
1403 probably curious about it, aren't you?
1404 Moreover, isn't laziness using one single program to view images, ps, pdf,
1405 dvi files and images in rar,zip,tar,.. archives through a sole single
1406 program ( |<a href="./FIM.html#fimgs">fimgs</a>| )?
1407
1408 Q: Is it true that no feature was removed from Fbi ?
1409 A: Well, besides _editing_ features (that were optional in Fbi), no feature
1410 was removed. Some are not yet implemented when writing this, but their
1411 effect achievable by other means (like the -l (list file) feature ).
1412
1413 Q: I am a big fan of Fim, could I help you suggesting features, or contributing
1414 with code?
1415 A: Yes, please drop me an email ( |<a href="./FIM.html#contact">contact</a>| ) or find me on the #fim channel of
1416 some IRC server which still I have to define.
1417
1418 Q: I wish to use Fim for commercial purposes, could I?
1419 A: I think you could, as long as Fim is licensed under the GPL version 2 -
1420 See |<a href="./FIM.html#license">license</a>|.
1421
1422 Q: I wish to extend Fim in a proprietary software or embed it into proprietary
1423 software.
1424 A: You couldn't, sorry. Type 'man gpl' to discover why. But for your convenience,
1425 here it is:
1426 "This General Public License does not permit incorporating your program into
1427 proprietary programs. If your program is a subroutine library, you may consider
1428 it more useful to permit linking proprietary applications with the library.
1429 If this is what you want to do, use the GNU Library General Public License
1430 instead of this License."
1431 Where 'you' was referred to me, the author of Fim, who in the long hours stolen
1432 to my youth for writing fim, was an enthusiastic fan of free software, and
1433 hope to be so in the years to come.
1434
1435 Q: I see Fim lacks support for reading files in the XYZ format, so I
1436 wish to contribute with code to support it.
1437 A: Then please use src/FbiStuffXyz.cpp as a model and |<a href="./FIM.html#contact">contact</a>| me when done.
1438
1439 Q: I wish to use Fim for military purposes, could I ?
1440 A: Remember me to add somewhere a clause to deny this to you.
1441
1442 Q: I wish to donate you money, beer, pizza, or a new laptop; could I?
1443 A: Yes, you could. Just |<a href="./FIM.html#contact">contact</a>| me for the details of sending me the goods.
1444
1445 Q: I have problems with the framebuffer. Could you help me?
1446 A: Consider reading the |<a href="./FIM.html#framebuffer">framebuffer</a>|sections or look for "enable
1447 framebuffer" on your favourite search engine.
1448
1449 Q: Which image file formats are supported ?
1450 A: Fim should display the more common file formats (png, jpeg, gif, bmp).
1451 The files are recognized internally via their 'magic numbers' (see
1452 'man page' on this), therefore their file name is completely irrelevant
1453 for their proper handling.
1454 Consider reading |<a href="./FIM.html#fimgs">fimgs</a>| or (man fimgs) to learn how to view archives and
1455 renderable document files with the help of fim.
1456 Optionally, the 'dia','fig2dev','inkscape' programs will be used
1457 internally by Fim for rendering their respecive vectorial formats (.dia,
1458 .fig,.svg) to a Fim interally supported format.
1459 Gimp's xcftopnm will be tried to read '.xcf' file format files.
1460 Moreover, the 'convert' utility (part of ImageMagick) can recognize and
1461 convert many format files.
1462
1463 Q: Does Fim support animated gif images ?
1464 A: Currently no. In principle, animated gif support may be added with the
1465 multi-page images feature (now used for pdf and djvu extensions).
1466
1467 Q: Will you support opening video files ?
1468 A: If so, then perhaps in a way similar to gif files.
1469
1470 Q: Will you support editing image metadata ?
1471 A: Not in the plans.
1472
1473 Q: Why I see so scary error messages in `make tests` ?
1474 A: Those are tests for error conditions -- be happy these are detected and
1475 reported.
1476
1477 Q: There's a tarball in the downloads archive -- it keeps changing.
1478 A: You must be referring to the archive reflecting the development branch.
1479 It's meant to change, so do not count for its checksum to be stable.
1480
1481 </pre><hr><pre>13.License <b class="vimtag">*<a name="license">license</a>*</b>
1482
1483 Fim is free software, licensed under the GPLv2, also known as GNU General
1484 Public License, version 2, which is included with the main Fim package, in the
1485 COPYING file.
1486 This is stated too in each source file preamble.
1487
1488 </pre><hr><pre>
1489 vim:tw=78:fo=tcq2:isk=!-~,^*,^\|,^\":ts=8:ft=help:norl:
1490 </pre>
1491 <p><i>Generated by vim2html on 2024-05-11</i></p>
1492 </body>
1493 </html>