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