README

   1
   2                                ==========
   3                                  lariza
   4                                ==========
   5
   6
   7 A simple web browser using GTK+ 2, GLib and WebKitGTK+.
   8
   9 Features:
  10
  11     - A WebKit viewport
  12     - An input box to change the URI or to search the current page
  13     - Built-in launching of suckless' tabbed
  14     - Built-in adblock
  15     - Built-in download manager
  16     - Optimized hotkeys: Left hand on keyboard, right hand on mouse
  17     - Keyword based searching: Opening "wi foo" will search wikipedia
  18     - Global content zoom
  19     - View source mode
  20     - Cooperative instances using FIFOs
  21     - Support for Flash and Java
  22
  23
  24 ==============
  25 About the name
  26 ==============
  27
  28 "lariza" stems from a german sentence:
  29
  30     Alle anderen waren mir zu anstrengend.
  31      l   a         r    i  z  a
  32
  33 That phrase basically means: "It was too tiresome to deal with any other
  34 browser." I couldn't find a simple browser that does just what I need.
  35 Most of them are utterly bloated, others lack essential functions. Thus,
  36 I was forced to write scripts and tools and stuff to deal with these
  37 issues. That is what was tiresome. I don't want to work around bugs or
  38 nonsensical behavior anymore.
  39
  40 So, I wrote my own browser^W WebKit GUI. WebKit does all the dirty work.
  41
  42
  43 ================================
  44 What lariza is and what it's not
  45 ================================
  46
  47 lariza does what I need. It won't do other things. I'm open for pull
  48 requests but please don't be upset if I turn them down -- which might
  49 happen if it's a feature that I simply don't need.
  50
  51 Especially, it's very likely that lariza will never have a "follow
  52 mode" like dwb, luakit or others have. I've used these browsers for
  53 quite some time and I've also used Firefox extensions that add a "follow
  54 mode". The point is, "follow mode" doesn't work anymore. This was a good
  55 thing ten years ago. Today, a lot of websites make heavy use of
  56 JavaScript or hovering. You NEED some kind of pointing device. I found
  57 using "follow mode" to be very frustrating today, because you still have
  58 to reach for the mouse all the time. So, you might as well just optimize
  59 your mousing workflow.
  60
  61 lariza does not compete with powerful browsers like dwb or luakit, nor
  62 with monstrous applications like Firefox or Chromium. lariza won't have
  63 persistent storage, nor a plugin system, nor cloud sync, nor bookmarks.
  64
  65 lariza tries not to exceed 1000 lines of code.
  66
  67 That being said, this kind of minimalism is not for everyone. If you're
  68 looking for more features (and a more open feature policy), then you
  69 might want to check out okraits' fork:
  70
  71     https://github.com/okraits/lariza/
  72
  73
  74 ========================
  75 Using lariza with tabbed
  76 ========================
  77
  78 By default, lariza automatically launches an instance of suckless'
  79 tabbed.
  80
  81 You can turn this feature off (see command line arguments) or you can
  82 specify a command line argument to embed lariza in an arbitrary
  83 container (XEMBED). Note that lariza will also automatically embed new
  84 windows in the same container.
  85
  86 When using the automatically launched tabbed instance, you can't use
  87 tabbed's Ctrl + Shift + Return hotkey. This is because tabbed is
  88 launched with "-d", so it knows nothing about lariza. However, lariza
  89 provides its own hotkey to launch a new window which will be embedded in
  90 the same instance of tabbed.
  91
  92
  93 =======
  94 Hotkeys
  95 =======
  96
  97 Main windows
  98
  99     When the WebKit viewport is focused:
 100
 101         Mod1 + q
 102             Close the current window.
 103
 104         Mod1 + w
 105             Go to your "homepage". See the environment variable
 106             $LARIZA_HOME_URI.
 107
 108         Mod1 + e
 109             Open a new window.
 110
 111         Mod1 + s
 112             Toggles "view source mode". This will display the web pages
 113             source code. Note that the page will be reloaded (which is
 114             annoying but WebKit enforces this).
 115
 116         Mod1 + r
 117             Reload the current page.
 118
 119         Mod1 + d
 120             Open the download manager.
 121
 122         Mod1 + l
 123             Focus the location bar.
 124
 125         Mod1 + k
 126             Focus the location bar and set its text to "/", allowing you
 127             to easily initiate a search.
 128
 129         Mod1 + 2  or  Mod1 + n
 130             Repeat the last search (forward).
 131
 132         Mod1 + 3
 133             Repeat the last search (backward).
 134
 135         Escape
 136             Stop loading.
 137
 138         Middle mouse
 139             Open the link under the pointer in a new window.
 140
 141         Backward / forward (mouse keys 8 and 9)
 142             Does the obvious.
 143
 144         Mod1 + Wheel up  or  Ctrl + Wheel up
 145             Increase zoom level of the current page.
 146
 147         Mod1 + Wheel down  or  Ctrl + Wheel down
 148             Decrase zoom level of the current page.
 149
 150
 151     When the location bar is focused:
 152
 153         Mod1 + q
 154             Close the current window.
 155
 156         Mod1 + d
 157             Open the download manager.
 158
 159         Mod1 + r
 160             Reload the current page.
 161
 162         Mod1 + k
 163             Reset the content of the location bar to "/".
 164
 165         Escape
 166             Reset the content of the location bar to the current URI.
 167
 168         Return
 169             "Commit", i.e. begin searching, do a keyword based search or
 170             open the URI.
 171
 172
 173 Download manager
 174
 175     Mod1 + d
 176         Close the download manager (downloads are not aborted).
 177
 178
 179 ======================
 180 Command line arguments
 181 ======================
 182
 183 Usage:
 184
 185     lariza [OPTION]... [URI]...
 186
 187 In addition to the standard arguments of GTK+ 2, lariza knows about the
 188 following options:
 189
 190     -e <wid>
 191         Embeds the main window and all newly created windows in the
 192         window specified by <wid>. The download manager is always a
 193         "popup".
 194
 195     -r
 196         Print all navigation requests on STDERR.
 197
 198     -C
 199         Disables cooperative instances.
 200
 201     -T
 202         Disables automatic launching of suckless' tabbed.
 203
 204 After these options there can be any number of URIs. If no URIs are
 205 given, $LARIZA_HOME_URI will be opened.
 206
 207
 208 =====================
 209 Environment variables
 210 =====================
 211
 212 In addition to the standard variables of GTK+ 2, lariza knows about the
 213 following environment variables:
 214
 215     LARIZA_ACCEPTED_LANGUAGE
 216         In HTTP requests, WebKit sets the "Accepted-Language" header to
 217         this value. Defaults to "en-US".
 218
 219     LARIZA_DOWNLOAD_DIR
 220         All downloads are automatically stored in this directory.
 221         Defaults to "/tmp".
 222
 223     LARIZA_FIFO_SUFFIX
 224         Cooperative instances are implemented using a named pipe in the
 225         file system. The name of this pipe usually is (at least on
 226         modern systems following XDG "standards"):
 227
 228             /var/run/user/$UID/lariza.fifo-$LARIZA_FIFO_SUFFIX
 229
 230         $UID is the id of your user. $LARIZA_FIFO_SUFFIX defaults to
 231         "main". If you change this variable, you can launch several
 232         independent cooperative instances of lariza.
 233
 234     LARIZA_HOME_URI
 235         This URI will be opened by pressing the appropriate hotkeys
 236         ("homepage" or "new window") and if no URIs are specified on the
 237         command line. Defaults to "about:blank".
 238
 239     LARIZA_USER_AGENT
 240         Lariza will identify itself with this string. See source code
 241         for the default value.
 242
 243     LARIZA_ZOOM
 244         Zoom level for WebKit viewports. Defaults to 1.0.
 245
 246
 247 =======
 248 Adblock
 249 =======
 250
 251 lariza has built-in adblock functionality. In each line of
 252
 253     ~/.config/lariza/adblock.black
 254
 255 you can store a regular expression. These expressions match
 256 case-insensitive and partially, i.e. ".*foo.*" is the same as ".*FOO.*"
 257 and you can use anchors like "^https?://...".
 258
 259 Lines starting with "#" are ignored.
 260
 261
 262 =======================
 263 Keyword based searching
 264 =======================
 265
 266 In this file, you can configure keywords and the associated URIs:
 267
 268     ~/.config/lariza/keywordsearch
 269
 270 Each line has to look like this:
 271
 272     wi https://en.wikipedia.org/w/index.php?title=Special:Search&search=%s
 273
 274 "wi" is the keyword, so when opening "wi foo", lariza will search in
 275 Wikipedia. Note the "%s" at the end of the URI: This is where your
 276 search term will be placed.
 277
 278 Lines starting with "#" are ignored.
 279
 280
 281 ================
 282 Download manager
 283 ================
 284
 285 Open the download manager using the appropriate hotkey. A new window
 286 listing your downloads will appear. Clicking on an item will remove it
 287 from the list and -- if needed -- cancel the download.
 288
 289 There's no file manager integration (I don't use one), nor does lariza
 290 delete, overwrite or resume downloads. If a file already exists, it
 291 won't be touched. Instead, the new file name will have a suffix such as
 292 ".1", ".2", ".3" and so on.
 293
 294
 295 ====================
 296 WebKit local storage
 297 ====================
 298
 299 WebKit does create files in your $XDG_* directories, i.e. ~/.local/share
 300 or ~/.cache. It's up to you what you want to do with this junk. I remove
 301 it regularly when no WebKit browser is running. Another option would be
 302 to change the $XDG_* variables.
 303
 304 I have explicitly not turned off the local storage feature in WebKit
 305 because I don't know if this breaks web applications.
 306
 307
 308 ============
 309 Dependencies
 310 ============
 311
 312 lariza needs the following Arch Linux packages:
 313
 314     - gtk2
 315     - webkitgtk2
 316
 317
 318 ==========
 319 Literature
 320 ==========
 321
 322 API references:
 323
 324     - http://webkitgtk.org/reference/webkitgtk/stable/index.html
 325     - https://developer.gnome.org/gtk2/stable/index.html
 326     - https://developer.gnome.org/glib/stable/index.html
 327
 328 Regular expressions supported by GRegex, you can use these in your
 329 adblock patterns:
 330
 331     - https://developer.gnome.org/glib/stable/glib-regex-syntax.html