dtfilemon Files

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

About
-----

dtfilemon is a .desktop files monitor which executes command(s) each time
an event occurs in a (monitored) .desktop file directory.

Requirements
------------
 
    * inotify-tools

Usage
-----

dtfilemon requires a configuration file specified in arguments of option
--config :

  8<--------------------------------------------------------------------
   $ dtfilemon --config /path/to/dtfilemon.conf
  8<--------------------------------------------------------------------

The sample configuration file dtfilemon-sample.conf is shipped with 
dtfilemon.

When this configuration is used, dtfilemon runs the command below to 
(re)generate the XDG menu for Fluxbox each time a .desktop file is 
created/delete/moved in any of the monitored .desktop file directories :

  8<----------------------------------------------------------------
  xdgmenumaker -i -f fluxbox > ~/.fluxbox/xdg.menu
  8<----------------------------------------------------------------

Attention, xdgmenumaker must be installed for this configuration to work
properly.

It is up to the user to start and stop dtfilemon. 

For instance, to use dtfilemon to update the XDG menu for Fluxbox at 
user-level, the script ~/.fluxbox/startup must be modified as below : 

  * Open the script, removes the line 'exec fluxbox'.
  
  * At the end of the script, add the code below :
  
    8<------------------------------------------------------------------
    dtfilemon --config /path/to/dtfilemon.conf &
    DTFILEMON_PID=$!
    
    exec fluxbox &
    FLUXBOX_PID=$!
    
    wait ${FLUXBOX_PID}
    kill ${DTFILEMON_PID}
    8<------------------------------------------------------------------

Delayed start
-------------

The Actual start of dtfilemon can be delayed using option --delay as in
example below :

  8<--------------------------------------------------------------------
   $ dtfilemon --delay 3 --config /path/to/dtfilemon.conf
  8<--------------------------------------------------------------------
  
Configuration File
------------------
a dtfilemon configuration file is a simple bash script which includes the
following properties :

 * TEMP_DIR = <DIR>

    Absolute path to the directory dedicated to dtfilemon temporary files.

 * DESTKOP_FILE_DIRS = ( <DIR> [<DIR> ...] )

    The .desktop file directories to monitor.
    
    When this property is either not set or empty, dtfilemon recursively
    monitors the folder 'applications' of each path specified by the
    environment variables XDG_DATA_HOME(1) and XDG_DATA_DIRS(2).
    
    (1) When XDG_DATA_HOME is either not set or empty, a default equal
        to $HOME/.local/share is used.
	
    (2) 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

 * DESKTOP_FILE_EXTS=( <EXT> [<EXT> ...] )

    The .desktop file extensions as a list of regular expression.
    
    When this property is either not set or empty, default to ( "[.]desktop" )

 * ON_EVENT_EXEC=( <EVENT>[|<EVENT> ...]:<CMD> [ <ARG> [<ARG> ...] ] ... )

    Defines the command(s) to execute when events occur in the monitored 
    directories.

    EVENT can be one of the following :

      * CREATE     : a .desktop file was created within a monitored directory.
      * DELETE     : a .desktop file was deleted within a monitored directory.
      * MOVED_FROM : a .desktop file was moved from a monitored directory.
      * MOVED_TO   : a .desktop file was moved into a monitored directory.

    CMD is the command to run when any of the specified events occurs. This
    must be an executable with or without path specification, in which case
    it must be on the PATH.
    
    [ <ARG> [<ARG> ...] ] are the arguments of the command CMD, if any.
    
    Note that commands with output redirection must be specified like
    in example below :
    
     ( "CREATE|DELETE:sh" "-c" "xdgmenumaker -i -f fluxbox > ~/.fluxbox/menu.xdg" )
      
    At runtime, the command CMD can get information on event that occured 
    through the environment variable DTFM_EVTNFO which is to the syntax
    "<DIR>:<EVT>:<FILE>" :
    
      * DIR is the directory in which the event occured.
      * EVT is the event that occured.
      * FILE is the name of the target file.

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
-------
dtfilemon logo was generated on patorjk.com/software/taag using font
Doom.