                          Introducing MenuMaker 0.17

   MenuMaker is utility written in Python that is capable of finding
   installed programs and generating menus for several supported X window
   managers. It is basically a frontend to library Prophet (currently
   shipped with MenuMaker) - very powerful heuristics-driven resource
   locator.

   It features:
     * Large knowledge base (KB) - currently over 600 programs are
       recognized, 300+ of them are X11-aware - potentional candidates
       for inclusion into window manager menu. Moreover, programs that
       require text console, are added as well.
     * Sophisticated search algorithms - since each KB entry is actually
       Python class, search algorithm's complexity is limited by nothing.
     * Unique Active Menus feature - dynamic menu regeneration with
       KDE-style Most Actively Used entries on almost every supported
       window manager.
     * Ease of use - just a single program call might create menus for
       several window managers at once.

                        MenuMaker software requirements

   The only requirement for MenuMaker is Python. It is supposed that
   Python version 2.0 will be enough, although MenuMaker is tested
   against 2.2 and 2.3 only.

   Python versions 1.5 and 1.6 are NOT supported at all. No attempt has
   been made to run MenuMaker under them so far. There are some plans to
   do that in near future, though.

                             Active Menus feature

   Active Menus is considered to be the central feature of MenuMaker, its
   main ``know-how''.

   It works by creating pools of Most Actively Used (MAU) entries at
   menus' top. When a user starts program from menu, MenuMaker refreshes
   window manager's menu to reflect changes made to MAU top list.

   KDE has very similar thing, but MenuMaker goes one step further by
   making several pools: one for KDE subtree, one for GNOME, one for text
   applications and so on. In addition there is one main pool in the
   window manager's root menu that contains entries from others. This
   system greatly increases menu usability as regardless of menu size
   access to MAU entries remains quick and simple. Note that all of this
   is for (almost) any supported X window manager (look at wm-specific
   notes though)!

   Unfortunately this requires some support from the window manager: the
   latter should check whether its menu file was altered since last menu
   draw and reload it automatically if so - not all recent window mangers
   are capable of this.

                          Supported X window managers

   Here is the list of environments MenuMaker curently provides some
   degree of support for, along with environment-specific notes:

     * Deskmenu
       This is the utility complementary to Oroborus X window manager
       that manages root menu for it. It is reported to work with some
       other window managers, however.
       Active Menus works fine, separators are supported as well.
     * FluxBox
       One of two known successors of currently dead BlackBox X window
       manager.
       Active Menus works, but menu flickers unpleasantly when being
       drawn on screen after change. No separators in menu.
     * IceWM
       Active Menus works great (there is no flicker). In fact,
       IceWM appears to be the best to use with MenuMaker :) as it is the
       one that allows to put separators in menu which greatly improves
       its look when Active Menus is used.
     * OpenBox
       Virtually the same as with FluxBox since they are based on the
       same code and haven't diverged significantly yet.
     * OpenBox3
       A complete rewrite of OpenBox, it uses different, XML'ed menu file
       format, therefore new driver is required. It now supports
       separators in menu (the good news), but at the moment it does not
       reload menu file during the session, so Active Menus is useless
       (not very good). This is likely to change in final OpenBox3,
       however.
     * WindowMaker
       Very powerful and slick X window manager with NeXTStep
       look'n'feel.
       Active Menus works as intended. Due to tiled nature of menu
       entries there is no way to implement separators.
     * XFce
       XFwm X window manager is a part of CDE-resembling XFce lightweight
       environment.
       Active Menus does not work with XFce version 3, since XFwm loads
       menu once upon startup and does not check for the changes during
       whole session. Hope this will be changed in the upcoming version
       4. No separators in menu.
     * XFce4
       XFce4 is a successor of XFce desktop environment. Now it has new
       component, XFdesktop, that is responsible for menu handling.
       Need to say that XFce4 is a huge step forward in terms of
       providing compability with MenuMaker ;). Active Menus works great
       - no flicker, quick response. Moreover, separators are now
       supported, too. Now it works as good as IceWM.

                           Installation instructions

   MenuMaker is Python package which does not follow conventional
   Linux/UNIX installation rules (but it follows Python's ones which are
   even simpler).

   1.
          Ensure you have Python installed. If you don't, install it -
          Python is included in vast majority of recent Linux/*BSD
          distributions.

   2.
          Unpack the tarball ``MenuMaker-*.tar.gz'' into temporary
          directory and cd to there.

   3.
          Become root and start ./setup.py install. This will compile the
          package, install files into Python's 3rd party package
          directory and place executable ``mmaker'' into ``bin''
          directory. If ``setup.py'' failes to start, try to specify
          Python interpreter explicitely - python2 ./setup.py install for
          example.

          IMPORTANT If you're upgrading from older version, it is wise to
          wipe out old package otherwise Prophet may get messed up with
          the mix of old and new files. Just run ./setup.py uninstall
          prior to installation. You might need root priviliges, of
          course.

   3a.
          If you can not become root you may run MenuMaker right from
          that temporary directory without installation - just type
          ./mmaker there. If it fails try to specify the interpreter as
          in 3. This is also useful if you do not intend to use it but
          just to see it in action. Note that Active Menus won't work in
          this case, so you should not use -A option.

                                  Usage notes

   IMPORTANT Before you start, backup your valuable menus, especially if
   they are hand-crafted - MenuMaker won't make any backups! Besides
   that, when running MenuMaker for the first time, redirect output to a
   temporary file (use -o option) and inspect its contents to ensure
   everything's OK.

   Once installation is complete you may play with MenuMaker by running
   ``mmaker''. mmaker -h will provide you with up-to-date usage
   information, here are just the most general notes:

     * Verbosity is controlled by -v option.
     * If option -o file_name is specified, generated menu is written to
       file_name instead of usual place - recommended option for the
       first run or if you have valuable menus and don't want to spoil
       it.
     * Active Menus is controlled by -A option. When run MenuMaker for
       the first time, do not use it - it may not work in your case; try
       regular mode first.
     * When -c option is specified, MenuMaker will first try to use
       cached data and therefore will not detect changes in programs, but
       will run times faster. Use it for fast regeneration of damaged
       menus.
     * Option -r allows to omit directory parts from full executable
       names where possible, i.e. the program can be started from command
       line without specifying full path to it. For example,
       /usr/X11R6/bin/xterm can be reduced to simple xterm as long as
       /usr/X11R6/bin is in PATH and there are no other Xterms installed.
       Other executables that can not be reduced in such way retain their
       full path names. This feature is useful for those people who use
       MenuMaker to generate menu templates for further customization.
     * Window managers to generate menus for go after all command-line
       options. You may specify any of them in arbitrary order (but if
       more than one, redirection option -o is not applicable!). They are
       case-insensitive. Refer to mmaker -h for full list of supported X
       window managers & options.

                                Trobleshooting

   MenuMaker is in active development and therefore everything is subject
   to change. If something goes wrong, first you should a) perform total
   cleanup and b) reinstall everything from scratch (only if you don't
   run it in-place).

   a)
          Total cleanup. The most likely cause of failure is
          incompability - when newly installed version of MenuMaker can't
          read cached information written by previous version. There are
          several steps you should follow sequentally; start with the
          first step and make next one only if previous didn't help.

        1.
                Regenerate menu from scratch, dropping all cached
                information. This means omitting -c option in the command
                line.

        2.
                Delete cached information manually. MenuMaker places it
                in directory ``~/.mmaker'', so you should delete
                everything inside it by typing rm -rf ~/.mmaker in
                command line. Unfortunately, you will loose then all the
                statistics gathered.

   b)
          Clean reinstall. Note that just reinstalling MenuMaker is not
          enough - you should wipe out previous version completly. And
          since Python installer can not do this itself, you'll have to
          make it by hand. First become root and find where Python stores
          its 3rd party packages. The usual path template is:

     ``<python_prefix>/lib/python<python_version>/site-packages''

          So, for Python 2.2.x on modern Linux system it becomes:

     ``/usr/lib/python2.2/site-packages''

          Then you should delete directories ``Prophet'' and
          ``MenuMaker'' inside it. And finally reinstall MenuMaker as
          usually. It is also recommended that you perform total cleanup
          after it, by making steps 2 and 1 (in that order).

                              Getting & feedback

   MenuMaker home page is:

     menumaker.sourceforge.net

   MenuMaker can be obtained from

     www.sourceforge.net/projects/menumaker

   hosted by SourceForge.net

   Author's email is:

     <fougas@mail.ru>

   And do not forget, your suggestions and ideas are always welcome!
     _________________________________________________________________


    Oleg A. Khlybov 2004-03-24
