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 [options] bookmark [search words]
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       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
65       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
69       There are some example bookmarks in /etc/xdg/surfraw/bookmarks
70
71

OPTIONS

73       Use  sr elviname -local-help for elvi‐specific options.
74
75       The following options work with all elvi.
76
77
78       -help  Show summary of options (including elvi‐specific options).
79
80
81       -local-help
82              Show elvi‐specific options.
83
84
85       -version
86              Show version of program.
87
88
89       -browser=EXECUTABLE
90              Set browser (default: sensible-browser).
91
92
93       -elvi  Display a list of other Surfraw mechanisms for conquering evil.
94
95
96       -escape-url-args=yes|no
97              Apply url escaping to arguments (default: yes)
98
99
100       -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
105               sr google foo "bar baz" bam
106
107              and the quoting is passed on to the search engine
108
109

EXAMPLES

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
116

CONFIGURATION

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
124       Surfraw gets its configuration from three sources, in order:
125
126
127       1.  Environment variables
128
129       2.  /etc/xdg/surfraw/conf
130
131       3.  $HOME/.config/surfraw/conf
132
133
134       /etc/xdg/surfraw.conf and $HOME/.config/surfraw/conf are both fragments
135       of bourne‐shell style shell script.
136
137       /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
142        def     SURFRAW_text_browser /usr/bin/lynx
143        defyn   SURFRAW_graphical         no
144
145       $HOME/.config/surfraw/conf should use sh‐style entries, eg:
146
147        SURFRAW_text_browser=/usr/bin/lynx
148        SURFRAW_graphical=no
149
150       This  is because you want them to override environment variables uncon‐
151       ditionally.
152
153

CONFIGURATION VARIABLES

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

FILES

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

BUGS

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
319

SEE ALSO

321       http://alioth.debian.org/projects/surfraw/
322
323

PROPAGANDA

325                                      Oh Baybe
326                                     I need some
327                                    Deep Linking
328                                      Let us go
329                                 Surfin' in the raw!
330
331       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
336       Join us on surfraw-devel@lists.alioth.debian.org
337
338

AUTHORS

340       Originally written by Julian Assange.
341
342       Now     maintained     by      the      surfraw-devel      team      <‐
343       surfraw-devel@lists.alioth.debian.org>.
344
345       See the file AUTHORS for the full list of contributors.
346
347       Man  page  by Ian Beckwith, based on the original README and an earlier
348       man page by Christian Surchi.
349
350
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
358       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
362
363
364                                 Feb 03, 2004                       SURFRAW(1)
Impressum