wmpamgen Files

                                                           
                                                           
      __      ___ __ ___  _ __   __ _ _ __ ___   __ _  ___ _ __  
      \ \ /\ / / '_ ` _ \| '_ \ / _` | '_ ` _ \ / _` |/ _ \ '_ \ 
       \ V  V /| | | | | | |_) | (_| | | | | | | (_| |  __/ | | |
        \_/\_/ |_| |_| |_| .__/ \__,_|_| |_| |_|\__, |\___|_| |_|
                         | |                     __/ |           
                         |_|                    |___/            

About
-----

wmpamgen is designed to generate a menu to ease access to user's preferred
applications under the following window managers :

  Fluxbox
  Openbox
  Window Maker

The menu is generated according to the installed applications, and, the 
user's preferred applications given as a list of .desktop file names.

The generated menu only includes entries for the preferred applications 
which are already installed when wmpamgen is run. Therefore, to ensure 
the menu is up-to-date, wmpamgen needs to be run on a regular basis: at 
startup of the window manager, or when application(s) is/are installed or
removed for instance. Under Linux, this can be automated using the inotify
API.


Requirements
------------
 
    * cmake 

Installation
------------

To compile wmpamgen with default settings and install it in /usr/bin, run
the following commands :

  8<--------------------------------------------------------------------
    $ mkdir _build
    $ cd _build
    $ cmake -DCMAKE_INSTALL_PREFIX=/usr -DCMAKE_BUILD_TYPE=Release ..
    $ make
    $ make install
  8<--------------------------------------------------------------------

Note that Native Language Support (NLS) can be disabled by passing 
-DENABLE_NLS=OFF to cmake.

Usage
-----
wmpamgen requires a configuration file that must be specified in argument
of option --config, like in example below :

  8<--------------------------------------------------------------------
    $ wmpamgen --config /path/to/wmpamgen-sample.conf

    [11:06:55] Configuration:
    [11:06:55]   target-window-manager    : fluxbox
    [11:06:55]   enable-icons             : 1
    [11:06:55]   preferred-applications   : xterm,htop
    [11:06:55]   desktop-file-search-path : /usr/share/applications
    [11:06:55]   icon-search-path         : /usr/share/pixmaps
    [11:06:55]   preferred-terminals      : /usr/bin/xterm
    [11:06:55]   top-separator            : 0
    [11:06:55]   bottom-separator         : 0

    [11:06:55] Generates the menu ...
    [11:06:55] 8<-------------------------------------------------------
    [exec] (XTerm) {xterm} </usr/share/pixmaps/xterm-color_48x48.xpm>
    [exec] (Htop) {/usr/bin/xterm -e htop} </usr/share/pixmaps/htop.png>
    [11:06:55] 8<-------------------------------------------------------
    [11:06:55] Done (28 ms).
    [11:06:55] Exiting...
    [11:06:55]   Cleaning all resources and memory in use....
    [11:06:55] Done.
  8<--------------------------------------------------------------------
  
In the example above, wmpmangen is run with a configuration to generate a
menu of preferred applications to fluxbox format. 1st, wmpamgen prints the
current configuration on stdout, then the menu is generated and printed on
stdout, and wmpamgen exits.

To prevent wmpamgen to print informational messages, the option --quiet must
be passed on the command line :

  8<--------------------------------------------------------------------
    $ wmpamgen --quiet --config /path/to/wmpamgen-sample.conf
    [exec] (XTerm) {xterm} </usr/share/pixmaps/xterm-color_48x48.xpm>
    [exec] (Htop) {/usr/bin/xterm -e htop} </usr/share/pixmaps/htop.png>
  8<--------------------------------------------------------------------

Note that wmpamgen terminates with exit-code 0 on success, 1 otherwise.

Configuration File
------------------
The configuration file passed in argument to option --config must be to
plain text format with entries to the format :

  property=value
  
Commented lines, i.e. which start with a # - preceded or not by space(s) -,
are ignored.

Spaces at both side of loaded values are automatically removed.

When there are more than one occurence of a given property, only the first
value is loaded, the others being ignored.

Here is the list of supported properties :

  target-window-manager
  ---------------------
  The name of the window-manager for which the menu must be generated. Can
  be one of the following :

      fluxbox
      openbox
      windowmaker

  enable-icons
  ------------
  Defines whether or not the generated menu must includes the icons (when
  available) for the preferred applications.
  
  Can be set to: 1,true,on,yes,0,false,off,no.
  
  Note that Window Maker does not support icons in menus, and thus, the 
  property enable-icons is ignored when this window manager is selected.
  
  preferred-applications
  ----------------------
  The user's preferred applications as a comma separated list of entries 
  using the syntax :
  
    list  ::= <entry>[,<list>]
    entry ::= <item>[:<item>]
    item  ::= <pathname>|<name>
  
  Each entry in this list can be :
  
    1. The absolute path of a .desktop file.
    
    2. A .desktop file name, with or without .desktop extension in which
    case wmpamgen selects the 1st matching .desktop file found on the
    'desktop file search path', if any.
    
    3. An alternative-expression as a colon separated list of .desktop
    file (path)names. In such case, wmpamgen selects the 1st of the
    specified (path)names found on the system, if any.
  
  The property preferred-applications must be set to "" when there is no
  preferred applications defined.
  
  desktop-file-search-path
  ------------------------
  Colon separated list of path to prepend to the ".desktop files search 
  path", which is initially set to :
  
    XDG_DATA_HOME/applications:XDG_DATA_DIRS/applications

  When XDG_DATA_HOME is either not set or empty, a default equal to
  $HOME/.local/share is used.
       
  When XDG_DATA_DIRS is either not set or empty, a default equal to
  /usr/local/share:/usr/share is used.

  see https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
  
  icon-search-path
  ----------------
  Defines the 'icon file search paths'. This must be a colon separated list
  of the paths in which to search for the icon files.
  
  This property is ignored when icons are disabled (see property enable-icons)
  and when Window Maker, which does not support icons in menus, is the targeted
  window manager.
  
  preferred-terminals
  -------------------
  The terminal emulators, in order of preference, as a comma separated 
  list of entry.
  
    -------------------------------------------------------------------
   ! At runtime, the 1st terminal in this list present on the system   !
   ! is defined as to be used to execute the command of any preferred  !
   ! application to run in a terminal, ie. whose the .desktop file has !
   ! an entry 'Terminal=true'.                                         !
    -------------------------------------------------------------------
  
  Each entry in this list must be to the following syntax :

    term[:exec-option]
    
  term:
    the program name, with or without path specification, in which case
    wmpamgen will search the program on the PATH.
   
  exec-option:
    The option to pass to the terminal to execute a program. When not 
    specified, wmpamgen assumes the terminal supports the option '-e' 
    the same way as xterm.

  top-separator
  -------------
  Defines whether or not a separator must be added at top of the menu.
  
  This property is ignored in the following cases :
  
    * none of the applications specified by property preferred-applications 
      is installed.
    
    * the property target-window-manager is set to windowmaker.

  bottom-separator
  ----------------
  Defines whether or not a separator must be added at bottom of the menu.
  
  This property is ignored in the following cases :
  
    * none of the applications specified by property preferred-applications 
      is installed.
    
    * the property target-window-manager is set to windowmaker.

Sample configuration files
--------------------------
wmpamgen comes with the sample configuration files below :

  * /usr/doc/wmpamgen/wmpamgen-sample.conf, which is designed to be used
    under Linux.
    
  * /usr/doc/wmpamgen/wmpamgen-sample_slackware.conf, which is designed to
    be used under Linux/Slackware.
    
  * /usr/doc/wmpamgen/wmpamgen-sample_freebsd.conf, which is designed to
    be used under FreeBSD.
    
These configurations target the window manager fluxbox with icons support
enabled.
  
The configuration wmpamgen-sample.conf and wmpamgen-sample_freebsd.conf
defines the following preferred applications :
  
      firefox
      thunderbird
      gimp
      xterm
      htop

The configuration wmpamgen-sample_slackware.conf defines the following 
preferred applications :

      thunar
      firefox
      thunderbird
      geeqie
      gimp
      audacious
      gmplayer
      xterm
      htop

Access the preferred applications menu from window managers
-----------------------------------------------------------
To access the preferred applications menu generated for a given window 
manager, this one need to be configured beforehand.

The instructions below assumes that generated menu files are stored in 
~/.wmpamgen, and have been generated by running wmpamgen like in example
below :

  8<--------------------------------------------------------------------
    $ wmpamgen -q -c /path/to/wmpamgen.conf > ~/.wmpamgen/fluxbox.pamenu
    $ wmpamgen -q -c /path/to/wmpamgen.conf > ~/.wmpamgen/openbox.pamenu
    $ wmpamgen -q -c /path/to/wmpamgen.conf > ~/.wmpamgen/wmaker.pamenu
  8<--------------------------------------------------------------------

  1. Fluxbox configuration
     ---------------------

     a. Configuration for an access from root-menu
        ------------------------------------------
	Open the root menu file (~/.fluxbox/menu by default), then, after
	the entry "[encoding]", add the following :
	
	8<--------------------------------------------------------------
	[include] (~/.wmpamgen/fluxbox.pamenu)
	[separator]
	8<--------------------------------------------------------------

     b. Configuration for an access from a sub-menu of the root-menu
        ------------------------------------------------------------
	Open the root menu file (~/.fluxbox/menu by default), then, after 
	the entry "[encoding]", add the following :
	
	8<--------------------------------------------------------------
	[submenu] (Preferred Applications)
	  [include] (~/.wmpamgen/fluxbox.pamenu)
	[end]
	[separator]
	8<--------------------------------------------------------------
	
	
     c. Configuration for an access from a popup-menu
        ---------------------------------------------
	Open the keyboard shortcuts configuration file ~/.fluxbox/keys, 
	then at the end of this file, add the following :
	
	8<--------------------------------------------------------------
	Mod4 p :CustomMenu ~/.wmpamgen/fluxbox.pamenu
	8<--------------------------------------------------------------
	
	This allows to access the preferred applications menu with the 
	shortcut <WinKey> + <P>.
     
  2. Openbox configuration
     ---------------------
     To access the preferred applications menu from OpenBox main menu, open
     ~/.config/openbox/menu.xml, then :
     
       1. Above the line <menu id="root-menu" label="Openbox 3">, add the
       following :
       
         8<-------------------------------------------------------------
	 <menu id="preferred-applications" 
	       label="Preferred Applications" 
	       execute="cat ~/.wmpamgen/openbox.pamenu" />
	 8<-------------------------------------------------------------
       
       2. Above the line <separator label="Applications" />, add the following :

         8<-------------------------------------------------------------
	   <menu id="preferred-applications" />
         8<-------------------------------------------------------------

  3. Window Maker configuration
     --------------------------
     To access the preferred applications menu from Window Maker main menu,
     open ~/GNUstep/Defaults/WMRootMenu, then, below the line "Window Maker",
     add the following :

         8<-------------------------------------------------------------
	   ("Preferred Applications",OPEN_MENU,"~/.wmpamgen/wmaker.pamenu"),
         8<-------------------------------------------------------------

Troubleshooting
---------------
In case of issue with wmpamgen, rebuild it with debug informations by passing
-DCMAKE_BUILD_TYPE=Debug (or RelWithDebInfo) to cmake, re-run wmpamgen to 
reproduce the issue, then send the system configuration in use, the output 
of wmpamgen, the back/stack trace, if any, and any other informations that 
could be useful to solve the issue, at :

  <slacker6896@gmail.com>

Known issues
------------
None

Translation
-----------
At the moment, wmpamgen manual page and messages (including help page), 
are only translated in french.

Anybody who wants to contribute to translation (or even correction) is 
welcome and can contact me at <slacker6896@gmail.com>.


Authors
-------

  + Sébastien Ballet <slacker6896@gmail.com>


License
-------
The source code of this program is governed by the BSD 3-clause license 
that can be found in the LICENSE file. 


Credits
-------
wmpamgen logo was generated on patorjk.com/software/taag using font Doom.