Move the 3k reST doc tree in place.

1 files changed, 199 insertions, 0 deletions

diff --git a/Doc/library/webbrowser.rst b/Doc/library/webbrowser.rst
new file mode 100644
index 0000000..c243f7c
--- /dev/null
+++ b/Doc/library/webbrowser.rst
@@ -0,0 +1,199 @@
+
+:mod:`webbrowser` --- Convenient Web-browser controller
+=======================================================
+
+.. module:: webbrowser
+   :synopsis: Easy-to-use controller for Web browsers.
+.. moduleauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
+.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
+
+
+The :mod:`webbrowser` module provides a high-level interface to allow displaying
+Web-based documents to users. Under most circumstances, simply calling the
+:func:`open` function from this module will do the right thing.
+
+Under Unix, graphical browsers are preferred under X11, but text-mode browsers
+will be used if graphical browsers are not available or an X11 display isn't
+available.  If text-mode browsers are used, the calling process will block until
+the user exits the browser.
+
+If the environment variable :envvar:`BROWSER` exists, it is interpreted to
+override the platform default list of browsers, as a os.pathsep-separated list
+of browsers to try in order.  When the value of a list part contains the string
+``%s``, then it is  interpreted as a literal browser command line to be used
+with the argument URL substituted for ``%s``; if the part does not contain
+``%s``, it is simply interpreted as the name of the browser to launch.
+
+For non-Unix platforms, or when a remote browser is available on Unix, the
+controlling process will not wait for the user to finish with the browser, but
+allow the remote browser to maintain its own windows on the display.  If remote
+browsers are not available on Unix, the controlling process will launch a new
+browser and wait.
+
+The script :program:`webbrowser` can be used as a command-line interface for the
+module. It accepts an URL as the argument. It accepts the following optional
+parameters: :option:`-n` opens the URL in a new browser window, if possible;
+:option:`-t` opens the URL in a new browser page ("tab"). The options are,
+naturally, mutually exclusive.
+
+The following exception is defined:
+
+
+.. exception:: Error
+
+   Exception raised when a browser control error occurs.
+
+The following functions are defined:
+
+
+.. function:: open(url[, new=0[, autoraise=1]])
+
+   Display *url* using the default browser. If *new* is 0, the *url* is opened in
+   the same browser window if possible.  If *new* is 1, a new browser window is
+   opened if possible.  If *new* is 2, a new browser page ("tab") is opened if
+   possible.  If *autoraise* is true, the window is raised if possible (note that
+   under many window managers this will occur regardless of the setting of this
+   variable).
+
+   .. versionchanged:: 2.5
+      *new* can now be 2.
+
+
+.. function:: open_new(url)
+
+   Open *url* in a new window of the default browser, if possible, otherwise, open
+   *url* in the only browser window.
+
+
+.. function:: open_new_tab(url)
+
+   Open *url* in a new page ("tab") of the default browser, if possible, otherwise
+   equivalent to :func:`open_new`.
+
+   .. versionadded:: 2.5
+
+
+.. function:: get([name])
+
+   Return a controller object for the browser type *name*.  If *name* is empty,
+   return a controller for a default browser appropriate to the caller's
+   environment.
+
+
+.. function:: register(name, constructor[, instance])
+
+   Register the browser type *name*.  Once a browser type is registered, the
+   :func:`get` function can return a controller for that browser type.  If
+   *instance* is not provided, or is ``None``, *constructor* will be called without
+   parameters to create an instance when needed.  If *instance* is provided,
+   *constructor* will never be called, and may be ``None``.
+
+   This entry point is only useful if you plan to either set the :envvar:`BROWSER`
+   variable or call :func:`get` with a nonempty argument matching the name of a
+   handler you declare.
+
+A number of browser types are predefined.  This table gives the type names that
+may be passed to the :func:`get` function and the corresponding instantiations
+for the controller classes, all defined in this module.
+
++-----------------------+-----------------------------------------+-------+
+| Type Name             | Class Name                              | Notes |
++=======================+=========================================+=======+
+| ``'mozilla'``         | :class:`Mozilla('mozilla')`             |       |
++-----------------------+-----------------------------------------+-------+
+| ``'firefox'``         | :class:`Mozilla('mozilla')`             |       |
++-----------------------+-----------------------------------------+-------+
+| ``'netscape'``        | :class:`Mozilla('netscape')`            |       |
++-----------------------+-----------------------------------------+-------+
+| ``'galeon'``          | :class:`Galeon('galeon')`               |       |
++-----------------------+-----------------------------------------+-------+
+| ``'epiphany'``        | :class:`Galeon('epiphany')`             |       |
++-----------------------+-----------------------------------------+-------+
+| ``'skipstone'``       | :class:`BackgroundBrowser('skipstone')` |       |
++-----------------------+-----------------------------------------+-------+
+| ``'kfmclient'``       | :class:`Konqueror()`                    | \(1)  |
++-----------------------+-----------------------------------------+-------+
+| ``'konqueror'``       | :class:`Konqueror()`                    | \(1)  |
++-----------------------+-----------------------------------------+-------+
+| ``'kfm'``             | :class:`Konqueror()`                    | \(1)  |
++-----------------------+-----------------------------------------+-------+
+| ``'mosaic'``          | :class:`BackgroundBrowser('mosaic')`    |       |
++-----------------------+-----------------------------------------+-------+
+| ``'opera'``           | :class:`Opera()`                        |       |
++-----------------------+-----------------------------------------+-------+
+| ``'grail'``           | :class:`Grail()`                        |       |
++-----------------------+-----------------------------------------+-------+
+| ``'links'``           | :class:`GenericBrowser('links')`        |       |
++-----------------------+-----------------------------------------+-------+
+| ``'elinks'``          | :class:`Elinks('elinks')`               |       |
++-----------------------+-----------------------------------------+-------+
+| ``'lynx'``            | :class:`GenericBrowser('lynx')`         |       |
++-----------------------+-----------------------------------------+-------+
+| ``'w3m'``             | :class:`GenericBrowser('w3m')`          |       |
++-----------------------+-----------------------------------------+-------+
+| ``'windows-default'`` | :class:`WindowsDefault`                 | \(2)  |
++-----------------------+-----------------------------------------+-------+
+| ``'internet-config'`` | :class:`InternetConfig`                 | \(3)  |
++-----------------------+-----------------------------------------+-------+
+| ``'macosx'``          | :class:`MacOSX('default')`              | \(4)  |
++-----------------------+-----------------------------------------+-------+
+
+Notes:
+
+(1)
+   "Konqueror" is the file manager for the KDE desktop environment for Unix, and
+   only makes sense to use if KDE is running.  Some way of reliably detecting KDE
+   would be nice; the :envvar:`KDEDIR` variable is not sufficient.  Note also that
+   the name "kfm" is used even when using the :program:`konqueror` command with KDE
+   2 --- the implementation selects the best strategy for running Konqueror.
+
+(2)
+   Only on Windows platforms.
+
+(3)
+   Only on MacOS platforms; requires the standard MacPython :mod:`ic` module.
+
+(4)
+   Only on MacOS X platform.
+
+Here are some simple examples::
+
+   url = 'http://www.python.org'
+
+   # Open URL in a new tab, if a browser window is already open. 
+   webbrowser.open_new_tab(url + '/doc')
+
+   # Open URL in new window, raising the window if possible.
+   webbrowser.open_new(url)
+
+
+.. _browser-controllers:
+
+Browser Controller Objects
+--------------------------
+
+Browser controllers provide two methods which parallel two of the module-level
+convenience functions:
+
+
+.. method:: controller.open(url[, new[, autoraise=1]])
+
+   Display *url* using the browser handled by this controller. If *new* is 1, a new
+   browser window is opened if possible. If *new* is 2, a new browser page ("tab")
+   is opened if possible.
+
+
+.. method:: controller.open_new(url)
+
+   Open *url* in a new window of the browser handled by this controller, if
+   possible, otherwise, open *url* in the only browser window.  Alias
+   :func:`open_new`.
+
+
+.. method:: controller.open_new_tab(url)
+
+   Open *url* in a new page ("tab") of the browser handled by this controller, if
+   possible, otherwise equivalent to :func:`open_new`.
+
+   .. versionadded:: 2.5
+