Provided by: openbox_3.6.1-8_amd64 bug

NAME

       obamenu - menu generator for the openbox window manager.

DESCRIPTION

       obamenu (openbox automenu) is a menu generator for the openbox window manager. Rather than
       striving for full and complete xdg compliance obamenu offers a reasonable basic  level  of
       xdg compliance and focuses on low resource usage and pragmatic issues.

       obamenu consists of a single python file without any exotic imports. It has been developed
       with Python 2.7 should, however, work fine with any Python > 2.5 (possibly even older) and
       with Python's standard included batteries.

       Usage:

       obamenu

       That's it. No options, no parameters, simple as that. But ...

       As  openbox  users  are  not  afraid of editing config files, a decision was taken to make
       obamenu's configuration powerful yet simple not by command line  üarameters  or  a  config
       file but by having a short config section right within obamenu itself.

       The basic idea

       It  seems  reasonable  to  assume that openbox users are quite different from users of the
       more common and usually monstrous window managers.  And while obamenu is perfectly capable
       to  just splash the usual full menu into your .jwmrc the authors needs (and assumptions on
       other openbox users needs)  and  accordingly  obamenu's  capabilities  are  somewhat  more
       refined.

       First  some  basics. On pretty much any halfway modern Unixoid OS, there is some directory
       with ".desktop" files which contain information  about  applications  needed  by  the  OS;
       things  like  its name, the command, possibly some comment, and so on. On most linuxes and
       BSD this directory is  "/usr/share/applications".  Of  course,  as  with  every  standard,
       there's  some  idio^H^H^H^H  players  (like Gnome) who don't care that much and dump their
       .desktop files elsewhere and anywhere.  Similarly there is also a place for all those nice
       application  (not  OS!)  icons.  Usually  they  are in "/usr/share/pixmaps".  Last but not
       least, there are "Categories" into which applications are grouped in menus.  Btw,  obamenu
       does not show empty categories to avoid senseless clutter.

       So, let's have a look at a obamenu's config section and its bits and pieces:

       #   ----   config  ---  applications_dirs  =  ("/usr/share/applications",  )  image_dir  =
       "/usr/share/pixmaps"

       application_groups = ("Office",
              "Development",   "Graphics",   "Internet",    "Games",   "System",    "Multimedia",
              "Utility",   "Settings") group_aliases = {"AudioVideo":"Multimedia","Game":"Games",
              "GTK":""}  ignoreList  =  ("evince-previewer",   "python3.4",   "feh","xfce4-power-
              manager-settings" )

       terminal_string = "svte -e"
              # your favourites terminal exec string # --- End of user config ---

       The first one, "applications_dirs" is a list of directories in which .desktop files are to
       be found. The default, which should be fine for most
              users, is where .desktop files are usually put by linux or BSD. Feel  free  to  add
              more, for instance some subdirectory within your $HOME.  The next one, "image_dir",
              is quite similar but is about icon images for applications. A small caveat, though:
              While  most  applications are nicely putting their .desktop files into the standard
              directory, the story with icons is quite different. Particularly the  wm  behemoths
              like  Gnome tend to spread icon files all over the place. Often, for instance, icon
              files are to be found in some obscure  subdirectory  of  "/usr/share/icons"  buried
              deep  depending in the chosen theme and the icon size. The author of obamenu admits
              freely to have taken a rather deliberate choice in that regard by having  image_dir
              be  a  simple string rather than a list, which might seem to be a reasonable way to
              some. The author, however, didn't consider it wise to  play  find  and  catch  with
              ignorance  and  idiosyncrasies  of some parties. He rather chose to use the trusted
              Unix mechanism of links. In other words: You are advised  to  soft  link  all  icon
              files outside the standard icon directory to /usr/share/pixmaps or similar. ("find"
              is your friend, e.g. find /usr/share/icons -name 'foo.*').

       The next setting, "application_groups" looks innocent enough but has some power  with  it.
       Obviously  the  entries  in that list are "menu groups" or categories into which xdg menus
       put the applications depending on some .desktop data. You might want to keep in mind  that
       obamenu  keeps  categories  in  the  the  order  of this setting, i.e. you will find those
       categories in the menu in that order, too.  And then there are buts ...  The first but  is
       that  you almost certaintly don't want more categories than the number of citizens in your
       home town. Another and more  interesting  but  is  that,  obviously,  usage  profiles  are
       different.  For  me  as a developer, for instance, a "shows coloured stuff or makes sound"
       category seems sensibly sufficient; some movie editing  people  though  might  have  quite
       different  views...  which  brings  us  to the next setting.  "group_aliases" is a list of
       string pairs, the first one being what is put as category in the .desktop file(s) and  the
       second  one  being  the category it will end up in. In other words: this is your chance to
       rearrange things the way you want them. The author, for  instance,  has  a  rather  frugal
       attitude  regarding  multimedia;  accordingly,  he  simply  throws anything audio or video
       related into  one  category  "multimedia".   To  illustrate,  though  admittedly  somewhat
       construed, another potentially useful feature, have a look at "GTK" in those string pairs.
       Its second string is empty which comes down to telling obamenu "ignore that  stuff.  Don't
       put  it into my menu". The reason being that openbox *only* creates menus for applications
       being sorted into a category. No category, no menu entry.  Hint: This setting may also  be
       used  to have translated strings in your menu; simply have the english cat. string aliased
       to a translated version.

       The second to last setting, "ignoreList" is  what  its  name  suggests.  It's  a  list  of
       .desktop  file names (without the ".desktop" part) you wish to ignore, i.e. to not have in
       your menu for whatever reason.  Finally the last setting,  "terminal_string",  is  telling
       obamenu how to call your favourite terminal emulator for console applications like "htop".
       (obamenu automagically takes care of having console  applications  called  in  a  terminal
       emulator).

       Note  that  the  auto-generated  menu can be put right into the menu section of an openbox
       menu.xml Last but not least you can, of course, also send obamenu's output to a file which
       can  be edited, inserted manually, feed your cat, and all the other things Unixoids can do
       with files.

       Just to avoid misunderstandings, here's an example (the authors usage) of obamenu in a  ob
       menu.xml file:

          <menu id="desktop-app-menu" label="Applications" icon="/usr/share/icons/applications.png" execute="~/obamenu" />

       License:  obamenu is under a dual license depending on who you are. If you are using it as
       a private person (which also means non-commercially) it's under a 3 clause BSD license. If
       you are using it as or in the context of anything not private, for instance, in a business
       or an agency, it's under GPL v.2.

       Disclaimer: The author uses mainly jwm. While obamenu has been tested to work properly  it
       has  been  considerably  less tested than the authors jwmamenu (same thing but for jwm. In
       fact, obamenu has been derived from jwmamenu).

       The main motivation behind obamenu was the fact that openbox-menu (probably the most  used
       menu  generator  for ob) doesn't compile properly on FreeBSD and the author saw absolutely
       no reason why a menu generator couldn't - and shouldn't - be cross  platform  (e.g.  using
       Python).

       News & Updates:

       ·  ported  (from jwmamenu) smarts to get rid of '%x' target specifiers in Exec spec. (used
          for file managers but disturbing in menus)

       ·  ported search for category icons in configurable Theme

       ·  some cleaning up and small enhancements, mainly for speed.