README

   1 THIS PROJECT IS NOT FOR:
   2 - people want a browser that does everything
   3 - people who want a browser with things like a built-in bookmark manager, address bar, forward/back buttons, ...
   4
   5
   6
   7 TO NEW PEOPLE:
   8  - please read the README in /usr/share/uzbl/docs
   9  - invoke uzbl --help
  10  - to get you started: uzbl --uri 'http://www.archlinux.org' --config /usr/share/uzbl/examples/configs/sampleconfig
  11  - 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
  12  - note that there is no url bar. all url editing is supposed to happen _outside_ of uzbl.
  13    for now, you can use the load_from_* dmenu based scripts to pick a url or type a new one (we should have a dmenu-like that functions as a better editor) or write commands into the fifo (see /usr/share/uzbl/docs/CHECKLIST)
  14  - If you have questions, you are likely to find answers in the FAQ
  15
  16 CURRENT STATE:
  17  alpha / prototype
  18
  19
  20 - Uzbl.
  21   In my opinion, any program can only be really useful if it complies to the unix philosophy.
  22   Web browsers are frequent violators of this principle.  Time to change that!
  23
  24 Right now uzbl is in a very early state but here are some ideas I would like to (not) implement
  25
  26 - 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.
  27   -> well actually, there is lots of dicussion about this, i'll probably implement a basic form of tabbing.
  28 - simple ini config file ("profile") for keyboard, network,.. settings
  29 - implement some basic keyboard shortcuts for going up, down, refresh etc. preferably vim-like command style.
  30 - listen to signals and do useful stuff when triggered.
  31 - open up a socket file/fifo/.. so we can easily control each instance by writing things like 'uri <foo>' to /tmp/uzbl-windowid
  32 - 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://>.
  33   use xbindkeys to bind keys to call uzblctrl.
  34 - 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.
  35   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.
  36 - history: log 'Y-m-d H:M:S <url>' entries to a plaintext file. you can then use dmenu or whatever to select an entry and pipe the output to uzbl's fifo.
  37 - no ad blocking built in (I think).
  38   alternatives:
  39   ->  /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. (dmenu can again be great here to automate this)
  40   -> privoxy looks cool and perfectly demonstrates the unix philosphy.
  41   -> same for http://bfilter.sourceforge.net
  42 - no download manager. allow user to pick wget/curl/a custom script/...
  43 - no build in command interpreters like ubiquity.  uzbl should be accessible and you should use a shell or similar.
  44 - no "clear cookies/cache/..." menu items. rm ~/$XDG_{DATA,CACHE}_DIR/uzbl/{cache,cookies}/*
  45 - vimperator/konqueror-like hyperlink following.
  46 - password management. maybe an encrypted store that unlocks with an ssh key?
  47 - use the XDG basedir spec for separation of config, data and cache. and state will be a subdir in the config dir (not part of the spec yet) too.
  48
  49 WIDGET ROADMAP:
  50 * statusbar? (the bar you see in pretty much every gtk program at the bottom. eg firefox)
  51   consumes too much space (if always visible) for the little it is used.  (+ you can put only 1 message in it at a time!)
  52   -> 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.
  53   -> 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.
  54 * viewing progress/state of pageload?  most programs use statusbar for this.
  55   -> option 1: titlebar can show a percentage when it's loading a new page.
  56   -> option 2: toggle a statusbar everytime we start loading a new page.
  57 * 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.
  58 * tabs -> yes. you don't have to use them, but you can.
  59 * back/forward/.. buttons? -> no: use keyboard shortcuts.
  60 * searching in a page? not sure.. maybe we can abuse the statusbar for that too.
  61   eg toggle it on when the user wants to search for something and then do searching in some vim-like fashion.
  62   we don't need a gtk text entry widget, just a feedback display of what the current command is.
  63 * scrollbar? no: use keyboard shortcuts.  we should however have some info about the page length and where we are.
  64   -> option 1: put a percentage in the window title
  65   -> option 2: everytime you hit a key to change position, temporarily make a statusbar visible and put the percentage in the statusbar.
  66   what will we do with pages who are too wide? horizontal scrolling?
  67 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.
  68
  69 input welcome!
  70
  71
  72 HISTORY FILE SIZE/PERFORMANCE
  73 each new pageload -> fopen(history_file, "a"), fwrite one line, fclose.
  74 I use utf8, so unless you use characters that are "special" (chinese etc)
  75 each character takes 1 byte.
  76 So, assume each entry is about 80 chars, you visit 100 pages per day (?), and you wonder when your history file will be 50MB big:
  77 (50 * 1000 * 1000 ) / ( 80 * 100 ) = 6250 days or 17 years.
  78 There is code to run a benchmark in the 'extra' dir.  For results & interpretation, see http://dieter.plaetinck.be/poor_mans_dmenu_benchmark
  79
  80 CONTROL:
  81 - FIFO opened in /tmp/uzbl_pid
  82 - See config file for commands
  83 - Press ESC/i to toggle command/insert mode
  84
  85 NOTES:
  86 - My c skills are very rusty, it will take me a while to get back up to speed
  87 - For more thoughts & ideas see http://bbs.archlinux.org/viewtopic.php?id=67463
  88
  89 REPO's:
  90 - http://github.com/Dieterbe/uzbl
  91   master -> uzbl stable branch
  92   experimental -> bleeding edge stuff that may break. after QA codes gets merged into master
  93 - various contributors also have their clones on github (http://github.com/dusanx, http://github.com/Barrucadu/uzbl, ...).
  94   They may be developing specific features, which get merged into Dieters experimental branch
  95
  96
  97 EXTERNAL SCRIPTS
  98 You can use external scripts with uzbl the following ways:
  99 1) let uzbl call them. these scripts are called handlers in the uzbl config. used for handling logging history, handling a new download,..
 100 2) call them yourself from inside uzbl.  you can bind keys for this. examples: add new bookmark, load new url,..
 101 3) if you want to call scripts that have no option, you can trigger them with something like xbindkeys. example: ? (we try to keep all possibilities inside option 1/2)
 102
 103 Scripts that are called by uzbl are passed the following arguments:
 104 $1 uzbl-config-file
 105 $2 uzbl-pid
 106 $3 uzbl-x-window-id
 107 $4 uzbl_fifo-filename
 108 $5 uzbl_socket-filename
 109 $6 current page url
 110 $7 current page title
 111 .. [ script specific ] (optional)
 112
 113 The script specific arguments are this:
 114 * history:
 115   $8 date of visit (Y-m-d H:i:s localtime)
 116 * add bookmark:
 117   none
 118 * download:
 119   $8 url of item to download
 120 * cookie handler
 121   $8 GET/PUT
 122   $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)
 123   $10 request address path
 124   $11 cookie (only with PUT requests)
 125
 126 KNOWN BUGS
 127 - Segfaults when using zoom commands (happens when max zoom already reached?).
 128 - Something in the FIFO code causes CPU usage to jump.
 129
 130 Report new issues @ uzbl.org/bugs
 131
 132
 133 VALGRIND PROFILING
 134 add this to Makefile header: CFLAGS=-g
 135 recompile
 136 valgrind --tool=callgrind ./uzbl ....
 137 kcachegrind callgrind.out.foo
 138
 139 CONFIG FILE
 140 ** Variable replacement and markup format
 141 See http://library.gnome.org/devel/pango/stable/PangoMarkupFormat.html for
 142 what you can do, markup wise.
 143 TODO: document possible variables, and what you can do with useragent/title/statusbar