Update README, document changes in 3.3 betas

[browser-switch] / README

diff --git a/README b/README
index 47b3260..774a77b 100644 (file)
--- a/README
+++ b/README
@@ -1,4 +1,5 @@
 BROWSER SWITCHBOARD
 BROWSER SWITCHBOARD

+version 3.3b2

 
 Browser Switchboard is a program which allows you to choose which
 browser to use as the default browser. It supports MicroB, Tear,
 
 Browser Switchboard is a program which allows you to choose which
 browser to use as the default browser. It supports MicroB, Tear,

@@ -22,18 +23,20 @@ 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
 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.  If you don't configure a default browser, MicroB will continue
-to be used as the default browser.
+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
 
 No matter which browser you select as the default, MicroB can always be

-opened via the Web menu entry in the applications menu (for Maemo 4.x,
-located in the Internet menu by default), or by running "browser" from
-the shell.  While MicroB is open, it will receive all links from other
-applications; closing MicroB will restore your chosen default browser.
+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.

 
 

-Some users have reported that a restart may be necessary to ensure that
-Browser Switchboard is functioning.  If you experience trouble after
-installing the package, try rebooting your device first.
+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:
 
 
 Configuring the Default Browser by Hand:

@@ -47,9 +50,9 @@ $ cat > $HOME/.config/browser-switchboard <<EOF
 default_browser = "your_browser"
 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
+where your_browser can be one of "tear", "microb", "fennec", "opera",
+"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:
 favorite text editor.
 
 To restore the default behavior, just delete the config file:

@@ -64,29 +67,42 @@ 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
 # 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"
+# continuously in the background (default)
+# On Fremantle, this is forced to 1 regardless of config setting
+continuous_mode = 1
+# default_browser: "tear", "microb", "fennec", "midori", "opera" 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"
 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"
+# autostart_microb: Fremantle only: whether MicroB should be
+# prestarted in the background: 0 -- never prestart MicroB; 1 -- always
+# prestart MicroB; -1 -- only prestart MicroB when MicroB is the default
+# browser (default behavior if unset)
+#autostart_microb = 0

 # END SAMPLE CONFIG FILE
 
 Lines beginning with # characters are comments and are ignored by the
 # END SAMPLE CONFIG FILE
 
 Lines beginning with # characters are comments and are ignored by the

-script.
+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
 
 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.
+about 100 KB extra memory.  Continuous mode is enabled by default; set
+continuous_mode to 0 to enable.  On Fremantle, continuous mode is always
+enabled regardless of the value of this config setting, to provide
+better compatibility with MicroB's behavior.  [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", "opera" 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
 
 If the default browser is "other", Browser Switchboard will run the
 program specified in other_browser_cmd as the default browser, with a

@@ -97,7 +113,62 @@ of typing in
 
 $ some_browser 'http://www.google.com/'
 
 
 $ some_browser 'http://www.google.com/'
 

-at a shell.
+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.
+
+On Fremantle only, autostart_microb controls whether MicroB is
+prestarted when the device boots and whether the MicroB browser process
+is left running when no browser windows are open.  By default, MicroB is
+prestarted (and the process left open when no browser windows are open)
+only when MicroB is set as the default browser; you can force MicroB to
+always prestart by setting autostart_microb = 1, while you can force it
+to never prestart by setting autostart_microb = 0.  [This option has no
+corresponding UI at the moment.]
+
+
+The browser-switchboard-config Command-Line Configuration Tool:
+
+A command-line configuration utility is provided to allow programs and
+scripts to query and set Browser Switchboard configuration variables.
+For example,
+
+$ browser-switchboard-config -b
+
+will display the default browser, and 
+
+$ browser-switchboard-config -s -b "opera"
+
+will set the default browser to Opera Mobile.  See the help output from
+running browser-switchboard-config with no arguments for more
+information.
+
+The primary purpose of this tool is to allow browser vendors to provide
+an option in their browsers to set themselves as the default browser,
+via something like this (shell-like pseudocode):
+
+if [ -x /usr/bin/browser-switchboard-config ]; then
+       if [ `browser-switchboard-config -b` = "mybrowser" ]; then
+               display "MyBrowser is the default browser."
+       else
+               button "Make MyBrowser the default browser"
+               action "browser-switchboard-config -s -b mybrowser"
+       fi
+else
+       display "Install Browser Switchboard to make MyBrowser the default browser"
+fi
+
+Browser vendors: setting yourself as the default browser without
+prompting the user first (via package maintainer scripts, for example)
+is strongly discouraged.

 
 
 Browser Switchboard and MicroB's browserd:
 
 
 Browser Switchboard and MicroB's browserd:

@@ -114,9 +185,9 @@ memory, but add a few seconds to MicroB's load time.
 Uninstalling Browser Switchboard:
 
 Remove the Browser Switchboard package using the Application Manager,
 Uninstalling Browser Switchboard:
 
 Remove the Browser Switchboard package using the Application Manager,

-and everything should be back to normal.  A reboot may be necessary for
-changes to take effect -- if you experience problems, try restarting
-your device first.
+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:
 
 
 Compiling Browser Switchboard:

@@ -125,7 +196,7 @@ 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
 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, hildon-dev,
+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:
 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:

@@ -135,12 +206,15 @@ SDK$ cd browser-switchboard-X.Y
 
 4. Compile:
 
 
 4. Compile:
 

-SDK$ make
-SDK$ make -C config-ui
+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
+If you want the standalone config application instead of the Control

 Panel plugin, do 
 Panel plugin, do 

-SDK$ make -C config-ui hildon-app
+SDK$ make -C config-ui diablo-hildon-app

 instead.
 
 If you're using the Scratchbox2-based SDK+, you want
 instead.
 
 If you're using the Scratchbox2-based SDK+, you want

@@ -184,10 +258,10 @@ 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.maemo.org.  You can get a copy of the current development version by
 cloning the repository:
 

-$ git clone https://git.maemo.org/projects/browser-switch
+$ git clone http://git.maemo.org/projects/browser-switch

 
 or you can browse the source using gitweb
 
 or you can browse the source using gitweb

-(https://git.maemo.org/projects/browser-switch/?p=browser-switch;a=summary).
+(http://git.maemo.org/projects/browser-switch/?p=browser-switch;a=summary).

 
 
 Maintainer:
 
 
 Maintainer: