doc/remote.txt

   1 Managing remote ELinks instances
   2 --------------------------------
   3
   4 Some programs provide the ability to pass URIs to external programs.  When
   5 stumbling upon a reference to a page you want to see, it is sometimes a kludge
   6 to copy and paste it into ELinks.  This is where -remote can be a nifty
   7 solution.
   8
   9 When invoking ELinks with the -remote argument, it does not start a new
  10 instance, but instead connects to an already running ELinks, making it
  11 possible to control that ELinks instance. The -remote command line switch
  12 takes a command consisting of the action to invoke and any parameters to the
  13 action. Commands must begin with a nonempty sequence of ASCII alphabetic
  14 characters followed by optional whitespace and an opening parenthesis. They
  15 must end with a closing parenthesis optionally followed by whitespace. Here is
  16 an example for opening freshmeat.net in a new tab:
  17
  18         $ elinks -remote "openURL(http://freshmeat.net/, new-tab)"
  19
  20 When running this command in a terminal, you will see a small delay before
  21 ELinks returns. If no running instance was found, it will return with the
  22 error message:
  23
  24         ELinks: No remote session to connect to.
  25
  26 All URLs passed to the openURL() commands can be URL prefixes, so the command
  27 above could have simply used ``openURL(fm, new-tab)''.
  28
  29
  30 Limitations and outstanding issues
  31 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  32
  33 Remote control is implemented using the intercommunication socket created in
  34 ~/.elinks/, so the command has to be run on the same machine as the instance
  35 you want to control; or put differently: the two ELinkses need to share a file
  36 system that supports socket files, which rules out usage of -remote over NFS.
  37 This also implies that the ELinks instance you want to control should be
  38 started without passing -no-home nor -no-connect.
  39
  40 The built-in -remote support is to some degree compatible with the one Mozilla
  41 provides (http://www.mozilla.org/unix/remote.html), but with some homebrew
  42 extensions added and few unsupported features. All the supported actions are
  43 documented below.
  44
  45 Under some circumstances, use of the -remote control can cause ELinks to
  46 become unresponsive. This is cause by the current key press and mouse focus
  47 being redirected to new tabs or dialogs opened by the -remote action.
  48
  49
  50 Remote Actions
  51 ~~~~~~~~~~~~~~
  52
  53 The command syntax is case-insensitive. For readability, we use the casing in
  54 the listing of supported commands.
  55
  56 .Mozilla `-remote` compatible commands.
  57 `-------------------------------`----------------------------------------------
  58 Command                         Description
  59 -------------------------------------------------------------------------------
  60 ping()                          Checks for existence of a remote instance.    \
  61                                 Makes it possible for scripts to query if     \
  62                                 remote controlling is possible.
  63 openURL()                       Prompts for a URL in current tab by opening   \
  64                                 the Goto dialog.
  65 openURL(URL)                    Open the passed URL in current tab.
  66 openURL(URL, new-tab)           Opens the passed URL in new tab.
  67 openURL(URL, new-window)        Opens the passed URL in new window.
  68 xfeDoCommand(openBrowser)       Opens an ELinks instance in a new window.     \
  69                                 This ELinks instance will connect to the      \
  70                                 already running one.
  71 -------------------------------------------------------------------------------
  72
  73 .ELinks extensions.
  74 `-------------------------------`----------------------------------------------
  75 Command                         Description
  76 -------------------------------------------------------------------------------
  77 addBookmark(URL)                Bookmarks the passed URL.
  78 infoBox(text)                   Show text in a message box.
  79 -------------------------------------------------------------------------------
  80
  81 `-remote` can also take a list of URLs without an explicit action, in which case
  82 the URL arguments will be opened in new tabs in the remote instance. For
  83 example, by running:
  84
  85         $ elinks -remote slashdot.org fm g:elinks
  86
  87 new tabs containing `slashdot.org`, `freshmeat.net` and a Google search of elinks
  88 will be opened.