X-Git-Url: http://git.maemo.org/git/?p=browser-switch;a=blobdiff_plain;f=README;h=e807f4b1b49dd573871d2957e0441a2a8fef7274;hp=77eefc472e40844657c2262559b89b0225abd72f;hb=f80c0225d95f310c24a8a69bedf97069f2859636;hpb=705b848e92de09f2adcad0c8d075634ca4909ac9

diff --git a/README b/README
index 77eefc4..e807f4b 100644
--- a/README
+++ b/README
@@ -1,29 +1,225 @@
-# browser-proxy.py
-# version 2.2 by steven676 and xiojason
-# (see http://browser-switch.garage.maemo.org/)
-
-# simple python-dbus service that proxies osso_browser events to Tear
-# based on code from http://paste.lisp.org/display/45824
-
-# installation:
-# 0. ensure the needed python packages are installed:
-#    python2.5, python2.5-dbus, and python2.5-gtk2
-# 1. place this file in /home/user as browser-proxy.py
-# 2. make executable (chmod +x browser-proxy.py)
-# 3. change /usr/share/dbus-1/services/com.nokia.osso_browser.service to read:
-# [D-BUS Service]
-# Name=com.nokia.osso_browser
-# Exec=/home/user/browser-proxy.py
-# 4. disable tablet-browser-service (aka browserd) (optional, saves memory)
-# 5. you may wish to reboot.
-
-# notes:
-# - opening urls will be a bit slow. it takes some time to relay the messages to Tear
-# - modifications to the script may require the killing of an already-running
-#   browser-proxy.py process -- just use 'kill' to stop it.
-# - modifying the osso_browser.service file prevents MicroB/browserd from working.
-#   if you wish to restore MicroB/browserd, change the service file's contents back to:
-# [D-BUS Service]
-# Name=com.nokia.osso_browser
-# Exec=/usr/bin/browser
-#   and re-enable tablet-browser-service again.
+BROWSER SWITCHBOARD
+version 3.2
+
+Browser Switchboard is a program which allows you to choose which
+browser to use as the default browser. It supports MicroB, Tear,
+Fennec/Mobile Firefox, and Midori out of the box, and can also be used
+to launch MicroB without having browserd running.
+
+
+Download:
+Binary packages and source are available for download from the project
+page on garage.maemo.org: https://garage.maemo.org/frs/?group_id=1159
+
+
+Quick Start:
+1. Download the binary package: browser-switchboard_X.Y-Z_all.deb
+(where X.Y-Z is the version number, of course).
+2. If you're using a Maemo 5 device, make sure all your MicroB browser
+windows are closed.
+3. Install the package using the Application Manager (open the
+Application Manager, then select Application->Install from file in the
+menu).
+
+You can now select the default browser by using the Browser Switchboard
+applet in the Control Panel.  Links in most applications, locally-saved
+web pages opened from the file manager, and (for Maemo 4.x) entries in
+the Web sidebar panel will open in the browser that you select as the
+default.  Opening the "Web" menu entry and running "browser" from the
+shell will also cause your chosen default browser to open.  If you don't
+configure a default browser, MicroB will continue to be used as the
+default browser.
+
+No matter which browser you select as the default, MicroB can always be
+opened via the MicroB menu entry in the applications menu (for Maemo
+4.x, installed in the Extras menu by default), or by running "microb"
+from the shell.  While MicroB is open, it will receive all links from
+other applications; closing MicroB will restore your chosen default
+browser.
+
+If you experience trouble after installing the package, try rebooting
+your device.  If that fixes things, please report this as a bug.
+
+
+Configuring the Default Browser by Hand:
+
+If for some reason, you don't want to use the Control Panel applet to
+configure Browser Switchboard, you can create the configuration file by
+hand from a shell.  Run the following (where $ is your prompt, not
+something you type):
+
+$ cat > $HOME/.config/browser-switchboard <<EOF
+default_browser = "your_browser"
+EOF
+
+where your_browser can be one of "tear", "microb", "fennec", "midori",
+or "other" (see below for more on the "other" option).  You can of
+course also edit the $HOME/.config/browser-switchboard file with your
+favorite text editor.
+
+To restore the default behavior, just delete the config file:
+
+$ rm $HOME/.config/browser-switchboard
+
+
+Advanced Configuration:
+
+Here's a more complete sample configuration file:
+
+# BEGIN SAMPLE CONFIG FILE
+# This is a comment
+# continuous_mode: 0 -- close after handling a request; 1 -- run
+# continuously in the background
+continuous_mode = 0
+# default_browser: "tear", "microb", "fennec", "midori", or "other"
+default_browser = "tear"
+# other_browser_cmd: If default browser is "other", what program
+# to run (%s will be replaced by URI)
+#other_browser_cmd = "some_browser %s"
+# logging: Where log output should go: "stdout", "syslog", "none"
+#logging = "stdout"
+# END SAMPLE CONFIG FILE
+
+Lines beginning with # characters are comments and are ignored by the
+script.  [Most options correspond directly to an option or option group
+in the configuration UI.]
+
+In continuous mode, Browser Switchboard keeps running in the background
+instead of closing after handling each request.  This saves a bit of
+startup time for each link (on my N800 running Diablo), but costs you
+about 100 KB extra memory.  Continuous mode is disabled by default; set
+continuous_mode to 1 to enable.  [This option corresponds to the
+"Optimize Browser Switchboard for" option group in the UI; "Lower memory
+usage" corresponds to continuous_mode off, while "Faster browser startup
+time" corresponds to continuous_mode on.]
+
+The "tear", "microb", "fennec", and "midori" options for default_browser
+should be self-explanatory.  [These correspond to the options in the
+"Default browser" combo box in the UI.]
+
+If the default browser is "other", Browser Switchboard will run the
+program specified in other_browser_cmd as the default browser, with a
+URI replacing the %s on the command line; for example, if
+other_browser_cmd is set to "some_browser %s", and Browser Switchboard
+is asked to load http://www.google.com/, it will perform the equivalent
+of typing in 
+
+$ some_browser 'http://www.google.com/'
+
+at a shell.  [In the UI, setting "Default brower" to "Other" activates
+the "Command (%s for URI)" setting, which corresponds to the value of
+other_browser_cmd.]
+
+The logging option controls where Browser Switchboard sends its debug
+logging output to.  You should not need to change this unless you're
+debugging Browser Switchboard, and there is no UI for this option.  The
+default option is "stdout", which means you won't see output unless you
+run Browser Switchboard from the shell.  "syslog" will send the output
+to the system log (assuming you have a syslogd set up on your device),
+and "none" disables debug logging entirely.
+
+
+Browser Switchboard and MicroB's browserd:
+
+MicroB uses a background process called browserd to decrease its load
+time.  Browser Switchboard knows how to launch MicroB without having
+browserd running all the time, so if you don't plan on using MicroB
+often, you can disable browserd (for example, by using the
+maemo-control-services control panel applet available in Maemo Extras to
+disable tablet-browser-daemon).  This will save you about 1 MB of
+memory, but add a few seconds to MicroB's load time.
+
+
+Uninstalling Browser Switchboard:
+
+Remove the Browser Switchboard package using the Application Manager,
+and everything should be back to normal.  If you experience problems
+after uninstalling, try restarting your device first; if that fixes
+things, please report this as a bug.
+
+
+Compiling Browser Switchboard:
+
+If for some reason you don't want to use the prebuilt binary package to
+install Browser Switchboard, you can compile and install by hand:
+1. You will need a copy of the SDK for your device.  Make sure the
+following packages are installed: libdbus-glib-1-dev for
+browser-switchboard; libdbus-1-dev, libgtk2.0-dev, libhildon1-dev,
+hildon-control-panel-dev for the config UI.
+2. Download the source tarball: browser-switchboard_X.Y.orig.tar.gz
+3. Unpack the source tarball in your SDK install:
+
+SDK$ tar -xvzf browser-switchboard_X.Y.orig.tar.gz
+SDK$ cd browser-switchboard-X.Y
+
+4. Compile:
+
+SDK$ make diablo
+SDK$ make -C config-ui diablo-plugin
+
+(Replace "diablo" with "fremantle" and "diablo-plugin" with
+"fremantle-plugin" if compiling for Fremantle.
+
+If you want the standalone config application instead of the Control
+Panel plugin, do 
+SDK$ make -C config-ui diablo-hildon-app
+instead.
+
+If you're using the Scratchbox2-based SDK+, you want
+SDK+$ sb2 make
+etc. as usual.)
+
+5. Install to a temporary directory, and tar up the result:
+
+SDK$ make DESTDIR=temp install
+SDK$ make -C config-ui install
+SDK$ cd temp
+SDK$ tar cf stuff.tar .
+
+6. As root on your device, move files that will be replaced in the
+install process out of the way:
+
+DEVICE# mv /usr/share/dbus-1/services/com.nokia.osso_browser.service
+  /usr/share/dbus-1/services/com.nokia.osso_browser.bak
+DEVICE# mv /usr/bin/browser /usr/bin/browser.bak
+
+7. Copy the tar file from step 5 to your device, and as root, unpack it
+in the root directory of your device:
+
+DEVICE# cd /
+DEVICE# tar xf /path/to/stuff.tar
+
+To uninstall, remove the files you installed, restore the backup copies,
+and reboot your device.
+
+
+Bug Reports and Patches:
+
+Bug reports, patches, and suggested improvements can either be sent to
+the maintainer via email (see below) or posted in the Tear thread on the
+talk.maemo.org forums (http://talk.maemo.org/showthread.php?t=28539).
+
+
+Source Code Repository:
+
+Source code is hosted in a Git (http://git-scm.com/) repository on
+git.maemo.org.  You can get a copy of the current development version by
+cloning the repository:
+
+$ git clone http://git.maemo.org/projects/browser-switch
+
+or you can browse the source using gitweb
+(http://git.maemo.org/projects/browser-switch/?p=browser-switch;a=summary).
+
+
+Maintainer:
+
+Steven Luo <steven+maemo@steven676.net> is the primary maintainer, with
+Jason Simpson (the original developer) assisting in development.
+
+
+License:
+
+Browser Switchboard is available under the terms of the GNU General
+Public License (GPL), version 2 or later (see the file LICENSE in the
+source).