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