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