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_DOWNLOAD_DIR
 240         All downloads are automatically stored in this directory.
 241         Defaults to "/tmp".
 242
 243     LARIZA_FIFO_SUFFIX
 244         Cooperative instances are implemented using a named pipe in the
 245         file system. The name of this pipe usually is (at least on
 246         modern systems following XDG "standards"):
 247
 248             /var/run/user/$UID/lariza.fifo-$LARIZA_FIFO_SUFFIX
 249
 250         $UID is the id of your user. $LARIZA_FIFO_SUFFIX defaults to
 251         "main". If you change this variable, you can launch several
 252         independent cooperative instances of lariza.
 253
 254     LARIZA_HOME_URI
 255         This URI will be opened by pressing the appropriate hotkeys
 256         ("homepage" or "new window") and if no URIs are specified on the
 257         command line. Defaults to "about:blank".
 258
 259     LARIZA_USER_AGENT
 260         Lariza will identify itself with this string. Uses WebKit's
 261         default value if unset.
 262
 263     LARIZA_WEB_EXTENSIONS_DIR
 264         Sets the directory where WebKit will look for "web extensions".
 265         Defaults to "~/.local/share/lariza/web_extensions".
 266
 267     LARIZA_ZOOM
 268         Zoom level for WebKit viewports. Defaults to 1.0.
 269
 270
 271 =======================
 272 Keyword based searching
 273 =======================
 274
 275 In this file, you can configure keywords and the associated URIs:
 276
 277     ~/.config/lariza/keywordsearch
 278
 279 Each line has to look like this:
 280
 281     wi https://en.wikipedia.org/w/index.php?title=Special:Search&search=%s
 282
 283 "wi" is the keyword, so when opening "wi foo", lariza will search in
 284 Wikipedia. Note the "%s" at the end of the URI: This is where your
 285 search term will be placed.
 286
 287 Lines starting with "#" are ignored.
 288
 289
 290 ================
 291 Download manager
 292 ================
 293
 294 Open the download manager using the appropriate hotkey. A new window
 295 listing your downloads will appear. Clicking on an item will remove it
 296 from the list and -- if needed -- cancel the download.
 297
 298 There's no file manager integration (I don't use one), nor does lariza
 299 delete, overwrite or resume downloads. If a file already exists, it
 300 won't be touched. Instead, the new file name will have a suffix such as
 301 ".1", ".2", ".3" and so on.
 302
 303
 304 ======================
 305 Bundled web extensions
 306 ======================
 307
 308 On startup, WebKit checks ~/.local/share/lariza/web_extensions for any
 309 .so files. See this blog post for further information on these
 310 extensions:
 311
 312 http://blogs.igalia.com/carlosgc/2013/09/10/webkit2gtk-web-process-extensions/
 313
 314 lariza comes with the following extensions:
 315
 316     we_adblock.so
 317
 318         Generic adblock. Reads patterns from the following file:
 319
 320             ~/.config/lariza/adblock.black
 321
 322         Each line can contain a regular expression. These expressions
 323         match case-insensitive and partially, i.e. ".*foo.*" is the same
 324         as ".*FOO.*" and you can use anchors like "^https?://...".
 325
 326         Lines starting with "#" are ignored.
 327
 328 Those bundled web extensions are automatically compiled when you run
 329 make. To use them, though, make sure to copy them to the directory
 330 mentioned above.
 331
 332
 333 ====================
 334 WebKit local storage
 335 ====================
 336
 337 WebKit does create files in your $XDG_* directories, i.e. ~/.local/share
 338 or ~/.cache. It's up to you what you want to do with this junk. I remove
 339 it regularly when no WebKit browser is running. Another option would be
 340 to change the $XDG_* variables.
 341
 342 I have explicitly not turned off the local storage feature in WebKit
 343 because I don't know if this breaks web applications.
 344
 345
 346 ============
 347 Dependencies
 348 ============
 349
 350 lariza needs the following Arch Linux packages:
 351
 352     - gtk3
 353     - webkit2gtk (WebKit2 API for GTK+ 3)
 354
 355
 356 ==========
 357 Literature
 358 ==========
 359
 360 API references:
 361
 362     - http://webkitgtk.org/reference/webkit2gtk/stable/index.html
 363     - https://developer.gnome.org/gtk3/stable/index.html
 364     - https://developer.gnome.org/glib/stable/index.html
 365
 366 Regular expressions supported by GRegex, you can use these in your
 367 adblock patterns:
 368
 369     - https://developer.gnome.org/glib/stable/glib-regex-syntax.html