Restructure how we look for Read files slightly.

[fvwm.git] / bin / fvwm-menu-desktop.1.in

.\" t
.\" @(#)@PACKAGE@-@VERSION@ @RELDATELONG@
.de EX          \"Begin example
.ne 5
.if n .sp 1
.if t .sp .5
.nf
.in +.5i
..
.de EE
.fi
.in -.5i
.if n .sp 1
.if t .sp .5
..
.ta .3i .6i .9i 1.2i 1.5i 1.8i
.TH fvwm-menu-desktop 1 "@RELDATELONG@ (@VERSION@)" Fvwm "Fvwm Modules"
.UC
.SH NAME
fvwm-menu-desktop \- builds GNOME and KDE menus and style commands for fvwm

.SH SYNOPSIS

fvwm-menu-desktop
[ \fB\-\-help\fR|\fB\-h\fR|\fB\-?\fR ]
[ \fB\-\-version\fR|\fB\-v\fR|\fB\-V\fR ]
[ \fB\-\-install\-prefix\fR \fIDIR\fR ]
[ \fB\-\-desktop\fR \fINAME\fR ]
[ \fB\-\-type\fR NAME\fR ]
[ \fB\-\-fvwmgtk\-alias\fR \fINAME\fR ]
[ \fB\-\-title\fR \fINAME\fR ]
[ \fB\-\-name\fR \fINAME\fR ]
[ \fB\-\-merge-user-menu\fR ]
[ \fB\-\-enable\-mini\-icons\fR ]
[ \fB\-\-enable\-tran\-mini\-icons\fR ]
[ \fB\-\-mini\-icons\-path\fR \fIDIR\fR ]
[ \fB\-\-png\-icons\-path\fR \fIDIR\fR ]
[ \fB\-\-tran\-mini\-icons\-path\fR \fIDIR\fR ]
[ \fB\-\-check-mini\-icons\fR \fIPATH\fR ]
[ \fB\-\-icon\-toptitle\fR
\fImicon\fR:\fIlaw\fR:\fIplace\fR:\fIside_pic\fR:\fIcolor\fR ]
[ \fB\-\-icon\-title\fR
\fImicon\fR:\fIlaw\fR:\fIplace\fR:\fIside_pic\fR:\fIcolor\fR ]
[ \fB\-\-icon\-folder\fR  \fImicon\fR:\fIlaw\fR:\fIplace\fR ]
[ \fB\-\-icon\-app\fR \fImicon\fR:\fIlaw\fR:\fIplace\fR ]
[ \fB\-\-wm\-icons\fR ]
[ \fB\-\-enable\-style\fR ]
[ \fB\-\-enable\-tran\-style\fR ]
[ \fB\-\-icon-style\fR \fImicon\fR:\fIicon\fR:\fIlaw\fR ]
[ \fB\-\-icons\-path\fR \fIDIR\fR ]
[ \fB\-\-tran\-icons\-path\fR \fIDIR\fR ]
[ \fB\-\-check-icons\fR \fIPATH\fR ]
[ \fB\-\-submenu\-name\-prefix\fR \fIname\fR ]
[ \fB\-\-dir\fR \fIDIR\fR ]
[ \fB\-\-destroy\-type\fR \fIFLAG\fR ]
[ \fB\-\-xterm\fR \fICMD\fR ]
[ \fB\-\-lang\fR \fINAME\fR ]
[ \fB\-\-utf8\fR ]
[ \fB\-\-uniconv\fR \fIcharset\fR ]
[ \fB\-\-uniconv-exec\fR \fIexec\fR ]
[ \fB\-\-menu-style\fR \fIname\fR ]
[ \fB\-\-no\-check\-app\fR ]
[ \fB\-\-time\-limit\fR \fINUM\fR ]

.SH DESCRIPTION
This is a perl script which parses GNOME or KDE menus definitions to build
corresponding fvwm or FvwmGtk menus. The script can also
build icon and mini\-icon style commands for the applications.

.SH USAGE
There are a lot of options. However the defaults are, I hope, good
enough.
If you want the KDE system menu in the menu "Utilities" add the
following lines in your .fvwm2rc file:
.EX
 ...
AddToMenu Utilities "KDE System Menu" Popup kde\-sys
 ...
PipeRead 'fvwm-menu-desktop --desktop kde-sys'
.EE
For KDE2 you may have to add --utf8 or --uniconv "charset" (see below).
Moreover, with KDE2 you can add --merge-user-menu.
If you use KDE version 1 (see below for KDE2) and you want mini\-icons
in the menu and if the KDE mini\-icons are in "mini/"
relative to your fvwm ImagePath add the option \-\-enable-mini\-icons.
(if the KDE mini\-icons are in some other place
use the \-\-mini\-icons\-path option, e.g., they are in your
ImagePath plus \-\-mini\-icons\-path). If you want to build Icon and
MiniIcon style commands for KDE applications, add the option \-\-enable-style.
If you want to have the KDE user menu replace "sys" by "user". If you use
the KDE menu editor, you may want to pop this menu up dynamically.
Then, put this into your .fvwm2rc file (note the destroy-type).
.EX
AddToMenu Utilities "KDE User Menu" Popup kde\-user
  ...
AddToMenu kde\-user
+ DynamicPopupAction PipeRead 'fvwm-menu-desktop --desktop kde-user --enable-mini-icons [--destroy-type dynamic] [other options]'
.EE

For GNOME it is natural to use FvwmGtk
menus. The following example builds "all" GNOME menus (with some
mini\-icons in the system menu). You need to specify the
GNOME installation prefix if it is not /usr (with the
option \-\-install\-prefix). Moreover, the GNOME icons need to be in your
ImagePath and the non .png mini\-icons you use for the user\-menu
need to be in mini/ (if not, use the \-\-png\-icons\-path option and
the \-\-mini\-icons\-path option, respectively).

.EX
Module FvwmGtk
*FvwmGtk: Destroy gnome-all
*FvwmGtk: Menu gnome-all
*FvwmGtk: Title "Gnome Menus"
*FvwmGtk: Separator
*FvwmGtk: Destroy gnome-sys
*FvwmGtk: Submenu "System" gnome-sys
*FvwmGtk: Destroy gnome-user
*FvwmGtk: Submenu "User" gnome-user
*FvwmGtk: Destroy gnome-redhat
*FvwmGtk: Submenu "RedHat" gnome-redhat

PipeRead 'fvwm-menu-desktop --type gtk --enable-mini-icons --icon-folder :re --icon-app :re --icon-title :re --icon-toptitle :re'

PipeRead 'fvwm-menu-desktop --type gtk --desktop gnome-user --enable-mini-icons'

PipeRead 'fvwm-menu-desktop --type gtk --desktop gnome-redhat --enable-mini-icons'

# To obtain the menu above with Alt-button1 on the root window
Mouse 1  R  M  SendToModule FvwmGtk gnome-all
.EE

You can specify FvwmGtk alias: Module FvwmGtk MyGnomeMenu.
In this case you must pass an additional parameter to fvwm-menu-desktop:
\-\-fvwmgtk-alias MyGnomeMenu.

Of course you can build fvwm (i.e., no FvwmGtk) GNOME menus.
GNOME and KDE2 use PNG icons which are not supported by fvwm menu.
However, if you have XPM version of the GNOME or of the KDE2 (mini-)icons
you can build fvwm menus and style commands with these icons using the
option \-\-enable-tran-mini\-icons and \-\-enable\-tran\-style. The
Fvwm Themes package (http://fvwm-themes.sourceforge.net/) contains
an utility, fvwm-themes-images, which can convert automatically
(with the help of ImageMagick) all GNOME and KDE2 icons to XPM
icons.

You can build sub menus using the \-\-dir options. However,
if you want to use more than one submenu
it is better to build the "all" menu and to use the submenu names.
See the option \-\-submenu\-name\-prefix for information on submenu
names. Nevertheless, you may put the menu in a tmp file using
redirection to see the submenu names.

If you think that fvwm-menu-desktop slows your startup too much do
not use PipeRead.  Instead run  fvwm-menu-desktop
and
redirect the menu to a file and Read that file in
your .fvwm2rc file.
Another possibility is to use DynamicPopupAction
(with fvwm menu), the menu (and the styles) will be built only if
you pop up the menu. The
following menu creates a "kde\-all" menu which contains the user menu
which is built each time you pop up "kde\-all" and contains a pop up
to the system menu which is built only the first time you pop it up.
.EX
AddToMenu kde\-all
+ DynamicPopupAction FuncRecreateKdeAll

AddToMenu kde\-sys
+ DynamicPopupAction PipeRead 'fvwm-menu-desktop \\
\-\-desktop kde\-sys [options, but \-\-destroy-type d* or n*]'

AddToFunc FuncRecreateKdeAll \\
I PipeRead 'fvwm-menu-desktop \\
\-\-desktop kde\-user \-\-enable\-mini\-icons \-\-name kde\-all \\
\-\-destroy-type dynamic [options you like]'
+ I AddToMenu "kde\-all" "" Nop
+ I AddToMenu "kde\-all" "Kde System%mini/mini\-k.xpm%" Popup kde\-sys
.EE

fvwm-menu-desktop takes into account your $LANG environment variable,
which may be overwritten using the --lang option.

Hint, if you need a different menu font or item format from the ones used
in the default MenuStyle, you may use the --menus-style option to assign
a non-default MenuStyle name to menus built by this script.
Don't forget to create a new menu style in your .fvwm2rc, using CopyMenuStyle
and MenuStyle commands.

.SH OPTIONS

.IP "Main Options"

.IP "\fB\-\-help\fR"
Show the help and exit.
.IP "\fB\-\-version\fR"
Show the version and exit.
.IP "\fB\-\-install-prefix\fR \fIDIR\fR"
The prefix of GNOME or KDE installation. Default
is /usr for GNOME (other common prefixes: /usr/local, /opt/gnome).
For KDE the default is $KDEDIR and you probably do not need
to use this option.
.IP "\fB\-\-desktop\fR \fINAME\fR"
Use gnome\-sys for the GNOME system menu (this is the default),
gnome\-user for
the GNOME user menu, gnome\-redhat for the AnotherLevel
menu of Red Hat,
gnome\-mandriva for Mandriva menudrake menus,
kde\-sys for the KDE system menu and kde\-user for
the KDE user menu. It may be useful to use KDE or GNOME as a flag with
the \-\-dir option.
.IP "\fB\-\-type\fR \fINAME\fR"
If NAME is fvwm, a native fvwm menu will be built (this is
the default). If NAME is gtk, a FvwmGtk menu will be built.
.IP "\fB\-\-fvwmgtk-alias\fR \fINAME\fR"
The name for then FvwmGtk module to use instead of default FvwmGtk.
.IP "\fB\-\-title\fR \fINAME\fR"
Define the menu title of the top menu. Default
is "Gnome System Menu" for gnome\-sys, "Gnome User Menu" for
gnome\-user, "Gnome Red Hat Menu" for gnome\-redhat,
"Gnome Mandriva Menu" for gnome\-mandriva. For KDE the
default is given by KDE itself (or are similar to GNOME title).
.IP "\fB\-\-name\fR \fINAME\fR"
Define the menu name of the top menu. Default is the \-\-desktop
name if you use one above.
.IP "\fB\-\-merge-user-menu\fR"
this option tries to merge the user menu
with the system menu (gnome-sys or kde-sys, based on the --desktop option)
and takes into account changes to the system menu that it is now
possible to do in the "user directory" (at least with KDE version 2
menu editor).


.IP "Icons Options"

By default, fvwm-menu-desktop  builds mini\-icon free menus. To enable
mini\-icons use one of the two following options.

.IP "\fB\-\-enable\-mini\-icons\fR"
This option enables mini\-icons in the menu.
The desktop hints are used if it is possible
(fvwm menu can't use .png icons). Use
the \-\-mini\-icons\-path and the \-\-png\-icons\-path to specify
the good paths. By using the \-\-icon-* options below you
can control mini\-icons in menus.
.IP "\fB\-\-enable\-tran\-mini\-icons\fR"
This option applies only to fvwm menus and is useful to build GNOME or KDE2
menus with mini\-icons (and if you have XPM version of the GNOME or KDE2
PNG icons).
If this option is used any
icon hint foo.png is translated to path/foo.xpm
where path is determined by the \-\-tran\-mini\-icons\-path option
(xpm icons are used as with the previous option).
.IP "\fB\-\-mini\-icons\-path\fR \fIDIR\fR"
Define the directory of the .xpm mini\-icons (relative to your
ImagePath). Default is "mini/".
.IP "\fB\-\-png\-icons\-path\fR \fIDIR\fR"
Define the directory of .png icons. Default is "" (i.e., in your
ImagePath). Useful only with FvwmGtk menus.
.IP "\fB\-\-tran\-mini\-icons\-path\fR \fIDIR\fR"
Define the directory of the mini\-icons for the \-\-enable\-tran\-mini\-icons
option. Default is mini/. It is
preferable to give the complete path so that fvwm-menu-desktop can check
if the translated mini\-icons exists (and the "re" law will apply in
a good way).
.IP "\fB\-\-check\-mini\-icons\fR \fIPATH\fR"
Where PATH is a list of directories with ":" as a separator. Then,
fvwm-menu-desktop checks that the mini icons actually exist in one of
these directories (this check is not done for the translated mini icons).

.IP Comments

To control  mini\-icons in menus you can use the 4 following options
which work similarly.

In these options \fIlaw\fR may be \fIno\fR, \fIdh\fR, \fIre\fR or \fIow\fR.
\fIno\fR means "do not use mini\-icon" (this does not affect side pic).
\fIdh\fR means "use only the mini\-icons GNOME/KDE hints".
\fIre\fR means "use mini\-icons GNOME/KDE hints but if it is empty
use the specified mini\-icon".
\fIow\fR means "override the mini\-icons GNOME/KDE hints by the specified
mini\-icon".

The path to the specified icons is given by the
options \-\-mini\-icons\-path, \-\-png\-icons\-path
or \-\-tran\-mini\-icons\-path (i.e., you just have to
specify the icon, the path is computed). For the sidepic you need to
give the complete relative path from your ImagePath.

Note that for the fvwm menu (without the \-\-enable\-tran\-mini\-icons option)
a .png icon hint is
considered as an empty hint, so for the system menu use no=dh and re=ow
(you may use .xpm icons in a user menu). If
the \-\-tran\-mini\-icons\-path option is set with a complete path,
then if the .xpm icon which corresponds  to a .png icon hint
does not exist, the icon hint is considered as empty.


\fIplace\fR, \fIsidepic\fR and \fIcolor\fR
apply only with fvwm menus. \fIplace\fR is either left or up.
\fIleft\fR means that the icon will be placed on the left of the
label. \fIup\fR means that the icon will be placed above the label.
\fIsidepic\fR needs to be nothing or an icon (for a picture in the
bottom left of the menu). \fIcolor\fR applies only
if a sidepic icon is given and it is the color for the region of the menu
containing the sidepic picture.

When you use an option below, if an icon, a law ...etc is not
specified (i.e., empty) the default is used (e.g, if you want,
for an fvwm menu, the icon folder.xpm on the left of the top title
and the sidepic fvwm2.xpm on the left of this menu
use the following: \-\-icon\-toptitle :ow::fvwm2.xpm).

.IP "\fB\-\-icon-toptitle\fR \fImicon\fR:\fIlaw\fR:\fIplace\fR:\fIsidepic\fR:\fIcolor\fR"
Mini\-icon for the top title and sidepic for the top menu.
Default for fvwm menus: folder.xpm:no:left::.
Default for fvwm menus with \-\-enable\-tran\-mini\-icons:
gnome\-logo\-icon\-transparent.xpm:no:left:.
Default for gtk menus:
gnome\-logo\-icon\-transparent.png:no.
.IP "\fB\-\-icon\-title\fR \fImicon\fR:\fIlaw\fR:\fIplace\fR:\fIsidepic\fR:\fIcolor\fR"
Use the option below for submenus.
Default for fvwm menus: folder.xpm:dh:left::.
Default for fvwm menus with \-\-enable\-tran\-mini\-icons:
gnome\-folder.xpm:dh:left::.
Default for gtk menus: gnome\-folder.png:dh
.IP "\fB\-\-icon\-folder\fR \fImicon\fR:\fIlaw\fR:\fIplace\fR:\fIsidepic\fR:\fIcolor\fR"
Mini-icons for pop up item.
Default for fvwm menus: folder.xpm:dh:left.
Default for fvwm menus with \-\-enable\-tran\-mini\-icons: gnome\-folder.xpm:dh:left.
Default for gtk menus: gnome\-folder.png:dh.
.IP "\fB\-\-icon\-app\fR \fImicon\fR:\fIlaw\fR:\fIplace\fR"
Mini\-icon for applications item.
Default for fvwm menus: mini\-x.xpm:dh.
Default for fvwm menus
with \-\-enable\-tran\-mini\-icons: gnome\-default.xpm:dh.
Default for gtk menus: gnome\-default.png:dh

.IP \fB--wm-icons\fR
This is a shortcut, which can be used if you plan to use icons from the
wm-icons package. Currently this is equivalent to:
\-\-enable\-mini\-icons
\-\-mini\-icons\-path ''
\-\-icon\-toptitle menu/folder-open.xpm:ow
\-\-icon\-title menu/folder-open.xpm:ow
\-\-icon\-folder menu/folder.xpm:ow
\-\-icon\-app menu/utility.xpm:ow.

.IP "Style Options"

.IP "\fB\-\-enable-style\fR \fImini\-icon\fR:\fIicon\fR:\fIlaw\fR:\fIaddstyle\fR"
Build icons and mini\-icons style commands for the applications in the built
menu.
.IP "\fB\-\-style\-tran\fR"
Only useful with FvwmGtk GNOME or KDE2 menus. Make translation as the
enable\-tran\-mini\-icon option but only for style
(not for mini\-icons menus).
.IP "\fB\-\-icon-style\fR \fImini\-icon\fR:\fIicon\fR:\fIlaw\fR:\fIaddstyle\fR"
This option
is  similar to the options \-\-icon-* above. Default law is "dh"
(there is no "no" law).
Default mini\-icon is mini\-x.xpm and default icon
is x.xpm. You can add a style to all applications with
addstyle. If you use the enable\-tran\-mini\-icon options the translated
(mini\-)icons will be used (if translation is needed)
and the default icons are gnome\-default.xpm.
If you use the \-\-enable\-tran\-style options above the default icons
are gnome\-default.xpm.
The paths to mini\-icons are the same as those for the menus. The
path to the icons is computed from the mini\-icons path: they are one
directory up to the corresponding mini\-icons path (so the "defaults"
are "" and this is consistent with KDE1 and XPM icons builded by
fvwm-themes-images).
.IP "\fB\-\-icons\-path\fR \fIDIR\fR"
Not useful in a normal situation.
Define the directory of the icons. Default is one directory up from
the path given by the \-\-mini\-icons\-path option. To set the path to ""
you need to use "inpath".
.IP "\fB\-\-tran\-icons\-path\fR \fIDIR\fR"
Similar to the above option.
.IP "\fB\-\-check\-icons\fR \fIPATH\fR"
Where PATH is a list of directories with ":" as a separator. Then,
fvwm-menu-desktop checks that the icons actually exist in one of
these directories (this chack is not done for the translated icons, use a
full path in --tran-icons-path to do so).

.IP "Other Options"

.IP "\fB\-\-submenu\-name\-prefix\fR \fINAME\fR"
May be useful in some unfortunate cases. By default the name of a sub menu
is of the form prefix\-adirname\-level where prefix is the desktop
flag, adirname is the name of the directory of the description of the
sub menus (not a complete path) and where level is an integer equal to
the number of "cd"s you need to do to go from the root to the directory of the
description of the sub menus. You may change the prefix using the
present option.
.IP "\fB\-\-dir\fR \fIDIR\fR"
Set the directory where fvwm-menu-desktop
looks for a GNOME/KDE menu description to \fIDIR\fR.
The name of the menu is 'desktop\-name' and the title is 'desktop' name
where 'desktop' is either GNOME or
KDE (if fvwm-menu-desktop can't find which desktop is concerned, you can
help with the \-\-desktop option) and where 'name' is the name of the
right directory of \fIDIR\fR (or a hint of the desktop for the title).
Note that if this option is not set, the description directory is
install\-prefix/share/gnome/apps if \-\-desktop is gnome\-sys,
$HOME/.gnome/apps  if \-\-desktop is gnome\-user,
$HOME/.gnome/apps\-redhat  if \-\-desktop is gnome\-redhat,
$HOME/.gnome/apps\-mdk  if \-\-desktop is gnome\-mandriva,
$KDEDIR/share/applink if \-\-desktop is kde\-sys and
$HOME/.kde/share/applnk if\-\-desktop is sys\-user.
.IP "\fB\-\-destroy\-type\fR \fIflag\fR"
flag may be "y(es)", "no", "d(ynamic)". Default is "yes" with fvwm menus,
"no" with FvwmGtk menus and dynamic applies only with fvwm menus.
If "yes" is used the top menu will be destroyed (DestroyMenu "name"),
if "no" is used the top menu will not be destroyed (useful for FvwmGtk
menus called by another menu via FvwmGtkSubMenu or to give the same
name to two or more menus built by fvwm-menu-desktop). If dynamic
is used the menu will be destroyed/recreated (may be useful with
DynamicPopupAction). Note that all the built sub menus are always
destroyed.
.IP "\fB\-\-xterm\fR \fICMD\fR"
Define complete X terminal command to run applications in it if needed.
Default is 'xterm -e'.
.IP "\fB\-\-lang\fR \fINAME\fR"
Default is the value of $LANG. Useful if your language is not GNOME/KDE
compliant and you prefer a non-English compliant
language. Also useful if fvwm-menu-desktop gives bad result with your language.
.IP "\fB\-\-utf8\fR"
Assume that the desktop entries used UTF-8 encoding. This is the case
with KDE version 2 and will be probably the case with GNOME version 2.
At the present time this option work only if you have perl version 5.6
or better and if your language use latin-1 font. If one of these conditions
is not satisfied, then this option is equivalent to \-\-lang en. For other
languages/charsets use the \-\-uniconv option. The advantage of this option
as compared to the following option is that it is fast.
.IP "\fB\-\-uniconv\fR \fIcharset\fR"
Use iconv, uniconv or internal method to translate utf8 desktop entries
into an appropriate "charset". You can choose between one of the supported
tools using \-\-uniconv-exec option. iconv comes with glibc >= 2.1.1 and
uniconv comes with the utf8 editor yudit. Type "iconv --list" or "man
uniconv" for the list of supported charsets. Of course you must also use the
appropriate font using the MenuStyle command. Also, $LANG (or --lang xx)
must be compatible with the charset. Note, if you don't use an internal
method, fvwm-menu-desktop is very slow with this option: you probably need
to use the --time-limit option and you should redirect the result into a
file and read this file in your fvwm configuration.
.IP "\fB\-\-uniconv-exec\fR \fIexec\fR"
Where exec is either iconv or uniconv or internal. Allows to choose the
program which perform the UTF8 translation in the case of the \-\-uniconv
option. The internal method is only available with perl 5.8.0 and better.
The default is either internal (if available) or iconv.
.IP "\fB\-\-menu-style\fR \fIname\fR"
By default the generated fvwm menus use the default MenuStyle (i.e., the
MenuStyle "*"). You can specify another MenuStyle name using this option.
.IP "\fB\-\-[no]check-app\fR"
Either check or don't check that applications to execute are in your path.
Default is \-\-check-app.
.IP "\fB\-\-time-limit\fR \fINUM\fR"
Change the internal limit (15 seconds) for running this script
to NUM seconds, 0 means unlimited running. This limiting may be useful
to cut mistakes with the \-\-dir or \-\-install\-path options.

.SH BUGS
This script needs more testing to see if all options work well
(note that the script does not check for inconsistency of the given options).
If Desktop menu hints are changed the script may not work as
expected. I have tested the script with gnome-core-1.0.3, kde-1.1, kde-1.2
and kde-2.0.

.SH AUTHORS
Olivier Chapuis <olivier.chapuis@free.fr>

Mikhael Goikhman <migo@homemail.com> - some changes

.SH COPYING
The script is distributed by the same terms as fvwm itself.
See GNU General Public License for details.