-
Notifications
You must be signed in to change notification settings - Fork 9
man page
Boruch Baum edited this page Mar 15, 2016
·
6 revisions
morc_menu(1) desktop application menu morc_menu(1)
NAME
morc_menu - categorized desktop application menu, independent of any
window manager
SYNOPSIS
morc_menu [ conf= [ path/to/file" | none ] ]
txt | xml [ in_file ]
[ build [ usr | loc | xml [in_file] ] [outfile] ]
[ show [ categories | desired | files ] ]
DESCRIPTION
morc_menu is a bash script that provides categorized menus of available applications in a manner similar to Openbox / Fluxbox style menus, but without requiring any window manager or its dependencies, and with wide lattitude for customization using its configuration file.
OPTIONS
When run with no parameters, morc_menu displays a dynamically-created,
navigable, and selectable menu of installed GUI applications. Depending
upon the chose front-end the menu may also be searchable.
conf= Over-ride the default order of reading configuration files. This
option must be listed first. It may point to the path of a spe‐
cific configuration file which will be the only one read, or it
may be set to 'none' to ignore all configuration files.
xml Display a static menu from the xml file specified, or if none is
specified, from the default (See below, section "Input files").
txt Display a static menu from the txt file specified, or if none is
specified, from the default (See below, section "Input files").
show Print to STDOUT the selected sub-option:
categories
A complete list of all categories referred to in all .desk‐
top files of folder /usr/share/applications.
desired
The list of categories that will actually appear in your
menu. It is based upon settings in the configuration file
or the default.
files
A complete list of all .desktop files in /usr/share/appli‐
cations.
build Build a static menu definition file, in text format, and name it
as specified, or the default (see section "Output files"). This
option accepts any one of three optional restrictions to compil‐
ing an entire menu:
usr Build a menu file only from .desktop file data in folder
/usr/share/applications.
loc Build a menu file only from .desktop file data in folder
~/.local/share/applications.
xml Build a menu file only from the specified xml file or the
default (see section "Input files"). This option was origi‐
nally intended to compare the results of this script with
methods used by other window managers. It takes as input
an xml file in in the format read by Openbox / Fluxbox and
as produced by the likes of ob_menu_generator. The output
is a text file usable by the other options of this script.
You will notice that some of those generator programs
inject entries even for programs which have no .desktop
entries and might not even exist.
REQUIREMENTS
Front-end
morc_menu requires some form of presenter program to which it passes
its menus. It was originally designed to work with dmenu-manjaro (a
feature-augmented version of dmenu), but it also funcitons with the
normal version of dmenu, as well as with rofi, zenity, yada and proba‐
bly others. If you've expressed an interest in morc_menu because of its
minimalism, flexibility, and full-features, we recommend using dmenu as
the front-end - it is the lightest presenter, is highly customizable,
and when presenting a menu it responds to your keyboard input by updat‐
ing the menu to the subset of matching keystrokes. The dmenu-manjaro
augmented version of dmenu adds support for customized positioning the
menu anywhere on your desktop, mouse support, and adjustable line
height. Refer to the configuration file for examples.
Positioning menu at mouse pointer
By default, morc_menu presents its menus at a static position on the
display, but setting variable 'use_mouse_position=TRUE' in the
morc_menu configuration file will have morc_menu position the menu at
the mouse pointer, but only if: 1) the presenter supports this (eg.
dmenu-manjaro or rofi, but not dmenu); 2) programs from two additional
packages, xdotool and wmutils, are available; and 3) variable
'menu_cmd' is set using the menu position string literals discussed in
the configuration file. There are handy examples in-place, so in prac‐
tice all you'll probably need to do is uncomment a line.
Environment
morc_menu expects that the programs the user wishes to have represented
in the menu be described in accordance with the freedesktop standard in
'.desktop' files, and that those files be present in locations consis‐
tent with the Linux LSB standard. In plain English, any normally main‐
tained Linux distribution and probably pretty much any *nix distribu‐
tion.
SETUP
If your distribution has a packaged version of this script, it is
advisable to install that package. That should automatically place the
configuration files and this man page in the locations appropriate for
your distribution, and include any customizations that your distribu‐
tion's packager may have added.
Manually installing the script involves five steps: Copy this script
file to a convenient location, for example, somewhere on your $PATH;
Make it executable by running 'chmod +x /path/to/file'; Optionally,
copy the script's associated config file to ${HOME}/.config/morc_menu;
Optionally, copy the script's associated man page to somehwere your
system will recognize (run command 'manpath', and if you can not place
it in any of those places, run 'man manpath' to see how to set $MAN‐
PATH), and; Create a keybinding for the script. An example keybinding
for use with the i3 window manager would be to modify your
${HOME}/.i3/config file to include a statement in the form:
bindsym $mod+z exec "${HOME}/path/to/morc_menu"
CUSTOMIZATION
This script offers methods to customize both the content of menus, and
their 'look' ('skin'). These methods are in the form of run-time
options and configuration file options.
Static content customization
The script offers run-time options to create a static menu based upon a
text file that it can initially build for you (option 'build') and
which you are then free to manually edit. The format of the text file
data is:
menu_name delim name delim execuatble
where:
menu_name is either the category or the value of
the string identifying a 'favorite'
item, by default '000'
delim is a delimiter, by default '---'
name is the conversational name of the program
executable is the command-line to run
Static menus will never be updated by changes to your operating system
or by operations performed by your system's package manager. They may
possily be adjusted by morc_menu if certain variables in the configura‐
tion file are changed. See the configuration file's in-line documenta‐
tion for details.
Static and Dynamic content customization
All available configuration options should be documented in place in
the configuration file. They include the options to define:
Desired categories: Categories to be displayed in your menu.
Category aliases: It turns out that some of the most commonly used cat‐
egory names displayed to users don't match the '.desktop' definitions.
The configuration file has an array variable for customizing this
behavior.
Unwanted names and executables: Easily exclude items from your menu.
Skins: A desired 'look' can be obtained by defining morc_menu's front-
end and the parameters to pass to that front-end, which typically
include coloring, positioning, sizing and fonts. Configuration files
desired for those front-end can also be imported. Also, the prefixes
and suffixes which mark sub-menus may be defined.
Positioning and Geometry: This will be suject to the limitations of the
presenter you choose. For example, dmenu does not support this, but
dmenu-manjaro and rofi do. These customization options allow the menu
to appear anywhere on the screen, in any size. Examples are given in
the configuration file.
ENVIRONMENTAL VARIABLES
${MORC_MENU_DIR}
The folder for morc_menu's default configuration and backup files.
If it is unset, or is set to an unreadable folder, or upon failure
to write to it, the default folder ${HOME}/.config/morc_menu is
used.
FILES
Except as otherwise noted, the location for all the files in this sec‐
tion is ${MORC_MENU_DIR}. The format of all .txt files is as discussed
above in section 'Static content customization'.
morc_menu_v1.conf
This file contains morc_menu's configuration and customization
options. If you would like all configuration file input to be
ignored, invoke morc_menu with a first parameter 'conf=none'. You
may also use that optional first parameter 'conf=' to specify a non-
default filename for a config file, in which case only that config
file will be used. By default, the script reads its configuration
options from up to four files, in the following sequence, allowing
later reads to modify prior settings (ie. last on the list wins):
/usr/share/morc_menu/morc_menu_v1.conf
/usr/local/share/morc_menu/morc_menu_v1.conf
${HOME}/.local/share/morc_menu/morc_menu_v1.conf
${MORC_MENU_DIR}/morc_menu_v1.conf
morc_menu.txt
The default input for displaying a static menu, and the default out‐
put for creating one.
morc_menu.xml
The default input for constructing a static menu based upon xml gen‐
erated by the like of ob_men_generator (see above, section OPTIONS).
morc_menu_xml.txt
The default output for static menus created from xml.
morc_menu_usr.txt
The default output for static menus created from data in folder
/usr/share/applications.
morc_menu_loc.txt
The default output for static menus created from data in folder
${HOME}/.local/share/applications.
Desktop files
morc_menu generates menus based upon the presence of /usr/share/appli‐
cations and the user-local definition folder
${HOME}/.local/share/applications, per the xfreedesktop and linux LSB
standards. Your system may have additional .desktop files in other
locations. That seems to be the case for 'optional' items. Linux's
expectation is that if a sysadmin would like entries for those items
system-wide, the sysadmin would copy them to /usr/share/applications.
If you want them for a specific user, place them in that user's
${HOME}/.local/share/applications folder. To find all system-wide desk‐
top files, you can run a command in the form 'find /usr -type f -name
"*.desktop"'.
Backup files
The configuration file includes an option to set the number of backups
to be kept. Setting that number to zero disables backups and will cause
morc_menu to delete currently stored backups the next time it checks
them. Backups are stored in the ${MORC_MENU_DIR} folder, and are iden‐
tifiable by their name ending in a timestamp. Backups are only added
when they would be different from the most recent prior backup; Other‐
wise, the modification time of the most recent backup is updated, so
its timestamp reflects when it was created and its modification time
when a subsequent run of morc_menu build was performed.
BUGS
Reporting bugs
It's strongly preferred to report bugs to the project's URL, currently
https://github.com/Boruch-Baum/morc_menu. If that's not possible, the
developer may be contacted directly by e-mail, prefixing the subject
line "[MORC_MENU]".
Items don't appear or don't execute
If you have another menu presenter available, it would be helpful to
check whether that other presenter exhibits the same problem. The sim‐
plest way to permanently add an item is to add it to the morc_menu con‐
figuration file in array 'additional_entries', but the canonical way is
to add a .desktop file to ${HOME}/.local/applications. If a program
runs from the command line but not from the menu, and this is because
it needs to be run from a particular folder or with particular addi‐
tional parameters, you can either manually make those changes in the
.desktop file, manually modify a static menu, or make two changes to
the morc_menu configuration file: Add the element to array 'addi-
tional_entries', and add the undesirable version of the executable
to array 'unwanted_execs'.
Pixel counting
The script does not auto-magically know the width and height of font
characters in order to accurately calculate the perfect menu width and
height. This can be in large measure ameliorated by adjusting the con‐
figuration variables 'line_height', 'avg_char_width', and 'menu_width'.
For more information, see the configuration file's in-line documenta‐
tion.
Panel overwriting
If your desktop has panels along its borders, the script will not be
aware of them, and its menus may overlap them.
Lack of icons
Not a bug. The primary design consideration of the script was minimal‐
ism.
SEE ALSO
dmenu(1),rofi(1),zenity(1),yada(1),ob_menu_generator(1)
COPYRIGHT
Copyright ©2016, Boruch Baum <boruch_baum AT gmx DOT com> This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License aspublished by the Free Software Foundation; either version 3 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 MER‐ CHANTABILITY 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
morc_menu version 1 2016-03-14 morc_menu(1)