SMJS (user): Add documentation on the available interfaces

Note that the interfaces may change at any time (which is the reason that
I've put off committing this file for so long).

contrib/smjs/README

@@ -0,0 +1,248 @@
+Methods
+-------
+
+do_file(path)
+
+   Load and evaluate the file with the given path (string). For example:
+
+      do_file("/home/me/.elinks/hooks.js");
+
+   will reload your hooks file.
+
+
+elinks.alert(message)
+
+   Display the given message (string) in a message box. For example:
+
+      elinks.alert("Hello, world!");
+
+   will display a friendly greeting.
+
+
+elinks.execute(command)
+
+   Execute the given command (string) on the current terminal. For example:
+
+      var quoted_uri = "'" + elinks.location.replace(/'/g, "'\\''") + "'";
+      elinks.execute("firefox " + quoted_uri);
+
+   will run Firefox with the URI of the current document.
+
+   Note: one must be very careful with elinks.execute, because depending
+   on the OS, the command may be subject to interpretation by a command shell
+   language. When constructing the command string, be sure to quote any
+   dubious parts (such as the URI of the current document, as above).
+
+
+elinks.load_uri(uri, callback)
+
+   Load the given URI (string). When the URI completes loading, ELinks calls
+   the given callback (function). The callback is passed the cache object
+   that corresponds to the URI. For example:
+
+     elinks.load_uri("http://www.eldar.org/cgi-bin/fortune.pl?text_format=yes",
+                     function (cached) { elinks.alert(cached.content); });
+
+   displays a fortune.
+
+
+Properties
+----------
+
+elinks.home (string)
+
+   ELinks's 'home' directory, where it stores its configuration files.
+   Read-only. For example,
+
+      do_file(elinks.home + "hooks.js");
+
+   will reload your hooks file.
+
+
+elinks.location (string)
+
+   The URI of the currently open document. This can be read to get a string
+   with the URI or set to load a different document. For example,
+
+      elinks.location = elinks.location + "/..";
+
+   will go up a directory (if the URI doesn't end in a file).
+
+
+elinks.bookmarks (hash)
+
+   This is a hash, the elements of which correspond to the bookmarks.
+   One can delve into the bookmarks hierarchy in a reasonably nifty
+   fashion, just by using standard ECMAScript syntax:
+
+      elinks.bookmarks.x.children.y.children.z.children.foo.title
+
+   gets the title of the bookmark titled 'foo' under the folder 'z',
+   which is a subfolder of 'y', which is a subfolder of 'x'.
+
+   A bookmark object has these properties:
+
+   item.title (string)
+
+      This is the title of the bookmark. It can be read and set.
+
+   item.url (string)
+
+      This is the URI of the bookmark. It can be read and set.
+
+   item.children (hash)
+
+      This is a hash, the elements of which are the bookmarks that
+      are children to the item. It is read-only.
+
+
+elinks.globhist (hash)
+
+   This is a hash, the elements of which correspond to entries in ELinks's
+   global history. The hash is indexed by URI. For example,
+
+      elinks.globhist["file:///"]
+
+   will get you the history item for your root directory.
+
+   A history item has these properties:
+
+   item.title (string)
+
+      This is the title of the history item. It can be read and set.
+
+   item.url (string)
+
+      This is the URI of the history item. It can be read and set.
+
+   item.last_visit (number)
+
+      This is the UNIX time of the last visit time for the item. UNIX time
+      is the number of seconds that have passed between the UNIX epoch (which
+      is 1970-01-01 00:00:00 UTC) and the represented time. Note that this is
+      _seconds_ since the epoch, whereas ECMAScript likes to use _milliseconds_
+      since the epoch. This property can be set or read.
+
+
+elinks.keybinding (hash)
+
+   This is a hash, the elements of which correspond to ELinks's keymaps.
+   Currently, there are three: elinks.keybinding.main, elinks.keybinding.edit,
+   and elinks.keybinding.menu. These elements are also hashes, the elements of
+   which correspond to bindings. For example, elinks.keymaps.main["q"] is
+   the binding to the 'q' key in the main map. These bindings can be red,
+   to get the name of the action to which the key is bound, or set, either
+   to a string with the name of the ELinks action or to a function, which will
+   thenceforth be called when the key is pressed. For example,
+
+      elinks.keymaps.main["!"] = function () { elinks.alert("Hello!"); }
+
+   binds the '!' key in the main map to a function that displays a friendly
+   alert.
+
+      elinks.keymaps.main["/"] = "search-typeahead-text";
+
+   changes the '/' key to use the nice typeahead search function instead of
+   opening that ugly old search dialogue box.
+
+
+Hooks
+-----
+
+These are actually properties, but a special case: one assigns functions
+to them, which functions are called at certain events.
+
+Note that the default hooks file assigns functions that provide a mechanism
+to register multiple functions to each hook. When these default hooks are
+called, they iterate over all functions that are registered to them, calling
+each one in serial.
+
+If you want to register a preformat_html hook, for example,
+the preferred way to do so is not this:
+
+   elinks.preformat_html = foo;
+
+but rather this:
+
+   elinks.preformat_html_hooks.push(foo);
+
+which adds foo to an array of functions, over which the default
+elinks.preformat_html function will iterate.
+
+If any function in that array returns false, the default hook
+will stop iteration, not calling any more handlers. This applies
+to all of the default hooks.
+
+
+elinks.preformat_html(cached, vs)
+
+   This function is called every time a document is loaded, before the document
+   is actually rendered, to give scripts the opportunity to modify it. The
+   first parameter is the cache object and the second is the view_state object
+   (documented below). As explained above, it is preferred to add your hook
+   to elinks.preformat_html_hooks rather than to assign it to
+   elinks.preformat_html.
+
+
+elinks.goto_url_hook(url)
+
+   This function is called every time the user enters something
+   in the Go to URL box. The url (string) can be modified or not,
+   and the returned string is substituted for what the user entered.
+   If the value false is returned, the URL is not changed and further hooks
+   in ELinks are not run. As explained above, it is preferred to add your hook
+   to elinks.goto_url_hooks rather than to assign it to elinks.goto_url_hook.
+
+
+elinks.follow_url_hook(url)
+
+   This function is called every time the user tries to load a document,
+   whether by following a link, by entering a URI in the Go to URL box,
+   by setting elinks.location, or whatever. It behaves the same as
+   elinks.goto_url_hook above. As explained above, it is preferred to add your
+   hook to elinks.follow_url_hooks rather than to assign it to
+   elinks.follow_url_hook.
+
+Other Objects
+-------------
+
+cache
+
+  The cache object mentioned in the descriptions of elinks.load_uri and
+  elinks.preformat_html is a wrapper for the internal ELinks cache object.
+  Its properties are:
+
+  cached.content (string)
+
+     This is the content received from the server. It can be read and set.
+
+  cached.type (string)
+
+     This is the MIME type of the cache entry. It can be read and set.
+
+  cached.length (number)
+
+     This is the length of cached.content. It is read-only.
+
+  cached.head (string)
+
+     This is the header received from the server. It can be read and set.
+
+  cached.uri (string)
+
+     This is the URI of the cache entry. It is read-only.
+
+view_state
+
+   The view_state object mentioned in the description of elinks.preformat_html
+   is a wrapper for the internal ELinks view_state object. The view state holds
+   information on how the current document is being displayed.
+
+   vs.plain (boolean)
+
+      Whether the current document is rendered as HTML or displayed
+      as plaintext. This can be read and set.
+
+   vs.uri (string)
+
+      This is the URI of the current document. It is read-only.