README for Wmconfig:

 1. What is Wmconfig ?
 2. Why should I use it ?
 3. How to install it ?
 4. How to configure it ?
 5. The wmconfig_launcer script ?
 6. Default Directories for the outputs ?
 7. Gnome2 won't display the menu ?
 8. KDE won't display the menu ?
 9. E17 and Freedesktop like (Gnome, KDE, Cinnamon, Mate) won't
    display the menu ?
10. Sawfish won't display the menu ?

--------------------------------------

1. What is Wmconfig ?

Wmconfig is a menu generation tool for various window managers and desktop
environments. See "wmconfig --help" for a list of supported window managers.
It reads configuration files and outputs the menu file to stdout or - if
supported - to files.

2. Why should I use it ?

Most Linux distributions (Debian, SuSe) already have tools like Wmconfig. But
these menus only work under these distributions. Once configured, you cannot
use the menu files with FreeBSD, OpenBSD or other Linux distributions.
Wmconfig uses the same configuration layout under all supported operating
systems.

3. How to install it ?

Download Wmconfig and extract the archive with:

tar -xvzf wmconfig-XXXX.tar.gz for the Gzip tar archive or
tar -xvjf wmconfig-XXXX.tar.bz2 for the Bzip2 tar archive.

Now run the usual commands:

./configure
make

for building and

su -c "make install" for installing.

4. How to configure it ?

The samples directory in the source directory contains some sample files.
Examples for emacs:

emacs name "Emacs"
emacs exec "emacs"
emacs group "Editors"
emacs icon "emacs.xpm"
emacs mini-icon "emacs-mini.xpm"
emacs description "Eight megabytes almost continuous swap usage"

The name entry describes the name of the program, that will be displayed in
the menu. The exec entry is used for the command and the group entry describes
the menu in which the entry will appear.
The two icon entries are only used, if the Window manager supports icon menus.
You may use the full path to the icon, if the Window manager cannot find it.
The description line describes a comment (used for KDE).

Wmconfig also support the creation of restart and exit commands, if supported
by the used Window Manager. Here is an examples:

restart name "Restart Session"
restart exec "/bin/sh"
restart group ""
restart description "Restarts the current Session"
restart restart "restart"

The "restart" line is important. When Wmconfig parses this entry, the content
of the "restart" line will be used for the creation of the menu entries.
This examples creates the normal restart function.
Valid entries instead of "restart" are "quit" and a Window manager name. With
the "quit" entry, Wmconfig will create an "exit" menu entry.
Here are 2 samples. The first will create the exit entry, the second one will
create an restart entry for Twm.

exit name "Exit Session"
exit exec "/bin/sh"
exit group ""
exit description "I want my text-console back"
exit restart "quit"

twm name "Restart with Twm"
twm exec "twm"
twm group "Other Windowmanagers"
twm description "Switch to the Twm Window Manager"
twm restart "twm"

Please note that the "/bin/sh" entry is specified, because Wmconfig will not
create the "Exit" or "Restart" menu entries when run with the "--check-existence"
option.
In the Twm sample, the "exec" line is the Window Manager you want to start. In
this case, the restart line signals Wmconfig to create an Restart entry for a
Window Manager.

5. The wmconfig_launcher script ?

You may use this script to start a small Tk based menubar with the --launcher
option.
If you specify a Windowmanager name as option, this script will try to read
your configuration ($HOME/.wmconfig/confs) or the default configuration
(/usr/local/etc/wmconfig/confs), integrate the Wmconfig menu output and
place the final configuration file in your $HOME directory.
The script reads the pre-configuration file, searches for the

# Wmconfig menu insert

line and inserts the Wmconfig output below this line. Here is a small sample
for Icewm:

wmconfig_launcher --icewm

now the script searches for $HOME/.wmconfig/confs/icewmrc.
If the script cannot find the file, it uses /usr/local/etc/wmconfig/confs/icewmrc
instead. Now it splits the file, appends the Wmconfig output to the first
splitted file, appends the second splitted file and copies the final file
to your Home directory ($HOME/.icewm/menu).
Now you may launch Icewm and you'll have the Wmconfig menu.
If you don't like the default configuration, you may copy icewmrc to
$HOME/.wmconfig/confs and edit the file. Please keep the Wmconfig line.

Here is a small sample $HOME/.xinitrc for Twm

rm $HOME/.twmrc
wmconfig_launcher --twm
twm

If you want to change your Windowmanager configuration when using the launcher
script, remember to edit the configuration files in $HOME/.wmconfig/confs.

6. Default Directories for the outputs ?

The default directories for various outputs are:

KDE1		- $HOME/.kde/share/applnk/wmconfig
KDE2		- $HOME/.kde/share/applnk/wmconfig
KDE3		- $HOME/.kde/share/applnk/wmconfig
Gnome		- $HOME/.config/menus/applications-merge	- the XML configuration
		  $HOME/.local/share/applications		- the application launchers
Enlightenment	- $HOME/.enlightenment/wmconfig
E17		- $HOME/.e/e/applications/menu/all/wmconfig
E19		- $HOME/.e/e/applications/menu/all/wmconfig
Freedesktop	- $HOME/.local/share
KDE4		- $HOME/.local/share
AfterStep	- $HOME/GNUstep/Library/AfterStep/wmconfig

7. Gnome2 won't display the menu ?

By default Gnome2 checks for a user menu file in:

$HOME/.config/menus/applications-merged/

Where the user can add or remove additional applications. If this file doesn't
exist, please create it with the following content:

<!DOCTYPE Menu PUBLIC "-//freedesktop//DTD Menu 1.0//EN" "http://www.freedesktop.org/standards/menu-spec/menu-1.0.dtd">
<Menu>
 <Name>Wmconfig</Name>
 <MergeFile type="parent">wmconfig.menu</MergeFile>
</Menu>

If this file already exists you may add these lines:

<Menu>
 <Name>Wmconfig</Name>
 <MergeFile type="parent">$HOME/.config/menus/applications-merged/wmconfig.menu</MergeFile>
</Menu>

to the file and Gnome will read the wmconfig.menu file and display the menu.
Please replace $HOME with your Home Directory.

8. KDE won't display the menu ?

By default KDE doesn't read $HOME/.config/menus/applications-merged and uses it's own structure. To
still add the Wmconfig submenu add a file in $HOME/.config/menus/applications-kmenuedit.menu with
the following content:

<!DOCTYPE Menu PUBLIC '-//freedesktop//DTD Menu 1.0//EN' 'http://www.freedesktop.org/standards/menu-spec/1.0/menu.dtd'>
<Menu>
 <MergeFile>wmconfig.menu</MergeFile>
</Menu>

If this file already exists, e.g. by using kmenuedit, add the last 3 lines of the file will KDE let
display the Wmconfig menu.
Finally adding a symlink inside $HOME/.config/menus with:

ln -s applications-merged/wmconfig.menu ./

will add a link as a work-around.

9. E17 and Freedesktop like (Gnome, KDE, Cinnamon, Mate) won't
   display the menu ?

Usually the Freedesktop specifications should let your favorite Freedesktop (XDG) window manager or
desktop environment show the Wmconfig generated menu.
In case this doesn't work, it may be the window manager or desktop environment comes with it's very
own specification and the Wmconfig output needs to be named corresponding this output. To find out
the name, the following commands will help:

ls /etc/xdg/menus/

/etc/xdg/menus/ is the path where XDG menu specifications are stored. Operating Systems apart Linux
and OpenBSD may store these specifications in another directory (e.g. /usr/local/etc/xdg/menus).
Once you found this directory, take a look on how the files are named.
There may be (as example):

enlightenment.menu
kde4-applications.menu
lxde-applications.menu

and a couple of other files. Following this scheme we now have the syntax where Wmconfig needs
to store it's own menu specification. Taking the above example and you wish to output "lxde", the
command for Wmconfig can be:

wmconfig --output lxde --outputdir ~/.config/menus/lxde-applications-merged

Another possibility making the outputdir parameter unneccesary is creating symlinks like:

cd ~/.config/menus
ln -s applications-merged lxde-applications-merged
ln -s applications-merged enlightenment-applications-merged
ln -s applications-merged kde4-applications-merged
ln -s applications-merged mate-applications-merged

and so on.

10. Sawfish won't display the menu ?

To let Sawfish display the Wmconfig menu some manual interaction is required, only once of course.
Open ~/.sawfish/rc with your favorite editor and append the following lines at the end:

(require 'wmconfig-menu)
(setq apps-menu wmconfig-menu))

Then launch Wmconfig with:

wmconfig --output sawfish > ~/.sawfish/lisp/wmconfig-menu.jl

This is a bit unflexible regarding to giving the Wmconfig menu the name of your choice. If you
want to rename the Wmconfig menu to something else, change the "wmconfig-menu.jl" file and the "rc"
file to the values you wish.
