1SURFRAW(1) General Commands Manual SURFRAW(1)
2
6 surfraw - a fast unix command line interface to WWW services
7
9 surfraw elviname [options] search words ...
10 sr elviname [options] search words ...
11 sr -elvi
12 sr [options] bookmark [search words]
13
16 Surfraw provides a fast unix command line interface to a variety of
17 popular WWW search engines and other artifacts of power. It reclaims
18 google, altavista, dejanews, freshmeat, research index, slashdot and
19 many others from the false‐prophet, pox‐infested heathen lands of html‐
20 forms, placing these wonders where they belong, deep in unix heartland,
21 as god loving extensions to the shell.
22 Surfraw consists of a collection of elvi, each of which knows how to
25 search a specific web site. To see the list of elvi type:
26 surfraw -elvi
28 Note that sr is an alias for surfraw, so that could equally be
30 sr -elvi
32 To search using an elvis use:
34 sr elviname [options] search terms..
36 For example, to search google for information on Debian ports, using
38 the "I'm feeling lucky" option:
39 sr google -l debian ports
41 Adding the elvi to your path
44 If you are a regular user of surfraw, you will probably get sick of
45 typing sr or surfraw each time. You can regain the old behaviour of
46 running the elvi directly by adding the elvi directory (‐
47 /usr/libexec/surfraw) to your path, either manually or using
48 surfraw-update-path(1).
49 Bookmarks
52 Surfraw supports bookmarks. To add a bookmark, add it to
53 /etc/xdg/surfraw/bookmarks or $HOME/.config/surfraw/bookmarks
54 The format of the bookmarks file is simple, each bookmark is on a sepa‐
56 rate line, with the bookmark and URL separated by whitespace, eg:
57 ntk http://www.ntk.net/
59 If the url contains the string %s, you can specify an optional argument
61 to the bookmark. Without an argument, only the domain will be returned.
62 With arguments, %s will be replaced by the arguments. This obviates the
63 need to create elvi for sites with very simple search options.
64 To invoke a bookmark, use "surfraw bookmark" or "sr bookmark", and if
66 an elvis of that name doesn't exist, it searches for a bookmark of that
67 name instead.
68 There are some example bookmarks in /etc/xdg/surfraw/bookmarks
70
73 Use sr elviname -local-help for elvi‐specific options.
74 The following options work with all elvi.
76 -help Show summary of options (including elvi‐specific options).
79 -local-help
82 Show elvi‐specific options.
83 -version
86 Show version of program.
87 -browser=EXECUTABLE
90 Set browser (default: sensible-browser).
91 -elvi Display a list of other Surfraw mechanisms for conquering evil.
94 -escape-url-args=yes|no
97 Apply url escaping to arguments (default: yes)
98 -q|-quote
101 Bracket all arguments with " characters (default: no). Note
102 that putting quotes round arguments works now, so you can do,
103 for example:
104 sr google foo "bar baz" bam
106 and the quoting is passed on to the search engine
108
111 $ sr ask why is jeeves gay?
112 $ surfraw google -results=100 RMS, GNU, which is sinner, which is sin?
113 $ sr austlii -method=phrase dog like
114 $ /usr/libexec/surfraw/rhyme -method=perfect Julian
115
118 Surfraw uses the XDG basedir spec (http://standards.freedesk‐
119 top.org/basedir-spec/basedir-spec-0.6.html) to locate config files. The
120 default locations are shown below, but can be modified by setting the
121 environment variables $XDG_CONFIG_HOME and $XDG_CONFIG_DIRS. See the
122 spec for more details.
123 Surfraw gets its configuration from three sources, in order:
125 1. Environment variables
128 2. /etc/xdg/surfraw/conf
130 3. $HOME/.config/surfraw/conf
132 /etc/xdg/surfraw.conf and $HOME/.config/surfraw/conf are both fragments
135 of bourne‐shell style shell script.
136 /etc/xdg/surfraw.conf should use def and defyn to define variables.
138 These functions set variables unless they are already set by the envi‐
139 ronment. defyn is used for boolean configuration variables, def for
140 all others. For instance:
141 def SURFRAW_text_browser /usr/bin/lynx
143 defyn SURFRAW_graphical no
144 $HOME/.config/surfraw/conf should use sh‐style entries, eg:
146 SURFRAW_text_browser=/usr/bin/lynx
148 SURFRAW_graphical=no
149 This is because you want them to override environment variables uncon‐
151 ditionally.
152
155 SURFRAW_global_conf
156 Location of global configuration file.
157 Default:
159 def SURFRAW_global_conf /etc/xdg/surfraw/conf
161 SURFRAW_conf
164 Location of per‐user configuration file.
165 Default:
167 def SURFRAW_conf $HOME/.config/surfraw/conf
169 SURFRAW_graphical
172 Whether to use a graphical browser.
173 Default:
175 defyn SURFRAW_graphical no
177 SURFRAW_text_browser
180 Name/path of text browser executable. e.g. links, lynx, w3m
181 Default:
183 def SURFRAW_text_browser sensible-browser
185 SURFRAW_graphical_browser
188 Name/path of graphical browser executable. e.g mozilla, net‐
189 scape etc.
190 Default:
192 def SURFRAW_graphical_browser sensible-browser
194 SURFRAW_text_browser_args
197 Text browser arguments, or "none".
198 Default:
200 def SURFRAW_text_browser_args none
202 SURFRAW_graphical_browser_args
205 Graphical browser arguments, or "none".
206 Default:
208 def SURFRAW_graphical_browser_args none
210 SURFRAW_graphical_remote
213 Whether to use "-remote openURL" for graphical browser.
214 Default:
216 defyn SURFRAW_graphical_remote yes
218 SURFRAW_new_window
221 When using SURFRAW_graphical_remote, open a new window?
222 Default:
224 defyn SURFRAW_new_window no
226 SURFRAW_screen
229 Name of screen command to run.
231 Default:
233 def SURFRAW_screen screen
235 SURFRAW_new_screen
238 If surfraw is running under screen(1), start a new screen for
239 each text browser invocation?
240 Default:
242 defyn SURFRAW_new_screen no
244 SURFRAW_screen_args
247 Arguments to pass to the SURFRAW_screen command
248 Default:
250 def SURFRAW_screen_args ""
252 SURFRAW_quote_args
255 Whether to "quote" all the arguments.
256 Default:
258 defyn SURFRAW_quote_args no
260 SURFRAW_quote_ifs
263 Whether to re‐quote arguments if they have spaces in, ie so:
264 sr google foo "bar baz" bam
265 works as expected.
266 Default:
268 defyn SURFRAW_quote_ifs yes
270 SURFRAW_results
273 Default number of results to return (not supported by all elvi).
274 Default:
276 def SURFRAW_results 30
278 SURFRAW_escape_url_args
281 Whether to escape [% "$%&+,/:;<=>?@[{|}~'] characters in command
282 line arguments subsequently used to construct a url.
283 Default:
285 defyn SURFRAW_escape_url_args yes
287
290 /usr/libexec/surfraw
291 Location of the elvi.
292 ${HOME}/.config/surfraw/elvi
295 Per‐user elvi.
296 /etc/xdg/surfraw/conf
299 Default system wide configuration file.
300 $HOME/.config/surfraw/conf
303 Default per‐user config file
304 /etc/xdg/surfraw/bookmarks
307 System wide bookmarks file.
308 $HOME/.config/surfraw/bookmarks
311 Per‐user bookmarks file.
312
315 Please report any bugs found (or any web sites in need of surfrawizing)
316 either via the debian bug tracking system (http://bugs.debian.org/) or
317 to the surfraw-devel list (surfraw-devel@lists.alioth.debian.org).
318
321 http://alioth.debian.org/projects/surfraw/
322
325 Oh Baybe
326 I need some
327 Deep Linking
328 Let us go
329 Surfin' in the raw!
330 Read HACKING. Surfrawize the soul of your favourite internet wonder.
332 Join the Shell Users' Revolutionary Front Against the WWW by submitting
333 code. Reclaim heathen lands. Bear witness to the truth. Its love
334 will set you free.
335 Join us on surfraw-devel@lists.alioth.debian.org
337
340 Originally written by Julian Assange.
341 Now maintained by the surfraw-devel team <‐
343 surfraw-devel@lists.alioth.debian.org>.
344 See the file AUTHORS for the full list of contributors.
346 Man page by Ian Beckwith, based on the original README and an earlier
348 man page by Christian Surchi.
349
352 Copyright (c) 2003-2018 The Surfraw-Devel Team
353 <surfraw-devel@lists.alioth.debian.org>
354 Copyright (c) 2000-2001 Julian Assange <proff@iq.org>
355 Copyright (c) 2001 Australian Institute for Collaborative Research
356 Copyright (c) 2000 Melbourne Institute for Advanced Study
357 The copyright holders listed above assert no rights on this release of
359 the software ``surfraw'' and thereby explicity place this release into
360 the into the public domain. Do what you will.
361 Feb 03, 2004 SURFRAW(1)