The EMDL (Easy Menu
Language Definition and
EMDL to UMENU Converter (GNU/GPL)
Copyright (C) 2002-2004 by Steve Litt
There is no warranty for anything contained in the
EMDL distribution or documentation or its web pages, to the extent
permitted by applicable law. Except when otherwise stated in
the copyright holders and/or other parties provide the program,
and web pages "as is" without warranty of any kind, either expressed or
implied, including, but not limited to, the implied warranties of
and fitness for a particular purpose. The entire risk as to the
and performance of the program is with you. Should the program,
or web pages prove defective, you assume the cost of all necessary
repair or correction.
EMDL is a language to quickly and
define an entire menu system. The emdlparser.pl program
an EMDL file to a tree of UMENU .mnu files.
The purpose of the EMDL language is to facilitate fast and easy
of large menu systems using a standard text editor capable of automatic
indentation (the ability to indent to the same level as the preceding
plus ways to cut, paste, indent and exdent multiple lines). The Vim
is one such editor. VimOutliner is ideally suited for EMDL authoring
of its ability to collapse and expand trees.
Priorities of the EMDL initiative are:
- Quick and easy creating and editing of large menu systems
Authoring can be done with a text editor
Use of a text outliner to define menu hierarchies
And the following are not design priorities at all:
- Cut and paste
- Promotion and demotion
- Assignment of commands, directories, prepaths, and other
Priorities #1, 3 and 4 preclude anything with end tags, and suggest
the language should be line based. So it is. #3 suggests use of an
to simulate the hierarchy of a menu system, with its tree of menus and
each menu's selection of choices, many of which have multiple
- Ease of parsing
- Run time efficiency
- Gui environments
- Inclusion of every last possible feature of every possible menu
EMDL is so productive you can create a substantial personal custom
menu" in an hour or so. It's featureful enough to create fairly complex
menus, although it lacks a generic facility for prompted argument
However, if the destination menu supports prompted argument
in its commands, then the prompted argument substitution tags can be
in an EMDL command parameter. This is why EMDL supports UMENU prompted
argument substitution. It's anticipated that version 2 of the EMDL
specification will support prompted argument substitution natively.
EMDL language version 1.1 has two very nice new features:
- Support for multiple command parameters
- Support for environment variable parameters
The first program to use EMDL is emdlparser.pl, which performs
suggested by its name. It's a GNU GPL licensed program that runs on any
Linux computer with a standard Perl 5 installation, and will likely run
on any UNIX, UNIX workalike, or BSD computer. It hasn't been tested
Windows, but making it run on Windows would likely require only the
emdlparser.pl is a
complete rewrite of the older emdl2umenu.pl.
Regression testing has proven that for a given input file, emdlparser.pl outputs identical
.mnu files as emdl2umenu.pl. However, the
newer program is an order of magnitude simpler, and it runs about 7
times faster. This efficiency in terms of speed and simplicity is
achieved by use of the Node.pm
Unlike its more complex predecessor, the emdlparser.pl program consists
of a single source file (which uses Node.pm). The newer program is
less object oriented, although all data structures are now based on
trees of Node objects. The new program has a simple main program
calling several fairly simple subroutines. The subroutines, in turn,
use Walker objects to traverse Node trees issuing callback routines for
each Node. The callback routines are all methods of the Callbacks object, which also
has variables for the number of errors and the number of warnings.
Having this program output a different kind of menu would essentially
involve only creating a new callback routine to output that new menu.
The intended audience of EMDL are those who possess all of the
- Have, or can create, a tool to convert EMDL to their menuing
- Willing to edit and create menus
Willing to use an editor instead of a "drag and drop environment"
All current and future maintainers of EMDL and various EMDL parsers
be very cognizant of the project's priorities. EMDL must be easy for
human creating or maintaining the menu system, even if this ease means
very complex parsing algorithms. Nothing slows a user like needing to
tags. Nor is a GUI "drag and drop" an appropriate solution, because
such software is slower than an editor for an experienced user.
The project spec consists of:
- EMDL version 1.1 language definition
EMDL version 1.1 Language Definition
Before defining the language, an example is in order:
C: m 3 2
Office ::: Office Menu
C: abiword &
C: lyx &
Information ::: Information Menu
The main menu is called "Example Menu" and contains three choices,
choices: Mouse Speedup, Office, Information, and eXit. Note that the
two choices are submenus, as shown by the triple colon separating their
choice text from their menu titles. The Abiword choice runs the
Any parameter beginning with C: is a command. As shown in the
choice of the Information Menu, a parameter with P: is one or
more directory to prepend to the path, and S: signifies that
stops after the command, and the user must press a key to get back to
menu. This is necessary to read output from commands that print to
As shown on the Lyx choice on the Office Menu, any parameter
with D: signifies a directory to switch to before executing
The Mouse Speedup choice runs
the following command:
xset m 3 2
What has happened is there are multiple C: lines. They are concatenated
with a single space in between them, to create a single command. This
enables you to place a small script inside a menu definition file.
Because these lines are strung together, each separate command must end
in a semicolon.
The preceding paragraph is actually a little misleading because in
fact, the separate C:
lines are passed individually to the menu program. It's the menu
program that concatenates them. This behavior might be configurable in
later EMDL parser programs.
Notice the Quit and eXit commands are preceded by
(^). That's EMDL shorthand for saying "this choice takes you up one
The violet item is the starting menu
and menu title for the main menu. Each green item
is a menu choice. Each red item is a
and of course a submenu is both a choice on its containing menu and a
header for a new submenu, so it parses like this:
(Choice text ::: Submenu Title)
The Seven Line Types
EMDL is line oriented. Each line defines something. Lines cannot
be arbitrarily split. It is also indentation dependent, because the
hierarchy is represented by a tab indented outline. There are seven
of lines in EMDL.:
|First Menu Line
||The first line containing :::
||Defines title of main menu and letter string of main menu
||1st non-whitespace character is #
||Ignored and not transferred to output
||Empty line or whitespace only line
||Ignored and not transferred to output
||Line containing :::
||Used as a choice on its containing menu and as a header for a
Office ::: Office Software Menu
||Any line whose only non-whitespace is the string "param" or
and such line is immediately subservient to a CHOICE line.
||Used to identify subsequent parameters for the parent CHOICE
||Any line subservient to a PARAMHEAD line.
||Used to add information about the parent CHOICE line.
||A line that isn't one of the preceding. It contains a single
||Denotes a choice on a menu
Choice lines contain the text of the choice, and via various tricks
contain the letter that activates them, as following
In practice, making the first upper case letter the activation letter
the best technique, because it's the most readable by the user of the
The other techniques provide options when that isn't the best
- The first character of the line, unless...
- The first upper case character in the line overrides the
- The first & followed by a non-whitespace, in which case the
is the activation letter, overrides all the preceding, unless...
- If the line starts with _LX_, where X stands for any letter, that
is the activation letter and overrides all the preceding.
A special case is a choice that begins with a carat (^). In such a
that choice escapes to the next higher level menu. Note that this could
also be done by giving that choice a command parameter line whose
is the carat character.
Choices contain the text to be displayed and the activation letter, and
in the case of choices that escape to a higher level menu, the choice's
command. All other information about a command must be specified in its
parameters. Parameter lines are key/value pairs, where the key is
by a single upper case letter, and the value is represented by a
A colon and optional whitespace separate the key from the value.
C: su -c "/sbin/halt"
|Multiple commands for a single line append in the order
|Directory to switch to before running the command
|1 or more directories, separated by path separators (colon in
which are prepended to the existing path before running the command
|Signifies a stop after running the command, so that the user
the output of the command. The user then presses a key to return to the
|Drive letter or NFS drive or the like. Unimplemented in EMDL
|The specification states there can be multiple environment
in a choice, each which must be set before running the command. This is
not implemented in the current emdlparser.pl.
|Not currently implemented in
UMENU, but included in EMDL to accommodate GUI menus.
is shorthand for:
The former is preferred because it's more readable and requires much
Common EMDL Errors
- A choice or menu indented under the preceding choice
- A choice or menu doubly indented under the precding menu
- A PARAMHEAD line that's not indented exactly one tab farther than
preceding choice line
- A parameter line that's indented more than 1 tab below the
- A parameter not starting with a capital letter, followed by a
may be surrounded by whitespace on either side)
- The most common example is forgetting the C: before the command
- A menu without a Quit is usually a bad thing
- A menu sporting multiple choices with the same menu letter is an
in some menu programs (including UMENU).
- A choice without a command is useless and should generate a
- A menu with no choices should generate a warning, because it's
Prompted Argument Substitution
EMDL version 1.1 doesn't directly support prompted argument
If it were to, it would probably use a special parameter syntax with a
parameter line for each argument.
Menu systems implementing prompted argument substitution entirely
their commands can obtain their prompted argument specifications
the command defined in the EDML file, as shown in the following UMENU
T_Grep for text in files
C: find %b%Starting directory%% -type f | xargs grep -l %a%Text to look for%% | less
The preceding first prompts for the text to look for, and then for
starting directory, after which it finds any files in the starting
tree containing the sought text.
Future Enhancements to the EMDL Spec
Parameters for menus and parameter mapping are two likely candidates
an upcoming version of the EMDL spec.
Parameters for Menus
The EMDL 1.1 specification neither specifies nor prohibits parameters
menus. It will probably be specified in an upcoming EMDL version.
the menu line itself specifies the menu title. Properties such as the
choice on a menu whose order is not top to bottom would need to be
as parameters subservient to a menu.
The parameter letter designations in EMDL 1.1 (C, P, D, S, E, I and V)
taken directly from UMENU (except for I), and might not be ideal for
users of other menus.
Future versions of EMDL will specify a letter to parameter type file,
that an organization can code parameters in a manner most obvious to
Such a mapping file will also provide for more accurate parameter
and might open the door for multi character parameter keys.
emdlparser.pl Program Specification
The emdlparser.pl program
parses an EMDL file in a fairly compliant way. It's
completely compliant with the following:
And the following EMDL features are inadequately supported or
- Menus and submenus
The emdlparser.pl program
is comprised of a main routine calling simple subroutines, which
perform their work using Node walkers (see Node.pm) and associated
callback routines. All callback routines are methods of the Callbacks object, which also
contains variables to keep count of errors and warnings.
- Drives (incompletely supported by UMENU)
- Same-lettered choices on a menu (not supported by UMENU)
Creating an output mechanism for a new type of menu is pretty
much as simple as creating a callback routine for that menu type, and
then calling that callback with a Node Walker.
There are two types of validation -- parse validation and menu
Parse validation checks that the EMDL code is a well formed outline,
with no double indents. Menu validation means that the outline
represents a valid outline, including:
Validation is done by callback routines.
- One paramhead per command choice
- Command choice has one child -- a paramhead
- Paramheads =~ m/^\s*params?\s*/i;
- Paramheads have only parameters as children
- Parameters have a paramhead as a parent
- Parameters have no children
- Menu choices have three colons
- Menu choices have a menu as a parent, or no parent at all
- Menu choices have menu choices and/or command choices as children
- Command choices have only a menu choice as a parent
- Command choices have only a single paramhead as a parent
All detected errors and warnings are written to stdout.
- Current downloads (0.7.0)
- Previous versions
Needed Programming and Documentation Tasks
- Specification for EMDL native prompted argument substitution.
- Writer callback for Icewm menus
- Writer callback for KDE menus
- Port to Windows and various Unices
How to Participate
Email Steve Litt if you'd
like to participate. I'll work with you as much or as little as you
There's no mailing list yet. For now, communicate directly with Steve
Litt. Once there are several participants, I'll make a mailing
FAQ (Frequently Asked Questions) list
None exists. The project is too new to really know what to put in it.
HTMLized versions of the project
README.html covers most of
what you need to install, configure
and use EMDL.
Links to related projects.
Dedication: We Stand On Their Shoulders
- Richard Stallman and the Free
Without them I shudder to think what the software world would be like
- Linus Torvalds and the various Linux projects: Without Linux, I
need EMDL or UMENU -- I'd just need a lot more money to purchase
software and a lot more patience to deal with Blue Screens of Death and
resulting data loss.
- Greater Orlando Linux User Group
(GoLUG): The peer to peer brain network of which
I'm a small part.
- The VimOutliner Project.
keep making VimOutliner better and better. VimOutliner was my original
reason for creating Node.pm, which so greatly enhanced this version
David Billsbrough, my UMENU co-conspirator who has given me many of my
ideas for specifications.
- On 3/5/2002,
the first distribution of the EMDL project was released as
version 0.5.0. This is alpha code. It seems to work perfectly on my
and I tested it hard.
- On 5/24/2004,
the second distribution of the EMDL project was released as
version 0.7.0. Much simpler and robust than the original, this can be
considered beta rather than alpha. It also is 7 times faster,
features, and is simple enough to reasonably allow output to menu
other than UMENU.
Top of Page