1SURFRAW(1)                  General Commands Manual                 SURFRAW(1)
2
3
4

NAME

6       surfraw - a fast unix command line interface to WWW services
7

SYNOPSIS

9       surfraw elviname [options] search words ...
10       sr elviname [options] search words ...
11       sr -elvi
12       sr bookmark
13
14

DESCRIPTION

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
23
24       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
27        surfraw -elvi
28
29       Note that sr is an alias for surfraw, so that could equally be
30
31        sr -elvi
32
33       To search using an elvis use:
34
35        sr elviname [options] search terms..
36
37       For  example,  to  search google for information on Debian ports, using
38       the "I'm feeling lucky" option:
39
40        sr google -l debian ports
41
42
43   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
50
51   Bookmarks
52       Surfraw  supports  bookmarks.  To   add   a   bookmark,   add   it   to
53       /etc/xdg/surfraw/bookmarks or $HOME/.config/surfraw/bookmarks
54
55       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
58        ntk   http://www.ntk.net/
59
60       To invoke a bookmark, use "surfraw bookmark" or "sr bookmark",  and  if
61       an elvis of that name doesn't exist, it searches for a bookmark of that
62       name instead.
63
64       There are some example bookmarks in /etc/xdg/surfraw/bookmarks
65
66

OPTIONS

68       Use  sr elviname -local-help for elvi‐specific options.
69
70       The following options work with all elvi.
71
72
73       -help  Show summary of options (including elvi‐specific options).
74
75
76       -local-help
77              Show elvi‐specific options.
78
79
80       -version
81              Show version of program.
82
83
84       -browser=EXECUTABLE
85              Set browser (default: sensible-browser).
86
87
88       -elvi  Display a list of other Surfraw mechanisms for conquering evil.
89
90
91       -escape-url-args=yes|no
92              Apply url escaping to arguments (default: yes)
93
94
95       -q|-quote
96              Bracket all arguments with "  characters  (default:  no).   Note
97              that  putting  quotes  round arguments works now, so you can do,
98              for example:
99
100               sr google foo "bar baz" bam
101
102              and the quoting is passed on to the search engine
103
104

EXAMPLES

106        $ sr ask why is jeeves gay?
107        $ surfraw google -results=100 RMS, GNU, which is sinner, which is sin?
108        $ sr austlii -method=phrase dog like
109        $ /usr/libexec/surfraw/rhyme -method=perfect Julian
110
111

CONFIGURATION

113       Surfraw  uses  the   XDG   basedir   spec   (http://standards.freedesk
114       top.org/basedir-spec/basedir-spec-0.6.html) to locate config files. The
115       default locations are shown below, but can be modified by  setting  the
116       environment  variables  $XDG_CONFIG_HOME and $XDG_CONFIG_DIRS.  See the
117       spec for more details.
118
119       Surfraw gets its configuration from three sources, in order:
120
121
122       1.  Environment variables
123
124       2.  /etc/xdg/surfraw/conf
125
126       3.  $HOME/.config/surfraw/conf
127
128
129       /etc/xdg/surfraw.conf and $HOME/.config/surfraw/conf are both fragments
130       of bourne‐shell style shell script.
131
132       /etc/xdg/surfraw.conf  should  use  def  and defyn to define variables.
133       These functions set variables unless they are already set by the  envi‐
134       ronment.   defyn  is  used for boolean configuration variables, def for
135       all others. For instance:
136
137        def     SURFRAW_text_browser /usr/bin/lynx
138        defyn   SURFRAW_graphical         no
139
140       $HOME/.config/surfraw/conf should use sh‐style entries, eg:
141
142        SURFRAW_text_browser=/usr/bin/lynx
143        SURFRAW_graphical=no
144
145       This is because you want them to override environment variables  uncon‐
146       ditionally.
147
148

CONFIGURATION VARIABLES

150       SURFRAW_global_conf
151              Location of global configuration file.
152
153              Default:
154
155               def SURFRAW_global_conf /etc/xdg/surfraw/conf
156
157
158       SURFRAW_conf
159              Location of per‐user configuration file.
160
161              Default:
162
163               def SURFRAW_conf $HOME/.config/surfraw/conf
164
165
166       SURFRAW_graphical
167              Whether to use a graphical browser.
168
169              Default:
170
171              defyn SURFRAW_graphical no
172
173
174       SURFRAW_text_browser
175              Name/path of text browser executable.  e.g. links, lynx, w3m
176
177              Default:
178
179              def SURFRAW_text_browser sensible-browser
180
181
182       SURFRAW_graphical_browser
183              Name/path  of  graphical  browser executable.  e.g mozilla, net‐
184              scape etc.
185
186              Default:
187
188               def SURFRAW_graphical_browser sensible-browser
189
190
191       SURFRAW_text_browser_args
192              Text browser arguments, or "none".
193
194              Default:
195
196               def SURFRAW_text_browser_args none
197
198
199       SURFRAW_graphical_browser_args
200              Graphical browser arguments, or "none".
201
202              Default:
203
204               def SURFRAW_graphical_browser_args none
205
206
207       SURFRAW_graphical_remote
208              Whether to use "-remote openURL" for graphical browser.
209
210              Default:
211
212               defyn SURFRAW_graphical_remote yes
213
214
215       SURFRAW_new_window
216              When using SURFRAW_graphical_remote, open a new window?
217
218              Default:
219
220               defyn SURFRAW_new_window no
221
222
223       SURFRAW_screen
224
225              Name of screen command to run.
226
227              Default:
228
229               def SURFRAW_screen screen
230
231
232       SURFRAW_new_screen
233              If surfraw is running under screen(1), start a  new  screen  for
234              each text browser invocation?
235
236              Default:
237
238               defyn SURFRAW_new_screen no
239
240
241       SURFRAW_screen_args
242              Arguments to pass to the SURFRAW_screen command
243
244              Default:
245
246               def SURFRAW_screen_args ""
247
248
249       SURFRAW_quote_args
250              Whether to "quote" all the arguments.
251
252              Default:
253
254               defyn SURFRAW_quote_args no
255
256
257       SURFRAW_quote_ifs
258              Whether to re‐quote arguments if they have spaces in, ie so:
259               sr google foo "bar baz" bam
260              works as expected.
261
262              Default:
263
264              defyn SURFRAW_quote_ifs    yes
265
266
267       SURFRAW_results
268              Default number of results to return (not supported by all elvi).
269
270              Default:
271
272               def SURFRAW_results 30
273
274
275       SURFRAW_escape_url_args
276              Whether to escape [% "$%&+,/:;<=>?@[{|}~'] characters in command
277              line arguments subsequently used to construct a url.
278
279              Default:
280
281               defyn SURFRAW_escape_url_args yes
282
283

FILES

285       /usr/libexec/surfraw
286              Location of the elvi.
287
288
289       ${HOME}/.config/surfraw/elvi
290              Per‐user elvi.
291
292
293       /etc/xdg/surfraw/conf
294              Default system wide configuration file.
295
296
297       $HOME/.config/surfraw/conf
298              Default per‐user config file
299
300
301       /etc/xdg/surfraw/bookmarks
302              System wide bookmarks file.
303
304
305       $HOME/.config/surfraw/bookmarks
306              Per‐user bookmarks file.
307
308

BUGS

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

SEE ALSO

316       http://alioth.debian.org/projects/surfraw/
317
318

PROPAGANDA

320                                      Oh Baybe
321                                     I need some
322                                    Deep Linking
323                                      Let us go
324                                 Surfin' in the raw!
325
326       Read HACKING. Surfrawize the soul of your  favourite  internet  wonder.
327       Join the Shell Users' Revolutionary Front Against the WWW by submitting
328       code.  Reclaim heathen lands.  Bear witness to  the  truth.   Its  love
329       will set you free.
330
331       Join us on surfraw-devel@lists.alioth.debian.org
332
333

AUTHORS

335       Originally written by Julian Assange.
336
337       Now      maintained      by      the      surfraw-devel     team     <‐
338       surfraw-devel@lists.alioth.debian.org>.
339
340       See the file AUTHORS for the full list of contributors.
341
342       Man page by Ian Beckwith, based on the original README and  an  earlier
343       man page by Christian Surchi.
344
345
347         Copyright (c) 2003-2008 The Surfraw-Devel Team
348                                  <surfraw-devel@lists.alioth.debian.org>
349         Copyright (c) 2000-2001 Julian Assange <proff@iq.org>
350         Copyright (c) 2001 Australian Institute for Collaborative Research
351         Copyright (c) 2000 Melbourne Institute for Advanced Study
352
353       The  copyright holders listed above assert no rights on this release of
354       the software ``surfraw'' and thereby explicity place this release  into
355       the into the public domain. Do what you will.
356
357
358
359                                 Feb 03, 2004                       SURFRAW(1)
Impressum