15
15
<li><a href="#name">NAME</a></li>
16
16
<li><a href="#description">DESCRIPTION</a></li>
17
17
<li><a href="#configuration_file">CONFIGURATION FILE</a></li>
18
<li><a href="#goto_url_rewrites">GOTO URL REWRITES</a></li>
19
<li><a href="#global_url_rewrites">GLOBAL URL REWRITES</a></li>
20
<li><a href="#html_rewriting_rules">HTML REWRITING RULES</a></li>
21
<li><a href="#smart_proxy_usage">SMART PROXY USAGE</a></li>
22
<li><a href="#onquit_actions">ON-QUIT ACTIONS</a></li>
18
<li><a href="#goto_url_hook">GOTO URL HOOK</a></li>
19
<li><a href="#follow_url_hook">FOLLOW URL HOOK</a></li>
20
<li><a href="#pre_format_html_hook">PRE FORMAT HTML HOOK</a></li>
21
<li><a href="#proxy_for_hook">PROXY FOR HOOK</a></li>
22
<li><a href="#quit_hook">QUIT HOOK</a></li>
23
23
<li><a href="#see_also">SEE ALSO</a></li>
24
24
<li><a href="#authors">AUTHORS</a></li>
36
36
<h1><a name="description">DESCRIPTION</a></h1>
37
37
<p>This file contains the Perl hooks for the ELinks text WWW browser.</p>
38
<p>These hooks can alter the browser's behavior in various ways; probably the most
39
popular is processing the user input in the Goto URL dialog box and rewriting
40
it in various ways (like the builtin URL prefix capability, but much more
41
powerful and flexible).</p>
42
<p>Another popular capability of the hooks is to rewrite the HTML source of a page
43
before it is rendered, usually to get rid of ads and/or make the web page more
44
ELinks-friendly. The hooks also allow you to fine-tune the proxying rules, can
45
show a fortune when ELinks exits, and more!</p>
38
<p>These hooks change the browser's behavior in various ways. They allow
39
shortcuts to be used in the Goto URL dialog, modifying the source of a page,
40
proxy handling, and other things such as displaying a fortune at exit.</p>
49
44
<h1><a name="configuration_file">CONFIGURATION FILE</a></h1>
50
<p>The hooks file reads its configuration from <em>~/.elinks/config.pl</em>.
51
Note that the following is only an example, and does not contain the default
45
<p>This hooks file reads its configuration from <em>~/.elinks/config.pl</em>.
46
The following is an example of the configuration file:</p>
54
48
bork: yep # BORKify Google?
55
49
collapse: okay # Collapse all XBEL bookmark folders on exit?
56
50
email: # Set to show one's own bugs with the "bug" prefix.
51
external: wget # Send the current URL to this application.
57
52
fortune: elinks # *fortune*, *elinks* tip, or *none* on quit?
58
53
googlebeta: hell no # I miss DejaNews...
59
gotosearch: not yet # Don't use this yet. It's broken. Don't use it at all, actually.
54
gotosearch: why not # Anything not a URL in the Goto URL dialog...
60
55
ipv6: sure # IPV4 or 6 address blocks with "ip" prefix?
61
56
language: english # "bf nl en" still works, but now "bf nl" does too
62
57
news: msnbc # Agency to use for "news" and "n" prefixes
81
<h1><a name="goto_url_rewrites">GOTO URL REWRITES</a></h1>
82
<p>This is a summary of all the available rewrites of what you type into the Goto
83
URL box. They are similar in spirit to the builtin URL rewrites, but more
84
flexible and immensely more powerful.</p>
76
<h1><a name="goto_url_hook">GOTO URL HOOK</a></h1>
77
<p>This is a summary of the shortcuts defined in this file for use in the Goto URL
78
dialog. They are similar to the builtin URL prefixes, but more flexible and
85
80
<p><em>Developer's usage</em>: The function <em>goto_url_hook</em> is called when the hook is
86
81
triggered, taking the target URL and current URL as its two arguments. It
87
82
returns the final target URL.</p>
88
<p>In this section, name mapping routines are described. They are probably of no
89
interest to regular hooks users, only for hooks developers.</p>
90
<p>These routines do a name->URL mapping - e.g. the <em>goto_url_hook()</em> described
91
above maps a certain prefix to <a href="#item_google"><code>google</code></a> and then asks the <em>search()</em> mapping
92
routine described below to map the <a href="#item_google"><code>google</code></a> string to an appropriate URL.</p>
93
<p>The mappings themselves should be obvious and are not described here.
94
Interested readers can look them up themselves in the <em>hooks.pl</em> file.</p>
95
<p>There are generally two URLs for each name, one for a direct shortcut jump and
96
another for a search on the given site (if any string is specified after the
83
<p>These routines do a name->URL mapping - for example, the <em>goto_url_hook()</em>
84
described above maps a certain prefix to <a href="#item_google"><code>google</code></a> and then asks the
85
<em>search()</em> mapping routine described below to map the <a href="#item_google"><code>google</code></a> string to an
87
<p>There are generally two URLs for each name. One to go to the particular URL's
88
main page, and another for a search on the given site (if any string is
89
specified after the prefix). A few of these prefixes will change their
90
behavior depending on the URL currently beung displayed in the browser.</p>
99
<dt><strong><a name="item_miscellaneous_shortcuts_3a">Miscellaneous shortcuts:</a></strong><br />
92
<dt><strong><a name="item_bugmenot_3a">Bugmenot:</a></strong><br />
102
<strong>bugmenot</strong>, <strong>bored</strong>, <strong>random</strong>, <strong>bofh</strong>, <strong>xyzzy</strong>, <strong>jack</strong> or <strong>handey</strong>
95
<strong>bugmenot</strong> or <strong>bn</strong>
106
98
<dt><strong><a name="item_web_search_3a">Web search:</a></strong><br />
140
132
<p>default engine: <strong>search</strong>, <strong>find</strong>, <strong>www</strong>, <strong>web</strong>, <strong>s</strong>, <strong>f</strong>, <strong>go</strong></p>
141
133
<p>The <em>%search_engines</em> hash maps each engine name to two URLs, <em>home</em> and
142
<em>search</em>. In case of <em>search</em>, the query is appended to the mapped URL.</p>
143
<p><strong>!bork!</strong> string in the URL is substitued for an optional <em>xx-bork</em>
144
localization specifier, but only in the <a href="#item_google"><code>google</code></a> mapping.</p>
134
<em>search</em>. With <em>search</em>, the query is appended to the URL.</p>
145
135
<p>The search engines mapping is done by the <em>search()</em> function, taking the
146
136
search engine name as its first parameter and optional search string as its
147
137
second parameter. It returns the mapped target URL.</p>
148
<p><em>Google</em> is used as the default search engine if the given engine is not
152
140
<dt><strong><a name="item_news_agencies_3a">News agencies:</a></strong><br />
186
174
<p>default agency: <strong>n</strong>, <strong>news</strong></p>
187
175
<p>The <em>%news_servers</em> hash maps each engine name to two URLs, <em>home</em> and
188
<em>search</em>. In case of <em>search</em>, the query is appended to the mapped URL.</p>
176
<em>search</em>. With <em>search</em>, the query is appended to the mapped URL.</p>
189
177
<p>The news servers mapping is done by the <em>news()</em> function, taking the search
190
178
engine name as its first parameter and optional search string as its second
191
179
parameter. It returns the mapped target URL.</p>
192
<p><em>BBC</em> is used as the default search engine if the given engine is not found.</p>
195
182
<dt><strong><a name="item_locators_3a">Locators:</a></strong><br />
224
211
<dt><strong><a name="item_gna_21_3a_gna">Gna!: <strong>gna</strong></a></strong><br />
213
<dt><strong><a name="item_berlios_3a_bl_or_berlios">BerliOS: <strong>bl</strong> or <strong>berlios</strong></a></strong><br />
226
215
<dt><strong><a name="item_uptime">Netcraft Uptime Survey: <strong>whatis</strong> or <strong>uptime</strong> (current url or specified)</a></strong><br />
228
217
<dt><strong><a name="item_who_27s_alive_and_who_27s_dead_3a_wanted_2c_dead_o">Who's Alive and Who's Dead: Wanted, <strong>dead</strong> or <strong>alive</strong>!</a></strong><br />
232
221
<dt><strong><a name="item_internet_public_library_3a_ipl">Internet Public Library: <strong>ipl</strong></a></strong><br />
223
<dt><strong><a name="item_vt">VIM Tips: <strong>vt</strong> (# or search)</a></strong><br />
225
<dt><strong><a name="item_urban_dictionary_3a_urbandict_or_ud__3cword_3e">Urban Dictionary: <strong>urbandict</strong> or <strong>ud</strong> <<em>word</em>></a></strong><br />
235
228
<p>The <em>%locators</em> hash maps each engine name to two URLs, <em>home</em> and <em>search</em>.</p>
236
<p><strong>!bork!</strong> string in the URL is substitued for an optional <em>xx-bork</em>
237
localization specifier (for any mappings in this case, not just <a href="#item_google"><code>google</code></a>).</p>
238
229
<p><strong>!current!</strong> string in the URL is substitued for the URL of the current
240
231
<p><strong>!query!</strong> string in the <em>search</em> URL is substitued for the search string. If
244
235
engine name as its first parameter, optional search string as its second
245
236
parameter and the current document's URL as its third parameter. It returns
246
237
the mapped target URL.</p>
247
<p>An error is produced if the given locator is not found.</p>
248
238
<dt><strong><a name="item_google_groups_3a">Google Groups:</a></strong><br />
254
244
<dt><strong><a name="item_mirrordot_3a">MirrorDot:</a></strong><br />
257
<strong>md</strong> or <strong>mirrordot</strong>
247
<strong>md</strong> or <strong>mirrordot</strong> <<em>URL</em>>
260
250
<dt><strong><a name="item_coral_cache_3a">Coral cache:</a></strong><br />
263
<strong>cc</strong>, <strong>coral</strong>, or <strong>nyud</strong> (requires URL)
253
<strong>cc</strong>, <strong>coral</strong>, or <strong>nyud</strong> <<em>URL</em>>
266
256
<dt><strong><a name="item_altavista_babelfish_3a">AltaVista Babelfish:</a></strong><br />
269
<strong>babelfish</strong>, <strong>babel</strong>, <strong>bf</strong>, <strong>translate</strong>, <strong>trans</strong>, or <strong>b</strong>
259
<strong>babelfish</strong>, <strong>babel</strong>, <strong>bf</strong>, <strong>translate</strong>, <strong>trans</strong>, or <strong>b</strong> <<em>from</em>> <<em>to</em>>
262
<p>``babelfish german english'' or ``bf de en''</p>
272
265
<dt><strong><a name="item_w3c_page_validators_3a">W3C page validators:</a></strong><br />
275
<strong>vhtml</strong> or <strong>vcss</strong> (current url or specified)
268
<strong>vhtml</strong> or <strong>vcss</strong> <<em>URL</em>> (or current url)
278
271
<dt><strong><a name="item_elinks_3a">ELinks:</a></strong><br />
289
282
<dt><strong><a name="item_the_dialectizer_3a">The Dialectizer:</a></strong><br />
292
<strong>dia</strong> <dialect> (current url or specified)
285
<strong>dia</strong> <<em>dialect</em>> <<em>URL</em>> (or current url)
295
288
<p>Dialects: <em>redneck</em>, <em>jive</em>, <em>cockney</em>, <em>fudd</em>, <em>bork</em>, <em>moron</em>, <em>piglatin</em>, or <em>hacker</em></p>
291
<dt><strong><a name="item_sender_3a">Sender:</a></strong><br />
294
<strong>send</strong>
296
<p>Send the current URL to the application specified by the configuration variable
297
'<em>external</em>'. Optionally, override this by specifying the application as in
298
'<em>send</em> <<em>application</em>>'.</p>
299
<dt><strong><a name="item_dictionary_3a">Dictionary:</a></strong><br />
302
<strong>dict</strong>, <strong>d</strong>, <strong>def</strong>, or <strong>define</strong> <<em>word</em>>
305
<dt><strong><a name="item_google_site_search">Google site search</a></strong><br />
308
<strong>ss</strong> <<em>domain</em>> <<em>string</em>>
310
<p>Use Google to search the current site or a specified site. If a domain is not
311
given, use the current one.</p>
312
<dt><strong><a name="item_anything_not_a_prefix_2c_url_2c_or_local_file_will">Anything not a prefix, URL, or local file will be treated as a search
313
using the search engine defined by the 'search' configuration option if
314
'gotosearch' is set to some variation of 'yes'.</a></strong><br />
301
<h1><a name="global_url_rewrites">GLOBAL URL REWRITES</a></h1>
302
<p>These rewrites happen everytime ELinks is about to follow an URL and load it,
303
so this is an order of magnitude more powerful than the Goto URL rewrites.</p>
320
<h1><a name="follow_url_hook">FOLLOW URL HOOK</a></h1>
321
<p>These hooks effect a URL before ELinks has a chance to load it.</p>
304
322
<p><em>Developer's usage</em>: The function <em>follow_url_hook</em> is called when the hook
305
323
is triggered, taking the target URL as its only argument. It returns the final
308
326
<dt><strong><a name="item_bork_21_bork_21_bork_21">Bork! Bork! Bork!</a></strong><br />
311
Rewrites many <em>google.com</em> URLs to use the phenomenal <em>xx-bork</em> localization.
329
Rewrites many <em>google.com</em> URLs.
314
332
<dt><strong><a name="item_nntp_over_google">NNTP over Google</a></strong><br />
317
Rewrites any <em>nntp:</em> or <em>news:</em> URLs to Google Groups HTTP URLs.
335
Translates any <em>nntp:</em> or <em>news:</em> URLs to Google Groups HTTP URLs.
323
<h1><a name="html_rewriting_rules">HTML REWRITING RULES</a></h1>
341
<h1><a name="pre_format_html_hook">PRE FORMAT HTML HOOK</a></h1>
324
342
<p>When an HTML document is downloaded and is about to undergo the final
325
rendering, the rewrites described here are done first. This is frequently used
326
to get rid of ads, but also various ELinks-unfriendly HTML code and HTML
327
snippets which are irrelevant to ELinks but can obfuscate the rendered
329
<p>Note well that these rules are applied <strong>only</strong> before the final rendering, not
343
rendering, this hook is called. This is frequently used to get rid of ads, but
344
also various ELinks-unfriendly HTML code and HTML snippets which are irrelevant
345
to ELinks but can obfuscate the rendered document.</p>
346
<p>Note that these hooks are applied <strong>only</strong> before the final rendering, not
330
347
before the gradual re-renderings which happen when only part of the document is
332
349
<p><em>Developer's usage</em>: The function <em>pre_format_html_hook</em> is called when the
336
353
<dt><strong><a name="item_slashdot_sanitation">Slashdot Sanitation</a></strong><br />
339
Kills Slashdot's Advertisements.
356
Kills Slashdot's Advertisements. (This one is disabled due to weird behavior
341
<p><em>This rewrite rule is <strong>DISABLED</strong> due to weird behavior with fragments.</em></p>
343
360
<dt><strong><a name="item_obvious_google_tips_annihilator">Obvious Google Tips Annihilator</a></strong><br />
346
Kills some Google tips which are obvious anyway to any ELinks user.
363
Kills some irritating Google tips.
349
366
<dt><strong><a name="item_sourceforge_adsmasher">SourceForge AdSmasher</a></strong><br />
355
372
<dt><strong><a name="item_gmail_27s_experience">Gmail's Experience</a></strong><br />
358
Gmail has obviously never met ELinks for it to suggest another browser for a
359
better Gmail experience.
375
Gmail has obviously never met ELinks...
362
378
<dt><strong><a name="item_source_readability_improvements">Source readability improvements</a></strong><br />
365
Rewrites some evil characters to entities and vice versa.
381
Rewrites some evil characters to entities and vice versa. These will be
382
disabled until such time as pre_format_html_hook only gets called for
383
content-type:text/html.
372
<h1><a name="smart_proxy_usage">SMART PROXY USAGE</a></h1>
389
<h1><a name="proxy_for_hook">PROXY FOR HOOK</a></h1>
373
390
<p>The Perl hooks are asked whether to use a proxy for a given URL (or what proxy
374
391
to actually use). You can use it if you don't want to use a proxy for certain
375
392
Intranet servers but you need to use it in order to get to the Internet, or if
376
you want to use some anonymizer for access to certain naughty sites.</p>
393
you want to use some anonymizer for access to certain sites.</p>
377
394
<p><em>Developer's usage</em>: The function <em>proxy_for_hook</em> is called when the hook is
378
395
triggered, taking the target URL as its only argument. It returns the proxy
379
396
URL, empty string to use no proxy or <em>undef</em> to use the default proxy URL.</p>