morc_menu(1)

NAME

morc_menu - categorized desktop application menu, independent of any window manager

SYNOPSIS

morc_menu
    [ conf= [ path/to/file" | none ] ] [ no-sys ]
    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 specific configuration file which will be the only one read, or it may be set to 'none' to ignore all configuration files.

no-sys
    Ignore the system-wide pre-built morc_menu txt definition file. See below, section 'System-wide definition file'. This option must precede any of the following options

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 .desktop 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/applications.

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 compiling 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 originally 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 probably 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 updating 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 practice 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 consistent with the Linux LSB standard. In plain English, any normally maintained Linux distribution and probably pretty much any *nix distribution.

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 distribution'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 $MANPATH), 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 configuration file are changed. See the configuration file's in-line documentation 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 category 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 section 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 output for creating one.

morc_menu.xml
    The default input for constructing a static menu based upon xml generated 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.

  System-wide definition file
A system administrator may elect to create and maintain a base-line system-wide menu definition file that all user may reference. morc_menu expects such a file to exist at /etc/morc_menu.txt, and if it exists, morc_menu will, by default, use that file instead of building a menu. This behavior may be altered at the command line with option 'no-sys', or in the conf file by setting variable 'ignore_system_txt' to 'TRUE'.

  Desktop files
morc_menu generates menus based upon the presence of /usr/share/applications 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 desktop 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 identifiable by their name ending in a timestamp. Backups are only added when they would be different from the most recent prior backup; Otherwise, 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 simplest way to permanently add an item is to add it to the morc_menu configuration 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 additional 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 'additional_entries', and add the undesired 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 configuration variables 'line_height', 'avg_char_width', and 'menu_width'. For more information, see the configuration file's in-line documentation.

  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 minimalism.

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 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