README

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