fvwm 1:2.6.7-3 / usr / bin / fvwm-menu-directory

#!/usr/bin/perl

# Copyright (c) 1999-2009 Mikhael Goikhman
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

# Filter this script to pod2man to get a man page:
#   pod2man -c "Fvwm Utilities" fvwm-menu-directory | nroff -man | less -e

# To speed up the script, several optimizations were made: trying to minimize
# the number of additional file operations, function calls and includes.

#print STDERR "fvwm-menu-directory @ARGV\n";

use strict;
use Getopt::Long;

my $version = "2.6.7";

my $name  = "MenuBrowser";  # used only with --reuse
my $title = "%*-40p";  # may contain specifiers %d, %p.
my $itemf = "%n";      # may contain specifiers %n, %t, %T, %d, %D, %s.
my $icont = "";
my $icond = "";
my $iconf = "";
my $icona = "";
my $home  = $ENV{'HOME'} || '/tmp';
my $dir   = $home;
my $xterm = "xterm -e";              # the X terminal program to invoke
my $exect = $ENV{'SHELL'} || '/bin/sh';
my $execf = $ENV{'EDITOR'} || "vi";  # the command to execute on plain files
my $execa = undef;
my $commt = undef;
my $commf = undef;
my $comma = undef;
my $all   = 0;  # whether show hidden files (like in 'ls -A')
my $links = 0;  # whether follow linked dirs or not
my $order = 5;  # -6, -5, -4, -3, -2, -1, 1, 2, 3, 4, 5, 6
my $reuse = 0;  # non-popup mode
my $wm_icons = 0;
my $check_subdirs = 0;  # whether check subdirs for +x permissions
my $special_dir_val = undef;  # which of (.. ~ /) dirs include or none
my $memory_for_speed = 0;
my $submenu_pos = " item +100 c";  # " menu +0 +0"
my $fvwm_user_dir = $ENV{'FVWM_USERDIR'} || "$home/.fvwm";
$fvwm_user_dir = $home unless -d $fvwm_user_dir;
my $dir_filename = "$fvwm_user_dir/.fvwm-menu-directory.dir";
my $change_menu_style = "";
my $func_name = "FuncFvwmMenuDirectory";

GetOptions(
	"help|h|?"     => \&show_help,
	"version|V"    => \&show_version,
	"name=s"       => \$name,
	"title=s"      => \$title,
	"item=s"       => \$itemf,
	"icon-title=s" => \$icont,
	"icon-dir=s"   => \$icond,
	"icon-file=s"  => \$iconf,
	"icon-app=s"   => \$icona,
	"dir=s"        => \$dir,
	"order=i"      => \$order,
	"all!"         => \$all,
	"links!"       => \$links,
	"xterm=s"      => \$xterm,
	"exec-title=s" => \$exect,
	"exec-file=s"  => \$execf,
	"exec-app:s"   => \$execa,
	"command-title=s" => \$commt,
	"command-file=s"  => \$commf,
	"command-app=s"   => \$comma,
	"reuse!"       => \$reuse,
	"wm-icons"     => \$wm_icons,
	"check-subdirs!"    => \$check_subdirs,
	"special-dirs:s"    => \$special_dir_val,
	"memory-for-speed!" => \$memory_for_speed,
	"menu-style=s" => \$change_menu_style,
	"func-name=s"  => \$func_name,
) || wrong_usage();
wrong_usage() if @ARGV;

$name = $dir unless $reuse;
$dir =~ s:^~(/|$):$home$1:;
chomp($dir = `cat "$dir_filename"`) if $reuse && -f $dir_filename;

unless (-d $dir) {
	# the next line may be commented not to throw error
	#die "$dir does not exist, exiting.\n";
	$dir = $home;
}

$links || !-l $dir || exit(-1);  # exit if linked directories are disabled
chdir($dir) || exit(-1);  # exit if no execute permission on the directory

# expand title
&expand_width_specifier(\$title, 'd', (split('/', $dir))[-1] || '/')
	if $title =~ /%(-?\d+)?(\*-?\d+)?d/;
&expand_width_specifier(\$title, 'p', $dir)
	if $title =~ /%(-?\d+)?(\*-?\d+)?p/;
$title =~ s/\\t/\t/g;
$itemf =~ s/\\t/\t/g;

# item format optimization variables
my $itemf_eval = $itemf ne '%f';  # evaluation needed
my $itemf_name = undef;
my $itemf_stat = undef;  # stat() needed
my $itemf_date = undef;
my $itemf_size = undef;
my $itemf_type = undef;

if ($itemf_eval) {
	$itemf_name = $itemf =~ /%(-?\d+)?(\*-?\d+)?[nN]/;
	$itemf_date = $itemf =~ /%[dD]/;
	$itemf_size = $itemf =~ /%(-?\d+)?(\*-?\d+)?s/;
	$itemf_type = $itemf =~ /%[tT]/;
	$itemf_stat = $itemf_size || $itemf_date || $itemf_size || $itemf_type;
}

my @type1 = ("Sock", "Link", "File", "Blck", "Dir ", "Char", "Pipe");
my @type2 = ("S", "L", "F", "B", "D", "C", "P");

if ($wm_icons) {
	$icont ||= "menu/folder-open.xpm";
	$icond ||= "menu/folder.xpm";
	$iconf ||= "menu/file.xpm";
	$icona ||= "menu/utility.xpm";
}

my $icont_str = $icont ? "%$icont%" : "";
my $icond_str = $icond ? "%$icond%" : "";
my $iconf_str = $iconf ? "%$iconf%" : "";
my $icona_str = $icona ? "%$icona%" : "";

$exect = undef if defined $exect && $exect eq '-';
$execf = undef if defined $execf && $execf eq '-';
$execa = undef if defined $execa && $execa eq '-';

$exect = $exect =~ /^\^(.*)$/ ? $1 : "$xterm $exect" if defined $exect;
$execf = $execf =~ /^\^(.*)$/ ? $1 : "$xterm $execf" if defined $execf;
$execa = $execa =~ /^\^(.*)$/ ? $1 : "$xterm $execa" if defined $execa;

$commt = undef if defined $commt && $commt eq '-';
$commf = undef if defined $commf && $commf eq '-';
$comma = undef if defined $comma && $comma eq '-';

$commt = defined $exect ? qq(Exec cd "%d"; $exect): "Nop" if !defined $commt;
$commf = defined $execf ? qq(Exec $execf "%f"):     "Nop" if !defined $commf;
$comma = defined $execa ? qq(Exec $execa "%f"):    $commf if !defined $comma;

# manage special directories if needed
my ($special_dir_lines, $special_dir_pos, @special_dirs) = ("");
$special_dir_val = "1,2" if defined $special_dir_val && $special_dir_val eq "";
if ($special_dir_val && $special_dir_val =~ /([\d,]+)(-?)/) {
	@special_dirs = grep(/^[1-3]$/, split(/,+/, $1));
	$special_dir_pos = $2 ? -1 : 1;
}
if (@special_dirs) {
	my $parent_dir = $dir eq '/' || $dir !~ m!^(.*)/[^\/]+$! ? undef : $1;
	$parent_dir = '/' if defined $parent_dir && $parent_dir eq '';
	my @special_dir_def = (
		[ '..' => $parent_dir ],
		[ '~'  => $home ],
		[ '/'  => '/' ],
	);
	foreach (@special_dirs) {
		$special_dir_lines .= qq(+ "" Nop\n) if $special_dir_lines;
		$special_dir_lines .= &eval_folder_line(@{$special_dir_def[$_ - 1]});
	}
} else {
	$special_dir_pos = 0;
}

# create file listing
opendir(DIR, ".");
my @files = readdir(DIR);
closedir(DIR);
@files = grep /^[^.]/, @files unless $all;

my $abs_order = abs($order);
# To avoid warnings, '!!' must be added before '-d'. Will this slow things?
my $sort_sub =
	$abs_order == 2 ? sub { -d $b <=> -d $a } :
	$abs_order == 3 ? sub { -d $a <=> -d $b } :
	$abs_order == 4 ? sub { $a cmp $b } :
	$abs_order == 5 ? sub { -d $b <=> -d $a || $a cmp $b } :
	$abs_order == 6 ? sub { -d $a <=> -d $b || $a cmp $b } :
	sub { 0 };
@files = sort $sort_sub @files if $abs_order != 1;
@files = reverse @files if $order < 0;

# dump all menu items and start adding new items
my $menu_name  = &escape_file_name($name);
my $menu_name2 = &escape_menu_name($name);
print qq(DestroyMenu recreate "$menu_name"\nAddToMenu "$menu_name2"\n);

# destroy the menu after it is popped down
print qq(+ DynamicPopDownAction DestroyMenu "$menu_name"\n)
	unless $memory_for_speed || $reuse;

# set the 'missing submenu function'
print qq(+ MissingSubmenuFunction $func_name\n) unless $reuse;

# add a new title (item and separator, or real Title if no action)
my $title_act = $commt; $title_act =~ s/%d/$dir/g;
if ($title ne "") {
	if ($title_act eq "") {
		print qq(+ "$icont_str$title" Title\n);
	} else {
		print qq(+ "$icont_str$title" $title_act\n+ "" Nop\n);
	}
}

# add special dirs at the top if needed
print qq($special_dir_lines+ "" Nop\n) if $special_dir_pos > 0;

# add directory contents
foreach (@files) {
	next if $_ eq '.' or $_ eq '..';
	my $file_path = "$dir/$_";
	$file_path =~ s|/+|/|g;
	if (-d) {
		# it's a directory
		print &eval_folder_line($_, $file_path);
	} else {
		# something else, apply editor to it or run itself
		my $item_str = $itemf_eval ? &eval_item($_, $file_path) : $_;
		$item_str = &escape_item_name($item_str);
		my $is_app = -x && -f;
		my $icon_str = $is_app && $icona_str ? $icona_str : $iconf_str;
		my $file_act = $is_app ? $comma : $commf;
		$file_act =~ s/%f/&escape_file_name($file_path)/ge;
		print qq(+ "$icon_str$item_str" $file_act\n);
	}
}

# add special dirs at the bottom if needed
print qq(+ "" Nop\n$special_dir_lines) if $special_dir_pos < 0;

# add style:
if ($change_menu_style ne "") {
	print qq(ChangeMenuStyle "$change_menu_style" "$menu_name"\n);
}
exit(0);

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

sub escape_fvwm_name ($) {
	my $name = shift;
	$name =~ s/\\/\\\\/g;
	$name =~ s/"/\\"/g;
	$name =~ s/\$/\$\$/g;
	$name;
}

sub escape_menu_name ($) {
	my $name = escape_fvwm_name(shift());
	# fvwm is really inconsistent here
	$name =~ s/\^/^^/g;
	$name =~ s/@/@@/g;
	$name;
}

sub escape_item_name ($) {
	my $name = escape_fvwm_name(shift());
	$name =~ s/%/%%/g;
	$name =~ s/&/&&/g;
	$name =~ s/\*/**/g;
	$name =~ s/\n/ /g;
	$name;
}

sub escape_file_name ($) {
	my $name = shift;
	$name =~ s/\\/\\\\/g;
	$name =~ s/"/\\"/g;
	$name =~ s/\$/\\\$\$/g;
	$name =~ s/\n/\\\n/g;
	$name;
}

sub eval_folder_line ($$) {
	my ($_name, $dir) = @_;
	my $item_str = $dir && $itemf_eval ? &eval_item($_name, $dir) : $_name;
	$item_str = escape_item_name($item_str);
	my $act = !$dir || $check_subdirs && !-x $dir ? "Nop" : !$reuse ?
		qq(Popup ") . escape_file_name($dir) . qq("$submenu_pos) :
		qq(PipeRead 'echo ") . escape_file_name($dir) . qq(" >$dir_filename; )
		. qq(echo Menu ") . escape_fvwm_name($name) . qq(" WarpTitle');
	return qq(+ "$icond_str$item_str" $act\n);
}

sub eval_item ($$) {
	my ($name, $file) = @_;
	return $name unless $itemf_eval;

	my $item_str = "$itemf";
	if ($itemf_name) {
		&expand_width_specifier(\$item_str, 'n', $name);
		&expand_width_specifier(\$item_str, 'N', $file);
	}
	return $item_str unless $itemf_stat;

	# / $dev, $ino, $mode, $nlink, $uid, $gid, $rdev,
	# \ $size, $atime, $mtime, $ctime, $blksize, $blocks
	my ($misc1, $misc2, $mode, $misc3, $misc4, $misc5, $misc6, $size,
		$misc7, $time) = stat($file);
	if ($itemf_date) {
		eval 'use POSIX qw(strftime);' unless defined $POSIX::VERSION;
		my @time = localtime($time);
		my $date1 = strftime("%Y-%m-%d %H:%M:%S", @time);
		my $date2 = strftime("%Y-%m-%d", @time);
		$item_str =~ s/%d/$date1/g;
		$item_str =~ s/%D/$date2/g;
	}
	if ($itemf_size) {
		&expand_width_specifier(\$item_str, 's', $size);
	}
	if ($itemf_type) {
		my $type;
#		$type = 2 if ($mode & 0100000);  # regular
#		$type = 4 if ($mode & 0040000);  # directory
#		$type = 0 if ($mode & 0140000);  # socket
#		$type = 1 if ($mode & 0120000);  # symlink
#		$type = 3 if ($mode & 0060000);  # block
#		$type = 5 if ($mode & 0020000);  # char-dev
#		$type = 6 if ($mode & 0010000);  # fifo
		$type = -p _ ? 6 : -c _ ? 5 : -b _ ? 3 : -l $file ? 1 :
			-S _ ? 0 : -d _ ? 4 : 2;
		$item_str =~ s/%t/$type1[$type]/g;
		$item_str =~ s/%T/$type2[$type]/g;
	}
	return $item_str;
}

# Substitutes all %N1*N2x in $name by properly stripped and justified $value.
sub expand_width_specifier (\$$$) {
	my ($name, $char, $value) = @_;
	$$name =~ s/%(-?\d+)?(\*(-?)(\d+))?$char/
		my $value = !$2 || $4 <= 3 || $4 > length($value) ? $value : $3
			? "..." . substr($value, -$4 + 3, $4 - 3)
			: substr($value, 0, $4 - 3) . "...";
		$1 ? sprintf("%$1s", $value) : $value;
	/ge;
}

sub show_help {
	print "A perl script that builds directory listing for fvwm.\n\n";
	print "Usage: $0 [OPTIONS]\n";
	print "Options:\n";
	print "\t--help             show this help and exit\n";
	print "\t--version          show the version and exit\n";
	print "\t--name=NAME        menu name,  default is '$name'\n";
	print "\t--title=NAME       menu title, default is '$title'\n";
	print "\t--item=NAME        menu item format, default is '$itemf'\n";
	print "\t--icon-title=XPM   menu title icon, default is none\n";
	print "\t--icon-dir=XPM     menu dir   icon, default is none\n";
	print "\t--icon-file=XPM    menu file  icon, default is none\n";
	print "\t--icon-app=XPM     menu +x    icon, default is none\n";
	print "\t--wm-icons         define icon names to use with wm-icons\n";
	print "\t--dir=NAME         starting dir, default is '$dir'\n";
	print "\t--order=NUM        NUM (-6 .. 6), default is 5\n";
	print "\t\t1 - do not sort,  2 - dirs first, 3 - files first\n";
	print "\t\t4 - sort by name, 5 - dirs first, 6 - files first\n";
	print "\t\tNegative number represents reverse order.\n";
	print "\t--all              show hidden files, default is no\n";
	print "\t--links            follow linked dirs, default is no\n";
	print "\t--xterm=CMD        xterm call, default is '$xterm'\n";
	print "\t--exec-title=CMD   title exec command, default is '$exect'\n";
	print "\t--exec-file=CMD    file exec command, default is '$execf'\n";
	print "\t--exec-app[=CMD]   +x files exec command, default is '-'\n";
	print "\t--command-title=CMD title fvwm command, default is '-'\n";
	print "\t--command-file=CMD file fvwm command, default is '-'\n";
	print "\t--command-app=CMD  +x files fvwm command, default is '-'\n";
	print "\t--reuse            no popups, reuse the same menu (no)\n";
	print "\t--check-subdirs    check subdir for +x permission (no)\n";
	print "\t--special-dirs[=X] include .. and ~ directories (no)\n";
	print "\t--memory-for-speed use speed optimization (no)\n";
	print "\t--menu-style=NAME  assign specified MenuStyle name to menus\n";
	print "Short options are ok if not ambiguous: -a, -icon-f.\n";
	exit 0;
}

sub show_version {
	print "$version\n";
	exit 0;
}

sub wrong_usage {
	print STDERR "Try '$0 --help' for more information.\n";
	exit -1;
}

__END__

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

=head1 NAME

fvwm-menu-directory - builds a directory browsing menu for fvwm

=head1 SYNOPSIS

B<fvwm-menu-directory>
[ B<--help>|B<-h>|B<-?> ]
[ B<--version>|B<-V> ]
[ B<--name>|B<-na> NAME ]
[ B<--title>|B<-t> NAME ]
[ B<--item>|B<-it> NAME ]
[ B<--icon-title>|B<-icon-t> XPM ]
[ B<--icon-dir>|B<-icon-d> XPM ]
[ B<--icon-file>|B<-icon-f> XPM ]
[ B<--icon-app>|B<-icon-a> XPM ]
[ B<--wm-icons> ]
[ B<--dir>|B<-d> NAME ]
[ B<--order>|B<-o> NUM ]
[ B<--[no]all>|B<-a> ]
[ B<--[no]links>|B<-l> ]
[ B<--xterm>|B<-x> CMD ]
[ B<--exec-title>|B<-exec-t> CMD ]
[ B<--exec-file>|B<-exec-f> CMD ]
[ B<--exec-app>|B<-exec-a> [CMD] ]
[ B<--command-title>|B<-command-t> CMD ]
[ B<--command-file>|B<-command-f> CMD ]
[ B<--command-app>|B<-command-a> CMD ]
[ B<--[no]reuse>|B<-r> ]
[ B<--[no]check-subdirs>|B<-ch> ]
[ B<--special-dirs>|B<-s> [VALUE] ]
[ B<--[no]memory-for-speed>|B<-mem> ]
[ B<--menu-style>|B<-men> NAME ]
[ B<--func-name>|B<-f> NAME ]

=head1 DESCRIPTION

A perl script which provides an output to read in with PipeRead to build an
fvwm menu containing a directory listing. Almost everything can be configured.

=head1 HINTS

The title item with its own attached action is usually added to the menu.
This may be used to define an action for the directory for which the menu is
built, such as starting a terminal in this directory (the default).
However, this may annoy some users. To disable the title action use
B<--command-title> "", to remove the title completely use B<--title> "".

=head1 OPTIONS

=over 4

=item B<--help>

show the usage and exit

=item B<--version>

show version and exit

=item B<--name> name

menu name, used only with --reuse, default is MenuBrowser

=item B<--title> title

menu title format, default is '%*-40p' - last 40 characters
of the current full path.
TAB can be specified as '\t', but in .fvwm2rc you should specify a double
backslash or a real TAB.

Format specifiers:
  %d - the current directory name
  %p - the current directory full path

These specifiers can receive an optional integer size, positive for right
adjusted string or negative for left adjusted, example: %8x; 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 "...", 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.

=item B<--item> format

menu item format, default is '%n'. TAB and width modifiers
for %n, %N and %s can be specified as described in B<--title> above.
Note, specifying a non default format slows the script.

Format specifiers:

  %n - file/dir name (without the path)
  %N - file/dir name (full with the path)
  %d - file/dir date (yyyy-mm-dd HH:MM:SS)
  %D - file/dir date (yyyy-mm-dd)
  %s - file/dir size (in bytes)
  %t - file/dir type (File|Dir |Link|Sock|Blck|Char|Pipe)
  %T - file/dir type (F|D|L|S|B|C|P)

Example: --title '%*-40p\tDate, Type\tSize' --item '%*40n\t%d %t\t%s'

=item B<--icon-title> icon

menu title icon, default is none

=item B<--icon-dir> icon

menu dir icon, default is none

=item B<--icon-file> icon

menu file icon, default is none

=item B<--icon-app> icon

menu application icon, default is none

=item B<--wm-icons>

define icon names suitable for use with wm-icons package.
Currently this is equivalent to: --icon-title menu/folder-open.xpm --icon-item
menu/file.xpm --icon-dir menu/folder.xpm --icon-app menu/utility.xpm.

=item B<--dir> dir

starting dir, default is ${HOME-.}

=item B<--order> number

in the range (-6 .. 6), default is 5:

  1 - do not sort,  2 - dirs first, 3 - files first
  4 - sort by name, 5 - dirs first, 6 - files first
  Negative number represents reverse order.

=item B<--[no]all>

show hidden files, like in 'ls -A', default is --noall

=item B<--[no]links>

follow linked directories, default is --nolinks

=item B<--xterm> command

X terminal call, default is 'xterm -e'

=item B<--exec-title> command

an fvwm Exec command on directory title (usually the
shell), default is ${SHELL-/bin/sh}.
'-' means no Exec command, i.e. Nop.
If the command is not started with '^' X terminal call is prepended.
The command is started in the currently browsed directory.

=item B<--exec-file> command

an fvwm Exec command on regular files,
default is ${EDITOR-vi}.
'-' means no Exec command, i.e. Nop.
If the command is not started with '^' X terminal call is prepended.
The actual file name is appended to the command.

=item B<--exec-app> [command]

an fvwm Exec command on +x files, default is '-',
which means the same command as on regular files. If no command is given,
it is assumed to be empty - simply run the +x file.
If the command is not started with '^' X terminal call is prepended.
The actual file name is appended to the command.

=item B<--command-title> command

an fvwm command to execute on title.
If this option is not given (or command is '-'), the C<--exec-title>
is used instead.
In the command, %d is substituted with the full directory path.

In fact, I<--exec-title=tcsh> is equivalent
to I<--command-title='Exec cd "%d"; xterm -e tcsh'>

The empty value disables the title action.

=item B<--command-file> command

an fvwm command to execute on regular files.
If this option is not given (or command is '-'), the C<--exec-file>
is used instead.
In the command, %f is substituted with the full file path.

In fact, --exec-file=vi is equivalent
to --command-file='Exec xterm -e vi "%f"'

=item B<--command-app> command

an fvwm command to execute on +x files.
If this option is not given (or command is '-'), the C<--command-app>
is used instead.
In the command, %f is substituted with the full file path.

In fact, --exec-app=^exec is equivalent
to --command-app='Exec exec "%f"'

=item B<--[no]reuse>

no pop-up menus, reuse the same menu, default is --noreuse.
When you specify this option the Menu action is used, not Popup. Also,
the --name parameter is not ignored, and --dir parameter is ignored
if there is ~/.fvwm/.fvwm-menu-directory.dir file. This file is only created
or used with this option specified, it is the only solution for the current
fvwm menu state.

=item B<--[no]check-subdirs>

check all subdirs for having execute (+x) permission
and replace "Popup"/"Menu" command with "Nop" for these without permissions.
This has a visual effect of disabling popup triangle in the subdirectory item.
The default is --nocheck-subdirs, because: 1) enabling this slows a bit the
script, 2) with this option enabled, if no icons used and no dir/file separate
sorting used there is no way to know that the item is directory and not file.

=item B<--special-dirs> value

add .. or ~ or / special directories according to
given optional value. Without with option these directories are not added.
Default value if not specified is "1,2". The value is comma separated ordered
special directory indexes, where 1 is parent directory, 2 is home directory,
3 is root directory. If minus is prepended to the value, special directories
are added at the bottom of menu instead of top. Value "0" or any bad value
is equivalent to non-specifying this option at all.

=item B<--[no]memory-for-speed>

use speed optimization, i.e. use previously
created directory menus without destroying it when closed, default is
--nomemory-for-speed

    Warning: speed optimization takes up a lot of memory
    that is never free'd again while fvwm is running.

=item B<--menu-style> name

assign MenuStyle name to the menus

=item B<--func-name> name

overwrite the default MissingSubmenuFunction name that is
"FuncFvwmMenuDirectory"

=back

Option parameters can be specified either using '=' or in the next argument.
Short options are ok if not ambiguous: C<-a>, C<-x>, C<-icon-f>; but be
careful with short options, what is now unambiguous, can become ambiguous
in the next versions.

=head1 USAGE

Put this into your fvwm configuration file to invoke the script:

  AddToFunc FuncFvwmMenuDirectory
  + I PipeRead "fvwm-menu-directory -d '$0'"

More complex example:

  # AddToFunc FuncFvwmMenuDirectory
  # + I PipeRead "fvwm-menu-directory -d '$0' -x 'Eterm -g 80x40 -e' \\
    -a -l -o 6 --exec-app --exec-title 'tcsh -l' --exec-file 'vim -R' \\
    -t 'Go to: %d' --wm-icons"

And put this in the menu from which you want to pop-up the directory menus:

  AddToMenu SomeMenu MissingSubmenuFunction FuncFvwmMenuDirectory
  + "Home Directory"  Popup $[HOME]
  + "Httpd Directory" Popup /home/httpd

Note: please use absolute path names.

It is a good idea to set the menu pop-up delay to something positive
and enable busy cursor

  MenuStyle * PopupDelayed, PopupDelay 200
  BusyCursor DynamicMenu True

in your configuration file when using this script for better results.

Another interesting usage (C<--reuse> or C<-r> is mandatary for this):

  AddToMenu Browser
  + DynamicPopupAction PipeRead \\
    "fvwm-menu-directory -r -na Browser -d / -s"
  AddToMenu SomeMenu "My Browser" Menu Browser

Here the C<--dir> parameter (starting directory) is ignored if there is
~/.fvwm/.fvwm-menu-directory.dir file, which you can delete.

=head1 AUTHORS

Inspired  on 1999-06-07 by Dominik Vogt     <domivogt@fvwm.org>.

Rewritten on 1999-08-05 by Mikhael Goikhman <migo@homemail.com>.

=head1 COPYING

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

=head1 BUGS

Report bugs to fvwm-bug@fvwm.org.

=cut

# ***************************************************************************