MakeMenus 0.1.9
=========

 2000 Zap Developers.


MakeMenus processes Zap menus source files. It allows the use of menu names
and conditional exclusion of parts of the menu structure. Usage:

  MakeMenus [options] [infile]...
  MakeMenus [options] [infile [outfile]]

Note that the latter usage is deprecated.

Available options are:

  -d LABEL
  --define=LABEL	Define the preprocessor label LABEL.

  -Z
  --zap-main-menus	The input file is the main Zap menus source file.
			This option also predefines some menu labels.

  -o
  --output=FILE		Output to FILE.

  -T
  --throwback		Report most errors using throwback.

  --help		Display the help text and exit.

  --version		Output version information and exit.

If the '-o' option is not used and there are exactly two filenames, then the second filename is the output filename.


The Zap menus source file format is very similar to the actual menus file
format used by Zap. It doesn't say how many valid menu handles there are
(this is calculated automatically by MakeMenus) or give the width for each
menu (this is calculated as required by Zap).

Here's an example menus file:


.Foo	"Foo"
	"Foo"		FOO > FOO
	-
	"Bar"		> .Foo.Bar
	* "\Ropen the Bar menu."
	"Baz"		> .Foo.Baz
	* "\Ropen the Baz menu."

.Foo.Bar "Bar"
=Foo.Baz
	"Wibble"	WIBBLE
#ifdef Question
	"42"		ANSWER
#endif


Menus
-----

.Foo		These are menu labels. They are case sensitive.
.Foo.Bar	 You must follow the label name with the menu title, as shown
		above.
		 With the --zap-main-menus option, you must use these for all
		non-system menus, and you may use either menu numbers or the
		predefined labels for the system menus.
		 Otherwise, you may use labels or numbers, but be careful how
		you mix them - when a label is declared, it is immediately
		assigned a menu number; if the same menu number is explicitly
		used later in the menus source file, then it will cause an
		error. It is therefore best to define any numbered menus
		first.

> .Foo.Bar	These are submenu references using menu labels. They are
> .Foo.Baz	replaced by menu numbers in the output menus file.

=Foo.Baz	This is an menu label alias. The menu may be referred to by
		its declared label or by any of its aliases.
		 This must be the only thing on the line.


Preprocessor
------------

Preprocessor labels must start with a letter or '_', and may only include
letters, digits and '_'s. They are case sensitive.

#ifdef, #ifndef
#else
#endif

  These are like the IF...ELSE...ENDIF construct in BASIC. The #else part, is
  of course, optional.

  #ifdef LABEL		True if the preprocessor label LABEL is defined.
  #ifdef & LABEL...	True if all of the listed labels are defined.
  #ifdef | LABEL...	True if any of the listed labels are defined.

  #ifndef LABEL		True if the preprocessor label LABEL is undefined.
  #ifndef & LABEL...	True if all of the listed labels are undefined.
  #ifndef | LABEL...	True if any of the listed labels are undefined.

  #else			Marks the start of the 'false' part of the IF block.
  #endif		Marks the end of the IF block.

  You may nest #ifdef and #ifndef.

#define LABEL

  Defines the preprocessor label LABEL, if not already defined.

#undef LABEL

  Undefines the preprocessor label LABEL, if not already undefined.

#error MESSAGE

  Generates an error with text MESSAGE, then exits.

#zap-main-menus

  Equivalent to the --zap-main-menus option. This may only be used before any
  menus are defined.


Predefined menu labels
----------------------

These labels are defined if the --zap-main-menus option is used or
#zap-main-menus is read. The names are chosen to be adequately descriptive.

You may use these labels to declare the standard menus or as submenu links.

 No. Name
  0  Zap.Iconbar
  1  Zap.Window
  2  Zap.Filetypes
  4  Zap.Fonts
  5  Zap.Selection
 10  Mode.Throwback
 11  Mode.Byte
 12  Mode.Word
 14  Mode.Code
 15  Mode.Halfword
 16  Mode.Doubleword


Output
------

The command line arguments are output, unquoted and prefixed by the string
  "| Arguments: "
in the third line of the generated file

Trailing spaces are removed from menu titles, menu entry text and help text.

Multiple '-' lines are collapsed into one.

If a dashed line is found at the start or end of a menu, it is ignored.

Comment lines and blank lines are not copied, although both appear in the
output file.

Various diagnostics will be displayed, informing you of such things as
unreferenced labelled menus or undefined system menus.


Bug reports etc.
----------------

Bugs:		<betabugs@zap.uk.eu.org>
Discussion:	<beta@zap.uk.eu.org>

When Zap v1.45 is released, these will change to, respectively, bugs/buglist
and devel, with the above two reserved for beta releases of MakeMenus.
