Style changes
[browser-switch] / README
1 BROWSER SWITCHBOARD
2
3 Browser Switchboard is a program which allows you to choose which
4 browser to use as the default browser. It supports MicroB, Tear,
5 Fennec/Mobile Firefox, and Midori out of the box, and can also be used
6 to launch MicroB without having browserd running.
7
8
9 Download:
10 Binary packages and source are available for download from the project
11 page on garage.maemo.org: https://garage.maemo.org/frs/?group_id=1159
12
13
14 Quick Start:
15 1. Download the binary package: browser-switchboard_X.Y-Z_all.deb
16 (where X.Y-Z is the version number, of course).
17 2. Install the package using the Application Manager (open the
18 Application Manager, then select Application->Install from file in the
19 menu).
20
21 If Tear (http://talk.maemo.org/showthread.php?t=28539) is installed,
22 it should now be the default browser, meaning that links in most
23 applications, locally-saved web pages opened in the file manager, and
24 entries in the Web sidebar panel should now open in Tear.  If Tear isn't
25 installed, MicroB will be used as the default browser; keep reading to
26 see how to change the default browser to something else.
27
28 MicroB can always be opened via the Web menu entry in the applications
29 panel (located in the Internet menu by default), or by running "browser"
30 from the shell.  While MicroB is open, it will receive all links from
31 other applications; closing MicroB will restore your chosen default
32 browser.
33
34 Some users have reported that a restart may be necessary to ensure that
35 Browser Switchboard is functioning.  If you experience trouble after
36 installing the package, try rebooting your device first.
37
38
39 Changing the Default Browser:
40
41 By default, Tear is used as the default browser if installed (otherwise
42 MicroB is the default browser).  To change this behavior, you need to
43 create a configuration file (from the shell for now -- a configuration
44 UI is in the works).  From a shell on your device (xterm, SSH, or
45 similar), run the following (where $ is your prompt, not something you
46 type):
47
48 $ cat > $HOME/.config/browser-switchboard <<EOF
49 default_browser = "your_browser"
50 EOF
51
52 where your_browser can be one of "tear", "microb", "fennec", "midori",
53 or "other" (see below for more on the "other" option).  You can of
54 course also edit the $HOME/.config/browser-switchboard file with your
55 favorite text editor.
56
57 To restore the default behavior, just delete the config file:
58
59 $ rm $HOME/.config/browser-switchboard
60
61
62 Advanced Configuration:
63
64 Here's a more complete sample configuration file:
65
66 # BEGIN SAMPLE CONFIG FILE
67 # This is a comment
68 # continuous_mode: 0 -- close after handling a request; 1 -- run
69 # continuously in the background
70 continuous_mode = 0
71 # default_browser: "tear", "microb", "fennec", "midori", or "other"
72 default_browser = "tear"
73 # other_browser_cmd: If default browser is "other", what program
74 # to run (%s will be replaced by URI)
75 #other_browser_cmd = "some_browser %s"
76 # END SAMPLE CONFIG FILE
77
78 Lines beginning with # characters are comments and are ignored by the
79 script.
80
81 In continuous mode, Browser Switchboard keeps running in the background
82 instead of closing after handling each request.  This saves roughly two
83 seconds of startup time for each link (on my N800 running Diablo), but
84 costs you about 2 MB extra memory.  Continuous mode is disabled by
85 default; set continuous_mode to 1 to enable.
86
87 The "tear", "microb", "fennec", and "midori" options for default_browser
88 should be self-explanatory.
89
90 If the default browser is "other", Browser Switchboard will run the
91 program specified in other_browser_cmd as the default browser, with a
92 URI replacing the %s on the command line; for example, if
93 other_browser_cmd is set to "some_browser %s", and Browser Switchboard
94 is asked to load http://www.google.com/, it will perform the equivalent
95 of typing in 
96
97 $ some_browser 'http://www.google.com/'
98
99 at a shell.
100
101
102 Browser Switchboard and MicroB's browserd:
103
104 MicroB uses a background process called browserd to decrease its load
105 time.  Browser Switchboard knows how to launch MicroB without having
106 browserd running all the time, so if you don't plan on using MicroB
107 often, you can disable browserd (for example, by using the
108 maemo-control-services control panel applet available in Maemo Extras to
109 disable tablet-browser-daemon).  This will save you about 1 MB of
110 memory, but add a few seconds to MicroB's load time.
111
112
113 Uninstalling Browser Switchboard:
114
115 Remove the Browser Switchboard package using the Application Manager,
116 and everything should be back to normal.  A reboot may be necessary for
117 changes to take effect -- if you experience problems, try restarting
118 your device first.
119
120
121 Manual Installation:
122
123 If for some reason you don't want to use the binary package to install
124 Browser Switchboard, you can install it by hand:
125 1. Make sure you have the necessary dependencies installed: packages
126 python2.5, python2.5-dbus, and python-2.5-gobject.
127 2. Download the source tarball: browser-switchboard_X.Y.orig.tar.gz
128 3. Unpack the source tarball on your device:
129
130 $ tar -xvzf browser-switchboard_X.Y.orig.tar.gz
131 $ cd browser-switchboard-X.Y
132
133 4. As root on your device, copy the browser-switchboard script to
134 /usr/bin:
135
136 # cp browser-switchboard /usr/bin
137
138 (where # represents a root shell prompt).
139 5. As root on your device, copy com.nokia.osso_browser.service to
140 /usr/share/dbus-1/services, moving the existing file out of the way
141 first:
142
143 # mv /usr/share/dbus-1/services/com.nokia.osso_browser.service
144   /usr/share/dbus-1/services/com.nokia.osso_browser.bak
145 # cp com.nokia.osso_browser.service /usr/share/dbus-1/services
146
147 6. (optional) If you want running "browser" from the command line to
148 work as intended, copy browser to /usr/bin, moving the original symlink
149 out of the way first:
150
151 # mv /usr/bin/browser /usr/bin/browser.bak
152 # cp browser /usr/bin
153
154 To uninstall, remove the files you installed, restore the backup copies,
155 and reboot your device.
156
157
158 Bug Reports and Patches:
159
160 Bug reports, patches, and suggested improvements can either be sent to
161 the maintainer via email (see below) or posted in the Tear thread on the
162 talk.maemo.org forums (http://talk.maemo.org/showthread.php?t=28539).
163
164
165 Source Code Repository:
166
167 Source code is hosted in a Git (http://git-scm.com/) repository on
168 git.maemo.org.  You can get a copy of the current development version by
169 cloning the repository:
170
171 $ git clone https://git.maemo.org/projects/browser-switch
172
173 or you can browse the source using gitweb
174 (https://git.maemo.org/projects/browser-switch/?p=browser-switch;a=summary).
175
176
177 Maintainer:
178
179 Steven Luo <steven+maemo@steven676.net> is the primary maintainer, with
180 Jason Simpson (the original developer) assisting in development.
181
182
183 License:
184
185 Browser Switchboard is available under the terms of the GNU General
186 Public License (GPL), version 2 or later (see the file LICENSE in the
187 source).