Merge branch 'master' of ssh://svjatoslav.eu:10006/home/n0/git/instantlauncher
[instantlauncher.git] / doc / index.org
1 #+TITLE: Instantlauncher - navigate to your files and programs quickly!
2
3 * (document settings) :noexport:
4 ** use dark style for TWBS-HTML exporter
5 #+HTML_HEAD: <link href="https://bootswatch.com/3/darkly/bootstrap.min.css" rel="stylesheet">
6 #+HTML_HEAD: <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/1.11.3/jquery.min.js"></script>
7 #+HTML_HEAD: <script src="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.5/js/bootstrap.min.js"></script>
8 #+HTML_HEAD: <style type="text/css">
9 #+HTML_HEAD:   footer {background-color: #111 !important;}
10 #+HTML_HEAD:   pre {background-color: #111; color: #ccc;}
11 #+HTML_HEAD: </style>
12
13 * General
14 - This program is free software: you can redistribute it and/or modify
15   it under the terms of the [[https://www.gnu.org/licenses/lgpl.html][GNU Lesser General Public License]] as
16   published by the Free Software Foundation, either version 3 of the
17   License, or (at your option) any later version.
18
19 - Program author:
20   - Svjatoslav Agejenko
21   - Homepage: http://svjatoslav.eu
22   - Email: mailto://svjatoslav@svjatoslav.eu
23
24 - [[http://www.svjatoslav.eu/projects/][Other software projects hosted at svjatoslav.eu]]
25
26 ** Source code
27 - [[http://www2.svjatoslav.eu/gitweb/?p=instantlauncher.git;a=snapshot;h=HEAD;sf=tgz][Download latest snapshot in TAR GZ format]]
28
29 - [[http://www2.svjatoslav.eu/gitweb/?p=instantlauncher.git;a=summary][Browse Git repository online]]
30
31 - Clone Git repository using command:
32   : git clone http://www2.svjatoslav.eu/git/instantlauncher.git
33
34 * Purpose
35 Quick filesystem based document/application launcher. It starts by
36 showing content of [[id:5ced6bf5-165a-49a0-8de4-3755d810d987][predefined directory]]. Sub directories can be chosen
37 by simply moving mouse pointer over corresponding directory.
38
39 [[file:screenshot.png]]
40
41 Files types are color-coded.
42
43 * Usage
44 Simply hovering mouse pointer over directory expands its contents in
45 the next right column.
46
47
48 + Executable file (red):
49   + Left mouse click:
50     + Run executable file.
51   + Right mouse click:
52     + Toggle executable state.
53
54 + Non-executable file (green):
55   + Left mouse click:
56     + Open file using corresponding application.
57   + Right mouse click:
58     + Toggle executable state.
59
60 + Directory/symlink (blue):
61   + Left mouse click:
62     + Open directory using configured filesystem browser.
63   + Right mouse click:
64     + Open directory using configured text based terminal emulator.
65
66 * Configuration
67 When instantlauncher starts, it looks for configuration file under
68 : ~/.instantlauncher
69
70 If file is not found, it creates new default configuration file in
71 YAML format:
72 #+BEGIN_SRC
73 !configuration
74 directoryOpenCommand: nautilus -w {file}
75 directoryTerminalOpenCommand: gnome-terminal --working-directory={file}
76 fileAssociations:
77 -  command: vlc {file}
78    fileRegex: .*\.mkv$
79 -  command: emacs {file}
80    fileRegex: .*\.txt$
81 -  command: eog {file}
82    fileRegex: .*\.jpeg$
83 -  command: eog {file}
84    fileRegex: .*\.png$
85 -  command: vlc {file}
86    fileRegex: .*\.avi$
87 -  command: vlc {file}
88    fileRegex: .*\.mp4$
89 -  command: eog {file}
90    fileRegex: .*\.jpg$
91 -  command: emacs {file}
92    fileRegex: .*\.org$
93 navigationRootPath: /home/svjatoslav/
94 #+END_SRC
95
96 ** directoryOpenCommand
97 Command to use when opening directory.
98
99 By default instantlauncher assumes that Gnome desktop environment is
100 installed and uses Nautilus file manager:
101 : directoryOpenCommand: nautilus -w {file}
102 ** directoryTerminalOpenCommand
103 Command to use when opening directory in text terminal based console.
104
105 By default instantlauncher assumes that Gnome desktop environment is
106 installed and uses Gnome Terminal:
107
108 : directoryTerminalOpenCommand: gnome-terminal --working-directory={file}
109 ** fileAssociations
110 Allows to map file name/extension using regular expression pattern
111 matching to corresponding application.
112
113 Example:
114 #+BEGIN_SRC conf
115 -  command: vlc {file}
116    fileRegex: .*\.mkv$
117 #+END_SRC
118
119 Where:
120 - command :: Command to execute to open given file. Special variable
121              {file} will point to user chosen file using absolute file
122              path.
123
124 - fileRegex :: Regular expression that must match the file.
125 ** navigationRootPath
126     :PROPERTIES:
127     :ID:       5ced6bf5-165a-49a0-8de4-3755d810d987
128     :END:
129 Root directory from where to start navigation.
130
131 This parameter is user specific! In my case instantlauncher by default
132 pointed this to my home directory. But it can be any directory user
133 chooses.
134
135 I think good use-case is to create special directory to be used for
136 instantlauncher root. This special root directory can in turn contain
137 symlinks to various places user wants to visit often. Instantlauncher
138 will follow symlinks as if they were directories.
139
140 : navigationRootPath: /home/svjatoslav/