86c7d74a56b381bf3afafe347e72efb9d29f83ce
[xscreensaver] / hacks / webcollage.man
1 .de EX          \"Begin example
2 .ne 5
3 .if n .sp 1
4 .if t .sp .5
5 .nf
6 .in +.5i
7 ..
8 .de EE
9 .fi
10 .in -.5i
11 .if n .sp 1
12 .if t .sp .5
13 ..
14 .TH XScreenSaver 1 "17-Jun-99" "X Version 11"
15 .SH NAME
16 webcollage - decorate the screen with random images from the web
17 .SH SYNOPSIS
18 .B webcollage
19 [\-display \fIhost:display.screen\fP]
20 [\-root]
21 [\-verbose]
22 [\-timeout \fIsecs\fP]
23 [\-delay \fIsecs\fP]
24 [\-background \fIbg\fP]
25 [\-no-output]
26 [\-urls-only]
27 [\-size \fIWxH\fP]
28 [\-filter \fIcommand\fP]
29 [\-filter2 \fIcommand\fP]
30 [\-http\-proxy host[:port]]
31 [\-dictionary \fIdictionary-file\fP]
32 [\-driftnet [\fIcmd\fP]]
33 .SH DESCRIPTION
34 The \fIwebcollage\fP program pulls random image off of the World Wide Web
35 and scatters them on the root window.  One satisfied customer described it
36 as "a nonstop pop culture brainbath."  This program finds its images by
37 doing random web searches, and extracting images from the returned pages.
38 It places the images on the root window by using the
39 .BR giftopnm (1),
40 .BR djpeg (1),
41 and
42 .BR xli (1),
43 .BR xv (1),
44 or
45 .BR xloadimage (1)
46 tools.
47
48 \fIwebcollage\fP is written in
49 .BR perl (1)
50 and requires Perl 5.
51
52 It will be an order of magnitude faster if you also have
53 the \fIwebcollage-helper\fP program installed (a GDK/JPEG image
54 compositor), but \fIwebcollage\fP works without it as well.
55
56 \fIwebcollage\fP can be used in conjunction with the
57 .BR driftnet (1)
58 program (the Unix equivalent of EtherPEG) to snoop images from traffic
59 on your local subnet, instead of getting images from search engines.
60 .SH OPTIONS
61 .I webcollage
62 accepts the following options:
63 .TP 8
64 .B \-root
65 Draw on the root window.  This option is manditory, if output is being
66 produced: drawing to a window other than the root window is not yet
67 supported.
68 .TP 8
69 .B \-verbose \fRor\fP \-v
70 Print diagnostics to stderr.  Multiple \fI-v\fP switches increase the
71 amount of output.  \fI-v\fP will print out the URLs of the images,
72 and where they were placed; \fI-vv\fP will print out any warnings,
73 and all URLs being loaded; \fI-vvv\fP will print information on
74 what URLs were rejected; and so on.
75 .TP 8
76 .B \-timeout \fIseconds\fP
77 How long to wait for a URL to complete before giving up on it and
78 moving on to the next one.
79 Default 30 seconds.
80 .TP 8
81 .B \-delay \fIseconds\fP
82 How long to sleep between images.  Default 2 seconds.  (Remember that
83 this program probably spends a lot of time waiting for the network.)
84 .TP 8
85 .B \-background \fIcolor-or-ppm\fP
86 What to use for the background onto which images are pasted.  This may be
87 a color name, a hexadecimal RGB specification in the form '#rrggbb', or 
88 the name of a PPM file.
89 .TP 8
90 .B \-size \fIWxH\fP
91 Normally, the output image will be made to be the size of the screen.
92 This lets you specify the desired size.
93 .TP 8
94 .B \-no-output
95 If this option is specified, then no composite output image will be
96 generated.  This is only useful when used in conjunction 
97 with \fB\-verbose\fP.
98 .TP 8
99 .B \-urls-only
100 If this option is specified, then no composite output image will be
101 generated: instead, a list of image URLs will be printed on stdout.
102 .TP 8
103 .B \-filter \fIcommand\fP
104 Filter all source images through this command.  The command must take
105 a PPM file on stdin, and write a new PPM file to stdout.  One good 
106 choice for a filter would be:
107 .EX
108 webcollage -root -filter 'vidwhacker -stdin -stdout'
109 .EE
110 .TP 8
111 .B \-filter2 \fIcommand\fP
112 Filter the \fIcomposite\fP image through this command.  The \fI-filter\fP
113 option applies to the sub-images; the \fI-filter2\fP applies to the
114 final, full-screen image.
115 .TP 8
116 .B \-http\-proxy \fIhost:port\fP
117 If you must go through a proxy to connect to the web, you can specify it 
118 with this option, or with the \fB$http_proxy\fP or \fB$HTTP_PROXY\fP 
119 environment variables.
120 .TP 8
121 .B \-dictionary \fIfile\fP
122 Webcollage normally looks at the system's default spell-check dictionary
123 to generate words to feed into the search engines.  You can specify an
124 alternate dictionary with this option.
125 .TP 8
126 .B \-driftnet \fI[ args ]\fP
127 .BR driftnet (1)
128 is a program that snoops your local ethernet for packets that look
129 like they might be image files.  It can be used in conjunction 
130 with \fIwebcollage\fP to generate a collage of what other people on
131 your network are looking at, instead of a search-engine collage.
132 If you have \fIdriftnet\fP installed on your $PATH, just use 
133 the \fI\-driftnet\fP option.  You can also specify the location
134 of the program like this:
135 .EX
136 -driftnet /path/to/driftnet
137 .EE
138 or, you can provide extra arguments like this:
139 .EX
140 -driftnet '/path/to/driftnet -extra -args'
141 .EE
142 Driftnet version 0.1.5 or later is required.  Note that 
143 the \fIdriftnet\fP program requires root access, so you'll have
144 to make \fIdriftnet\fP be setuid-root for this to work.
145 Please exercise caution.
146 .SH ENVIRONMENT
147 .PP
148 .TP 8
149 .B DISPLAY
150 to get the default host and display number.
151 .TP 8
152 .B XENVIRONMENT
153 to get the name of a resource file that overrides the global resources
154 stored in the RESOURCE_MANAGER property.
155 .TP 8
156 .B http_proxy\fR or \fPHTTP_PROXY
157 to get the default HTTP proxy host and port.
158 .SH FILES AND URLS
159 .I /usr/dict/words,
160 .I /usr/share/lib/dict/words,\fP
161 or
162 .I /usr/share/dict/words
163 to find the random words to feed to search engines.
164 .PP
165 .I http://image.altavista.com/,
166 .I http://images.google.com/,
167 .I http://news.yahoo.com/
168 .I http://random.yahoo.com/bin/ryl,
169 and
170 .I http://lycospro.lycos.com/,
171 to find random web pages.
172 .SH BUGS
173 When drawing on the root window, it always uses the default colormap.
174 This is actually a limitation of xv.  But regardless, when using this
175 program with xscreensaver, it must be given the \fBdefault-n\fP 
176 visual specification (see the
177 .BR xscreensaver (1)
178 manual for more details.)
179
180 Animating GIFs are not supported: only the first frame will be used.
181
182 Too many of the images that it finds are text, not pictures.  This is 
183 because most of the web is pictures of text.  Which is pretty sad.
184 .SH UPGRADES
185 The latest version of webcollage can be found as a part of
186 xscreensaver, at 
187 .B http://www.jwz.org/xscreensaver/,
188 or on the WebCollage page at 
189 .B http://www.jwz.org/webcollage/.
190
191 DriftNet:
192 .B http://www.ex-parrot.com/~chris/driftnet/
193 .SH SEE ALSO
194 .BR X (1),
195 .BR xscreensaver (1),
196 .BR xli (1),
197 .BR xv (1),
198 .BR xloadimage (1),
199 .BR ppmmake (1),
200 .BR giftopnm (1),
201 .BR pnmpaste (1),
202 .BR pnmscale (1),
203 .BR djpeg (1),
204 .BR cjpeg (1),
205 .BR xdpyinfo (1),
206 .BR perl (1),
207 .BR vidwhacker (1),
208 .BR dadadodo (1),
209 .BR driftnet (1)
210 .BR EtherPEG ,
211 .BR EtherPeek
212 .SH COPYRIGHT
213 Copyright \(co 1998-2002 by Jamie Zawinski.  Permission to use, copy, modify,
214 distribute, and sell this software and its documentation for any purpose is
215 hereby granted without fee, provided that the above copyright notice appear
216 in all copies and that both that copyright notice and this permission notice
217 appear in supporting documentation.  No representations are made about the
218 suitability of this software for any purpose.  It is provided "as is" without
219 express or implied warranty.
220 .SH AUTHOR
221 Jamie Zawinski <jwz@jwz.org>, 24-May-98.