Menu Maintainer README

UMENU2's menu hierarchy and definitions are contained in a single tree,
headed by a lower case single-letter directory a-z. Thus, you can have
26 menu trees, which is enough in any reasonable situation.
Unreasonable situations can be handled with workarounds.

The u menu system is distributed with UMENU2 as both a convenience and
an example, so although it would be easy to re-use u for your own
purposes, I recommend you use other letters.

# MENU DATA
Every choice on every menu falls into one of three types:

* m (menu)
* c (command)
* r (return)

An m choice brings you to a submenu, a c choice runs a command, and an r
choice brings you back up one level to an earlier menu, or if you're
already at the top of the menu hierarchy, exits the program.

The data for a menu system is contained in a tree, where containers are
represented by directories, and key-value relationships are represented
by files whose name is the key and whose contents is the value.

Every choice on every menu is a container and thus is represented by a
directory. Throughout the whole directory hierarchy, there are two kinds
of directories and one kind of file. The two kinds of directories are:

* A single lowercase letter, a-z
* A directory called data, within a letter directory

The single type of file is a key-value type file, where the filename is
the key, and its contents are the value. These key-value type files are
contained *only* in data directories. One of those key-value files is
called type, and it contains either m for menu, c for command, or r for
return. This type applies to the choice defined by the letter directory
containing the data directory. See the following ascii art:

r  (menu)
|--data
|   |---type (m)
|   `---other config files
|
|---g    (command, gnumeric)
|   `---data
|        |---type (c)
|        `---other config files
`---q   (return, quit)
    `---data
         |---type (r)
         `---other config files

Look at the preceding until it becomes clear. Menu r contains choices g
and q, each being a subdirectory of r. It also contains a subdirectory
called data, whose contained files define it. The type file has a value
of m, indicating r is a menu. In the same way, g/data/type has value c,
indicating that g is a command, and r/data/type has value r, indicating
its a return to prior menu. Once you truly understand this, menu
definition and modification will be easy.

It is an error for a data directory to contain any directories.

It is an error for a letter directory of type c or type r to have any
directory except data. Specifically, it must have no letter directories.

It is an error for a letter directory of type m *not* to contain at
least one letter directory of type r. Usually a type m will contain
several more one letter directories of various types.

The data directory for each choice (letter directory) contains several
key-value pairs. Two key-value pairs manditory for every choice type are
choicetitle and type. Other manditory and optional key value pairs are
required/allowed in the data directories of various choice types.

Using a file manager, browse the u directory distributed with UMENU2.
Notice how it's laid out. Notice that letter directories with only a
data directory are type c or r, while letter directories also containing
other letter directories are type m. Go into the data directories of
each type of choice, and note the filenames and their contents.

The following is a list of key-value pairs found in data directories:

* type: Always manditory, choice of m (menu), c (command) or r (return)
* choicetitle: How the choice is represented on a menu's list. Manditory
  for all types.
* menutitle: The top of menu title for the choice as a submenu.
  Manditory for m type, not valid for other types
* sort: Defines sort order on an m type's choice list.
* cmd: The command to be run by this choice. Manditory for c type.
* bkground: Optional, c type only. Run the spawned program in the
  background. Used primarily for choices running GUI programs.
* stop: Optional, c type only. After the command completes, prompt the
  user to press Enter to return to the menu, so the user can see all the
  output from the command. Used primarily for choices running CLI
  programs.
* env: Optional, c type only. Multiline list of environment vars to set.
  path: Optional, c type only. Path entries to prepend before the
  existing path.
* icon: Optional perhaps on all types. Inclusion of this property makes
  a GUI version just a matter of reprogramming, rather than
  rearchitecting. Not currently used.


# HELPER PROGRAMS

Helper programs are ./newmenu.py and ./newitem.py, in the procs
directory. 





/* vim: set ai tw=72: */

