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