,.
                               ;:::
            ,  _ .___mouseHole_;:::_web_proxy___. __, .


                      ... rewrite web pages
                       ... run little apps
                        ... crossite ajax
                         ... persistence
                          ... all that!

= about mouseHole =

MouseHole is a personal web proxy written in Ruby designed to be simple to
script.  Scripts can rewrite the web as you view it, altering content and
behavior as you browse.  Basically, it's an alternative to Greasemonkey,
which does similar things from inside the Firefox web browser.

Believe it or not, though, MouseHole does a lot more than that.
Here's a taste of what you'll be seeing:


= running mouseHole =

MouseHole can either intrude completely upon your browsing experience or you
can keep it off in the outskirts, for whenever you've got a second to duck into
that little crack in the wall.  You can run it on one machine and use it
wherever, allowing whomever you want to poke their head in.

The underlying ideas are always the same, though.

* [1] Start MouseHole.
* [2] Visit http://127.0.0.1:3704/ to view your settings.
* [3] Set MouseHole as your web proxy.
* [4] Install user scripts.
* [5] Or, write your own.


== starting mouseHole ==

To start using mouseHole, simply run the script. On Windows, click on
mouseHole.exe.  On other operating systems, run `ruby bin/mouseHole' from inside the
unpacked mouseHole directory.  A text window should popup showing that
mouseHole is started.

You can pass in the hostname and port number you'd like to run MouseHole on.

* mouseHole 203.203.203.203 to run on publicly accessible IP 203.203.203.203.
* mouseHole 127.0.0.1 5300 to run on a different port on localhost.

If your Web access itself is through a proxy, set the HTTP_PROXY environment
variable to the IP:PORT of that proxy.


== the doorway ==

Visit the hostname and port you choose above in your browser.  Normally, this
will be http://127.0.0.1:3704/.  The doorway will appear.  A page with a bit
of mouseHole-related graffitis.  (Once you get the proxy setup, you'll be able
to use http://mh/ or http://mouse.hole/ instead of the IP:PORT.)

The doorway lets you configure the scripts you have installed.  There's not
much to it.  You can turn scripts on and off.  Or you can tell it what sites it
can or can't control.  The doorway will also let you know if a script has been
loaded or if it has errors.


== setting mouseHole as proxy ==

This is the moment of decision.  Will you use mouseHole for your whole browser
experience?  Or will you use it only occassionally?  Or would you like to be
able to turn it on and off at will?


=== using mouseHole exclusively ===

If you're using Firefox, open the Preferences window.  Select the General tab.
Click the Connection Settings button. Activate the Manual Proxy Configuration
settings.  Fill in MouseHole's hostname and port.  (Again, the default is
127.0.0.1 and port 3704.)

If you're on OS X and want to use it to proxy all Safari traffic, go to the
Network preference pane (in System Preferences), select Web Proxy, enter
127.0.0.1 as address and 3704 as port.


=== speeding up with lighttpd or apache2 ===

If you want to go robust, you can run MouseHole through LightTPD/FastCGI (a
free web server) or Apache2/mod_ruby (also free).  The LightTPD seems to work
better for most people, so (if you're on Linux or OSX) give it a try.

You'll need LightTPD, FastCGI, and FCGI-Ruby installed.  Once all are installed,
fire it all up with:

  mouseHole -s lighttpd

You can pass in all the typical commandline options as well, if you like.

  mouseHole -s lighttpd --no-tidy 127.0.0.1 3704

Logs for script errors are stored in ~/.mouseHole/log.

If you'd like to run Apache2, be sure you have Apache2 and mod_ruby installed.
Then, get it started with:

  mouseHole -s apache2

To stop Apache:

  apachectl -f ~/.mouseHole/temp/apache/httpd.conf -k stop

=== occasional mouseHole ===

Firefox has a few useful extensions for managing proxies.

* [http://addons.mozilla.org/extensions/moreinfo.php?id=648 ProxyButton] which
adds a button to your toolbar. The button turns proxying on and off.

* [http://addons.mozilla.org/extensions/moreinfo.php?id=125 SwitchProxy] adds a
toolbar, a context menu and/or a status bar menu for switching between several
proxies.  The status bar menu is especially handy as it is small, but displays
the name of your current proxy, which you can right-click on to change.


=== using proxyLike ===

ProxyLike is a mouseHole user script which lets you pass URLs into mouseHole
for rewriting on a case-by-case.  To install ProxyLike, you'll need to use
mouseHole as your proxy for a bit.  Once you've got mouseHole running as your
proxy (described above), visit
http://www.whytheluckystiff.net/mouseHole/proxylike.user.rb.
mouseHole will guide you through the installation.

You can now turn off your proxy settings in your browser.  Pass URLs into
ProxyLike by prefixing the URL with your mouseHole IP:PORT.

* http://127.0.0.1:3704/http:/google.com will run Google through mouseHole.
* http://127.0.0.1:3704/http:/hoodwink.d/onslaught will view Hoodwink'd
Onslaught through mouseHole.

You can also install scripts through ProxyLike. If you have it installed, you
can upgrade ProxyLike with:

  http://127.0.0.1:3704/http:/www.whytheluckystiff.net/mouseHole/proxylike.user.rb.


== install user scripts ==

To install a script, simply visit an existing script and MouseHole will
auto-detect this and prompt you for installation.

At this time, there is no way to install a script sitting on your hard drive
(because file:// URLs don't go through proxies) without throwing it in
.mouseHole/userScripts and restarting MouseHole or uploading the script to a
remote server. (1.2 and up detects new scripts in .mouseHole/userScripts and
refreshes them as you edit it.)

A list of known MouseHole scripts is available at UserScripts.

== Making Your Own Scripts ==

For help in writing your own script, see 
http://mousehole.rubyforge.org/wiki/wiki.pl?Editing_MouseHole_Scripts.

For debugging purposes, you can visit http://localhost:3704/mouseHole/database
to view a database dump of MouseHole.