X-Git-Url: http://vcs.maemo.org/git/?a=blobdiff_plain;f=README;h=4f394bdf3da5369330fa87d959baf2643463af05;hb=94b6dff8f74e9cb2a74b21c1d0f7721ef56b0369;hp=fe7daabbf2f4464bae99e66acff45aeecdf4802e;hpb=fea82c14797ef41a410c90805b64c3e9bab8a5c3;p=uzbl-mobile

diff --git a/README b/README
index fe7daab..4f394bd 100644
--- a/README
+++ b/README
@@ -1,54 +1,238 @@
-- 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.
-
-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
+
+