-- Uzbl.
+### 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
+
+
+### TO NEW PEOPLE:
+* please read the documentation in /usr/share/uzbl/docs
+* invoke uzbl --help
+* to get you started: uzbl --uri 'http://www.archlinux.org' --config /usr/share/uzbl/examples/configs/sampleconfig
+* study the sample config, have a look at all the bindings, and note how you can call the scripts to load new url from history and the bookmarks file
+* note that there is no url bar. all url editing is supposed to happen _outside_ of uzbl.
+ For now, you can use the `load_from_*` dmenu based scripts to pick a url or type a new one or write commands into the fifo (see /usr/share/uzbl/docs/CHECKLIST)
+* If you have questions, you are likely to find answers in the FAQ or in the other documentation.
+
+
+### INTRODUCTION
In my opinion, any program can only be really useful if it complies to the unix philosophy.
- Web browsers are frequent violators of this principle. Time to change that!
-
-Right now uzbl is in a very early state but here are some ideas I would like to (not) implement
-
-- each instance of uzbl renders 1 page (eg it's a small wrapper around webkit), no tabbing, tab previews, or speed dial things. we have window managers for that.
-- simple ini config file ("profile") for keyboard, network,.. settings
-- implement some basic keyboard shortcuts for going up, down, refresh etc
-- listen to signals and do useful stuff when triggered.
-- open up a socket file/fifo/.. so we can easily control each instance by writing things like 'uri <foo>' to /tmp/uzbl-pid
-- MAYBE (if needed): 1 control application called uzblctrl or something. use this to modify the behavior of a uzbl instance (change url, refresh). use xdotool to get the window with focus. eg uzblctrl -win <id> -url <http://>.
- use xbindkeys to bind keys to call uzblctrl.
-- no bookmark management builtin. make your own solution. for pulling a bookmark a plaintxt-based program using dmenu would work great here. combine with uzbltcrl and xbindkeys.
- uzblctrl should support an option to query the current page so you can script something to add to your bookmarks. use zenity or something to add tags.
-- similar story for history.
-- no ad blocking built in. use the power of /etc/hosts. though uzblctrl should support an option to list all images on a page, so you can easily pick the links to ads to add them to your /etc/hosts. (dmenu can again be great here to automate this)
-- no download manager. allow user to pick wget/curl/a custom script/...
-- no build in command interpreters like ubiquity. uzbl should be accessible and you should use a shell or similar.
-- no "clear cookies/cache/..." menu items. rm ~/$XDG_{DATA,CACHE}_DIR/uzbl/{cache,cookies}/*
-
-
-to figure out:
-- password management. maybe an encrypted store that unlocks with an ssh key?
-- how to handle hyperlinks? number them like konqueror does?
-
-
-WIDGET ROADMAP:
-* statusbar? (the bar you see in pretty much every gtk program at the bottom. eg firefox)
- consumes too much space (if always visible) for the little it is used. (+ you can put only 1 message in it at a time!)
- -> option 1: no statusbar at all. when hovering over a link (or pressing key to preview the url without changing page) -> show url in tooltip on page.
- -> option 2: toggle visibility of statusbar on/off when hovering over a link. since it's at the bottom I don't think it will disturb too much.
-* viewing progress/state of pageload? most programs use statusbar for this.
- -> option 1: titlebar can show a percentage when it's loading a new page.
- -> option 2: toggle a statusbar everytime we start loading a new page.
-* uri bar -> yes, even though we can write stuff to the fifo, it can still be convenient to change the url manually and stuff, so a widget in uzbl itself is good.
-* tabs -> yes. you don't have to use them, but you can.
-* back/forward/.. buttons? -> no: use keyboard shortcuts.
-* searching in a page? not sure.. maybe we can abuse the statusbar for that too.
- eg toggle it on when the user wants to search for something and then do searching in some vim-like fashion.
- we don't need a gtk text entry widget, just a feedback display of what the current command is.
-* scrollbar? no: use keyboard shortcuts. we should however have some info about the page length and where we are.
- -> option 1: put a percentage in the window title
- -> option 2: everytime you hit a key to change position, temporarily make a statusbar visible and put the percentage in the statusbar.
- what will we do with pages who are too wide? horizontal scrolling?
-all of the above goes in 1 bar at the top of the program. there should be a key to toggle visibility of it and one to toggle visibilety + focus on the entrybar at once.
-
-input welcome!
-
-
-
-
-
-NOTE:
-- My c skills are very rusty, it will take me a while to get back up to speed
-- For more thoughts & ideas see http://bbs.archlinux.org/viewtopic.php?id=67463
+ Web browsers 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 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:
+
+* 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, or scripts.
+ This way you can get something much more useful than tabbing (see rationale in docs)
+* 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)
+ uzblctrl would need to support an option to list all images on a page, 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.
+
+
+### CONFIGURATION / CONTROL:
+The general idea is that uzbl by default is very bare bones. you can send it commands to update settings and perform actions, through various interfaces.
+There is a limited default configuration. Please see config.h to see what it contains.
+By default, there are *no* keybinds defined at all. (Default keybinds would work counterproductive when you try to customize)
+For examples of the possibilities what you can do, please see the sample config(s).
+There are several interfaces to interact with uzbl:
+
+* uzbl --config <filename>: <filename> will be read line by line, and the commands in it will be executed. useful to configure uzbl at startup.
+ If you have a file in `$XDG_CONFIG_HOME/uzbl/config` (this expands to ~/.config/uzbl/config on most systems) it will be automatically recognized
+* stdin: you can also write commands into stdin
+* interactive: you can enter commands (and bind them to shortcuts, even at runtime)
+ By default, the behaviour is modal (vi style):
+ command mode: every keystroke is interpreted to run commands
+ insert mode: keystrokes are not interpreted so you can enter text into html forms
+ Press ESC/i to toggle command/insert mode
+ But if you don't like modal interfaces, you can set `always_insert_mode` and configure a modkey to execute the commands. (emacs style).
+ There is also support for "chained" commands (multiple characters long) (with backspace/esc shortcuts), and keyworded commands.
+ Also you can have incremental matching on commands or match after pressing return. (see sampleconfig for more info)
+ Also, copy paste works when typing commands:
+ * insert (paste X cliboard)
+ * shift insert (paste primary selection buffer)
+* FIFO & socket file: if enabled by setting their paths through one of the above means, you can have socket and fifo files available which are very useful to programatically control uzbl (from scripts etc).
+ The advantage of the fifo is you can write plaintxt commands to it, but it's half duplex only (uzbl cannot send a response to you).
+ The socket is full duplex but you need a socket-compatible wrapper such as netcat to work with it, or uzblctrl of course,
+ an utitly we include with uzbl made especially for writing commnands to the socket (and at some point, it will be able to tell you the response
+ too): `uzblctrl -s <socketfile> -c <command>`
+
+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.
+
+### COMMAND SYNTAX
+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, which must be the first thing on a line; preceding whitespace is not allowed.
+A command is terminated by a newline. Empty lines and lines that start with the hash sign are ignored by the parser. Command names are always written in lowercase.
+
+The following commands are recognized:
+
+* `set <key> = <value>`
+ - used for changing variables on the fly
+ - the changes are effective immediately; for example, setting the variable `uri` will make uzbl start loading, and changing `status_format` will make the status bar react immediately
+ - if you want to unset a string, use `set` with one space after the equals sign
+* `get <key>`
+ - use this to print the value of a variable. (and TODO, get the value through the socket)
+* `bind <string> = <command>`
+ - 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)
+ * `<string>` ends with an asterisk: similar behavior as with an underscore, but also makes the binding incremental (i.e. the command will be invoked on every keystroke).
+ * `<string>` ends on a different character: you need to type the full string, which will trigger the command immediately, without pressing enter/return.
+ - examples:
+
+ # uzbl will load the url when you type: 'o <url><enter>'
+ bind o _ = uri %s
+ # a search command which is called on every character typed after the slash, letting you see the search narrow down while typing.
+ # Hitting return, enter or esc will terminate the search.
+ bind /* = search %s
+ # when you type `ZZ` and nothing else, the exit command will be triggered immediately.
+ bind ZZ = exit
+
+* `back`
+* `forward`
+* `scroll_vert <amount>`
+* `scroll_horz <amount>`
+ - amount is given in pixels(?) or as a percentage of the size of the view
+ - set amount to 100% to scroll a whole page
+* `scroll_begin`
+* `scroll_end`
+* `reload`
+* `reload_ign_cache`
+* `stop`
+* `zoom_in`
+* `zoom_out`
+* `uri <address>`
+* `js <body>`
+ - execute the javascript in `<body>`
+ - remember that the commands must not contain line breaks
+* `script <file>`
+ - execute the javascript in `<file>`
+* `toggle_status`
+* `spawn <executable> <additonal args>`
+ - 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.
+* `sh <command>`
+ - runs a shell command by expanding `%s` in the `shell_cmd` variable with the specified command; primarily useful as a shortcut for `spawn sh -c <body>`
+ - note that the arguments as specified in "EXTERNAL SCRIPTS" are appended at the end, so the argument numbers will be higher.
+* `sync_spawn <executable> <additional args>`
+* `sync_sh <command>`
+ - these are synchronous variants of `spawn` and `sh`, which means uzbl will wait for them to return
+ - you should only need to use these manually if you want to use a chain command in a handler that wants output from the command it runs
+* `exit`
+* `search <string>`
+* `search_reverse <string>`
+ - search with no string will search for the next/previous occurrence of the string previously searched for
+* `toggle_insert_mode <optional state>`
+ - if the optional state is 0, disable insert mode. If 1, enable insert mode.
+* `keycmd <string>`
+* `keycmd_nl <string>`
+ - keycmd sets the interactive command buffer to `<string>`. If the given string is a valid binding, it will execute. `Keycmd_nl` is like `keycmd`, but it also emulates a press of return, causing bindings with a parameter to execute. For example, `keycmd_nl o google.com` would load the said url if you have a binding like `bind o _ = uri %s`.
+* `keycmd_bs`
+ - erase (backspace) one character from the command buffer
+* `chain <command> <command> ..`
+ - use for chaining multiple commands
+ - remember to quote the commands; one command must come as one parameter
+ - if you use `chain` with a handler script which must return some output (such as a cookie handler -- uzbl will wait for and use its output), use sync_spawn or sync_sh instead of spawn or sh in the command that should give the output
+
+
+### VARIABLE REPLACEMENT
+Some of the variables are interpreted:
+
+* title bar: variable replacement (long and short version, depending if statusbar is visible or not)
+* user agent: variable replacement
+* statusbar: variable replacement + pango markup
+
+This means you can customize how these things appear, what's shown in them and for the statusbar you can even play with the layout.
+For examples, see the example config.
+For a list of possible variables, see uzbl.h
+For more info about the markup format see http://library.gnome.org/devel/pango/stable/PangoMarkupFormat.html
+
+
+### EXTERNAL SCRIPTS
+You can use external scripts with uzbl the following ways:
+
+* let uzbl call them. these scripts are called handlers in the uzbl config. used for handling logging history, handling a new download,..
+* call them yourself from inside uzbl. you can bind keys for this. examples: add new bookmark, load new url,..
+* You could also use xbindkeys or your WM config to trigger scripts if uzbl does not have focus
+
+Have a look at the sample configs and scripts!
+
+Handler scripts that are called by uzbl are passed the following arguments:
+
+ $1 uzbl-config-file
+ $2 uzbl-pid
+ $3 uzbl-x-window-id
+ $4 uzbl_fifo-filename
+ $5 uzbl_socket-filename
+ $6 current page url
+ $7 current page title
+ .. [ script specific ] (optional)
+
+The script specific arguments are this:
+
+* history:
+
+ $8 date of visit (Y-m-d H:i:s localtime)
+
+* add bookmark:
+
+ none
+
+* download:
+
+ $8 url of item to download
+
+* cookie handler
+
+ $8 GET/PUT
+ $9 request address host (if current page url is www.foo.com/somepage, this could be something else then foo, eg advertising from another host)
+ $10 request address path
+ $11 cookie (only with PUT requests)
+
+
+Custom, userdefined scripts (`spawn foo bar`) get first the arguments as specified in the config and then the above 7 are added at the end.
+
+### COMMAND LINE ARGUMENTS
+
+ -u, --uri=URI Uri to load (equivalent to 'set uri = URI')
+ -v, --verbose Whether to print all messages or just errors.
+ -n, --name=NAME Name of the current instance (defaults to Xorg window id)
+ -c, --config=FILE Config file (this is pretty much equivalent to uzbl < FILE )
+ --display=DISPLAY X display to use
+ --help Help
+
+
+### BUGS
+known bugs:
+
+* Segfaults when using zoom commands (happens when max zoom already reached?).
+
+Please report new issues @ uzbl.org/bugs
+
+