Merge with git+ssh://pasky.or.cz/srv/git/elinks.git
[elinks.git] / doc / urlshortcuts.txt
blob8b9a4955d7d45d473cb95a753efe840069c09e08
1 URL Shortcuts in ELinks
2 -----------------------
4 One extremely useful and convenient feature in ELinks, which may not be very
5 well known, is so-called URL rewriting.  If you give ELinks a URL (by passing it
6 on the command line, through the -remote magic device or, most frequently, by
7 typing it to the Goto URL dialog), it has the ability to mangle it in certain
8 ways before processing it.  This mangling is called URI rewriting.
11 What it does
12 ~~~~~~~~~~~~
14 The URI rewriting can expand certain URL shortcuts to complete URLs.  For
15 example, if you type 'sd' to the Goto URL dialog, it will be rewritten to:
17         http://www.slashdot.org/
19 first, and then loaded.  /.'s front page will be displayed.
21 Further, if you type 'g elinks' to the Goto URL dialog, it will be rewritten to:
23         http://www.google.com/search?q=elinks&btnG=Google+Search
25 and then loaded, therefore, a Google search for the keyword 'elinks' will be
26 performed.  Note that you can separate the 'g' by either a space or a colon, so
27 'g:elinks' will do the exact same thing.
29 A large number of those shortcuts are already defined for you.  You can browse
30 Protocols :: URI Rewriting :: Dumb/Smart prefixes in the Options Manager for
31 a complete listing of already defined shortcuts (press the [Info] button on
32 a shortcut to see what it will be rewritten to).  See below for details on how
33 to enable or disable this rewriting and how to define your own shortcuts.
36 How it works
37 ~~~~~~~~~~~~
39 All the URI rewriting can be controlled by options in the 'protocol.rewrite'
40 option tree.
42 In the case of 'sd', a URI rewriting mechanism called 'dumb prefixes' is used.
43 If protocol.rewrite.enable-dumb is true, ELinks looks at the contents of the
44 protocol.rewrite.dumb.* tree, and if it finds option protocol.rewrite.dumb.sd,
45 it will use its value as the target URI.
47 Therefore, more generally speaking, if ELinks looks at
48 protocol.rewrite.dumb.<typed_string>, and if it exists, will replace the
49 entered URI with it.  These dumb prefixes can be used as a kind of alternative
50 bookmark systen - if you want to have fast access to a certain site and you
51 don't want to spend a while navigating the bookmarks manager, you can just fire
52 up the Goto URL dialog, type the shortcut and there you go.
54 A dumb prefix can contain '%c', which will be replaced by the URI of the current
55 document.  This is used, for example, in the 'arc' dumb-prefix, which provides
56 a shortcut to the Wayback machine at archive.org.
58 In the case of 'g', a slightly different URI rewriting mechanism called 'smart
59 prefixes' is used.  If protocol.rewrite.enable-smart is true, ELinks looks at
60 the contents of the protocol.rewrite.smart tree and, if it finds option
61 protocol.rewrite.smart.g, it will use its value as the target URI.
63 The difference is that the smart prefixes can take arguments and reference them
64 in the target URI.  As with dumb prefixes, '%c' in the URI means the current
65 address.  Additionally, '%s' will be substituted by the whole string following
66 the prefix ('elinks' in the 'g' example above; '%s' is by far the most
67 frequently used expansion), while you can reference individual space-separated
68 arguments with the codes '%0' thru '%9'.  Finally, if you want a plain % to the
69 resulting URI, use '%%'.
71 Note that the prefix searched in the protocol.rewrite.smart tree is everything
72 in the typed address up to the first space or colon (so 'bug:123' and 'bug 123'
73 are identical).  These prefixes are generally useful for searching anything very
74 fast - be it Google ('g:foo', 'gi:foo', 'gr:foo', ...), ELinks Bugzilla bugs
75 ('bug:1234'), the RFC database ('cr:foo'), or the Czech-English dictionary
76 ('czen:foo').  The only limit is your imagination.
79 Alternative URI rewriting mechanisms
80 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
82 In the past, before this was implemented, Lua scripting did the job.  And you
83 still have complete control over the URI in the internal scripting goto-url
84 hook.  The advantages are clear - you get complete control over the URI and you
85 can do many more interesting things with it.  For example, there are some very
86 advanced CVSweb and Debian package database URI prefixes implemented in the
87 sample Lua hooks file.  The one disadvantage to this is that you must have Lua
88 scripting enabled in order to make use of it, and many users don't have Lua
89 installed.