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.  Here is an example for opening freshmeat.net in a new tab:
  14
  15         $ elinks -remote "openURL(http://freshmeat.net/, new-tab)"
  16
  17 When running this command in a terminal, you will see a small delay before
  18 ELinks returns. If no running instance was found, it will return with the
  19 error message:
  20
  21         ELinks: No remote session to connect to.
  22
  23 All URLs passed to the openURL() commands can be URL prefixes, so the command
  24 above could have simply used ``openURL(fm, new-tab)''.
  25
  26
  27 Limitations and outstanding issues
  28 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  29
  30 Remote control is implemented using the intercommunication socket created in
  31 ~/.elinks/, so the command has to be run on the same machine as the instance
  32 you want to control; or put differently: the two ELinkses need to share a file
  33 system that supports socket files, which rules out usage of -remote over NFS.
  34 This also implies that the ELinks instance you want to control should be
  35 started without passing -no-home nor -no-connect.
  36
  37 The built-in -remote support is to some degree compatible with the one Mozilla
  38 provides (http://www.mozilla.org/unix/remote.html), but with some homebrew
  39 extensions added and few unsupported features. All the supported actions are
  40 documented below.
  41
  42 Under some circumstances, use of the -remote control can cause ELinks to
  43 become unresponsive. This is cause by the current key press and mouse focus
  44 being redirected to new tabs or dialogs opened by the -remote action.
  45
  46
  47 Remote Actions
  48 ~~~~~~~~~~~~~~
  49
  50 The command syntax is case-insensitive. For readability, we use the casing in
  51 the listing of supported commands.
  52
  53 .Mozilla `-remote` compatible commands.
  54 `-------------------------------`----------------------------------------------
  55 Command                         Description
  56 -------------------------------------------------------------------------------
  57 ping()                          Checks for existence of a remote instance.    \
  58                                 Makes it possible for scripts to query if     \
  59                                 remote controlling is possible.
  60 openURL()                       Prompts for a URL in current tab by opening   \
  61                                 the Goto dialog.
  62 openURL(URL)                    Open the passed URL in current tab.
  63 openURL(URL, new-tab)           Opens the passed URL in new tab.
  64 openURL(URL, new-window)        Opens the passed URL in new window.
  65 xfeDoCommand(openBrowser)       Opens an ELinks instance in a new window.     \
  66                                 This ELinks instance will connect to the      \
  67                                 already running one.
  68 -------------------------------------------------------------------------------
  69
  70 .ELinks extensions.
  71 `-------------------------------`----------------------------------------------
  72 Command                         Description
  73 -------------------------------------------------------------------------------
  74 addBookmark(URL)                Bookmarks the passed URL.
  75 infoBox(text)                   Show text in a message box.
  76 -------------------------------------------------------------------------------
  77
  78 `-remote` can also take a list of URLs without an explicit action, in which case
  79 the URL arguments will be opened in new tabs in the remote instance. For
  80 example, by running:
  81
  82         $ elinks -remote slashdot.org fm g:elinks
  83
  84 new tabs containing `slashdot.org`, `freshmeat.net` and a Google search of elinks
  85 will be opened.