~ubuntu-branches/ubuntu/feisty/elinks/feisty-updates

« back to all changes in this revision

Viewing changes to doc/html/perl-hooks.html

  • Committer: Bazaar Package Importer
  • Author(s): Martin Pitt
  • Date: 2006-06-30 08:57:43 UTC
  • mfrom: (1.1.2 upstream)
  • Revision ID: james.westby@ubuntu.com-20060630085743-l81fgbw9dehvl1ds
Tags: 0.11.1-1ubuntu1
* Merge to Debian unstable.
* Removed gnutls12 porting, this is upstream now.
* Only Ubuntu changes left:
  - Killed type-handling.
  - Add X-Ubuntu-Gettext-Domain to .desktop files.

Show diffs side-by-side

added added

removed removed

Lines of Context:
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>
25
25
</ul>
35
35
<hr />
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>
46
41
<p>
47
42
</p>
48
43
<hr />
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
52
 
values:</p>
 
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>
53
47
<pre>
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 &quot;bug&quot; 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 &quot;ip&quot; prefix?
61
56
        language:   english   # &quot;bf nl en&quot; still works, but now &quot;bf nl&quot; does too
62
57
        news:       msnbc     # Agency to use for &quot;news&quot; and &quot;n&quot; prefixes
78
73
<p>
79
74
</p>
80
75
<hr />
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
 
79
powerful.</p>
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-&gt;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
97
 
prefix, usually).</p>
 
83
<p>These routines do a name-&gt;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
 
86
appropriate URL.</p>
 
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>
98
91
<dl>
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 />
100
93
</dt>
101
94
<dd>
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>
103
96
</dd>
104
 
<p></p></dl>
105
 
<dl>
 
97
<p></p>
106
98
<dt><strong><a name="item_web_search_3a">Web search:</a></strong><br />
107
99
</dt>
108
100
<dl>
139
131
</dl>
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
149
 
found.</p>
150
138
</dl>
151
139
<dl>
152
140
<dt><strong><a name="item_news_agencies_3a">News agencies:</a></strong><br />
185
173
</dl>
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>
193
180
</dl>
194
181
<dl>
195
182
<dt><strong><a name="item_locators_3a">Locators:</a></strong><br />
223
210
</dt>
224
211
<dt><strong><a name="item_gna_21_3a_gna">Gna!:                               <strong>gna</strong></a></strong><br />
225
212
</dt>
 
213
<dt><strong><a name="item_berlios_3a_bl_or_berlios">BerliOS:                            <strong>bl</strong> or <strong>berlios</strong></a></strong><br />
 
214
</dt>
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 />
227
216
</dt>
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 />
231
220
</dt>
232
221
<dt><strong><a name="item_internet_public_library_3a_ipl">Internet Public Library:            <strong>ipl</strong></a></strong><br />
233
222
</dt>
 
223
<dt><strong><a name="item_vt">VIM Tips:                           <strong>vt</strong> (# or search)</a></strong><br />
 
224
</dt>
 
225
<dt><strong><a name="item_urban_dictionary_3a_urbandict_or_ud__3cword_3e">Urban Dictionary:                   <strong>urbandict</strong> or <strong>ud</strong> &lt;<em>word</em>&gt;</a></strong><br />
 
226
</dt>
234
227
</dl>
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
239
230
document.</p>
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 />
249
239
</dt>
250
240
<dd>
254
244
<dt><strong><a name="item_mirrordot_3a">MirrorDot:</a></strong><br />
255
245
</dt>
256
246
<dd>
257
 
<strong>md</strong> or <strong>mirrordot</strong>
 
247
<strong>md</strong> or <strong>mirrordot</strong> &lt;<em>URL</em>&gt;
258
248
</dd>
259
249
<p></p>
260
250
<dt><strong><a name="item_coral_cache_3a">Coral cache:</a></strong><br />
261
251
</dt>
262
252
<dd>
263
 
<strong>cc</strong>, <strong>coral</strong>, or <strong>nyud</strong> (requires URL)
 
253
<strong>cc</strong>, <strong>coral</strong>, or <strong>nyud</strong> &lt;<em>URL</em>&gt;
264
254
</dd>
265
255
<p></p>
266
256
<dt><strong><a name="item_altavista_babelfish_3a">AltaVista Babelfish:</a></strong><br />
267
257
</dt>
268
258
<dd>
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> &lt;<em>from</em>&gt; &lt;<em>to</em>&gt;
 
260
</dd>
 
261
<dd>
 
262
<p>``babelfish german english'' or ``bf de en''</p>
270
263
</dd>
271
264
<p></p>
272
265
<dt><strong><a name="item_w3c_page_validators_3a">W3C page validators:</a></strong><br />
273
266
</dt>
274
267
<dd>
275
 
<strong>vhtml</strong> or <strong>vcss</strong> (current url or specified)
 
268
<strong>vhtml</strong> or <strong>vcss</strong> &lt;<em>URL</em>&gt; (or current url)
276
269
</dd>
277
270
<p></p>
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 />
290
283
</dt>
291
284
<dd>
292
 
<strong>dia</strong> &lt;dialect&gt; (current url or specified)
 
285
<strong>dia</strong> &lt;<em>dialect</em>&gt; &lt;<em>URL</em>&gt; (or current url)
293
286
</dd>
294
287
<dd>
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>
296
289
</dd>
297
 
<p></p></dl>
 
290
<p></p>
 
291
<dt><strong><a name="item_sender_3a">Sender:</a></strong><br />
 
292
</dt>
 
293
<dd>
 
294
<strong>send</strong>
 
295
</dd>
 
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> &lt;<em>application</em>&gt;'.</p>
 
299
<dt><strong><a name="item_dictionary_3a">Dictionary:</a></strong><br />
 
300
</dt>
 
301
<dd>
 
302
<strong>dict</strong>, <strong>d</strong>, <strong>def</strong>, or <strong>define</strong> &lt;<em>word</em>&gt;
 
303
</dd>
 
304
<p></p>
 
305
<dt><strong><a name="item_google_site_search">Google site search</a></strong><br />
 
306
</dt>
 
307
<dd>
 
308
<strong>ss</strong> &lt;<em>domain</em>&gt; &lt;<em>string</em>&gt;
 
309
</dd>
 
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 />
 
315
</dt>
 
316
</dl>
298
317
<p>
299
318
</p>
300
319
<hr />
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
306
324
target URL.</p>
308
326
<dt><strong><a name="item_bork_21_bork_21_bork_21">Bork! Bork! Bork!</a></strong><br />
309
327
</dt>
310
328
<dd>
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.
312
330
</dd>
313
331
<p></p>
314
332
<dt><strong><a name="item_nntp_over_google">NNTP over Google</a></strong><br />
315
333
</dt>
316
334
<dd>
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.
318
336
</dd>
319
337
<p></p></dl>
320
338
<p>
321
339
</p>
322
340
<hr />
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
328
 
document.</p>
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
331
348
available.</p>
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 />
337
354
</dt>
338
355
<dd>
339
 
Kills Slashdot's Advertisements.
 
356
Kills Slashdot's Advertisements.  (This one is disabled due to weird behavior
 
357
with fragments.)
340
358
</dd>
341
 
<p><em>This rewrite rule is <strong>DISABLED</strong> due to weird behavior with fragments.</em></p>
342
 
<dl>
 
359
<p></p>
343
360
<dt><strong><a name="item_obvious_google_tips_annihilator">Obvious Google Tips Annihilator</a></strong><br />
344
361
</dt>
345
362
<dd>
346
 
Kills some Google tips which are obvious anyway to any ELinks user.
 
363
Kills some irritating Google tips.
347
364
</dd>
348
365
<p></p>
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 />
356
373
</dt>
357
374
<dd>
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...
360
376
</dd>
361
377
<p></p>
362
378
<dt><strong><a name="item_source_readability_improvements">Source readability improvements</a></strong><br />
363
379
</dt>
364
380
<dd>
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.
366
384
</dd>
367
385
<p></p></dl>
368
 
</dl>
369
386
<p>
370
387
</p>
371
388
<hr />
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>
387
404
<p>
388
405
</p>
389
406
<hr />
390
 
<h1><a name="onquit_actions">ON-QUIT ACTIONS</a></h1>
 
407
<h1><a name="quit_hook">QUIT HOOK</a></h1>
391
408
<p>The Perl hooks can also perform various actions when ELinks quits.  These can
392
409
be things like retouching the just saved ``information files'', or doing some fun
393
410
stuff.</p>
405
422
<dt><strong><a name="item_words_of_wisdom">Words of Wisdom</a></strong><br />
406
423
</dt>
407
424
<dd>
408
 
A few words of wisdom from ELinks the Sage.  (Prints a fortune. ;-)
 
425
A few words of wisdom from ELinks the Sage.
409
426
</dd>
410
427
<p></p></dl>
411
428
<p>