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

- NAME
- DESCRIPTION
- CONFIGURATION FILE
- GOTO URL HOOK
- FOLLOW URL HOOK
- PRE FORMAT HTML HOOK
- PROXY FOR HOOK
- QUIT HOOK
- SEE ALSO
- AUTHORS

# 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 change the browser's behavior in various ways. They allow shortcuts to be used in the Goto URL dialog, modifying the source of a page, proxy handling, and other things such as displaying a fortune at exit.

# CONFIGURATION FILE

This hooks file reads its configuration from ~/.config/elinks/config.pl. The following is an example of the configuration file:

    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.
    external:   wget      # Send the current URL to this application.
    fortune:    elinks    # *fortune*, *elinks* tip, or *none* on quit?
    googlebeta: hell no   # I miss DejaNews...
    gotosearch: why not   # Anything not a URL in the Goto URL dialog...
    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 HOOK

This is a summary of the shortcuts defined in this file for use in the Goto URL dialog. They are similar to the builtin URL prefixes, but more flexible and 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.

  These routines do a name->URL mapping - for example, 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.

  There are generally two URLs for each name. One to go to the particular URL's main page, and another for a search on the given site (if any string is specified after the prefix). A few of these prefixes will change their behavior depending on the URL currently beung displayed in the browser.

Bugmenot:

  bugmenot or bn

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. With search, the query is appended to the URL.

  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.

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. With 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.

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
  BerliOS: bl or berlios
  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
  VIM Tips: vt (# or search)
  Urban Dictionary: urbandict or ud <word>

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

  !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.

Google Groups:

  deja, gg, groups, gr, nntp, usenet, nn

MirrorDot:

  md or mirrordot <URL>

Coral cache:

  cc, coral, or nyud <URL>

AltaVista Babelfish:

  babelfish, babel, bf, translate, trans, or b <from> <to>

  "babelfish german english" or "bf de en"

W3C page validators:

  vhtml or vcss <URL> (or current url)

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> <URL> (or current url)

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

Sender:

  send

  Send the current URL to the application specified by the configuration variable 'external'. Optionally, override this by specifying the application as in 'send <application>'.

Dictionary:

  dict, d, def, or define <word>

Google site search

  ss <domain> <string>

  Use Google to search the current site or a specified site. If a domain is not given, use the current one.

Anything not a prefix, URL, or local file will be treated as a search using the search engine defined by the 'search' configuration option if 'gotosearch' is set to some variation of 'yes'.

# FOLLOW URL HOOK

These hooks effect a URL before ELinks has a chance to load it.

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.

NNTP over Google

  Translates any nntp: or news: URLs to Google Groups HTTP URLs.

# PRE FORMAT HTML HOOK

When an HTML document is downloaded and is about to undergo the final rendering, this hook is called. 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 that these hooks 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 one is disabled due to weird behavior with fragments.)

Obvious Google Tips Annihilator

  Kills some irritating Google tips.

SourceForge AdSmasher

  Wipes out SourceForge's Ads.

Gmail's Experience

  Gmail has obviously never met ELinks...

Source readability improvements

  Rewrites some evil characters to entities and vice versa. These will be disabled until such time as pre_format_html_hook only gets called for content-type:text/html.

# PROXY FOR HOOK

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 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`.

# QUIT HOOK

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.

# SEE ALSO

elinks(1), perl(1)

# AUTHORS

Russ Rowan, Petr Baudis