README

   1
   2                                ==========
   3                                  lariza
   4                                ==========
   5
   6
   7 A simple web browser using GTK+ 3, GLib and WebKit2GTK+.
   8
   9 Features:
  10
  11     - A WebKit2 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 download manager
  15     - Optimized hotkeys: Left hand on keyboard, right hand on mouse
  16     - Keyword based searching: Opening "wi foo" will search wikipedia
  17     - Global content zoom
  18     - Cooperative instances using FIFOs
  19     - Support for Flash and Java
  20     - Bundled web extensions:
  21         - Adblock
  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 + r
 112             Reload the current page.
 113
 114         Mod1 + d
 115             Open the download manager.
 116
 117         Mod1 + l
 118             Focus the location bar.
 119
 120         Mod1 + k
 121             Focus the location bar and set its text to "/", allowing you
 122             to easily initiate a search.
 123
 124         Mod1 + 2  or  Mod1 + n
 125             Repeat the last search (forward).
 126
 127         Mod1 + 3
 128             Repeat the last search (backward).
 129
 130         Escape
 131             Stop loading.
 132
 133         Middle mouse
 134             Open the link under the pointer in a new window.
 135
 136         Backward / forward (mouse keys 8 and 9)
 137             Does the obvious.
 138
 139         Mod1 + Scroll up  or  Ctrl + Scroll up
 140             Increase zoom level of the current page.
 141
 142         Mod1 + Scroll down  or  Ctrl + Scroll down
 143             Decrase zoom level of the current page.
 144
 145         Mod1 + Scroll horizontally  or  Ctrl + Scroll horizontally
 146             Reset zoom to $LARIZA_ZOOM.
 147
 148
 149     When the location bar is focused:
 150
 151         Mod1 + q
 152             Close the current window.
 153
 154         Mod1 + d
 155             Open the download manager.
 156
 157         Mod1 + r
 158             Reload the current page.
 159
 160         Mod1 + k
 161             Reset the content of the location bar to "/".
 162
 163         Escape
 164             Reset the content of the location bar to the current URI.
 165
 166         Return
 167             "Commit", i.e. begin searching, do a keyword based search or
 168             open the URI.
 169
 170
 171 Download manager
 172
 173     Mod1 + d
 174         Close the download manager (downloads are not aborted).
 175
 176
 177 ======================
 178 Command line arguments
 179 ======================
 180
 181 Usage:
 182
 183     lariza [OPTION]... [URI]...
 184
 185 In addition to the standard arguments of GTK+ 3, lariza knows about the
 186 following options:
 187
 188     -e <wid>
 189         Embeds the main window and all newly created windows in the
 190         window specified by <wid>. The download manager is always a
 191         "popup".
 192
 193     -C
 194         Disables cooperative instances.
 195
 196     -T
 197         Disables automatic launching of suckless' tabbed.
 198
 199 After these options there can be any number of URIs. If no URIs are
 200 given, $LARIZA_HOME_URI will be opened.
 201
 202
 203 =====================
 204 Environment variables
 205 =====================
 206
 207 In addition to the standard variables of GTK+ 3, lariza knows about the
 208 following environment variables:
 209
 210     LARIZA_ACCEPTED_LANGUAGE
 211         In HTTP requests, WebKit sets the "Accepted-Language" header to
 212         this value. Defaults to "en-US".
 213
 214     LARIZA_CRASH_AUTORELOAD_DELAY
 215         If/when the WebKit process crashes, lariza's main process will
 216         receive a signal and can act accordingly. The default value of
 217         this variable is "2", which means that lariza will wait two
 218         seconds and then reload each window/tab.
 219
 220         If you set $LARIZA_CRASH_AUTORELOAD_DELAY to zero or any
 221         negative value, then lariza will not automatically reload
 222         anything. Note, however, that you can still do this manually by
 223         pressing the "reload" hotkey for each window.
 224
 225     LARIZA_DOWNLOAD_DIR
 226         All downloads are automatically stored in this directory.
 227         Defaults to "/tmp".
 228
 229     LARIZA_FIFO_SUFFIX
 230         Cooperative instances are implemented using a named pipe in the
 231         file system. The name of this pipe usually is (at least on
 232         modern systems following XDG "standards"):
 233
 234             /var/run/user/$UID/lariza.fifo-$LARIZA_FIFO_SUFFIX
 235
 236         $UID is the id of your user. $LARIZA_FIFO_SUFFIX defaults to
 237         "main". If you change this variable, you can launch several
 238         independent cooperative instances of lariza.
 239
 240     LARIZA_HOME_URI
 241         This URI will be opened by pressing the appropriate hotkeys
 242         ("homepage" or "new window") and if no URIs are specified on the
 243         command line. Defaults to "about:blank".
 244
 245     LARIZA_USER_AGENT
 246         Lariza will identify itself with this string. Uses WebKit's
 247         default value if unset.
 248
 249     LARIZA_WEB_EXTENSIONS_DIR
 250         Sets the directory where WebKit will look for "web extensions".
 251         Defaults to "~/.local/share/lariza/web_extensions".
 252
 253     LARIZA_ZOOM
 254         Zoom level for WebKit viewports. Defaults to 1.0.
 255
 256
 257 =======================
 258 Keyword based searching
 259 =======================
 260
 261 In this file, you can configure keywords and the associated URIs:
 262
 263     ~/.config/lariza/keywordsearch
 264
 265 Each line has to look like this:
 266
 267     wi https://en.wikipedia.org/w/index.php?title=Special:Search&search=%s
 268
 269 "wi" is the keyword, so when opening "wi foo", lariza will search in
 270 Wikipedia. Note the "%s" at the end of the URI: This is where your
 271 search term will be placed.
 272
 273 Lines starting with "#" are ignored.
 274
 275
 276 ================
 277 Download manager
 278 ================
 279
 280 Open the download manager using the appropriate hotkey. A new window
 281 listing your downloads will appear. Clicking on an item will remove it
 282 from the list and -- if needed -- cancel the download.
 283
 284 There's no file manager integration (I don't use one), nor does lariza
 285 delete, overwrite or resume downloads. If a file already exists, it
 286 won't be touched. Instead, the new file name will have a suffix such as
 287 ".1", ".2", ".3" and so on.
 288
 289
 290 ======================
 291 Bundled web extensions
 292 ======================
 293
 294 On startup, WebKit checks ~/.local/share/lariza/web_extensions for any
 295 .so files. See this blog post for further information on these
 296 extensions:
 297
 298 http://blogs.igalia.com/carlosgc/2013/09/10/webkit2gtk-web-process-extensions/
 299
 300 lariza comes with the following extensions:
 301
 302     we_adblock.so
 303
 304         Generic adblock. Reads patterns from the following file:
 305
 306             ~/.config/lariza/adblock.black
 307
 308         Each line can contain a regular expression. These expressions
 309         match case-insensitive and partially, i.e. ".*foo.*" is the same
 310         as ".*FOO.*" and you can use anchors like "^https?://...".
 311
 312         Lines starting with "#" are ignored.
 313
 314 Those bundled web extensions are automatically compiled when you run
 315 make. To use them, though, make sure to copy them to the directory
 316 mentioned above.
 317
 318
 319 ====================
 320 WebKit local storage
 321 ====================
 322
 323 WebKit does create files in your $XDG_* directories, i.e. ~/.local/share
 324 or ~/.cache. It's up to you what you want to do with this junk. I remove
 325 it regularly when no WebKit browser is running. Another option would be
 326 to change the $XDG_* variables.
 327
 328 I have explicitly not turned off the local storage feature in WebKit
 329 because I don't know if this breaks web applications.
 330
 331
 332 ============
 333 Dependencies
 334 ============
 335
 336 lariza needs the following Arch Linux packages:
 337
 338     - gtk3
 339     - webkit2gtk (WebKit2 API for GTK+ 3)
 340
 341
 342 ==========
 343 Literature
 344 ==========
 345
 346 API references:
 347
 348     - http://webkitgtk.org/reference/webkit2gtk/stable/index.html
 349     - https://developer.gnome.org/gtk3/stable/index.html
 350     - https://developer.gnome.org/glib/stable/index.html
 351
 352 Regular expressions supported by GRegex, you can use these in your
 353 adblock patterns:
 354
 355     - https://developer.gnome.org/glib/stable/glib-regex-syntax.html