| blob | a6b5fbed25e369efd937363cee5a61ad83c7622f |
1 .\" Automatically generated by Pod::Man 2.16 (Pod::Simple 3.02)
2 .\"
3 .\" Standard preamble:
4 .\" ========================================================================
5 .de Sh \" Subsection heading
6 .br
7 .if t .Sp
8 .ne 5
9 .PP
10 \fB\\$1\fR
11 .PP
12 ..
13 .de Sp \" Vertical space (when we can't use .PP)
14 .if t .sp .5v
15 .if n .sp
16 ..
17 .de Vb \" Begin verbatim text
18 .ft CW
19 .nf
20 .ne \\$1
21 ..
22 .de Ve \" End verbatim text
23 .ft R
24 .fi
25 ..
26 .\" Set up some character translations and predefined strings. \*(-- will
27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
28 .\" double quote, and \*(R" will give a right double quote. \*(C+ will
29 .\" give a nicer C++. Capital omega is used to do unbreakable dashes and
30 .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
31 .\" nothing in troff, for use with C<>.
32 .tr \(*W-
33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
34 .ie n \{\
35 . ds -- \(*W-
36 . ds PI pi
37 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
39 . ds L" ""
40 . ds R" ""
41 . ds C` ""
42 . ds C' ""
43 'br\}
44 .el\{\
45 . ds -- \|\(em\|
46 . ds PI \(*p
47 . ds L" ``
48 . ds R" ''
49 'br\}
50 .\"
51 .\" Escape single quotes in literal strings from groff's Unicode transform.
52 .ie \n(.g .ds Aq \(aq
53 .el .ds Aq '
54 .\"
55 .\" If the F register is turned on, we'll generate index entries on stderr for
56 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
57 .\" entries marked with X<> in POD. Of course, you'll have to process the
58 .\" output yourself in some meaningful fashion.
59 .ie \nF \{\
60 . de IX
61 . tm Index:\\$1\t\\n%\t"\\$2"
62 ..
63 . nr % 0
64 . rr F
65 .\}
66 .el \{\
67 . de IX
68 ..
69 .\}
70 .\"
71 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
72 .\" Fear. Run. Save yourself. No user-serviceable parts.
73 . \" fudge factors for nroff and troff
74 .if n \{\
75 . ds #H 0
76 . ds #V .8m
77 . ds #F .3m
78 . ds #[ \f1
79 . ds #] \fP
80 .\}
81 .if t \{\
82 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
83 . ds #V .6m
84 . ds #F 0
85 . ds #[ \&
86 . ds #] \&
87 .\}
88 . \" simple accents for nroff and troff
89 .if n \{\
90 . ds ' \&
91 . ds ` \&
92 . ds ^ \&
93 . ds , \&
94 . ds ~ ~
95 . ds /
96 .\}
97 .if t \{\
98 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
99 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
100 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
101 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
102 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
103 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
104 .\}
105 . \" troff and (daisy-wheel) nroff accents
106 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
107 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
108 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
109 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
110 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
111 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
112 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
113 .ds ae a\h'-(\w'a'u*4/10)'e
114 .ds Ae A\h'-(\w'A'u*4/10)'E
115 . \" corrections for vroff
116 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
117 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
118 . \" for low resolution devices (crt and lpr)
119 .if \n(.H>23 .if \n(.V>19 \
120 \{\
121 . ds : e
122 . ds 8 ss
123 . ds o a
124 . ds d- d\h'-1'\(ga
125 . ds D- D\h'-1'\(hy
126 . ds th \o'bp'
127 . ds Th \o'LP'
128 . ds ae ae
129 . ds Ae AE
130 .\}
131 .rm #[ #] #H #V #F C
132 .\" ========================================================================
133 .\"
134 .IX Title "fvwm-menu-headlines 1"
135 .TH fvwm-menu-headlines 1 "2009-03-22" "2.5.28 (from cvs)" "Fvwm Utilities"
136 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
137 .\" way too many mistakes in technical documents.
138 .if n .ad l
139 .nh
140 .SH "NAME"
141 fvwm\-menu\-headlines \- builds headlines menu definition for fvwm
142 .SH "SYNOPSIS"
143 .IX Header "SYNOPSIS"
144 \&\fBfvwm-menu-headlines\fR [ \fB\-\-help\fR|\fB\-h\fR|\fB\-?\fR ] [ \fB\-\-version\fR|\fB\-V\fR ] [ \fB\-\-info\fR [site] ] [ \fB\-\-site\fR|\fB\-s\fR site ] [ \fB\-\-name\fR|\fB\-n\fR name ] [ \fB\-\-title\fR|\fB\-t\fR title ] [ \fB\-\-item\fR item ] [ \fB\-\-exec\fR|\fB\-e\fR exec-command ] [ \fB\-\-command\fR|\fB\-e\fR fvwm-command ] [ \fB\-\-icon\-title\fR icon ] [ \fB\-\-icon\-item\fR icon ] [ \fB\-\-icon\-home\fR icon ] [ \fB\-\-icon\-error\fR icon ] [ \fB\-\-wm\-icons\fR ] [ \fB\-\-frontpage\fR [where] ] [ \fB\-\-proxy\fR|\fB\-p\fR host:port ] [ \fB\-\-file\fR [file] ] [ \fB\-\-fake\fR [file] ] [ \fB\-\-timeout\fR seconds ]
145 .SH "DESCRIPTION"
146 .IX Header "DESCRIPTION"
147 This configurable perl script builds an fvwm menu definition for headlines of popular news web sites: FreshMeat, Slashdot, LinuxToday, DaemonNews, GNOME-News, KDE-News, RootPrompt, LinuxFr, ThinkGeek, \s-1CNN\s0, \s-1BBC\s0 and more.
148 .PP
149 It is possible to specify a customized menu item format, change a command (usually launching a browser) and add menu icons (there is a support for the wm-icons package).
150 .SH "OPTIONS"
151 .IX Header "OPTIONS"
152 .IP "\fB\-\-help\fR" 4
153 .IX Item "--help"
154 show the help and exit
155 .IP "\fB\-\-version\fR" 4
156 .IX Item "--version"
157 show the version and exit
158 .IP "\fB\-\-info\fR [site]" 4
159 .IX Item "--info [site]"
160 if site name is given print the site specific info, otherwise print all site names
161 .IP "\fB\-\-site\fR site" 4
162 .IX Item "--site site"
163 defile a web site, headlines of which to show, this option also can be used together with \-\-help to get new defaults. Default site: freshmeat.
164 .IP "\fB\-\-name\fR name" 4
165 .IX Item "--name name"
166 define menu name (default is \*(L"MenuHeadlinesFreshmeat\*(R")
167 .IP "\fB\-\-title\fR title" 4
168 .IX Item "--title title"
169 define menu title (default is \*(L"Freshmeat Headlines\*(R").
170 .IP "\fB\-\-item\fR label-format" 4
171 .IX Item "--item label-format"
172 .PD 0
173 .IP "\fB\-\-exec\fR command-format" 4
174 .IX Item "--exec command-format"
175 .PD
176 define format for menu item or command (what is shown and what is executed when the item is chosen). Default label is '%h\et%[(%Y\-%m\-%d \f(CW%H:\fR%M)]'. \s-1TAB\s0 can be specified as '\et', but in .fvwm2rc you should specify a double backslash or a real \s-1TAB\s0.
177 .Sp
178 Format specifiers for a headline format:
179 .Sp
180 .Vb 11
181 \& %h \- headline
182 \& %u \- url
183 \& %d \- date in the native format (that site backend supplied)
184 \& %[strftime\-argument\-string] \- date/time, see strftime(3)
185 \& the date/time is represented according to the local time;
186 \& date and/or time fields that can\*(Aqt be guessed are stripped
187 \& Example: %[|%d %B %Y| %H:%M %S]
188 \& If site supplied only date \- this becomes %[|%d %B %Y|],
189 \& if site supplied no date \- this becomes an empty string.
190 \& %{name} \- site specific named value, like %{comments}
191 \& %(text) \- arbitrary text, good for escaping or aligning
192 .Ve
193 .Sp
194 These specifiers can receive an optional integer size, positive for right adjusted string or negative for left adjusted, example: \f(CW%8x\fR; and optional *num or *\-num, which means to leave only the first or last (if minus) num of chars, the num must be greater than 3, since the striped part is replaced with \*(L"...\*(R", example: %*30x. Both can be combined: %\-10*\-20x, this instructs to get only the 20 last characters, but if the length is less then 10 \- to fill with up to 10 spaces on the right.
195 .Sp
196 Example:
197 .Sp
198 .Vb 1
199 \& \-\-exec "iceweasel \-remote \*(AqopenURL(%u, new\-window)\*(Aq || iceweasel \*(Aq%u\*(Aq"
200 .Ve
201 .IP "\fB\-\-command\fR command-format" 4
202 .IX Item "--command command-format"
203 like \fB\-\-exec\fR above, but enables to specify any fvwm command, for example, \*(L"Function FuncFvwmShowURL '%u'\*(R" not only Exec.
204 .Sp
205 In fact, \-\-exec=\*(L"mozilla '%u'\*(R" is equivalent to \-\-command=\*(L"Exec mozilla '%u'\*(R"
206 .IP "\fB\-\-icon\-title\fR icon" 4
207 .IX Item "--icon-title icon"
208 .PD 0
209 .IP "\fB\-\-icon\-item\fR icon" 4
210 .IX Item "--icon-item icon"
211 .IP "\fB\-\-icon\-home\fR icon" 4
212 .IX Item "--icon-home icon"
213 .IP "\fB\-\-icon\-error\fR icon" 4
214 .IX Item "--icon-error icon"
215 .PD
216 define menu icon for title, regular item, frontpage item and error item respectively. Default is no menu icons (equivalent to an empty icon argument).
217 .IP "\fB\-\-wm\-icons\fR" 4
218 .IX Item "--wm-icons"
219 define icon names suitable for use with wm-icons package. Currently this is equivalent to: \-\-icon\-title '' \-\-icon\-item menu/information.xpm \-\-icon\-home menu/home.xpm \-\-icon\-error menu/choice\-no.xpm.
220 .IP "\fB\-\-frontpage\fR [where]" 4
221 .IX Item "--frontpage [where]"
222 add the site frontpage item to the menu. Optional value can be used to specify where this item will be placed in the menu \- 'top' or 't', 'bottom' or 'b'.
223 .IP "\fB\-\-proxy\fR host[:port]" 4
224 .IX Item "--proxy host[:port]"
225 define a proxy to use. Example: \-\-proxy proxy.inter.net:3128
226 .IP "\fB\-\-file\fR [file]" 4
227 .IX Item "--file [file]"
228 write the menu output to specified file. If no filename is given with this option (or empty filename), the default filename \s-1WORK_HOME/SITE\s0.menu is used. Without this option or with '\-' filename, the menu output is written to standard output.
229 .IP "\fB\-\-fake\fR [file]" 4
230 .IX Item "--fake [file]"
231 don't connect to the host using \s-1HTTP\s0 protocol, instead, read from \s-1WORK_HOME/SITE\s0.in file. The following reads input from freshmeat.in (downloaded http://freshmeat.net/backend/recentnews.txt) and saves output to segfault.menu (both files are in \s-1WORK_HOME\s0): fvwm-menu-headlines \-\-site freshmeat \-\-fake \-\-file
232 .IP "\fB\-\-timeout\fR seconds" 4
233 .IX Item "--timeout seconds"
234 limit a line reading from a socket to this timeout, the default timeout is 20 seconds.
235 .PP
236 \&\s-1WORK_HOME\s0 of this script is ~/.fvwm/.fvwm\-menu\-headlines. It is created if needed.
237 .PP
238 Option parameters can be specified either using '=' or in the next argument. Short options are ok if not ambiguous: \f(CW\*(C`\-h\*(C'\fR, \f(CW\*(C`\-t\*(C'\fR; but be careful with short options, what is now unambiguous, can become ambiguous in the next versions.
239 .SH "USAGE"
240 .IX Header "USAGE"
241 1. One of the ways to use this script is to define a crontab entry to run the script every hour or so for every monitored site:
242 .PP
243 .Vb 3
244 \& 0,30 * * * * fvwm\-menu\-headlines \-\-file \-\-site freshmeat
245 \& 1,31 * * * * fvwm\-menu\-headlines \-\-file \-\-site linuxtoday
246 \& 2,32 * * * * fvwm\-menu\-headlines \-\-file \-\-site slashdot
247 .Ve
248 .PP
249 Then add these lines to your fvwm configuration file:
250 .PP
251 .Vb 3
252 \& DestroyFunc FuncFvwmMenuHeadlines
253 \& AddToFunc FuncFvwmMenuHeadlines
254 \& + I Read "$HOME/.fvwm/.fvwm\-menu\-headlines/$0.menu"
255 \&
256 \& DestroyMenu MenuHeadlines
257 \& AddToMenu MenuHeadlines "Headlines" Title
258 \& + MissingSubmenuFunction FuncFvwmMenuHeadlines
259 \& + "FreshMeat" Popup freshmeat
260 \& + "LinuxToday" Popup linuxtoday
261 \& + "Slashdot" Popup slashdot
262 .Ve
263 .PP
264 2. Another way to use this script (only if you have fast network/proxy) is to run it every time you want to open your Headlines submenus. (Note, the submenu that is once created is not reloaded, use \*(L"Reset all\*(R".)
265 .PP
266 In this case your fvwm configuration lines could be:
267 .PP
268 .Vb 4
269 \& DestroyFunc FuncFvwmMenuHeadlines
270 \& AddToFunc FuncFvwmMenuHeadlines
271 \& + I PipeRead "fvwm\-menu\-headlines \-\-site $0"
272 \& #+ I Schedule 900000 DestroyMenu $0 # reset generated menu in 15 minutes
273 \&
274 \& DestroyMenu MenuHeadlines
275 \& AddToMenu MenuHeadlines "Headlines" Title
276 \& + MissingSubmenuFunction FuncFvwmMenuHeadlines
277 \& + "FreshMeat" Popup freshmeat
278 \& + "Slashdot" Popup slashdot
279 \& + "LinuxToday" Popup linuxtoday
280 \& + "GNOME News" Popup gnome\-news
281 \& + "KDE News" Popup kde\-news
282 \& + "" Nop
283 \& + "Reset all" FuncResetHeadlines
284 \&
285 \& DestroyFunc FuncResetHeadlines
286 \& AddToFunc FuncResetHeadlines
287 \& + I DestroyMenu freshmeat
288 \& + I DestroyMenu linuxtoday
289 \& + I DestroyMenu slashdot
290 \& + I DestroyMenu gnome\-news
291 \& + I DestroyMenu kde\-news
292 .Ve
293 .PP
294 And finally, add \*(L"Popup MenuHeadlines\*(R" somewhere.
295 .PP
296 3. Here is a usual usage. Use FvwmConsole or FvwmCommand to run fvwm commands from a shell script. Every time you want headlines from some site, execute (give any additional options if you want):
297 .PP
298 .Vb 3
299 \& PipeRead "fvwm\-menu\-headlines \-\-site newsforge \-\-name MenuHeadlinesNewsForge"
300 \& # this may take several seconds, you may use: BusyCursor Read true
301 \& Popup MenuHeadlinesNewsForge
302 .Ve
303 .SH "HOW TO ADD SITE HEADLINES"
304 .IX Header "HOW TO ADD SITE HEADLINES"
305 It is possible to add user defined site headlines without touching the script itself. Put your perl extensions to the file WORK_HOME/extension.pl. For each site add something similar to:
306 .PP
307 .Vb 8
308 \& $site_info\->{\*(Aqmyslashdot\*(Aq} = {
309 \& \*(Aqname\*(Aq => "MySlashdot",
310 \& \*(Aqhost\*(Aq => "myslashdot.org",
311 \& \*(Aqpath\*(Aq => "/myslashdot.xml",
312 \& \*(Aqfunc\*(Aq => \e&process_my_slashdot,
313 \& # the following string is only used in \-\-info
314 \& \*(Aqflds\*(Aq => \*(Aqtime, title, department, topic, author, url\*(Aq,
315 \& };
316 \&
317 \& sub process_my_slashdot () {
318 \& return process_xml(
319 \& \*(Aqstory\*(Aq,
320 \& # mandatory \*(Aqh\*(Aq, \*(Aqu\*(Aq and \*(Aqd\*(Aq aliases or undef
321 \& { \*(Aqh\*(Aq => \*(Aqtitle\*(Aq, \*(Aqu\*(Aq => \*(Aqurl\*(Aq, \*(Aqd\*(Aq => \*(Aqtime\*(Aq },
322 \& sub ($) { # convert \*(Aqd\*(Aq string to (y, m, d, H, M, S)
323 \& $_[0] =~ /(\ed+)\-(\ed+)\-(\ed+) (\ed+):(\ed+):(\ed+)/;
324 \& ($1, ($2 || 0) \- 1, $3, $4, $5, $6);
325 \& }, +0, # timezone offset; already in UTC
326 \& );
327 \& }
328 \&
329 \& 1;
330 .Ve
331 .SH "AUTHORS"
332 .IX Header "AUTHORS"
333 This script is inspired by WMHeadlines v1.3 by:
334 .PP
335 .Vb 2
336 \& Jeff Meininger <jeffm@boxybutgood.com>
337 \& (http://rive.boxybutgood.com/WMHeadlines/).
338 .Ve
339 .PP
340 Reimplemented for fvwm and heavily enhanced by:
341 .PP
342 .Vb 1
343 \& Mikhael Goikhman <migo@homemail.com>, 16 Dec 1999.
344 .Ve
345 .SH "COPYING"
346 .IX Header "COPYING"
347 The script is distributed by the same terms as fvwm itself. See \s-1GNU\s0 General Public License for details.
348 .SH "BUGS"
349 .IX Header "BUGS"
350 I try to keep all supported site info up to date, but sites often go down, change their backend formats, change their httpd responses, just stop to post news and so on; the script in the latest cvs may be more up to date.
351 .PP
352 The headline times may be off by one hour or more, since the time is displayed for your local time zone, and the time zone of the original time in the site backend output is often guessed (sometimes incorrectly); similarly it is guessed whether to apply the daylight saving correction.
353 .PP
354 Report bugs to fvwm\-bug@fvwm.org.