WMINFO(1)

NAME

wminfo - Window Maker showing information dockable application

SYNOPSIS
wminfo [-p <plugin_name>] [options]

DESCRIPTION
wminfo is a dockapp that displays text-format information using the plugin. The standard plugin is a shell script. The plugin writes the information to stdout and wminfo captures the output and displays it row by row. Using the appropriate plugins wminfo can display different information got from the system or from Internet.

The wminfo program was designed as a platform to run the plugins written in bash. Since the version 4.0.0 it allows also to run the scripts written in different languages as well as the binary programs.

For the quick start read first the README.1st document.

OPTIONS

-p <plugin_name>
    runs the selected plugin.

-s <scrolling_speed>
    sets scrolling speed from 0 upwards -- default is 1.

-r <rewinding_speed>
    sets rewinding speed from 0 upwards -- default is 18.

-i <iso_encoding_number>
    sets ISO-8859-* encoding -- allowed values are 1, 2, 5, and 0 for none -- default is 0.

-u <update_information_period>
    depending on the parameter format sets the period between information updates in seconds -- default is 180 -- or uses regular expression to match the time string (see: README.regex).

-b <background_color>
    sets the background color in the range from #000000 to #ffffff -- default is #000000.

-f <foreground_color>
    sets the foreground color in the range from #000000 to #ffffff -- default is #c0c0c0.

-t <timing_coefficient>
    sets the time of the idle states between the consecutive application window refreshings -- it affects the responsiveness of the program reactions to the mouse actions as well as the level of the CPU usage; allowed coefficient values are 1, 2, 4, 8, or 16 -- these numbers are the multipliers of the 1/32 of a second (31250 microseconds) so the first is for 1/32 of a second and the last is for 1/2 of a second; the lower timing coefficient values are for the faster responsiveness and the higher CPU usage; the higher timing coefficient values are for the slower responsiveness and the lower CPU usage -- the default value is 4 which means the idle time equal 1/8 of a second: it combines a good responsiveness with a good preformance.

-c  commoves changed lines -- default is to not move (value 0).

-k  keeps empty lines -- default is to not keep (value 0).

-v  switches verbose mode -- default is to be silent (value 0).

-h  displays short help.

PROGRAM
To display wminfo help run the command:

    wminfo -h

or:

    wminfo

To use the plugin run the command such as:

    wminfo -p plugin.wmi

where plugin.wmi is the name of the plugin.

The command without -p switch:

    wminfo plugin.wmi

displays in wminfo window wminfo help (it uses default.wmi plugin).

The command with an invalid plugin name:

    wminfo -p plageen.wmi

displays the messages such as:

    sh: plageen.wmi: command not found

    wminfo: there is no "plageen.wmi" plugin or it is invalid.

The similar message appears when plugin.wmi is not executable or it is not script nor binary program.

DOCKAPP

The wminfo window looks like:

    +---------+
    |DOWN ALL|
    | ONE |
    | ONE |
    | ONE |
    |UP RERUN|
    +---------+

Click the given position to get the desired result:

    ONE -- the middle of the line: switches the scrolling of the line of the text;

    ALL -- upper right corner: switches the scrolling of all lines;

    UP -- lower left corner: rewinds the text up;

    DOWN -- upper left corner: rewinds the text down;

    RERUN -- lower right corner: reruns the plugin on demand.

The wminfo program can display the lines of the text up to 1023 characters in a line and no more than 1023 lines of the text. When the number of the characters in some line is bigger wminfo splits that line after each consecutive 1023 character and it displays just first 1023 lines of the text.

To check the lengths and the number of the lines it is enough to redirect wminfo plugin output to a file:

    plugin.wmi > file.tmp

PLUGINS
A lot of the plugins is included in the tarball plugins.* and samples directories. All these directories are copied to the system doc directory during the installation of wminfo.

Note that the plugins need not have the extension .wmi and need not to be the bash scripts. The wminfo program can run as plugins also Perl, AWK, Ruby etc. scripts as well as binary programs.

According to the convention used in the wminfo package all plugins have .wmi extesion regardless of their contents except for the binary plugins which have .bin extension and have the accompanying scripts with .wmi extension.

FILES

contrib
    The run-all-wminfo-plugins script runs all the plugins from the current directory -- used with the -c or --compact switch places wminfo windows more tightly.

    The counter script used with the -r or --reset switch resets all counters used by different plugins and used with the -R or --remove switch removes all the counters (that option is useful before you start the wminfo-benchmark in order to get the repeatable results).

    The plugin script displays the names of the plugins available in /usr/local/bin directory -- that script used with -a or --all switch displays the recommended commands for all available plugins and used with -h or --help switch displays the descriptions of all available plugins.

    The suspend script is used by thinkpad.wmi and conky.thinkpad.wmi plugins to suspend the system when the battery level is low.

    The timestring script tests the time string against the regular expression (it cooperates with the timestring.wmi plugin).

    The time+date script displays time and date for the given time zone, country, region/city, or GMT offset.

    The weather- script displays the current weather and the weather forecast for the given city.

    The weather-poland script displays weather reports for the cities in Poland.

    The wminfo-benchmark script tests the performance of the any number of wminfo instances running different plugins at the same time (you do not have to switch the system to the idle state before the test).

    The wminfo-conky script used with -d or --daemon switch starts the conky daemon using wminfo settings, used with -r or --restart switch restarts the daemon in order to force conky to reload the weather reports, and used with -t or --test switch tests whether conky daemon is running.

    The conky-parser function is used by numerous conky-related plugins.

    The following scripts: forecast, netmon, sysmon, and traffic are used by the respective plugins.

    The scripts: dos-unix and macos-unix convert CR+LF or CR ends of lines to LF ones. The html-iso? scripts convert HTML entities to ISO-8859-[1,2,5]. The punctuation script converts punctuation marks from HTML encoding and UTF-8 to ASCII. The scripts utf8-iso? convert from UTF-8 to ISO-8859-[1,2,5].

    The iso?-utf8 scripts reverse the convertions made by the respective plugins allowing to display properly the localized text on the console. The format script formats text files displayed on the console.

    The default.wmi plugin displays wminfo help when there is no -p switch in the wminfo command line and the bash-empty.wmi script displays the empty application window.

    All these scripts and plugins are copied to the PATH during the installation of wminfo.

plugins.binary
    This directory contains the binary plugins. To test them run run-all-wminfo-plugins script (optionally with -c or --compact switch).

plugins.conky
    This directory contains the conky dependent versions of a few plugins that work in a similar way to their bash equivalents from plugins.offline, plugins.online, and plugins.system-* directories as well as some conky dependent plugins that have not bash equivalents. In order to test them run run-all-wminfo-plugins script and follow the instructions (you can use the -c or --compact switch when wminfo windows are placed sparsely).

    To use conky-related plugins you have to run conky daemon using conky.conf configuration file provided with wminfo. Keep that file in your ~/.wminfo/ directory. To start the daemon use the command:

    conky -c "$HOME/.wminfo/conky.conf" -d 2> "$HOME/.wminfo/conky.log"

    or just run the script:

    wminfo-conky -d

    Instead or running conky manually you can register it in your ~/.xinitrc file:

    #--------------------------------------------------------------

    xhost `hostname`

    xmodmap ~/.Xmodmap

    eval rm "$HOME/.wminfo/.counter.*"

    if [ "`ps aux | grep "$USER" | grep conky | grep -vE 'grep|wminfo -p'`" == "" ] ; then conky -c "$HOME/.wminfo/conky.conf" -d 2> "$HOME/.wminfo/conky.log"; fi

    wmaker

    #--------------------------------------------------------------

    If you put a few weather monitors in the conky.conf file after a couple of minutes or hours conky daemon will break without any error messages. The only method to avoid that is to run the crontab entry that monitors your conky daemon and restarts it after the breakdown:

    */1 * * * * if [ "`ps aux | grep "$USER" | grep conky | grep -vE 'grep|wminfo -p'`" == "" ] ; then conky -c "$HOME/.wminfo/conky.conf" -d 2> "$HOME/.wminfo/conky.log"; fi

plugins.online
    This directory contains a lot of Internet-related plugins. These plugins work when there is constant Internet access. To test them run run-all-wminfo-plugins script (you can use the -c or --compact switch when wminfo windows are placed sparsely).

plugins.offline
    This directory contains the same plugins as the directory above but in the versions not requiring the constant Internet access. Before running these plugins you have to run at least once online script when Internet connection is available. The recommended method of running that script is to use the following crontab task:

    */6 * * * * if [ "`route | grep 'default'`" != "" ] ; then /usr/local/bin/online ; fi

    or:

    */6 * * * * if [ "`route | grep -E 'pan0|wlan0'`" != "" ] ; then /usr/local/bin/online ; fi

    or the similar specific for your system.

    The online script stores all the mirrored sites in the /var/www/htdocs/wminfo directory. So it has to be run with root priviledges or root has to make such a directory and change its mode bits to allow the other users to write there. If your HTTPD server stores HTML files in another location than /var/www/htdocs customize the DIRECTORY variable at the beginning of the online script. The wminfo plugins from the current directory require working HTTPD server.

    To test the plugins from the current directory run run-all-wminfo-plugins script (optionally with -c or --compact switch).

    You can access mirrored websites with your browser at the address http://localhost/wminfo/.

plugins.system-*
    This directory contains the plugins that are Internet independent (see also: the plugins from the plugins.conky directory). To test them run run-all-wminfo-plugins script (you can use the -c or --compact switch when wminfo windows are placed sparsely).

samples
    This directory contains four HTML files: full-utf8.html, html.html, quick-utf8.html and quick-koi8r.html with the characters in ISO-8859-[1,2,5] encodings, HTML entities, or sentences in English, German, French, Polish, and Russian as well as a few full-utf8-*.wmi, html-*.wmi, and quick-*-*.wmi wminfo plugins that display these HTML files using the proper ISO-8859-[1,2,5] encoding. The additional test.html file and two test-*.wmi wminfo plugins are useful during the tests of the scrolling and rewinding speeds. The a-1050-line-plugin.wmi and a-1913-letter-plugin.wmi plugins show how wminfo treats the plugins which generate more than 1023 lines or more than 1023 characters in a line. To test them all run run-all-wminfo-plugins script.

Plugins-HOWTO
This is the short instruction for wminfo plugins writers. The wminfo program displays dynamically different frequently changing information. It can be data got from the system as well as an information got from Internet.

The empty wminfo window looks like:

    +---------+
    | |
    | |
    | |
    | |
    | |
    +---------+

It has five lines each of nine characters. In the case of the plugins which display the information got from the system or some precisely defined information got from Internet such as weather reports, currency exchange rates etc. the task is to put these information into 5x9 window in a reasonable and intelligible way. In the case of the plugins displaying the information got from Internet websites such as system updates, headlines news etc. it usually doesn't fit 9-characters wide window and is longer than 5 lines. In such a case you have to scroll the contents of the wminfo window in order to read the entire information.

To write wminfo plugins it is enough to know the basics of bash and some frequently used commands. The more you know the shell and the commands the better your plugins are. Poorly designed plugins consume a lot of the system resources (mostly the CPU power). Well designed plugins can be really state of the art products.

To learn bash and the command line utilities read:

- man bash,

- Bash Guide for Beginners by Machtelt Garrels

    (see: http://tldp.org/LDP/Bash-Beginners-Guide/html/),

- Advanced Bash-Scripting Guide by Mendel Cooper

    (see: http://tldp.org/LDP/abs/html/),

- GNU/Linux Command-Line Tools Summary by Gareth Anderson

    (see: http://tldp.org/LDP/GNU-Linux-Tools-Summary/html/).

Since version 4.0.0 wminfo runs not only bash scripts but also the scripts written in different languages as well as binary programs. The languages such as Lua, AWK or C allow to write the plugins which have much better performance than their equivalents written in bash.

The plugins which display the information got from the system use the commands or programs displaying such an information and format these data to fit them in wminfo window. It is difficult to describe the general strategy for such situations because it depends on the format of the information provided by these commands or programs.

All the plugins which display the information got from Internet websites do basically the same: read HTML code and extract from it the valuable data. The present document describes the methods which can be used in that process.

                        *
                        * *

In order to display the particular information got from the website or FTP server it is enough to: download the source code of the site, change it to one line and then insert a line break before each HTML tag, look up for the required information and pass over the useless information, and finally remove all HTML tags leaving the ASCII text only.

In the case of the websites in languages using diacritic characters or special alphabets additional modifications of the code are required in order to translate it to one of the ISO encodings used by the program.

1.

The first step is to grab the code of the website. Usually lynx --source command does the job but in some cases links -source command is required -- sometimes with the additional switches. The commands to download the source code are:

    lynx --source http://www.linuxquestions.org/questions/slackware-14/

or:

    links -source -http-bugs.no-compression 1 http://slashdot.org/

It is possible to download HTML code of the website or FTP server.

In the case of HTML code using DOS CR+LF end-of-lines the following modification is allowed:

    tr -d '\r'

In the case of HTML code using Mac OS CR end-of-lines the following modification is required:

    tr '\r' '\n'

2.

The second step is to clean the code formatting. A convenient method is to convert the code with sed into one line by replacing new line characters with spaces and then to insert new line characters before each HTML tag:

    sed 's/\n/ /g;s/</\n</g'

In some rare cases sed refuses to work but Perl does the job:

    perl -pe 's/\n/ /g;s/</\n</g'

If, after that command it is impossible to distinguish the tags including the information we want from the other tags, it is necessary to use the trick implemented in the following plugins: bbc-mundo.wmi, cnet.wmi, commentcamarche.wmi, dpreview.wmi, kommersant.wmi, and wyborcza.wmi.

In such a case we split the above command into two parts.

At the beginning we use the command:

    sed 's/\n/ /g'

Then we seek for a pair of tags in which one tag includes some keyword and the other tag includes our information. Next we change all these following pairs of the HTML tags into one tag nonsensical from HTML validity point of view but helpful when the script has to identify the information using the mentioned keyword. The sample command joins the tag ending with 'class="title">' with the tag beginning with '<a href=':

    sed 's/class="title"><a href=/class="title" a href=/g'

At the end we insert new line characters before each HTML tag:

    sed 's/</\n</g'

3.

The third step is to select the information we look for. There are two methods -- one is to include some information and the other is to omit some information.

To include and omit the information we use grep -- in the other case with -v switch:

Including lines with 'onclick' word:

    grep 'onclick'

Omitting lines with 'NONE' word:

    grep -v 'NONE'

There is no need to omit empty lines -- wminfo does it for us -- though we can do it for the cosmetics purposes:

    grep -v '^$'

4.

The fourth step is to remove all HTML tags:

    sed 's/<.*>//g'

5.

The processing of the websites written in Western European or Eastern European languages as well as the websites using Cyrillic alphabet requires a few additional steps. The wminfo program recognizes diacritics used in those languages according to ISO-8859-1 and ISO-8859-2 encodings and Cyrillic alphabet according to ISO-8859-5 encoding but it requires the additional conversion when the website uses the other encoding such as UTF-8, CP-1250, CP-1251, or KOI8-R.

The samples directory contains two multilingual HTML files and some corresponding wminfo plugins for educational purposes.

5.1

The simplest case is with English. To display the punctuation marks properly it is enough to filter the output of the plugin through the following script:

    punctuation

5.2.

The other Western European languages require a few filters...

This is the code for the website in Western European language encoded in UTF-8:

    utf8-iso1 | punctuation

In the case of the websites using HTML entities such as: &nbsp;, &cent;, &sect;, &Oacute;, &oacute;, etc. the additional filtering is required:

    html-iso1

5.3.

The Eastern European languages are a more complicated case...

This is the code for Eastern European language website encoded in UTF-8:

    utf8-iso2 | punctuation

this is the code for Eastern European language website encoded in CP-1250:

    piconv -f CP-1250 -t ISO-8859-2 | punctuation

In the case of the websites using HTML entities such as: &nbsp;, &#728;, &sect;, &Oacute;, &oacute;, etc. the additional filtering is required:

    html-iso2

5.4.

The most complicated case are languages using the Cyrillic alphabet...

This is the code for website using Cyrillic alphabet encoded in UTF-8:

    utf8-iso5 | punctuation

this is the code for website using Cyrillic alphabet encoded in KOI8-R:

    piconv -f KOI8-R -t ISO-8859-5 | punctuation

this is the code for website using Cyrillic alphabet encoded in CP-1251:

    piconv -f CP-1251 -t ISO-8859-5 | punctuation

In the case of the websites using HTML entities such as: &nbsp;, &#1026;, &#1075;, &#1107;, &sect;, etc. the additional filtering is required:

    html-iso5

6.

If there is a risk that the output of some plugin can be sometimes empty -- for example after the upgrade of the system the list of the patches is empty -- to avoid the error message and the program break it is enough to put at the end of such a plugin the command:

    echo

The better method is to use the following commands:

    echo " "
    echo " "
    echo " "
    echo " "
    echo " "

or:

    echo -e " \n \n \n \n \n"

because they clear the application window when the former information disappears.

If the input does not end with the end-of-line mark to prevent the error message and the program break the same command is necessary:

    echo

All the above commands are not the parts of the pipeline but the separate commands put at the end of the plugin.

7.

The above instruction covers the basics of the wminfo plugins writing. In the specific situations the optimal order of the steps may be different and the other operations may be required. In plugins.online and plugins.offline directories there is a lot of the instructive plugins demonstrating the different Internet-related scripting methods.

8.

Instead of grabbing the information with the plugin it is possible to grab it with the script registered in the crontab and store it locally. In such a case wminfo plugins can use these local mirrors of the different websites.

The following crontab tasks run online script every six minutes when the system is on-line:

    */6 * * * * if [ "`route | grep 'default'`" != "" ] ; then /usr/local/bin/online ; fi

or:

    */6 * * * * if [ "`route | grep -E 'pan0|wlan0'`" != "" ] ; then /usr/local/bin/online ; fi

or the similar specific for your system.

As a result the crontab runs online script every six minutes and that script runs the registered commands. Because the crontab task recognizes the Internet connection and runs the online script only if the system is on-line wminfo is able to display the information even without the Internet connection using old temporary and mirror files. That method results in the more stable work of the program because it can display the information regardless of the Internet connection. It prevents aborting wminfo when the timeout is too long and prevents stucking of the scrolling text when the program gets and processes the information from the website.

Some websites do not allow to download the source code with lynx --source command. In such a case the command links -source is helpful. Sometimes it requires the additional switches. After mirroring the site locally with the links -source command the valid command to download the locally mirrored source code is lynx --source.

9.

The websites change from time to time. Some changes can cause the particular wminfo plugin stop to work. In such a situation try to remove the consecutive commands one by one starting from the end of the plugin. You can redirect the output of the plugin to the file or display it with less. When you will see the correct output recreate the plugin using the new set of the commands.

TODO

Add more ISO encodings -- to do that I need your encouragement and your cooperation in the case of the languages which use the alphabets other than Latin, Cyrillic, or Greek. The designing of the characters is time consuming so I would like to know that at least one person will use the results of my work.

The wminfo program can interpret the texts encoded in ISO encodings that is characters fitting the ASCII range from 32 to 255. So I can implement the characters specific for your language if there exist the suitable ISO encoding.

If you want to see the sample of the text in your language put into quick-utf8.html file from samples directory send me the sentence encoded in UTF-8 that contain all diacritics and special letters specific for your language. I do not expect you to invent such a sentence but to find the already existing sentence for your language. You can send it to Markus Kuhn too. Here is the list of the sentences collected by him:

    http://www.cl.cam.ac.uk/~mgk25/ucs/examples/quickbrown.txt

BUGS
Ten bugs encountered so far are described and solved in BUGS file.

If you discover any bugs in this software, please send a bugreport to c.kruk@bigfoot.com and describe the problem as a detailed way as you can.

LICENSE
wminfo is provided on the terms of the GNU General Public License v. 3. Read the COPYING file for the complete text of the license.

AUTHORS
wminfo 4.2.1:

    (C) 2011-2015 Cezary M. Kruk <c.kruk@bigfoot.com>

    (C) 2012 Peter Trenholme

    (C) 2012 Noam Postavsky

wmInfo 1.51:

    (C) 2000 Robert Kling

WMDOCKAPPS
For more Window Maker dockapps see:

    http://dockapps.windowmaker.org/

and:

    http://web.cs.mun.ca/~gstarkes/wmaker/dockapps/.

WINDOWMAKER
The current versions of Window Maker are available at:

    http://repo.or.cz/w/wmaker-crm.git

    (the fork maintained by Carlos R. Mafra)

and:

    http://git.altlinux.org/people/raorn/packages/WindowMaker.git

    (the fork maintained by Alexey I. Froloff).

The Window Maker site is available at:

    http://windowmaker.org/.