Initial revision

1 files changed, 372 insertions, 0 deletions

diff --git a/data/README.menu b/data/README.menu
new file mode 100644
index 0000000..ecee95f
--- /dev/null
+++ b/data/README.menu
@@ -0,0 +1,372 @@
+-- data/README.menu for Blackbox 0.61.x - an X11 Window manager
+
+Creating a user defined menu:
+-----------------------------
+Creating a menu for Blackbox requires a text editor of some sort.  Familiarity
+with your choice of text editor is assumed, since editor preference differs
+as much (if not more than) window manager preference.
+
+First, we need to decide on a location for our custom menu.  Your home
+directory is the most logical solution, since you will most likely not have
+write access anywhere else.  You place the menu file in any directory, and
+give it any name you choose, as we will later tell Blackbox the path or
+location for this file.
+
+As an example, let's assume that my home directory is `/home/bhughes' (which it
+is).  I've decided to keep all my Blackbox related files in a directory named
+`blackbox.'  After creating the directory, I now have two options for creating
+my new menu.  I can either copy the system default (usually in
+`/usr/local/share/Blackbox/menu') to this directory, or I can create a new
+one from scratch.  Let's do the latter, for the sake of completeness.
+
+I've decided to name the file `rootmenu.'  I fire up my favorite text editor
+and now have a clean file.  So let's begin.
+
+
+Menu syntax:
+------------
+The menu syntax is very simple and very effective.  There are upto three
+fields in a menu line. They are of the form:
+
+        [tag] (label or filename) {command or filename}
+
+The supported tags are as follows:
+
+[begin] (label for root menu)
+
+        This tells Blackbox to start parsing the menu file.  This tag is
+        required for Blackbox to parse your menu file.  If it cannot find it,
+        the system default menu is used instead.
+
+[end]
+
+        This tells Blackbox that it is at the end of a menu.  This can either
+        be a submenu or the main root menu.  There must be at least one
+        of these tags in your menu to correspond to the required [begin] tag.
+
+[exec] (label for command) {shell command}
+
+        This tells Blackbox to insert a command item into the menu.  When you
+        select the menu item from the menu, Blackbox runs `shell command.'
+
+[exit] (label for exit)
+
+        This tells Blackbox to insert an item that shuts down and exits
+        Blackbox.  Any open windows are reparented to the root window before
+        Blackbox exits.
+
+[include] (filename)
+
+        This tells Blackbox to parse the file specified by `filename' inline
+        with the current menu.  `filename' can be the full path to a file
+        (such as /usr/local/share/Blackbox/brueghel/stylesmenu) or it can
+        begin with `~/', which will be expanded into your home directory
+        (e.g. [include] (~/blackbox/stylesmenu) will include
+        /home/bhughes/blackbox/stylesmenu in my menu)
+
+[nop] (label - optional)
+
+        This tells Blackbox to insert a non-operational item into the current
+        menu.  This can be used to help format the menu into blocks or sections
+        if so desired (e.g. you could put all your ssh accounts together, add
+        a [nop] and then add all your telnet accounts together).  [nop] does
+        accept a label, but it is not required, and a blank item will be used
+        if none is supplied.
+
+[style] (label) {filename}
+
+        This tells Blackbox to read `filename' and apply the new textures,
+        colors and fonts to the current running session.  The filename is
+        just like the [include] tag, it can be the full path to the file,
+        or it can be of the form `~/path/from/home/dir.'  Blackbox also
+        re-reads the entire menu structure from disk, incase the menu has
+        changed.
+
+[submenu] (label) {title for menu - optional}
+
+        This tells Blackbox to create and parse a new menu.  This menu is
+        inserted as a submenu into the parent menu.  These menus are parsed
+        recursively, so there is no limit to the number of levels or nested
+        submenus you can have.  The title for the new menu is optional, if
+        none is supplied, the new menu's title is the same as the item label.
+
+[reconfig] (label)
+
+        This tells Blackbox to reread the current style and menu files and
+        apply any changes.  This is useful for creating a new style or theme,
+        as you don't have to constantly restart Blackbox every time you save
+        your style.
+
+[restart] (label) {shell command - optional}
+
+        This tells Blackbox to restart.  If `shell command' is supplied, it
+        shuts down and runs the command (which is commonly the name of another
+        window manager).  If the command is omitted, Blackbox restarts itself.
+
+[workspaces] (label)
+
+        This tells Blackbox to insert a "link" to the workspaces menu directly
+        into your menu.  This is handy for those users who can't access the
+        workspace menu directly (e.g. if you don't have a 3 button mouse, it's
+        rather hard to middle click to show the workspace menu).  This is a
+        "link" to the systems workspace menu, so multiple [workspaces] tags
+        will display the same workspace menu, so expect it to move around if
+        you do so. ;)
+
+[config] (label)
+
+        This tells Blackbox to insert the ConfigMenu into your menu.  From
+        this menu you can configure several options stored in your
+        ~/.blackboxrc, and the changes take effect immediately.
+
+Comments may be inserted on any line of the file, as long as the first
+character on the line is a `#.'
+
+Also, in the labels/commands/filenames fields, you can escape any character
+like so:
+
+        [exec] (\(my cool\) \{XTERM\}) {\(xterm -T \\\"cool XTERM\\\"\)}
+
+Using `\\' inserts a literal back-slash into the label/command/filename field.
+
+
+Putting it all together:
+------------------------
+Alrighty, so let's see if we can understand the arcane incantation above.  It
+says we have to have a [begin] and an [end] tag, which create our menu and
+give it a title.  Let's do that first:
+
+
+        [begin] (Example \[Menu\])
+        
+        [end]
+
+Simple enough. Now let's add some items to the list.  We always want to have
+access to a terminal emulator, be it a regular xterm or something else.
+So we add the item to our menu, and it now looks like this:
+
+...
+[begin] (Example \[Menu\])
+[exec] (xterm) {xterm -ls}
+[end]
+...
+
+Great!  Now let's add us some items to run an irc client, netscape, xv and
+some other common programs.  This gives up this:
+
+...
+[begin] (Example \[Menu\])
+[exec] (xterm) {xterm -ls}
+[exec] (efnet irc) {xterm -e irc fnord irc.efnet.net}
+[exec] (Netscape Navigator) {netscape}
+[exec] (xv 3.10a) {xv}
+[exec] (XEmacs) {xemacs}
+[exec] (The GIMP) {gimp}
+[exec] (Video Tune) {xvidtune}
+[end]
+...
+
+Whoa, wait a second.  This menu file is beginning to look a little cluttered.
+Not a problem, just like programmers indent and space their code, we can
+do this with our menu file, so let's clean it up a bit:
+
+...
+[begin] (Example \[Menu\])
+        [exec] (xterm) {xterm -ls}
+        [exec] (efnet irc) {xterm -e irc fnord irc.efnet.net}
+
+        [exec] (Netscape Navigator) {netscape}
+        [exec] (XEmacs) {xemacs}
+
+        [exec] (xv 3.10a) {xv}
+        [exec] (The GIMP) {gimp}
+
+        [exec] (Video Tune) {xvidtune}
+[end]
+...
+
+Ahh... now that looks a little better.  Now we decide that we kind of like the
+spacing in the file, and decide we want to apply it to the menu itself.  Now
+we take advantage of the [nop] tag:
+
+...
+[begin] (Example \[Menu\])
+        [exec] (xterm) {xterm -ls}
+        [exec] (efnet irc) {xterm -e irc fnord irc.efnet.net}
+
+        [nop]
+
+        [exec] (Netscape Navigator) {netscape}
+        [exec] (XEmacs) {xemacs}
+
+        [nop]
+
+        [exec] (xv 3.10a) {xv}
+        [exec] (The GIMP) {gimp}
+
+        [nop]
+
+        [exec] (Video Tune) {xvidtune}
+[end]
+...
+
+Now, let's create a submenu to put some items to change between all these
+themes we downloaded from http://blackbox.themes.org/.  Let's assume we
+untarred the themes into the ~/.blackbox directory like the documentation on
+the themes.org site recommends.
+
+...
+[begin] (Example \[Menu\])
+        [exec] (xterm) {xterm -ls}
+        [exec] (efnet irc) {xterm -e irc fnord irc.efnet.net}
+
+        [nop]
+
+        [exec] (Netscape Navigator) {netscape}
+        [exec] (XEmacs) {xemacs}
+
+        [nop]
+
+        [exec] (xv 3.10a) {xv}
+        [exec] (The GIMP) {gimp}
+
+        [nop]
+
+        [exec] (Video Tune) {xvidtune}
+
+        [submenu] (Themes) {Themes from blackbox.themes.org}
+                [style] (Blackbox) {~/.blackbox/Styles/blackbox}
+                [style] (Blackbox II) {~/.blackbox/Styles/blackbox2}
+                [style] (Hardware) {~/.blackbox/Styles/hardware}
+                [style] (Nova) {~/.blackbox/Styles/nova}
+                [style] (Orbital) {~/.blackbox/Styles/orbital}
+                [style] (Orbital II) {~/.blackbox/Styles/orbital2}
+                [style] (Seething) {~/.blackbox/Styles/seething}
+                [style] (Zero) {~/.blackbox/Styles/zero}
+                [style] (Cold Fusion) {~/.blackbox/Styles/coldfusion}
+        [end]
+[end]
+...
+
+Even better.  Now hold on a second, if we have our themes and styles in
+~/.blackbox why do we have to have our menu in ~/blackbox?  Answer:  WE DON'T!
+This is where the choice comes.  Do we keep our stuff in two separate
+directories? Do we put it all in one directory?  That is up to you to decide.
+I personally prefer to keep everything in one directory (but, I use ~/blackbox
+and have been for a long, long time; long before blackbox.themes.org was
+even thought of... and again that is *personal* preference, not a hard-fast
+rule).
+
+Now that we've gotten a feel for the menu syntax, we decide to finish off our
+menu.  In addition to the styles we downloaded, we decide we also want to
+keep a submenu for the default styles that came with Blackbox.  All we need
+to do is [include] the styles file from the share directory for Blackbox.
+After putting everything together, we have:
+
+
+...
+# custom menu file for Blackbox
+
+[begin] (Example \[Menu\])
+        [exec] (xterm) {xterm -ls}
+        [exec] (efnet irc) {xterm -e irc fnord irc.efnet.net}
+
+        [nop]
+
+        [exec] (Netscape Navigator) {netscape}
+        [exec] (XEmacs) {xemacs}
+
+        [nop]
+
+        [exec] (xv 3.10a) {xv}
+        [exec] (The GIMP) {gimp}
+
+        [nop]
+
+        [exec] (Video Tune) {xvidtune}
+
+        [nop] (...)
+
+        [submenu] (Themes) {Themes from blackbox.themes.org}
+                [style] (Blackbox) {~/.blackbox/Styles/blackbox}
+                [style] (Blackbox II) {~/.blackbox/Styles/blackbox2}
+                [style] (Hardware) {~/.blackbox/Styles/hardware}
+                [style] (Nova) {~/.blackbox/Styles/nova}
+                [style] (Orbital) {~/.blackbox/Styles/orbital}
+                [style] (Orbital II) {~/.blackbox/Styles/orbital2}
+                [style] (Seething) {~/.blackbox/Styles/seething}
+                [style] (Zero) {~/.blackbox/Styles/zero}
+                [style] (Cold Fusion) {~/.blackbox/Styles/coldfusion}
+
+# include the default style menu... this is assuming Blackbox was installed
+# into /usr/local
+
+                [nop]
+
+                [include] (/usr/local/share/Blackbox/styles/stylesmenu)
+        [end]
+
+        [workspaces] (Workspace list)
+
+        [submenu] (Restart) {Restart which?}
+                [restart] (Blackbox)
+
+# let's also give us access to some other window managers
+
+                [restart] (Window Maker) {wmaker}
+                [restart] (Enlightenment) {enlightenment}
+                [restart] (KWM) {kwm}
+                [restart] (TWM) {twm}
+        [end]
+
+        [nop] (...)
+
+        [reconfig] (Reconfigure)
+        [exit] (Quit!)
+[end]
+...
+
+And voila!  our menu file is finished.  Now we need to tell Blackbox to read
+this menu file.  We do this by editing the file ~/.blackboxrc.
+
+NOTE: your ~/.blackboxrc is auotmatically updated every time Blackbox restarts,
+reconfigures, changes styles or exits.  Changes to dynamic data like workspace
+count, names, etc. is lost.  About the only thing you can change and have it
+preserved is the menu filename, which is what we are about to change.
+
+The format of ~/.blackboxrc is in the X resource database format (just like
+~/.Xdefaults).  Since the file is updated automatically, it may be full of
+stuff or it may not even exist (especially if this is the first time we've
+ran Blackbox).  Don't worry if you have to create ~/.blackboxrc, Blackbox will
+see the file the next time it starts.
+
+What we need to do is change the resource for the menu's filename.  This is
+done by changing (or adding) the line that looks like so:
+
+...
+session.menuFile:       /path/to/some/file
+...
+
+If this resource exists, we change it.  If it does not, we add it.  Depending
+on where we put the menu file, our new resource could look like this:
+
+...
+session.menuFile:       /home/bhughes/blackbox/rootmenu
+...
+
+We save ~/.blackboxrc and then restart Blackbox (reconfiguring doesn't work,
+we need Blackbox to completely shutdown and reread ALL of it's configuration
+files, not just the ones that control colors/fonts/etc.)
+
+If we've done everything correctly, Blackbox restarts itself and our new menu
+is now ready for use.  If something doesn't work, read over the above example
+again to make sure you didn't forget a step or leave out the necessary tags.
+
+Now that Blackbox has been told where to find it's menu, it does a little more.
+Blackbox 0.51.x introduces automagic menu updates.  As long as you never
+change session.menuFile, you will never have to restart or reconfigure Blackbox
+whenever you change your menu.  Blackbox watches the timestamps on all the
+files it reads to build your menu.  If any of them change, they are reread and
+your menu updated.  This check is done everytime you open the root menu.  Like
+I said... it is a check, it doesn't reread the menu everytime, it just looks
+at the modification time and rereads when it changes.