SURFRAW(1)						      General Commands Manual							SURFRAW(1)

NAME

       surfraw - a fast unix command line interface to WWW services

SYNOPSIS

       surfraw elviname [options] search words ...
       sr elviname [options] search words ...
       sr -elvi
       sr bookmark

DESCRIPTION

       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, 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 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

   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 (/usr/lib/surfraw) to your path, either manually or using surfraw-update-path(1).

   Bookmarks
       Surfraw supports bookmarks. To add a bookmark, add it to /etc/xdg/surfraw/bookmarks or $HOME/.config/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, eg:

	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/xdg/surfraw/bookmarks

OPTIONS

       Use  sr elviname -local-help for elvi-specific options.

       The following options work with all elvi.

       -help  Show summary of options (including elvi-specific options).

       -local-help
	      Show elvi-specific options.

       -version
	      Show version of program.

       -browser=EXECUTABLE
	      Set browser (default: sensible-browser).

       -elvi  Display a list of other Surfraw mechanisms for conquering evil.

       -escape-url-args=yes|no
	      Apply url escaping to arguments (default: yes)

       -q|-quote
	      Bracket all arguments with " characters (default: no).  Note that putting quotes round arguments works now, so you can do, for exam-
	      ple:

	       sr google foo "bar baz" bam

	      and the quoting is passed on to the search engine

EXAMPLES

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

CONFIGURATION

       Surfraw uses the XDG basedir spec (http://standards.freedesktop.org/basedir-spec/basedir-spec-0.6.html) to locate config files. The default
       locations  are  shown  below, but can be modified by setting the environment variables $XDG_CONFIG_HOME and $XDG_CONFIG_DIRS.  See the spec
       for more details.

       Surfraw gets its configuration from three sources, in order:

       1.  Environment variables

       2.  /etc/xdg/surfraw/conf

       3.  $HOME/.config/surfraw/conf

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

       /etc/xdg/surfraw.conf should use def and defyn to define variables.  These functions set variables unless they are already set by the envi-
       ronment.  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/.config/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

       SURFRAW_global_conf
	      Location of global configuration file.

	      Default:

	       def SURFRAW_global_conf /etc/xdg/surfraw/conf

       SURFRAW_conf
	      Location of per-user configuration file.

	      Default:

	       def SURFRAW_conf $HOME/.config/surfraw/conf

       SURFRAW_graphical
	      Whether to use a graphical browser.

	      Default:

	      defyn SURFRAW_graphical no

       SURFRAW_text_browser
	      Name/path of text browser executable.  e.g. links, lynx, w3m

	      Default:

	      def SURFRAW_text_browser sensible-browser

       SURFRAW_graphical_browser
	      Name/path of graphical browser executable.  e.g mozilla, netscape etc.

	      Default:

	       def SURFRAW_graphical_browser sensible-browser

       SURFRAW_text_browser_args
	      Text browser arguments, or "none".

	      Default:

	       def SURFRAW_text_browser_args none

       SURFRAW_graphical_browser_args
	      Graphical browser arguments, or "none".

	      Default:

	       def SURFRAW_graphical_browser_args none

       SURFRAW_graphical_remote
	      Whether to use "-remote openURL" for graphical browser.

	      Default:

	       defyn SURFRAW_graphical_remote yes

       SURFRAW_new_window
	      When using SURFRAW_graphical_remote, open a new window?

	      Default:

	       defyn SURFRAW_new_window no

       SURFRAW_screen

	      Name of screen command to run.

	      Default:

	       def SURFRAW_screen screen

       SURFRAW_new_screen
	      If surfraw is running under screen(1), start a new screen for each text browser invocation?

	      Default:

	       defyn SURFRAW_new_screen no

       SURFRAW_screen_args
	      Arguments to pass to the SURFRAW_screen command

	      Default:

	       def SURFRAW_screen_args ""

       SURFRAW_quote_args
	      Whether to "quote" all the arguments.

	      Default:

	       defyn SURFRAW_quote_args no

       SURFRAW_quote_ifs
	      Whether to re-quote arguments if they have spaces in, ie so:
	       sr google foo "bar baz" bam
	      works as expected.

	      Default:

	      defyn SURFRAW_quote_ifs	 yes

       SURFRAW_results
	      Default number of results to return (not supported by all elvi).

	      Default:

	       def SURFRAW_results 30

       SURFRAW_escape_url_args
	      Whether to escape [% "$%&+,/:;<=>?@[{|}~'] characters in command line arguments subsequently used to construct a url.

	      Default:

	       defyn SURFRAW_escape_url_args yes

FILES

       /usr/lib/surfraw
	      Location of the elvi.

       ${HOME}/.config/surfraw/elvi
	      Per-user elvi.

       /etc/xdg/surfraw/conf
	      Default system wide configuration file.

       $HOME/.config/surfraw/conf
	      Default per-user config file

       /etc/xdg/surfraw/bookmarks
	      System wide bookmarks file.

       $HOME/.config/surfraw/bookmarks
	      Per-user bookmarks file.

BUGS

       Please report any bugs found (or any web sites in need of surfrawizing) either via the debian bug tracking system (http://bugs.debian.org/)
       or to the surfraw-devel list (surfraw-devel@lists.alioth.debian.org).

SEE ALSO

       http://alioth.debian.org/projects/surfraw/

PROPAGANDA

									Oh Baybe
								       I need some
								      Deep Linking
									Let us go
								   Surfin' in the raw!

       Read HACKING. Surfrawize the soul of your favourite internet wonder.  Join the Shell Users' Revolutionary Front Against the WWW by  submit-
       ting code.  Reclaim heathen lands.  Bear witness to the truth.  Its love will set you free.

       Join us on surfraw-devel@lists.alioth.debian.org

AUTHORS

       Originally written by Julian Assange.

       Now maintained by the surfraw-devel team <surfraw-devel@lists.alioth.debian.org>.

       See the file AUTHORS for the full list of contributors.

       Man page by Ian Beckwith, based on the original README and an earlier man page by Christian Surchi.

COPYRIGHT

	 Copyright (c) 2003-2008 The Surfraw-Devel Team
				  <surfraw-devel@lists.alioth.debian.org>
	 Copyright (c) 2000-2001 Julian Assange <proff@iq.org>
	 Copyright (c) 2001 Australian Institute for Collaborative Research
	 Copyright (c) 2000 Melbourne Institute for Advanced Study

       The  copyright  holders	listed above assert no rights on this release of the software ``surfraw'' and thereby explicity place this release
       into the into the public domain. Do what you will.

								   Feb 03, 2004 							SURFRAW(1)