1% File src/library/utils/man/browseURL.Rd
2% Part of the R package, https://www.R-project.org
3% Copyright 1995-2018 R Core Team
4% Distributed under GPL 2 or later
5
6\name{browseURL}
7\alias{browseURL}
8\title{Load URL into an HTML Browser}
9\description{
10  Load a given URL into an HTML browser.
11}
12\usage{
13browseURL(url, browser = getOption("browser"),
14          encodeIfNeeded = FALSE)
15}
16\arguments{
17  \item{url}{a non-empty character string giving the URL to be loaded.
18   Some platforms also accept file paths.
19  }
20  \item{browser}{a non-empty character string giving the name of the
21    program to be used as the HTML browser.  It should be in the PATH,
22    or a full path specified.  Alternatively, an \R function to be
23    called to invoke the browser.
24
25    Under Windows \code{NULL} is also allowed (and is the default), and
26    implies that the file association mechanism will be used.
27  }
28  \item{encodeIfNeeded}{Should the URL be encoded by
29    \code{\link{URLencode}} before passing to the browser?  This is not
30    needed (and might be harmful) if the \code{browser} program/function
31    itself does encoding, and can be harmful for \samp{file://} URLs on some
32    systems and for \samp{http://} URLs passed to some CGI applications.
33    Fortunately, most URLs do not need encoding.}
34}
35\details{
36  \describe{
37    \item{On Unix-alikes:}{
38  The default browser is set by option \code{"browser"}, in turn set by
39  the environment variable \env{R_BROWSER} which is by default set in
40  file \file{\var{\link{R_HOME}}/etc/Renviron} to a choice
41  made manually or automatically when \R was configured.  (See
42  \code{\link{Startup}} for where to override that default value.)
43  To suppress showing URLs altogether, use the value \code{"false"}.
44
45  On many platforms it is best to set option \code{"browser"} to a
46  generic program/script and let that invoke the user's choice of
47  browser.  For example, on macOS use \command{open} and on many other
48  Unix-alikes use \command{xdg-open}.
49
50  If \code{browser} supports remote control and \R knows how to perform
51  it, the URL is opened in any already-running browser or a new one if
52  necessary.  This mechanism currently is available for browsers which
53  support the \code{"-remote openURL(...)"} interface (which includes
54  Mozilla and Opera), Galeon, KDE konqueror (\emph{via} kfmclient) and
55  the GNOME interface to Mozilla. (Firefox has dropped support, but
56  defaults to using an already-running browser.)  Note that the type of
57  browser is determined from its name, so this mechanism will only be
58  used if the browser is installed under its canonical name.
59
60  Because \code{"-remote"} will use any browser displaying on the X
61  server (whatever machine it is running on), the remote control
62  mechanism is only used if \code{DISPLAY} points to the local host.
63  This may not allow displaying more than one URL at a time from a
64  remote host.
65
66  It is the caller's responsibility to encode \code{url} if necessary
67  (see \code{\link{URLencode}}).
68
69  To suppress showing URLs altogether, set \code{browser = "false"}.
70
71  The behaviour for arguments \code{url} which are not URLs is
72  platform-dependent.  Some platforms accept absolute file paths; fewer
73  accept relative file paths.
74
75    }
76    \item{On Windows:}{
77  The default browser is set by option \code{"browser"}, in turn set by
78  the environment variable \env{R_BROWSER} if that is set, otherwise to
79  \code{NULL}.
80  To suppress showing URLs altogether, use the value \code{"false"}.
81
82  Some browsers have required \code{:} be replaced by \code{|} in file
83  paths: others do not accept that.  All seem to accept \code{\\} as a
84  path separator even though the RFC1738 standard requires \code{/}.
85
86  To suppress showing URLs altogether, set \code{browser = "false"}.
87    }
88  }% {describe}
89}
90
91\examples{
92\dontrun{
93## for KDE users who want to open files in a new tab
94options(browser = "kfmclient newTab")
95
96browseURL("https://www.r-project.org")
97
98## On Windows-only, something like
99browseURL("file://d:/R/R-2.5.1/doc/html/index.html",
100          browser = "C:/Program Files/Mozilla Firefox/firefox.exe")
101}}
102
103\section{URL schemes}{
104  Which URL schemes are accepted is platform-specific: expect
105  \samp{http://}, \samp{https://} and \samp{ftp://} to work, but
106  \samp{mailto:} may or may not (and if it does may not use the user's
107  preferred email client).
108
109  For the \samp{file://} scheme the format accepted (if any) can depend on
110  both browser and OS.
111}
112\keyword{file}
113