updated readme and example config

2 files changed, 39 insertions, 13 deletions

diff --git a/README b/README
index ae9932b..266a207 100644
--- a/README
+++ b/README
@@ -235,22 +235,48 @@ the java script in @< >@.
 Variable expansion also works within a java script substitution.
 
 
+When a piece of text needs to be XML escaped after it is expanded (for example,
+in the status bar format), you can use @[ ]@ substitution:
+
+    print This text is XML escaped: @[<&>]@
+
+    # prints: This text is XML escaped: &lt;&amp;&gt;
+
+
 NOTE: If you need to use literal @ or \ characters you will need to escape them:
 
     print At sign: \@  and backslash: \\
 
 
-### VARIABLE REPLACEMENT
-Some of the variables are interpreted:
+### TITLE AND STATUS BAR EVALUATION
+
+The contents of the status bar can be customized by setting the status_format
+variable. The contents of the window title can be customized by setting the
+title_format_short variable (which is used when the status bar is displayed) and
+the title_format_long variable (which is used when the status bar is not
+displayed). Their values can be set using the expansion and substitution
+techniques described above.
+
+These variables are expanded in multiple stages; once when the variable is set,
+and again every time that the status bar or window title are updated. Expansions
+that should be evaluated on every update need to be escaped:
+
+    set title_format_short = @(date)@
+    # this expansion will be evaluated when the variable is set.
+    # the title will stay constant with the date that the variable was set.
+
+    set title_format_short = \@(date)\@
+    # this expansion will be evaluated when the window title is updated.
+    # the date in the title will change when you change pages, for example.
 
-* title bar: variable replacement (long and short version, depending if statusbar is visible or not)
-* user agent: variable replacement
-* statusbar: variable replacement + pango markup
+    set title_format_short = \\\@(date)\\\@
+    # the title will stay constant as a literal "@(date)@"
 
-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
+The status_format variable can contain Pango markup (see
+<http://library.gnome.org/devel/pango/stable/PangoMarkupFormat.html>). In the
+status_format, variables that might contain characters like '<', '&' and '>',
+should be wrapped in a @[]@ substitution so that they don't interfere with the
+status bar's markup; see the example config for examples.
 
 
 ### EXTERNAL SCRIPTS
diff --git a/examples/config/uzbl/config b/examples/config/uzbl/config
index 4d455b1..126df49 100644
--- a/examples/config/uzbl/config
+++ b/examples/config/uzbl/config
@@ -68,11 +68,11 @@ set shell_cmd         = sh -c
 set show_status       = 1
 # you can optionally use this setting to override the background color of the statusbar from your GTK theme.
 set status_background = #303030
-set status_format     = <span font_family="monospace"><span background="khaki" foreground="black">[MODE]</span> [<span weight="bold" foreground="red">KEYCMD</span>] <span foreground="#606060"> LOAD_PROGRESSBAR </span><span foreground="#99FF66">URI</span> <span foreground="khaki">NAME</span> <span foreground="orange">MSG</span><span foreground="#606060">SELECTED_URI</span></span>
+set status_format     = <span font_family="monospace"><span background="khaki"            foreground="black">[\@[\@MODE]\@]</span> [<span weight="bold" foreground="red">\@[\@      keycmd]\@</span>] <span foreground="#606060"> \@[\@LOAD_PROGRESSBAR]\@ </span><span       foreground="#99FF66">\@[\@uri]\@</span> <span foreground="khaki">\@[\@NAME]\@</span>      <span foreground="orange">\@status_message</span><span foreground="#606060">\@[\@         SELECTED_URI]\@</span></span>
 set status_top        = 0
 # define how your titlebar should look like. (short = statusbar is also shown, long = show everything you must see if statusbar is off)
-set title_format_short = TITLE - Uzbl browser <NAME>
-set title_format_long = KEYCMD MODE TITLE - Uzbl browser <NAME> > SELECTED_URI
+set title_format_short = \@TITLE - Uzbl browser <\@NAME>
+set title_format_long = \@keycmd \@MODE \@TITLE - Uzbl browser <\@NAME> > \@SELECTED_URI
 # set the characters to use for, and the width of the progress bar
 set status_pbar_done  = *
 set status_pbar_pending = -
@@ -91,7 +91,7 @@ set always_insert_mode = 0
 #set  http_debug      = 0
 #set  useragent       = uzbl (Webkit @WEBKIT_MAJOR.@WEBKIT_MINOR.@WEBKIT_MICRO)
 # Example user agent containing everything:
-set  useragent       = Uzbl (Webkit @WEBKIT_MAJOR.@WEBKIT_MINOR.@WEBKIT_MICRO) (@SYSNAME @NODENAME @KERNREL @KERNVER @ARCH_SYSTEM [@ARCH_UZBL]) (Commit @COMMIT)
+set  useragent       = Uzbl (Webkit @WEBKIT_MAJOR.@WEBKIT_MINOR.@WEBKIT_MICRO) (@(uname-s)@ @(uname -n)@ @(uname -r)@ @(uname -v)@ @(uname -m)@ [@ARCH_UZBL]) (Commit @COMMIT)
 #set  max_conns	      = 0
 #set  max_conns_host  = 0