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

diff --git a/README b/README
index 733d4c8..4f394bd 100644
--- a/README
+++ b/README
@@ -53,8 +53,10 @@ Time to change that!
 
 
 ### 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. (TODO: some default settings)
-For examples, please see the sample config(s).
+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.
@@ -81,64 +83,42 @@ When uzbl forks a new instance (eg "open in new window") it will use the same co
 If you made changes to the configuration at runtime, these are not pased on to the child.
 
 ### COMMAND SYNTAX
-Commands are used for:
-
-* creating keybindings
-* altering variables
-* getting the values of variables
-* running actions
-* setting the input buffer
-
 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 not case sensitive.
+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>
-Set is used for changing variables.  Every variable can be changed on the fly and for some variables, some additional logic is performed.
-For example, setting the variable `uri` will make uzbl start loading it, and changing the format of the statusbar/windowtitle/user agent/.. will be effective 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 key. (and TODO, get the value through the socket)
-
-    BIND <string> = <action>
-Makes the character sequence `<string>` invoke `<action>` when typed interactively in uzbl.
-There are a few tricks you can do:
-
-* `<string>` ends with an underscore: the action will only be invoked after pressing return/enter. If the user enters text where `<string>` has the underscore, `%s` in the `<action>` 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 action will be invoked on every keystroke).
-* `<string>` ends on a different character: you need to type the full string, which will trigger the action immediately, without pressing enter/return.
-
-Examples:
-
-    # uzbl will load the url when you type: 'o <url><enter>'
-    bind o _ = uri %s
-    # a search action 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 action will be triggered immediately.
-    bind ZZ  = exit
-
-    ACT <action>
-This tells uzbl to execute an action immediately.  The simplest example of this would be `act exit`; you know what that'll do.
-
-    KEYCMD <string>
-This sets the interactive command buffer to `<string>`.  Keycmd is primarily useful for scripts that help you type a command while still letting you edit it before execution.
-For example, if you have a binding like "o _" that opens an URL, then you could create a binding `O` that spawns a script which will set the command buffer to "o current-uri-here", letting you enter relative URLs easily.
-(See sample config)
-
-### ACTIONS
-Actions are invoked via bindings and by the ACT command.  Most actions are self-explanatory, though a few need to be clarified.  A list of
-actions follows:
+* `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`
@@ -147,9 +127,11 @@ actions follows:
 * `zoom_in`
 * `zoom_out`
 * `uri <address>`
-* `script <body>`
+* `js <body>`
    - execute the javascript in `<body>`
-   - remember that the commands, and thus actions, must not contain line breaks
+   - 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
@@ -158,13 +140,25 @@ actions follows:
 * `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.
-* `runcmd`
-   - can be used for running a command such as SET or BIND
+* `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