Patch #754022: Greatly enhanced webbrowser.py.

Author: birkenfeld

Diff for: Doc/lib/libwebbrowser.tex

@@ -6,9 +6,8 @@ \section{\module{webbrowser} ---
 \moduleauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
 \sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
 
-The \module{webbrowser} module provides a very high-level interface to
-allow displaying Web-based documents to users.  The controller objects
-are easy to use and are platform-independent.  Under most
+The \module{webbrowser} module provides a high-level interface to
+allow displaying Web-based documents to users. Under most
 circumstances, simply calling the \function{open()} function from this
 module will do the right thing.
 
@@ -17,19 +16,26 @@ \section{\module{webbrowser} ---
 display isn't available.  If text-mode browsers are used, the calling
 process will block until the user exits the browser.
 
-Under \UNIX, if the environment variable \envvar{BROWSER} exists, it
+If the environment variable \envvar{BROWSER} exists, it
 is interpreted to override the platform default list of browsers, as a
-colon-separated list of browsers to try in order.  When the value of
+os.pathsep-separated list of browsers to try in order.  When the value of
 a list part contains the string \code{\%s}, then it is interpreted as
 a literal browser command line to be used with the argument URL
 substituted for the \code{\%s}; if the part does not contain
 \code{\%s}, it is simply interpreted as the name of the browser to
 launch.
 
-For non-\UNIX{} platforms, or when X11 browsers are available on
+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 browser to maintain its own window on
-the display.
+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: \programopt{-n} opens the URL in a new browser window,
+if possible; \programopt{-t} opens the URL in a new browser page ("tab"). The
+options are, naturally, mutually exclusive.
 
 The following exception is defined:
 
@@ -40,15 +46,24 @@ \section{\module{webbrowser} ---
 The following functions are defined:
 
 \begin{funcdesc}{open}{url\optional{, new=0}\optional{, autoraise=1}}
-  Display \var{url} using the default browser.  If \var{new} is true,
-  a new browser window is opened if possible.  If \var{autoraise} is
+  Display \var{url} using the default browser. If \var{new} is 0, the
+  \var{url} is opened in the same browser window.  If \var{new} is 1,
+  a new browser window is opened if possible.  If \var{new} is 2,
+  a new browser page ("tab") is opened if possible.  If \var{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).
+
 \end{funcdesc}
 
-\begin{funcdesc}{open_new}{url}
+\begin{funcdesc}{open_new_win}{url}
   Open \var{url} in a new window of the default browser, if possible,
-  otherwise, open \var{url} in the only browser window.
+  otherwise, open \var{url} in the only browser window.  Alias
+  \function{open_new}.
+\end{funcdesc}
+
+\begin{funcdesc}{open_new_tab}{url}
+  Open \var{url} in a new page ("tab") of the default browser, if possible,
+  otherwise equivalent to \function{open_new_win}.
 \end{funcdesc}
 
 \begin{funcdesc}{get}{\optional{name}}
@@ -67,7 +82,7 @@ \section{\module{webbrowser} ---
 
   This entry point is only useful if you plan to either set the
   \envvar{BROWSER} variable or call \function{get} with a nonempty
-  argument matching the name of a handler you declare.  
+  argument matching the name of a handler you declare.
 \end{funcdesc}
 
 A number of browser types are predefined.  This table gives the type
@@ -76,16 +91,24 @@ \section{\module{webbrowser} ---
 in this module.
 
 \begin{tableiii}{l|l|c}{code}{Type Name}{Class Name}{Notes}
-  \lineiii{'mozilla'}{\class{Netscape('mozilla')}}{}
-  \lineiii{'netscape'}{\class{Netscape('netscape')}}{}
-  \lineiii{'mosaic'}{\class{GenericBrowser('mosaic \%s \&')}}{}
+  \lineiii{'mozilla'}{\class{Mozilla('mozilla')}}{}
+  \lineiii{'firefox'}{\class{Mozilla('mozilla')}}{}
+  \lineiii{'netscape'}{\class{Mozilla('netscape')}}{}
+  \lineiii{'galeon'}{\class{Galeon('galeon')}}{}
+  \lineiii{'epiphany'}{\class{Galeon('epiphany')}}{}
+  \lineiii{'skipstone'}{\class{GenericBrowser('skipstone \%s \&')}}{}
+  \lineiii{'konqueror'}{\class{Konqueror()}}{(1)}
   \lineiii{'kfm'}{\class{Konqueror()}}{(1)}
+  \lineiii{'mosaic'}{\class{GenericBrowser('mosaic \%s \&')}}{}
+  \lineiii{'opera'}{\class{Opera()}}{}
   \lineiii{'grail'}{\class{Grail()}}{}
   \lineiii{'links'}{\class{GenericBrowser('links \%s')}}{}
+  \lineiii{'elinks'}{\class{Elinks('elinks')}}{}
   \lineiii{'lynx'}{\class{GenericBrowser('lynx \%s')}}{}
   \lineiii{'w3m'}{\class{GenericBrowser('w3m \%s')}}{}
   \lineiii{'windows-default'}{\class{WindowsDefault}}{(2)}
   \lineiii{'internet-config'}{\class{InternetConfig}}{(3)}
+  \lineiii{'macosx'}{\class{MacOSX('default')}}{(4)}
 \end{tableiii}
 
 \noindent
@@ -101,13 +124,15 @@ \section{\module{webbrowser} ---
 implementation selects the best strategy for running Konqueror.
 
 \item[(2)]
-Only on Windows platforms; requires the common
-extension modules \module{win32api} and \module{win32con}.
+Only on Windows platforms.
 
 \item[(3)]
 Only on MacOS platforms; requires the standard MacPython \module{ic}
 module, described in the \citetitle[../mac/module-ic.html]{Macintosh
 Library Modules} manual.
+
+\item[(4)]
+Only on MacOS X platform.
 \end{description}
 
 
@@ -117,12 +142,18 @@ \subsection{Browser Controller Objects \label{browser-controllers}}
 module-level convenience functions:
 
 \begin{funcdesc}{open}{url\optional{, new}}
-  Display \var{url} using the browser handled by this controller.  If
-  \var{new} is true, a new browser window is opened if possible.
+  Display \var{url} using the browser handled by this controller.
+  If \var{new} is 1, a new browser window is opened if possible.
+  If \var{new} is 2, a new browser page ("tab") is opened if possible.
 \end{funcdesc}
 
-\begin{funcdesc}{open_new}{url}
+\begin{funcdesc}{open_new_win}{url}
   Open \var{url} in a new window of the browser handled by this
   controller, if possible, otherwise, open \var{url} in the only
-  browser window.
+  browser window.  Alias \function{open_new}.
+\end{funcdesc}
+
+\begin{funcdesc}{open_new_tab}{url}
+  Open \var{url} in a new page ("tab") of the browser handled by this
+  controller, if possible, otherwise equivalent to \function{open_new_win}.
 \end{funcdesc}