update readme, faq and installation instructions for the new stuff

3 files changed, 86 insertions, 156 deletions

diff --git a/README b/README
index b73978d..f4c53db 100644
--- a/README
+++ b/README
@@ -1,55 +1,43 @@
-### THIS PROJECT IS NOT FOR:
-* people want a browser that does everything
-* people who want a browser with things like a built-in bookmark manager, address bar, forward/back buttons, ...
-* people who expect something that works by default.  You'll need to read configs and write/edit scripts
-* people who like nothing from this list: mpd, moc, wmii, dwm, awesome, xmonad, mutt, pine, vim, dmenu, screen, irssi, weechat, bitlbee
-
-### TO NEW PEOPLE:
-* invoke uzbl-browser --help
-* to get you started: `XDG_DATA_HOME=/usr/share/uzbl/examples/data XDG_CONFIG_HOME=/usr/share/uzbl/examples/config uzbl-browser --uri www.archlinux.org`
-* alternatively, copy the above data to your real `$XDG_DATA_HOME` and `$XDG_CONFIG_HOME` directories
-* try and study the sample config, read the readme to find out how it works.
-* You can change the url with commands (if you have setup the appropriate keybinds) but to be most effective it's better to do url editing/changing _outside_ of uzbl-browser.
-  Eg, you can use the `load_from_*` dmenu based scripts to pick/edit a url or type a new one.
-* If you have questions, you are likely to find answers in the FAQ or in the other documentation.
-* documentation is in /usr/share/uzbl/docs
-
-
 ### INTRODUCTION
   Any program can only be really useful if it complies to the unix philosophy.
-  Web browsers are frequent violators of this principle:
+  Web browsers (and other tools that work with html, such as feedreaders) are frequent violators of this principle:
 
-* They build in way too much things into the browser, dramatically decreasing the options to do things the way you want.
+* They build in way too much things into one (complex) program, dramatically decreasing the options to do things the way you want.
 * They store things in way too fancy formats (xml, rdf, sqlite, ... ) which are hard to store under version control, reuse in other scripts, ...
 
-Time to change that!
-
-  Here are the general ideas (not all of these are implemented perfectly yet):
-
-* each instance of uzbl renders 1 page (eg it's a small wrapper around webkit), no tabbing, tab previews, or speed dial things.
-  For "multiple instances management" use your window managers, scripts or wrappers.
-* very simple, plaintext , changeable at runtime configuration
-* various interfaces for (programmatic) interaction with uzbl (see below)
-* customizable keyboard shortcuts in vim or emacs style (whatever user wants)
-* "outsource" logic that is not browsing to external scripts under the users control:
-    - managing bookmarks
-    - loading a url from bookmarks, history,..  Editing the curent url
-    - control cookies
-    - handling of downloads, history logging, etc.
-    - management of cache.
-    - password management
-    - Leverage the power of utilities such as grep, awk, dmenu, zenity, wget, gnupg (password file) etc.
-* listen to signals and do useful stuff when triggered.
-* no ad blocking built in.
-  Alternatives:
-    - privoxy looks cool and perfectly demonstrates the unix philosphy.
-    - same for http://bfilter.sourceforge.net
-    - /etc/hosts (not very good cause you need root and it affects the whole system)
-      one can list all images on a page using the socket, so you can easily pick the links to ads to add them to your /etc/hosts.
-* vimperator/konqueror-like hyperlink following.
-* password management. maybe an encrypted store that unlocks with an ssh key?
-* no messing in the users $HOME or in /etc: no writing of anything unless the user (or sysadmin) asks for it.
-  We recommend using XDG basedir spec for separation of config, data and cache. and state should be a subdir in the config dir (not part of the spec yet) too.
+The uzbl project was started as an attempt to resolve this.
+
+### EDITIONS
+
+"Uzbl" is an umbrella-project consisting of different flavors.
+In the future more things may come, but for now:
+
+#### uzbl-core: main component meant for integration with other tools and scripts
+
+ * Uses WebkitGtk+ for rendering, network interaction (libsoup).  Css, javascript, plugin support etc come for free
+ * Provides interfaces to get data in (commands/configuration) and out (events): stdin/stdout/fifo/unix sockets    
+ * You see a webkit view and (optionally) a statusbar which gets popuplated externally       
+ * No built-in means for url changing, loading/saving of bookmarks, saving history, keybinds, downloads, ...
+ * Extra functionality: many sample scripts come with it, on <a href="http://www.uzbl.org/wiki/scripts">uzbl wiki</a> or write them yourself
+ * Entire configuration/state can be changed at runtime
+ * Uzbl keeps it simple, and puts <strong>you</strong> in charge.
+
+#### uzbl-browser: a complete browser experience based on uzbl-core
+
+ * Uses a set of scripts (mostly python) that will fit most people, so things work out of the box.  Yet plenty of room for customisation
+ * Brings everything you expect: url changing, history, downloads, form filling, link navigation, cookies, event management etc
+ * Advanced, customizable keyboard interface with support for modes, modkeys, multichars, variables (keywords) etc. (eg you can tweak the interface to be vim-like, emacs-like or any-other-program-like)
+ * Adequate default configuration      
+ * Focus on plaintext storage for your data and configs in simple, parseable formats and adherence to the xdg basedir spec
+ * Visually, similar to uzbl-core except that the statusbar contains useful things.  One window per webpage  
+
+#### uzbl-tabbed: wraps around uzbl-browser and multiplexes it
+
+ * Spawns one window containing multiple tabs, each tab containing a full embedded uzbl-browser
+ * Ideal as a quick and simple solution to manage multiple uzbl-browser instances without getting lost
+
+
+Throughout the documentation, when referring to `uzbl` we mean uzbl-core, unless otherwise specified.
 
 
 ### CONFIGURATION / CONTROL:
@@ -80,8 +68,19 @@ There are several interfaces to interact with uzbl:
 When uzbl forks a new instance (eg "open in new window") it will use the same commandline arguments (eg the same --config <file>), except --uri and--name.
 If you made changes to the configuration at runtime, these are not pased on to the child.
 
+
+#### Uzbl-browser
+- default config
+- EM
+- EM plugins
+- bindings/events/requests
+
+#### Uzbl-tabbed
+- also has some own keybindings
+
+
 ### COMMAND SYNTAX
-Uzbl-browser will read commands via standard input, named fifo pipe (if `fifo_dir` is set) and IPC socket (when `socket_dir` is set).
+Uzbl will read commands via standard input, named fifo pipe (if `fifo_dir` is set) and IPC socket (when `socket_dir` is set).
 For convenience, uzbl can also be instructed to read commands from a file on startup by using the `-c` option.  Indeed, the config file is nothing more than a list of commands.
 
 Each command starts with the name of the command or an uzbl variable that expands to it.  A command is terminated by a newline.
@@ -95,7 +94,7 @@ The following commands are recognized:
    - if you want to unset a string, use `set` with one space after the equals sign
 * `print @<key>`
    - use this to print the value of a variable.
-* `bind <string> = <command>`
+* `bind <string> = <command>` OUTDATED !!!
    - sets the character sequence `<string>` to invoke `<command>` when typed interactively in uzbl
    - there are a few tricks you can do:
        * `<string>` ends with an underscore: the command will only be invoked after pressing return/enter. If the user enters text where `<string>` has the underscore, `%s` in the `<command>` string will be replaced by this text. (optional)
@@ -130,7 +129,7 @@ The following commands are recognized:
 * `script <file>`
    - execute the javascript in `<file>`
 * `toggle_status`
-* `spawn <executable> <additonal args>`
+* `spawn <executable> <additonal args>` TODO explain path-alike expansion
    - runs a command; see EXTERNAL SCRIPTS for details
    - PATH is searched so giving the full path to commands is not neccessary
    - note that the arguments as specified in "EXTERNAL SCRIPTS" are appended at the end, so the argument numbers will be higher.
diff --git a/docs/FAQ b/docs/FAQ
index b5c4dcc..f6a1a21 100644
--- a/docs/FAQ
+++ b/docs/FAQ
@@ -2,60 +2,24 @@ FAQ
 ---
 
 ### I just installed uzbl but it doesn't do much.  What now?
-Uzbl includes very limited default settings (statusbar settings, but no keybinds, history/download handlers etc.)
-Look at /usr/share/uzbl/docs/config.h to see the default settings.
-Have a look in /usr/share/uzbl/examples/configs to see what you can do.
-
-If you save a config as $XDG\_CONFIG\_HOME/uzbl/config it will be loaded automatically.
-Running with the `--verbose` flag on a command line can also be interesting.
-To get you started, try this:
-`XDG_DATA_HOME=/usr/share/uzbl/examples/data XDG_CONFIG_HOME=/usr/share/uzbl/examples/config uzbl`
-It will temporarily override your $XDG\_CONFIG\_HOME and $XDG\_DATA\_HOME
-variables so you can try the sample stuff directly in /usr/share/uzbl/examples.
-If you like what you can do, you can copy the sample stuff into your ~ and edit to your liking.
-
-### Why don't you just use a reasonable config by default?
-We actually did some attempts to make uzbl "usable by default" but in the
-end we had to conclude it cannot be done because of the following reasons:
-
- * We don't want to store anything "automagically" in the users home.
-   Some people prefer different file/directory layouts, most of just want to
-   control the files in $HOME themselves.
- * We considered the option of having a global '/etc/uzbl' which user
-   specific ones could override but that would overcomplicate things.
- * We adhere to the [FHS](http://www.pathname.com/fhs/) (`man hier`), so
-   `uzbl -c /usr/share/...` is not an option.
-
-So even though we would like to make uzbl more usable by default, we think
-there is no sensible way to do it.  Maybe downstream packagers could provide
-a note that users could copy the examples from /usr/share/uzbl/examples into
-their homes, because really, that's all that is needed if you want it to
-just "work" without controlling how yourself. (unless you have no
-xdg variables set, in which case you should be smart enough to edit the sample
-config yourself).
-
-### Where is the location bar? How do I change the URL ?
-Uzbl has no location bar.  All changes to the uri (editing of current uri, typing new uri, loading of uri from bookmarks/history/...) happens *outside* of uzbl.
-Have a look at the sample scripts in /usr/share/uzbl/examples.  Most of our examples use dmenu which is a nifty little tool to pick an item from a list of items (very
-useful with history/bookmarks) with a limited set of keystrokes.  see man dmenu.
-You can also use it to make edits to a uri (press tab to load it into the
-search field) or type a url from scratch, though dmenu
-is not the most suitable editor. We're looking into a better way to make edits.
-Tools such as Zenity are also quite suited for this.
-And you can always make keybinds to load the current uri in the command field, paste/load urls from
-clipboard etc.
+"Uzbl" is the name for the umbrella project that has several subprojects.
+You probably want `uzbl-browser` or any of the other projects.
+The main program (uzbl-core) is a program meant for integration with other
+tools and scripts, by itself doesn't do many usefull things.  See README.
 
 ### Where are the widgets (forward, back,.. button etc)
-Uzbl's layout only contains what you really need to see.  we only have a statusbar, which even can also be disabled.  There are no buttons, but we do
+The layout of uzbl (and derivatives) only contains what you really need to see.  we only have a statusbar, which even can also be disabled.  There are no buttons, but we do
 have lots of keybinding possibilities.
 
-### No tabs? Why do you need a new window for each page?
-We stick to "one page per uzbl instance" because that's a simple, clean and flexible method.  We believe "multiple instances management" is something that must
+### Why can uzbl-browser only show one page?
+Among uzbl hackers, there are 2 groups: some people prefer tabs, they use
+uzbl-tabbed.  The others stick to "one page per uzbl-browser instance" because
+it's a very flexible approach.  They believe "multiple instances management" is something that must
 be handled outside of uzbl by a separate/different program.  Here are some solutions:
 
- * Many window managers can (and should) handle this by default.  Xmonads tabbed layout, Wmii's stacked layout, fluxbox or kwin tabs and so on.
+ * Many window managers can handle this by default.  Xmonads tabbed layout, Wmii's stacked layout, fluxbox or kwin tabs and so on.
  * Uzbl supports acting as a GtkPlug to plug into GtkSockets (Xembed) so you can embed uzbl instances in other Gtk applications.
-   This allows several implementatinos, a popular one is [uzbl_tabbed.py](http://www.uzbl.org/wiki/uzbl_tabbed)
+   (This is also what uzbl-tabbed does)
  * If you want highest customizablity, you need the 3rd option:
    You can also write a custom script.  The only thing you need to do is focus/maximize the instance you want,
    keep the others out of sight and use tools like dmenu and wmctrl to switch instances.
@@ -63,23 +27,10 @@ be handled outside of uzbl by a separate/different program.  Here are some solut
    For more information about this approach, see docs/multiple-instances-management.
    (If you want to work on such script, let us know and we might include it along with the other sample scripts)
 
-### What?  No support for bookmarks/history/downloads/cookies/... ? Your project sucks!
-We do not support *management* of those things, because we believe a browser should only do browsing.  We are firm believers in the unix philosophy.
-You have to look at the bigger picture.  In fact, we do support all these things.  Take bookmarks as an example:
-
- * we support keybinding and spawning external programs, so you can bind a key to spawn any script you want
- * Your script receives properties such as the current url, window title etc.
- * You can then call a tool such as zenity to prompt for any more information you may want to specify (tags,...)
- * You have the freedom to store the bookmarks in whichever format you want. (plaintext, sqlite, any database, on a remote system, in version control, ...)
- * To load a bookmark, you trigger another script which invokes a tool such as dmenu to let you pick a bookmark.  Your script can send the command to load the url to uzbl very easily by using the socket or fifo interface.
- * To manage your bookmarks, you can use whatever you want, depending on how you store them (simple text editor, database interface, ... )
-
-These ideas are something we want to consistently apply throughout the entire application.  (Even more, throughout our entire desktop environment)
-In fact, we actually ship various sample scripts and some sample configs that make it easy for you to implement your workflow.
-
 ### Okay, what can I actually do?  What commands are there?  How do I get more information?
   * Commands and other features are documented in README.  Read it.
   * You should also peek into the sampleconfigs to see how commands are used in practice.
+  * The wiki is also a great resource.
 
 ### Why can't I type anything in forms?  How does the keybinding work?
 You are in command mode, not in insert mode.
@@ -87,17 +38,11 @@ You are in command mode, not in insert mode.
 * command mode: you can trigger actions inside uzbl with minimum amount of keypresses (eg 'b' to go back, 'ZZ' to quit etc)  (see config examples), but not to type actual text into forms, because all your keypresses are interpreted.
 * insert mode: after going into insert mode (by default this is the 'i' binding from inside command mode), your keypresses are not interpreted but passed on, so you can enter text into forms.  Press Esc to go out of insert mode.
 
-The above method is called "modal" as inspired on VI.  If you don't like
-this you can easily change this:
-
-* enable always\_insert\_mode in your config.  You will always be in insert mode.
-* configure a modkey.  Since your keypresses are not interpreted anymore to trigger actions, you need a modkey to do things (eg alt+'b' to go back instead of just 'b' from command mode)
+The above method is called "modal" as inspired on VI.  If you don't like this you can easily change this.
 
 This method is how many applications work.
+TODO: you can call things from inside insert mode by using modkeys, right?
 
-Both have their pro's and cons.  We don't want to force anyone in using
-either, so by tuning the modkey and always\_insert\_mode settings you can pick
-whichever method you like, or both at the same time (command mode, insert mode, and the modkey to perform actions while in insert mode)
 
 ### Why do you depend on gtk?
 Uzbl itself doesn't use much gtk stuff (only the statusbar) so we could do without gtk.  But Webkit needs a widget toolkit to create widgets (think javascript popups, html forms etc).
@@ -117,9 +62,9 @@ They both have advantages and disadvantages:
 So, when writing scripts, using fifo's is usually the fastest method (because you do not need to fork another process), so fifo is preferred unless you need a response.
 
 ### What the hell is this 'XDG' stuff??
-You'll notice our example scripts and configs use variables such as `$XDG_CONFIG_HOME` and `$XDG_DATA_HOME`.
-Most of us really like the [xdg basedir spec](http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html)
-so our example material folows it.  Basically it helps you keeping a clean `$HOME` and it separates config, data and cache.
+You'll notice our example/default scripts and configs use variables such as `$XDG_CONFIG_HOME` and `$XDG_DATA_HOME`.
+Most of us really like the [xdg basedir spec](http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html).
+Basically it helps you keeping a clean `$HOME` and it separates config, data and cache.
 If these variables are not defined on your system, it could be that you need to install an xdg package.
 If you don't like this, no one is stopping you from changing the scripts and configs to point to a single `$HOME/.uzbl` directory or whatever you want.
 
diff --git a/docs/INSTALL b/docs/INSTALL
index 93e55f7..059155b 100644
--- a/docs/INSTALL
+++ b/docs/INSTALL
@@ -2,9 +2,8 @@ Packages
 --------
 [Arch Linux](http://www.archlinux.org) is our distro of choice, and the distro we use for testing.
 
-You can find a [PKGBUILD](http://aur.archlinux.org/packages.php?ID=25972) on the AUR, which installs the latest
-from the master branch. You can edit the PKGBUILD to change to any other
-branch you want.
+You can find [PKGBUILDS](http://aur.archlinux.org/packages.php?K=uzbl) on the AUR
+for all subprojects and for both the master and experimental branches.
 
 For other distros, see [uzbl.org/wiki/howtos](http://www.uzbl.org/wiki/howtos)
 
@@ -25,43 +24,30 @@ Tarballs can be pulled from [github.com/Dieterbe/uzbl/downloads](http://github.c
 
 Though you can only get tagged versions from the master branch, which may be older then what you'll have through git.
 
+If you want the specific subprojects, you can issue:
+
+	$ sudo make install-uzbl-core
+	$ sudo make install-uzbl-browser
+	$ sudo make install-uzbl-tabbed
+
 Dependencies
 ------------
-* git (for downloading)
-* pkg-config (for Make/gcc)
+Dependencies which are optional for uzbl-core are marked with an asterisk. (i.e. these are needed for extra scripts)
 * libwebkit 1.1.4 or higher
 * libsoup 2.24 or higher (dep for webkit/gtk+)
 * gtk 2.14 or higher
+* socat (for socket communication) [*]
+* dmenu (vertical patch recommended) [*]
+* zenity [*]
+* bash [*]
+* python [*]
+* perl (formfiller.pl) [*]
+
+Make dependencies
+-----------------
+* git (for downloading)
+* pkg-config (for Make/gcc)
 
-Optional/Recommended
---------------------
-The following tools are quite useful, and some of them are used in the
-sample scripts:
-
-* socat (for socket communication)
-* dmenu (with vertical patch)
-* zenity
-* bash
-* python (cookies.py)
-* perl (formfiller.pl)
-
-File locations
---------------
-After installing - using either method - you will find:
-
-* /usr/bin : uzbl
-* /usr/share/uzbl/docs/ : documentation files included with uzbl. (readme, checklist, .. )
-* /usr/share/uzbl/examples: sample scripts, config files and a sample data (boomarks, .. )
-
-You will probably want to change the scripts to behave more like you want, so copy the scripts to your home dir. If you save your config as
-$XDG\_CONFIG\_HOME/uzbl/config (this expands to ~/.config/uzbl/config on most systems) it will be recognized automatically. You can also pass the path to
-the config file with the --config parameter.
-
-You're free to store your personal stuff where you want, but we think the [XDG basedir spec](http://standards.freedesktop.org/basedir-spec/basedir-spec-0.6.html)
-is very useful for keeping a clean home directory, so we recommend:
-
-* $XDG\_CONFIG\_HOME/uzbl/config* (~/.config/uzbl/config on most systems): config file
-* $XDG\_DATA\_HOME/uzbl (~/.local/share/uzbl on most systems): bookmarks file, history file. and "scripts" directory with scripts
 
 Git Repo's & branches
 --------------------