NAME

hooks.pl -- Perl hooks for the ELinks text WWW browser


DESCRIPTION

This file contains the Perl hooks for the ELinks text WWW browser.

These hooks can alter the browser's behavior in various ways; probably the most popular is processing the user input in the Goto URL dialog box and rewriting it in various ways (like the builtin URL prefix capability, but much more powerful and flexible).

Another popular capability of the hooks is to rewrite the HTML source of a page before it is rendered, usually to get rid of ads and/or make the web page more ELinks-friendly. The hooks also allow you to fine-tune the proxying rules, can show a fortune when ELinks exits, and more!


CONFIGURATION FILE

The hooks file reads its configuration from ~/.elinks/config.pl. Note that the following is only an example, and does not contain the default values:

        bork:       yep       # BORKify Google?
        collapse:   okay      # Collapse all XBEL bookmark folders on exit?
        email:                # Set to show one's own bugs with the "bug" prefix.
        fortune:    elinks    # *fortune*, *elinks* tip, or *none* on quit?
        googlebeta: hell no   # I miss DejaNews...
        gotosearch: not yet   # Don't use this yet.  It's broken.  Don't use it at all, actually.
        ipv6:       sure      # IPV4 or 6 address blocks with "ip" prefix?
        language:   english   # "bf nl en" still works, but now "bf nl" does too
        news:       msnbc     # Agency to use for "news" and "n" prefixes
        search:     elgoog    # Engine for (search|find|www|web|s|f|go) prefixes
        usenet:     google    # *google* or *standard* view for news:// URLs
        weather:    cnn       # Server for "weather" and "w" prefixes
        # news:    bbc, msnbc, cnn, fox, google, yahoo, reuters, eff, wired,
        #          slashdot, newsforge, usnews, newsci, discover, sciam
        # search:  elgoog, google, yahoo, ask jeeves, a9, altavista, msn, dmoz,
        #          dogpile, mamma, webcrawler, netscape, lycos, hotbot, excite
        # weather: weather underground, google, yahoo, cnn, accuweather,
        #          ask jeeves

Developer's usage: The function loadrc() takes a preference name as its single argument and returns either an empty string if it is not specified, yes for a true value (even if specified like sure or why not), no for a false value (even if like nah, off or 0), or the lowercased preference value (like cnn for weather: CNN).


GOTO URL REWRITES

This is a summary of all the available rewrites of what you type into the Goto URL box. They are similar in spirit to the builtin URL rewrites, but more flexible and immensely more powerful.

Developer's usage: The function goto_url_hook is called when the hook is triggered, taking the target URL and current URL as its two arguments. It returns the final target URL.

In this section, name mapping routines are described. They are probably of no interest to regular hooks users, only for hooks developers.

These routines do a name->URL mapping - e.g. the goto_url_hook() described above maps a certain prefix to google and then asks the search() mapping routine described below to map the google string to an appropriate URL.

The mappings themselves should be obvious and are not described here. Interested readers can look them up themselves in the hooks.pl file.

There are generally two URLs for each name, one for a direct shortcut jump and another for a search on the given site (if any string is specified after the prefix, usually).

Miscellaneous shortcuts:
bugmenot, bored, random, bofh, xyzzy, jack or handey

Web search:
Google: g or google (default)
Yahoo: y or yahoo
Ask Jeeves: ask or jeeves
Amazon A9: a9
Altavista: av or altavista
Microsoft: msn or microsoft
Mozilla Open Directory: dmoz, odp, mozilla
Dogpile: dp or dogpile
Mamma: ma or mamma
Webcrawler: wc or webcrawler
Netscape: ns or netscape
Lycos: ly or lycos
Hotbot: hb or hotbot
Excite: ex or excite
Elgoog: eg, elgoog, hcraes, dnif, bew, og

default engine: search, find, www, web, s, f, go

The %search_engines hash maps each engine name to two URLs, home and search. In case of search, the query is appended to the mapped URL.

!bork! string in the URL is substitued for an optional xx-bork localization specifier, but only in the google mapping.

The search engines mapping is done by the search() function, taking the search engine name as its first parameter and optional search string as its second parameter. It returns the mapped target URL.

Google is used as the default search engine if the given engine is not found.

News agencies:
British Broadcasting Corporation: bbc (default)
MSNBC: msnbc
Cable News Network: cnn
FOXNews: fox
Google News: gn
Yahoo News: yn
Reuters: rs or reuters
Electronic Frontier Foundation: eff
Wired: wd or wired
Slashdot: /. or sd or slashdot
NewsForge: nf or newsforge
U.S.News & World Report: us or usnews
New Scientist: newsci or nsci
Discover Magazine: dm
Scientific American: sa or sciam

default agency: n, news

The %news_servers hash maps each engine name to two URLs, home and search. In case of search, the query is appended to the mapped URL.

The news servers mapping is done by the news() function, taking the search engine name as its first parameter and optional search string as its second parameter. It returns the mapped target URL.

BBC is used as the default search engine if the given engine is not found.

Locators:
Internet Movie Database: imdb, movie, or flick
US zip code search: zip or usps (# or address)
IP address locator / address space: ip
WHOIS / TLD list: whois (current url or specified)
Request for Comments: rfc (# or search)
Weather: w or weather
Yahoo! Finance / NASD Regulation: stock, ticker, or quote
Snopes: ul, urban, or legend
Torrent search / ISOHunt: bt, torrent, or bittorrent
Wayback Machine: ia, ar, arc, or archive (current url or specified)
Freshmeat: fm or freshmeat
SourceForge: sf or sourceforge
Savannah: sv or savannah
Gna!: gna
Netcraft Uptime Survey: whatis or uptime (current url or specified)
Who's Alive and Who's Dead: Wanted, dead or alive!
Google Library / Project Gutenberg: book or read
Internet Public Library: ipl

The %locators hash maps each engine name to two URLs, home and search.

!bork! string in the URL is substitued for an optional xx-bork localization specifier (for any mappings in this case, not just google).

!current! string in the URL is substitued for the URL of the current document.

!query! string in the search URL is substitued for the search string. If no !query! string is found in the URL, the query is appended to the mapped URL.

The locators mapping is done by the location() function, taking the search engine name as its first parameter, optional search string as its second parameter and the current document's URL as its third parameter. It returns the mapped target URL.

An error is produced if the given locator is not found.

Google Groups:
deja, gg, groups, gr, nntp, usenet, nn

MirrorDot:
md or mirrordot

Coral cache:
cc, coral, or nyud (requires URL)

AltaVista Babelfish:
babelfish, babel, bf, translate, trans, or b

W3C page validators:
vhtml or vcss (current url or specified)

ELinks:
Home: el or elinks
Bugzilla: bz or bug (# or search optional)
Documentation and FAQ: doc(|s|umentation) or faq

There's no place like home...

The Dialectizer:
dia <dialect> (current url or specified)

Dialects: redneck, jive, cockney, fudd, bork, moron, piglatin, or hacker


GLOBAL URL REWRITES

These rewrites happen everytime ELinks is about to follow an URL and load it, so this is an order of magnitude more powerful than the Goto URL rewrites.

Developer's usage: The function follow_url_hook is called when the hook is triggered, taking the target URL as its only argument. It returns the final target URL.

Bork! Bork! Bork!
Rewrites many google.com URLs to use the phenomenal xx-bork localization.

NNTP over Google
Rewrites any nntp: or news: URLs to Google Groups HTTP URLs.


HTML REWRITING RULES

When an HTML document is downloaded and is about to undergo the final rendering, the rewrites described here are done first. This is frequently used to get rid of ads, but also various ELinks-unfriendly HTML code and HTML snippets which are irrelevant to ELinks but can obfuscate the rendered document.

Note well that these rules are applied only before the final rendering, not before the gradual re-renderings which happen when only part of the document is available.

Developer's usage: The function pre_format_html_hook is called when the hook is triggered, taking the document's URL and the HTML source as its two arguments. It returns the rewritten HTML code.

Slashdot Sanitation
Kills Slashdot's Advertisements.

This rewrite rule is DISABLED due to weird behavior with fragments.

Obvious Google Tips Annihilator
Kills some Google tips which are obvious anyway to any ELinks user.

SourceForge AdSmasher
Wipes out SourceForge's Ads.

Gmail's Experience
Gmail has obviously never met ELinks for it to suggest another browser for a better Gmail experience.

Source readability improvements
Rewrites some evil characters to entities and vice versa.


SMART PROXY USAGE

The Perl hooks are asked whether to use a proxy for a given URL (or what proxy to actually use). You can use it if you don't want to use a proxy for certain Intranet servers but you need to use it in order to get to the Internet, or if you want to use some anonymizer for access to certain naughty sites.

Developer's usage: The function proxy_for_hook is called when the hook is triggered, taking the target URL as its only argument. It returns the proxy URL, empty string to use no proxy or undef to use the default proxy URL.

No proxy for local files
Prevents proxy usage for local files and http://localhost.


ON-QUIT ACTIONS

The Perl hooks can also perform various actions when ELinks quits. These can be things like retouching the just saved ``information files'', or doing some fun stuff.

Developer's usage: The function quit_hook is called when the hook is triggered, taking no arguments nor returning anything. ('cause, you know, what would be the point?)

Collapse XBEL Folders
Collapses XBEL bookmark folders. This is obsoleted by bookmarks.folder_state.

Words of Wisdom
A few words of wisdom from ELinks the Sage. (Prints a fortune. ;-)


SEE ALSO

elinks(1), perl(1)


AUTHORS

Russ Rowan, Petr Baudis