______  _     _  ______   _______  ______   _______  _  _  _
          / _____)(_)   (_)(_____ \ (_______)(_____ \ (_______)(_)(_)(_)
         ( (____   _     _  _____) ) _____    _____) ) _______  _  _  _
          \____ \ | |   | ||  __  / |  ___)  |  __  / |  ___  || || || |
          _____) )| |___| || |  \ \ | |      | |  \ \ | |   | || || || |
         (______/  \_____/ |_|   |_||_|      |_|   |_||_|   |_| \_____/
         Surfraw - Shell Users' Revolutionary Front Rage Against the Web

About Surfraw

Surfraw provides a fast unix command line interface to a variety of popular WWW search engines and other artifacts of power. It reclaims google, altavista, babelfish, dejanews, freshmeat, research index, slashdot and many others from the false-prophet, pox-infested heathen lands of html-forms, placing these wonders where they belong, deep in unix heartland, as god loving extensions to the shell.

Surfraw abstracts the browser away from input. Doing so lets it get on with what it's good at. Browsing. Interpretation of linguistic forms is handed back to the shell, which is what it, and human beings are good at. Combined with netscape-remote or incremental text browsers, such as lynx, links or w3m, along with screen a Surfraw liberateur is capable of navigating speeds that leave GUI tainted idolaters agape with fear and wonder.

For example:

         $ surfraw google -results=100 RMS, GNU, which is sinner, which is sin?
         $ sr wikipedia surfraw
         $ sr austlii -method=phrase dog like
         $ /usr/lib/surfraw/rhyme -method=perfect Julian

News

Current surfraw version: 2.2.2

Thu Jul 3 08:47:14 BST 2008 - surfraw 2.2.2

• New elvis:
  • arxiv - Search the Los Alamos Science E-Print Archive replaces xxx which was just a stub (thanks to John Gruenenfelder).
  • javasun - search Java API Docs (thanks to James TD Smith)
• Fixed elvis:
  • debpackages/debcontents: update options and distributions, add -a options to use archive.debian.net.
  • wetandwild: switched to weather.com, as yahoo now uses AJAX. Command line options and SURFRAW_weather_* variables no longer supported.
  • austlii: fixed search URL, default method is now 'auto'.
  • port: original site is back.
  • translate: fixed URLs.
• Removed elvis:
  • sundocs: use sunonesearch.
  • xxx: replaced by arxiv.
• surfraw: fix w3_url_escape quoting (thanks Micah Anderson)
• surfraw-update-path: fix csh syntax (thanks John Gruenenfelder)
• google: Add -country option to specify country. Respects
• SURFRAW_lang variable (Thanks to James TD Smith).

March 9th, 2008 - Released Surfraw 2.2.1

• New elvi:
  • lsm - Search the Linux Software Map.
  • sunonesearch - Search Sun's One Search (replaces sunsolve).
• Fixed elvi: cddb, cnn, debcontents, deblists, debpackages, freedb, fsfdir, genpkg, and yubnub (thanks for the latter to Nathaniel Heinrichs).
• Removed elvi: sunsolve (replaced by sunonesearch).
• amazon, ebay, translate: expanded language/country list.
• Added new configuration variable SURFRAW_lang. Elvi that support specifying language or country will use this as a default. If used, it should be set to an ISO 2-letter country code (eg uk, de, ca). Thanks to Simon Ernst for the idea.
• Fixed quoting single quotes in URLs (thanks to Alexander Becher for the patch).

September 14th, 2007 - Resumed making upstream releases.

Surfraw is now maintained by the Debian Surfraw-Devel Team. Please report bugs to surfraw-devel@lists.alioth.debian.org, and feel free to join us on the list.

There have been many changes since the last official release:

• New elvi: alioth archpkg bbcnews cddb cia codesearch ctan cve deblists deblogs debpts debsec debwiki discogs dmoz ebay etym foldoc freedb fsfdir genpkg gutenberg happypenguin imdb ixquick lastfm leodict musicbrainz opensearch pgpkeys port rae rfc scholar scpan w3css w3html w3link w3rdf wayback wikipedia yubnub

• Removed elvi: appwatch britannica ftpfind ftpsearch jake raging swhois

• Elvi now live in /usr/lib/surfraw (or /usr/local/lib/surfraw) Use surfraw-update-path to add this directory to your path or prefix elvi with sr or surfraw, eg sr google foo bar.

• Bookmarks can be defined in /etc/surfraw.bookmarks or ~/.surfraw.bookmarks. See /etc/surfraw.bookmarks for the format. Bookmarks can be used with sr [options] bookmarkname.

• There is now a test suite. make test to run it or see test/README.

Old news entries can be viewed here. For a full list of changes to surfraw, consult the ChangeLog file from the surfraw source distribution. Earlier log entries were kept in debian/changelog.

Downloading

The current version of surfraw is 2.2.2

surfraw-2.2.2.tar.gz is signed by the surfraw release key, also available from keyservers.

Debian packages:

Older versions are available here.

Installation

Source Tarball

Unpack the source with

gzip -dc surfraw-2.2.2.tar.gz | tar xvvf -

Then, change into the surfraw-2.2.2 directory, and type

./configure

make

then, as root,

make install

This will install surfraw into /usr/local/

For more detailed installation instructions, see the INSTALL file that is part of the surfraw distribution.

Note that the opensearch elvis depends on the perl libraries WWW::OpenSearch, HTML::Parser and LWP (libwww-perl). If you don't want to install opensearch, use

./configure --disable-opensearch

Debian Binary Package

To install the version in your Debian distribution, as root, type:

apt-get install surfraw surfraw-extra

To install the .deb files directly, as root, type:

dpkg -i surfraw_2.2.2-1_all.deb surfraw-extra_2.2.2-1_all.deb

Note that calling dpkg directly does not automatically install dependencies, and surfraw-extra in particular has many dependencies, so it is best to stick with apt-get install where possible.

Debian source package

First you need to ensure you have the necessary packages installed to successfully build surfraw.

The following commands (run as root) should ensure you have everything necessary to build surfraw:

apt-get install build-essential fakeroot
apt-get build-dep surfraw

Download the surfraw_2.2.2-1.dsc, surfraw_2.2.2-1.diff.gz and surfraw_2.2.2.orig.tar.gz files, then type:

dpkg-source -x surfraw_2.2.2-1.dsc

This will unpack the source into a subdirectory called surfraw-2.2.2

Change into this directory, and type:

fakeroot debian/rules binary

This should produce files called surfraw_2.2.2-1_all.deb and surfraw-extra_2.2.2-1_all.deb in the directory above the surfraw source directory. To install these files, type as root:

dpkg -i surfraw_2.2.2-1_all.deb surfraw-extra_2.2.2-1_all.deb

List of Elvi

Surfraw contains the following web site search scripts (elvi)

Usage

Surfraw consists of a collection of elvi, each of which knows how to search a specific web site.

To see the list of elvi type:

surfraw -elvi

Note that sr is an alias for surfraw, so that could equally be:

sr -elvi

To search using an elvis use:

sr elviname [options] search terms..

For example, to search google for information on Debian ports, using the "I'm feeling lucky" option:

sr google -l debian ports

Note that putting quotes round arguments works now, so you can do, for example:

sr google foo "bar baz" bam

and the quoting is passed on to the search engine.

Adding the elvi to your path

If you are a regular user of surfraw, you will probably get sick of typing sr or surfraw each time. You can regain the old behaviour of running the elvi directly by adding the elvi directory (usually /usr/lib/surfraw/ or /usr/local/lib/surfraw/) to your path, either manually or using surfraw-update-path(1).

Bookmarks

Surfraw now supports bookmarks. To add a bookmark, add it to /etc/surfraw.bookmarks or $HOME/.surfraw.bookmarks

The format of the bookmarks file is simple, each bookmark is on a separate line, with the bookmark and URL separated by whitespace, for example:

ntk http://www.ntk.net/

To invoke a bookmark, use surfraw bookmark or sr bookmark, and if an elvis of that name doesn't exist, it searches for a bookmark of that name instead.

There are some example bookmarks in /etc/surfraw.bookmarks

Completion

Surfraw has support for bash completion. If bash completion is enabled you can use the <TAB> key to complete elvi names, options and arguments.

Options

All elvi have useful low calorie help, for example:

$ sr rhyme -help
Usage: rhyme [options] [search words]...
Description:
  Surfraw search for rhymes and other word correlations using
  Lycos Rhyme (http://rhyme.lycos.com)
Example:
  $ surfraw rhyme Julian
  $ sr rhyme -method=rel surfer
Results:
  Hurclean St. Julien.
  surfboarder, bather, natator, swimmer
Local options:
  -method=                      Type of word correlation to search for
          prefect       |       Perfect rhyme
          syn           |       Synonyms
          hom           |       Homophones
          cons          |       Consonsant rhymes only
          rel           |       Semantically related words
          sub           |       Phrases
          spell         |       Similar spellings
          pic           |       Pictures
          shake         |       Match with Shakespeare archives
          def                   Find wordnet definition
                                Default: perfect
                                Environment: SURFRAW_rhyme_method
Global options:
  -browser=EXECUTABLE           Set browser
                                Default: mozilla
  -elvi                         List Surfraw mechanisms for conquering evil
  -escape-url-args=yes|no       Apply url escaping to arguments
                                Default: yes
                                Environment: SURFRAW_escape_url_args
  -g | -graphical               Get some windowed sin
  -help                         What you're reading now, dude
  -quiet=yes|no                 I can't enjoy it with you talking all the time
                                Default: no
                                Environment: SURFRAW_quiet
  -new[=yes|no]                 Start in a new window
                                Default: no
                                Environment: SURFRAW_new_window
  -t | -text                    Back to the yellow brick road
  -q | -quote                   Quote arguments with " characters
                                Default: no
                                Environment: SURFRAW_quote_args
  -version                      Display Surfraw version (1.0.4)
Copyright:
  Copyright (c) 2003-2007 The Surfraw-Devel Team
                           <surfraw-devel@lists.alioth.debian.org>
  Copyright (c) 2000-2001 Julian Assange
  Copyright (c) 2001 Australian Institute for Collaborative Research
  Copyright (c) 2000 Melbourne Institute for Advanced Study
  ---

Configuration

Surfraw gets its configuration from three sources, in order:

1. Environment variables
2. /etc/surfraw.conf
3. $HOME/.surfraw.conf

/etc/surfraw.conf and $HOME/.surfraw.conf are both fragments of bourne-shell style shell script.

/etc/surfraw.conf should use def and defyn to define variables. These functions set variables unless they are already set by the environment. defyn is used for boolean configuration variables, def for all others. For instance:

 def     SURFRAW_text_browser	/usr/bin/lynx
 defyn   SURFRAW_graphical		no

$HOME/.surfraw.conf should use sh-style entries, eg:

 SURFRAW_text_browser=/usr/bin/lynx
 SURFRAW_graphical=no

This is because you want them to override environment variables unconditionally.

Configuration Variables

Files

$(libdir)/surfraw

Location of the elvi.

/etc/surfraw.conf

Default system wide configuration file.

$HOME/.surfraw.conf

Default per-user config file

/etc/surfraw.bookmarks

System wide bookmarks file.

$HOME/.surfraw.bookmarks

Per-user bookmarks file.

Development and Support

Surfraw was originally written by Julian Assange. It is now maintained and improved by a team of programmers based around the surfraw-devel mailing list.

The surfraw project webpage is at surfraw.alioth.debian.org

To report a bug or request an enhancement (e.g. a new elvis), send email to surfraw-devel@lists.alioth.debian.org

The current development version of surfraw can be obtained from the surfraw CVS repository

Interested in contributing? Subscribe to surfraw-devel. View the surfraw-devel list archives. Read the surfraw HACKING guide. Surfrawize the soul of your favourite internet wonder. Join the Shell Users' Revolutionary Front Against the WWW by submitting code. Reclaim heathen lands. Bear witness to the truth. Its love will set you free.

Last modified: Sat Jul 5 05:50:51 BST 2008