bin/fvwm-menu-headlines.1

   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.