File: HACKING

package info (click to toggle)
surfraw 2.1.0-1
  • links: PTS
  • area: main
  • in suites: sarge
  • size: 780 kB
  • ctags: 139
  • sloc: sh: 7,085; perl: 355; makefile: 155
file content (183 lines) | stat: -rw-r--r-- 6,461 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
        ______  _     _  ______   _______  ______   _______  _  _  _
       / _____)(_)   (_)(_____ \ (_______)(_____ \ (_______)(_)(_)(_)
      ( (____   _     _  _____) ) _____    _____) ) _______  _  _  _
       \____ \ | |   | ||  __  / |  ___)  |  __  / |  ___  || || || |
       _____) )| |___| || |  \ \ | |      | |  \ \ | |   | || || || |
      (______/  \_____/ |_|   |_||_|      |_|   |_||_|   |_| \_____/
                                                               
      Surfraw - Shell Users' Revolutionary Front Rage Against the Web

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

			       H A C K I N G
				   
Or... How to Eat The CHEESE

1)  First, find a front end (`an elvi, types of elvis -- makes evil
    nice') in the elvi/ directory that does something similar to what you
    want. In this example we shall use the `google' elvis.

2)  Copy the `google' elvis to the name of your new elvis.
    In this example we shall create an elvis for the
    Peoples' Front Against Forum Stealing Dogs
    http://www.pfafsd.org/ mailing-list search service

3)  At the top of the file, you will see something like:

    # elvis: google -- Search the web using Google (http://www.google.com)

    Keep the "elvis:" take and change the rest of the line. This
    description is used at Surfraw installation time to generate a list
    of Surfraw clients

    Immediately after we see:

        . surfraw || exit 1
    
    Which pulls in the Surfraw functions. Keep it.

4)  Next we (optionally) define w3_config_hook(). It is  called
    by w3_config and is used to define default configuration
    variables. It is called after the global configuration file
    is interpreted, but before ~/.surfraw.

    You will notice the use of:

    def    -- define configuration variable unless already defined
              (i.e by the environment)
    defyn  -- define boolean configuration variable unless
	      already defined

    Which are pre-defined surfraw functions, but you can
    of course use your own arbitrary broken shell code instead.

5)  Any non-trivial program will then define w3_usage_hook(). 
    $w3_argv0 is set to contain $0, otherwise usage is self
    explanatory. You must call w3_global_usage at the end
    of this function and follow the surfraw usage style
    least you be marked a quiche eater.
    
6)  Next define w3_parse_option_hook(). This is called at w3_config()
    time, and takes two arguments. The first is the current
    option being examined, the second is only present if the
    option was of the form `-foo=bar'. It's the `bar'.

    w3_parse_option_hook() is called before Surfraw global options
    are parsed and so you can selectively over-ride them.

    Return value: 0 if the option was recognised, 1 otherwise.

7)  After this, w3_config() and w3_parse_args "$@" are called.
    w3_config() scans the configuration files and calls
    w3_config_hook(). w3_parse_args "$@" processes options,
    called w3_parse_option_hook() as needed and builds
    $w3_args -- the list non-option arguments.

    This ends the regular initialisation code.

7.5)Note that surfraw now supports quoting arguments, eg with:
	  sr google foo "bar baz" bam
	it adds the quotes back.

	Not all sites support arguments in double quotes. If you want to
	disable it for your elvis, add
	  SURFRAW_quote_ifs=0
	in between the calls to w3_config and w3_parse_args.

8)  What happens next depends on the type of evil we are dealing
    with. In the Peoples' Front Against Forum Stealing Dogs case, we have
    previously performed a search on the http://www.pfafsd.org search
    service, and noted (with the '=' key in lynx, links) the url
    returned. We then analyse this url to work out which CGI variable is
    being used to convey search the search string, number of results et
    al.

    Q: What about those proslytizers of iniquity that worship idols like
       method=POST?
      
    A: Most sites will take GETs in the place of POSTs, even if they
       preach method=POST in forms. For those that don't? Walking with
       the devil should not be a an exercise in relaxed discourse. The
       problem is getting the browser to automatically submit the data
       using POST as a method. One partial solution is to have surfraw
       generate a pre-filled method=POST form as a local file and have
       the browser read it. Exploration of other ideas is encouraged.

    w3_url_of_arg() is then used to escape the command line search
    string argument into something that can be seen in a URL without
    embarrassment.

    i.e escaped_args=`w3_url_of_arg $w3_args`

    In our last exhilarating moments we then build the final URL and
    pass it onto the currently selected browser with w3_browse_url,
    proud in the knowledge that the Shell Users' Revolutionary Front
    Against the WWW has brought the holy word of the command line to
    yet another heathen land.

    -Julian Assange <proff-projects-surfraw@iq.org>

 APPENDIX 1
    
    Adding an elvi to the distribution:

    1: write it (see above)

    2: copy elviname to the elvi directory

    3: add elviname to the bin_SCRIPTS list in elvi/Makefile.am

    4: add a link for the manpage in links.IN
    
    5: run automake and autoconf

    6: rebuild the package (eg fakeroot debian/rules binary)
       (this recreates elvi/surfraw.list)

    7: update the elvi list in README from elvi/surfraw_elvi.list

    8: add an entry to the changelog.

    9: if using cvs, '(cd elvi;cvs add elviname)' then 'cvs commit'

 APPENDIX 2

    Preparing a release of surfraw:

    1: Change into the surfraw source directory.

    2: cvs update

    3: If you have made changes, cvs commit

    4: cvs tag -c surfraw_version-number_debianversion

    5: mkdir ../release

    6: cd ../release

    7: cvs -d :ext:user@cvs.alioth.debian.org:/cvsroot/surfraw export -r surfraw_version-number_debianversion surfraw

    8: cd surfraw

    9: fakeroot make distcheck

    10: cp surfraw-version.tar.gz ../surfraw_version.orig.tar.gz

    11: mv surfraw-version.tar.gz ..

    12: fakeroot dpkg-buildpackage -sa

    13: cd ..

    14: upload the debian packages

    15: copy the .tar.gz, .orig.tar.gz, .dsc, .deb, .diff.gz files to the webspace

    16: see the README.WEB file in the website tree for how to update the website.

$Id: HACKING,v 1.5 2004/09/15 16:56:54 ianb-guest Exp $