\HeaderA{browseURL}{Load URL into a WWW Browser}{browseURL}
\keyword{file}{browseURL}
\begin{Description}\relax
Load a given URL into a WWW browser.
\end{Description}
\begin{Usage}
\begin{verbatim}
browseURL(url, browser = getOption("browser"), encodeIfNeeded = FALSE)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{url}] a non-empty character string giving the URL to be loaded.
\item[\code{browser}] a non-empty character string giving the name of the
program to be used as hypertext browser.  It should be in the PATH,
or a full path specified.  Alternatively, an \R{} function to be
called to invoke the browser.

\item[\code{encodeIfNeeded}] Should the URL be encoded by
\code{\LinkA{URLencode}{URLencode}} before passing to the browser?  This is not
needed (and might be harmful) if the \code{browser} program/function
itself does encoding, and can be harmful for \code{file://} URLs on some
systems and for \code{http://} URLs passed to some CGI applications.
Fortunately, most URLs do not need encoding.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
The default browser is set by option \code{"browser"}, in turn set by
the environment variable \env{R\_BROWSER} which is by default set
in file \file{\var{\LinkA{R\_HOME}{R.Rul.HOME}}/etc/Renviron} to a choice made manually or
automatically when \R{} was configured.  (See \code{\LinkA{Startup}{Startup}} for
where to override that default value.)

If \code{browser} supports remote control and \R{} knows how to perform
it, the URL is opened in any already running browser or a new one if
necessary.  This mechanism currently is available for browsers which
support the \code{"-remote openURL(...)"} interface (which includes
Opera 5/6, Mozilla >= 0.9.5 and Mozilla Firefox),
Galeon, KDE konqueror (via kfmclient) and the GNOME interface to
Mozilla.  Netscape 7.0 and Opera 7 behave slightly differently,
and you will need
to open them first.  Note that the type of browser is determined from
its name, so this mechanism will only be used if the browser is
installed under its canonical name.

Because \code{"-remote"} will use any browser displaying on the X
server (whatever machine it is running on), the remote control
mechanism is only used if \code{DISPLAY} points to the local host.
This may not allow displaying more than one URL at a time from a
remote host.

It is the caller's responsibility to encode \code{url} if necessary
(see \code{\LinkA{URLencode}{URLencode}}).  This can be tricky for file URLs,
where the format accepted can depend on the browser and OS.
\end{Details}
\begin{Examples}
\begin{ExampleCode}
## Not run: 
## for KDE users who want to open files in a new tab
option(browser="kfmclient newTab") 
browseURL("http://www.r-project.org")
## End(Not run)\end{ExampleCode}
\end{Examples}

