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