suzanne.soy/racket
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Attempt to properly documents the `external-browser' mess.

Browse Source 
Hopefully fixing PR10900.
This commit is contained in:
Eli Barzilay 2010-05-08 23:32:54 -04:00
parent 155cc4ac05
commit d9917b27a0
1 changed files with 26 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

46
collects/net/scribblings/sendurl.scrbl
View File

@ -29,16 +29,18 @@ use an intermediate redirecting file due to a bug in IE7.)
Under Mac OS X, @scheme[send-url] runs @exec{osascript} to start the Under Mac OS X, @scheme[send-url] runs @exec{osascript} to start the
user's chosen browser. user's chosen browser.
Under Unix, @scheme[send-url] uses the value of the Under Unix, @scheme[send-url] uses a user-preference, or when none is
@scheme[external-browser] parameter to select a browser. set, it will look for a known browser. See the description of
@scheme[external-browser] for details.
The @scheme[url] string is usually escaped to avoid dangerous shell The @scheme[url] string is usually escaped to avoid dangerous shell
characters (quotations, dollar signs, backslashes, and non-ASCII). characters (quotations, dollar signs, backslashes, and non-ASCII). Note
Note that it is a good idea to encode URLs before passing them to this that it is a good idea to encode URLs before passing them to this
function. Also note that the encoding is meant to make the URL work function.
in shell quotes: URLs can still hold characters like @litchar{#},
@litchar{?}, and @litchar{&}, so the @scheme[external-browser] should On all platforms, @scheme[external-browser] parameter can be set to a
use quotations.} procedure to override the above behavior --- the procedure will be
called with the @scheme[url] string.}
@defproc[(send-url/file [path path-string?] [separate-window? any/c #t] @defproc[(send-url/file [path path-string?] [separate-window? any/c #t]
[#:fragment fragment (or/c string? false/c) #f] [#:fragment fragment (or/c string? false/c) #f]
@ -71,20 +73,24 @@ old temporary files are still deleted as described above.}
@defparam[external-browser cmd browser-preference?]{ @defparam[external-browser cmd browser-preference?]{
A parameter that, under Unix, determines the browser started A parameter that can hold a procedure to override how a browser is
@scheme[send-url]. started, or @scheme[#f] to use the default platform-dependent command.
The parameter is initialized to the value of the Under Unix, the command that is used depends on the
@scheme['external-browser] preference. @scheme['external-browser] preference. If the preference is unset,
@scheme[send-url] uses the first of the browsers from
@scheme[unix-browser-list] for which the executable is found.
Otherwise, the preference should hold a symbol indicating a known
browser (from the @scheme[unix-browser-list]), or it a pair of a prefix
and a suffix string that are concatenated around the @scheme[url] string
to make up a shell command to run. In addition, the
@scheme[external-browser] paremeter can be set to one of these values,
and @scheme[send-url] will use it instead of the preference value.
The parameter value can be any of the symbols in Note that the URL is encoded to make it work inside shell double-quotes:
@scheme[unix-browser-list], @scheme[#f] to indicate that the URLs can still hold characters like @litchar{#}, @litchar{?}, and
preference is unset, or a pair of strings. If the preference is @litchar{&}, so if the @scheme[external-browser] is set to a pair of
unset, @scheme[send-url] uses the first of the browsers from prefix/suffix strings, they should use double quotes around the url.
@scheme[unix-browser-list] for which the executable is found. If the
parameter is a pair of strings, then a command line is constructed by
concatenating in order the first string, the URL string, and the
second string.
If the preferred or default browser can't be launched, If the preferred or default browser can't be launched,
@scheme[send-url] fails. See @scheme[get-preference] and @scheme[send-url] fails. See @scheme[get-preference] and