README

   1 WebThing - A modular webkit browser
   2
   3 I. A HISTORICAL TREATISE ON WEB BROWSERS
   4
   5 =====
   6   |
   7   |
   8 ===== N THE BEGINNING the Web was void and without form.  Then came
   9 Mosaic, which was the first of the graphical web browsers.  Descended
  10 from Mosaic was Mozilla, oft known as Netscape, and their heretical
  11 offshoot Spyglass Mosaic.  Netscape grew in power to become the dominant
  12 browser, but Microsoft used Spyglass to create Internet Explorer, which
  13 later Netscape's thunder through underhanded means.  This would not be
  14 the last of Netscape, though.
  15
  16     The world entered a dark age as Internet Explorer's influence grew
  17 throughout the land.  But in a far away corner of the world, the legacy
  18 of Mozilla continued.  Dwarves toiled in the darkest caves re-tooling
  19 Mozilla to challenge Internet Explorer, and it was through them that it
  20 was reborn as Phoenix.  Er, Firebird.  Wait, no, Firefox.  Yes,
  21 definetly Firefox.  As Firefox began to strike back, others emerged from
  22 the shadows to help fight.
  23
  24     From the brightly colored fields of KDE came KHTML, which was
  25 transformed into WebKit by Apple's elves, and packaged into Safari by
  26 Apple's turtlenecked humans.  From the wild north of Norway came Opera,
  27 which had actually been around since 1996, but nobody noticed it was
  28 there even though it was small and quick and generally better than
  29 everything else at the time.  And from these a thousand fold have
  30 spawned:  Chrome, Midori, Shiira, Camino, Arora, Epiphany, iCab,
  31 K-Meleon, Galeon, and many, many others.
  32
  33
  34 II. AN INFORMAL INTRODUCTION TO WEBTHING
  35
  36 =====
  37   |
  38   |
  39 ===== T IS FROM the WebKit line that WebThing descends.  It is inspired
  40 largely by the Firefox add-on Vimperator, and the hyper-minimal WebKit
  41 browser uzbl.  WebThing's strength is that it is highly modular -- parts
  42 of WebThing can be swapped out for others, or removed entirely.
  43 WebThing is a browser for tinkerers and hackers, for people who want to
  44 be able to customize things to the limit, and for anyone who believes
  45 they could do it better themselves.
  46
  47
  48 III. ON THE PROCUREMENT, ASSEMBLAGE, AND EXECUTION OF WEBTHING
  49
  50 =====
  51   |
  52   |
  53   |  HE SOURCE FOR WebThing is currently only available from a git
  54 repository.  If you're reading this, you can probably figure out how to
  55 check out the code.
  56
  57     There is currently no support for compile-time configuration or
  58 installation.  I'm not a fan of automake, and the project's complexity
  59 currently doesn't merit such finaglery.
  60
  61     To compile WebThing, you will need:
  62
  63 * A C compiler (configuration of libsoup cannot yet be done from .NET)
  64 * Mono 2.0+ (the adventurous may find that .NET works fine, too)
  65 * GTK# 2.12 (though it may work with previous versions, I have not
  66   tested them)
  67 * WebKit# built on a recent WebKit-Gtk (I used 1.1.8)
  68   WebKit requires a lot of things on its own -- you'll have a fun
  69   adventure getting it compiled, I'm sure.
  70
  71     When you build WebKit#, you will have to copy webkit-sharp.dll into
  72 the same directory as WebThing.  It does not seem to link properly
  73 otherwise.  If anyone knows what's going on there, I'd be highly
  74 appreciative of a fix.
  75
  76     Once the dependencies are satisfied, type 'make', and some magic
  77 should happen to produce a WebThingMain.exe with a host of dll files.
  78 From there, you should be able to run the WebThing script and the
  79 browser will launch.  The default set of plugins creates a Vim-like
  80 browsing experience reminiscent of Vimperator (but not nearly as
  81 complete), or uzbl (but slightly less incomplete).
  82
  83
  84 IV. EXPLORING THE DARK DEPTHS OF WEBTHING
  85
  86 =====
  87   |
  88   |
  89   |  HE source is divided roughly into two sections, the WebThing core,
  90 and plugins.  It is my intent to keep the core as minimal as possible,
  91 implementing only the barest functionality.  The functionality that
  92 makes up the user experience should be added into plugins.  Also,
  93 plugins allow code to be separated into clean, easy-to-understand
  94 chunks.  Clean separation of code was a failing of the uzbl project that
  95 in large part inspired WebThing.
  96
  97 The core provides:
  98
  99 * A bare WebKit control
 100 * Simple tab functionality through a GtkNotebook widget
 101 * Option parsing
 102 * Plugin loading
 103 * Facilities for attaching widgets to points in the window
 104
 105 Here is the plugin set so far:
 106
 107 * DefaultPage
 108     Loads a page specified on the command line, or else a default page
 109 * LoadProgress
 110     Places a small widget in the upper right corner that shows page
 111     loading progress
 112 * FFNav
 113     Implements Firefox-like navigation keys (Alt-Left and Right,
 114     Backspace, Ctrl-T, Ctrl-Tab, and Ctrl-W)
 115 * Vimish
 116     Implements Vim-like navigation keys (HJKL) and a command bar that
 117     allows opening URLs and configuring state
 118
 119
 120 V. THE ARCHITECTURE OF PLUGINS, AND THEIR REQUIREMENTS
 121
 122  /~\
 123 |   |
 124 |---|
 125 |   | PLUGIN IS a subclass of WebThingPlugin, which defines two
 126 functions that may be of interest to the developer:
 127
 128 * Init(WebThing wt) - Called when WebThing is starting up, and passes a
 129   WebThing instance to the plugin
 130 * InitWebView(WebView wv) - Called when a new WebView is created, and
 131   passes a WebView instance to the plugin
 132
 133 The WebThing class contains everything that WebThing is.  Since the
 134 details are still very much in flux, I won't bother describing it just
 135 yet.  At this point I would recommend anyone against writing plugins
 136 until the plugin API stabilizes.  Comments, suggestions, and criticisms
 137 are welcome.
 138
 139
 140 VI. MEANS BY WHICH THE AUTHOR MAY BE CONTACTED
 141
 142 |    |
 143 |\  /|
 144 | \/ |
 145 |    | Y EMAIL ADDRESS is bytex64@bytex64.net.  I'm not yet ready to
 146 accept general patches, but patches for fixing bugs are welcome.
 147
 148     Have fun!