Patch #754022: Greatly enhanced webbrowser.py.
diff --git a/Doc/lib/libwebbrowser.tex b/Doc/lib/libwebbrowser.tex
index 285fcf5..42c7691 100644
--- a/Doc/lib/libwebbrowser.tex
+++ b/Doc/lib/libwebbrowser.tex
@@ -6,9 +6,8 @@
\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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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}