[src/trunk]: src/usr.bin/menuc Improve a parameter list, add the actual docum...

[phil <phil%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/f8053e3af633
branches:  trunk
changeset: 501762:f8053e3af633
user:      phil <phil%NetBSD.org@localhost>
date:      Sun Jan 07 06:09:19 2001 +0000

description:
Improve a parameter list, add the actual documentation for menuc.

diffstat:

 usr.bin/menuc/mdb.c        |    8 +-
 usr.bin/menuc/menu_sys.def |    4 +-
 usr.bin/menuc/menuc.1      |  405 ++++++++++++++++++++++++++++++++++++++++++++-
 3 files changed, 404 insertions(+), 13 deletions(-)

diffs (truncated from 481 to 300 lines):

diff -r b6688809983c -r f8053e3af633 usr.bin/menuc/mdb.c
--- a/usr.bin/menuc/mdb.c       Sun Jan 07 06:08:33 2001 +0000
+++ b/usr.bin/menuc/mdb.c       Sun Jan 07 06:09:19 2001 +0000
@@ -1,4 +1,4 @@
-/*     $NetBSD: mdb.c,v 1.19 2000/12/28 02:07:00 mrg Exp $     */
+/*     $NetBSD: mdb.c,v 1.20 2001/01/07 06:09:19 phil Exp $    */
 
 /*
  * Copyright 1997 Piermont Information Systems Inc.
@@ -216,7 +216,8 @@
                        "int new_menu (char * title, menu_ent * opts, "
                                "int numopts, \n"
                                "\tint x, int y, int h, int w, int mopt,\n"
-                               "\tvoid (*post_act)(void), void (*exit_act), "
+                               "\tvoid (*post_act)(void), "
+                               "void (*exit_act)(void), "
                                "char * help);\n"
                        "void free_menu (int menu_no);\n"
                        );
@@ -379,7 +380,8 @@
        if (error_act.code == NULL) {
                (void) fprintf (out_file,
                        "\t(void) fprintf (stderr, "
-                       "\"%%s: Could not initialize curses\\n\",__progname);\n"
+                       "\"%%s: Could not initialize curses\\n\", "
+                       "__progname);\n"
                        "\texit(1);\n"
                        "}\n");
        } else {
diff -r b6688809983c -r f8053e3af633 usr.bin/menuc/menu_sys.def
--- a/usr.bin/menuc/menu_sys.def        Sun Jan 07 06:08:33 2001 +0000
+++ b/usr.bin/menuc/menu_sys.def        Sun Jan 07 06:09:19 2001 +0000
@@ -1,4 +1,4 @@
-/*     $NetBSD: menu_sys.def,v 1.24 2000/08/15 02:09:11 phil Exp $     */
+/*     $NetBSD: menu_sys.def,v 1.25 2001/01/07 06:09:20 phil Exp $     */
 
 /*
  * Copyright 1997 Piermont Information Systems Inc.
@@ -750,7 +750,7 @@
 int
 new_menu (char * title, menu_ent * opts, int numopts, 
        int x, int y, int h, int w, int mopt,
-       void (*post_act)(void), void (*exit_act), char * help)
+       void (*post_act)(void), void (*exit_act)(void), char * help)
 {
        int ix;
 
diff -r b6688809983c -r f8053e3af633 usr.bin/menuc/menuc.1
--- a/usr.bin/menuc/menuc.1     Sun Jan 07 06:08:33 2001 +0000
+++ b/usr.bin/menuc/menuc.1     Sun Jan 07 06:09:19 2001 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: menuc.1,v 1.4 1999/12/31 04:03:18 garbled Exp $
+.\"    $NetBSD: menuc.1,v 1.5 2001/01/07 06:09:20 phil Exp $
 .\"
 .\" Copyright 1997 Piermont Information Systems Inc.
 .\" All rights reserved.
@@ -48,11 +48,11 @@
 menus, their options, and how to process the options is given to
 .Nm
 and produces both a .c and a .h file that implement the menu system.
-The standard root name of the files is 
+The standard base name of the files is 
 .Pa menu_defs .
 The 
 .Fl o Ar name
-can be used to specify a different root name.
+can be used to specify a different base name.
 .Sh ENVIRONMENT
 .Bl -tag -width MENUDEF
 .It Ev MENUDEF
@@ -62,16 +62,405 @@
 The current location defaults to
 .Pa /usr/share/misc .
 .El
+.Sh MENU DESCRIPTIONS
+The input 
+.Ar file 
+defines static menus and options for processing
+those menus.  It also contains comments, initial C code that
+is required to provide for definitions and other code necssary
+for the menu system, and an option declaration if dynamic
+menus are requested.
+.Pp
+Comments may appear anywhere in the input
+.Ar file
+and are like a space in the input.  
+They are like C comments starting with
+.Em /*
+and ending with
+.Em */.
+They are unlike C comments in that they may be nested.  A comment
+does not end until a matching end comment is found. 
+.Pp
+In many places, C code is included in the definition
+.Ar file.
+All C code is passed verbatim to the C output file.
+.Nm menuc 
+comments do not start in C code
+and comments in the C code are passed verbatim to
+the output.  The C comments are not recognized by 
+.Nm menuc.
+In all cases, C code starts with a left brace
+.Em ({)
+and ends with the matching right brace
+.Em (}).
+It is important to recognize that in code segments, any brace
+will be counted, even if it is in a C comment inside the code.
+.Pp
+The
+.Ar file
+contains an initial (and optional) code block followed by any
+number of menu definition elements in any order.  The initial
+code block usually contains includes of header files used by
+code in the menu code blocks later in the 
+.Ar file.
+The file is free format, so the actual formatting of the input
+.Ar file
+is to the taste of the programmer.
+.Pp
+All other C code that will appear in an
+.Em action.
+This will be specified as 
+.Em <action>
+in later text.  Such an action will appear as:
+.Dl action <opt_endwin> <code>
+in the 
+.Ar file.
+The 
+.Em <opt_endwin>,
+if present is:
+.Dl ( endwin )
+and specifies that the curses
+.Fn endwin
+function should be called before executing the code and
+then reinstating the current curses window after the
+code has been run.  The 
+.Em <code>
+is as described above.
+.Pp
+There are four kinds of menu definition elements.   The first
+one just declares whether the programmer wants dynamic menus
+available.  The default is static menus only.  The static menus
+are the ones defined by the menu definitions and do not change
+at run time.  The dynamic menus provide the programmer with a
+method to create and modify menus during the running of the program.
+To include dynamic menus, one needs only add the declaration:
+.Dl allow dynamic menus ;
+The semicolon is required to terminate this declaration.  This
+declaration may appear anywhere in the 
+.Ar file,
+but usually appears before any menus are defined.
+.Pp
+The next element is a code block to execute if the curses 
+screen can not be sucessfully initialized.  The declaration
+.Dl error code ;
+tells the menu system to execute the associated code block
+if the initialization fails.  If no code is provided, a
+default code block is used that prints
+.Dl Could not initialize curses.
+and exits.  This element may appear anywhere in the
+.Ar file
+but usually appers before any menus are defined.
+.Pp
+The next element defines default options for menus.  Each
+menu is built from a list of options.   These options include
+the location of the upper left corner of the menu, whether
+there is a "box" drawn around the menu, whether the menu is
+scrollable, the menu's title, whether shortcut letters are
+allowed, whether a standard exit option should be included
+in the menu and text associated with the standard exit option.
+The general format is:
+.Dl default <comma separated option list> ;
+The options appear in three forms:
+.Dl variable = value
+.Dl [no] switch
+.Dl variable "string"
+.Pp
+The variables for the first form are 
+.Va x,
+.Va y,
+.Va h,
+and
+.Va w.
+These specify the upper left (x,y) and the
+height (h) and width (w) of the menu window.  The upper
+left is in the curses coordinate system.  If not 
+specified, the upper left is the upper left of the screen
+and the height and width of the menu window is computed
+from the menu definition.
+.Pp
+Options of the second form turn on or off (with the 
+optional no) features of the menu system.  The
+.Li box
+option turns on a box around the menu window.  The
+.Li exit
+opton enables the standard exit option in the menus.  The
+.Li scrollable
+option allows the menu to be scrollable if the 
+menu window is smaller than the number of menu options.  The
+.Li shortcut
+option prints a single character shortcut with each menu
+option.
+.Pp
+The third sets text variables.  The variable 
+.Va title
+sets the text title for the menus.  The varible
+.Va exitstring
+sets the text for the exit menu option.
+.Pp
+The default declaration may appear multiple times.  Each time,
+it sets the default values for menu definitions that follow
+in the 
+.Ar file.
+In each menu definition, any or all of these default definitions
+may be overridden for that menu.
+.Pp
+The final element is the actual static menu menu definition.
+The format and order for a menu definition is:
+.Bd -ragged -offset indent
+menu <name> <options> ;
+  <display action>
+  <menu items>
+  <exit action>
+  <help string>
+.Ed
+.Pp
+Names are unquoted strings of alpha-numeric and underscore
+characters.  They must start with an alpha character. 
+In C source, a menu named
+.Nm foo
+is appears as 
+.Nm MENU_foo.
+(Capitalization is important.)  This is important,
+because the menu is displayed and processed by
+calling the function
+.Dl process_menu (MENU_foo) ; 
+.Pp
+The options are a comma separated list of options as in the
+.Na default 
+declaration.  These override the options from the most
+recent default declaration.
+.Pp
+The display action is optional and provides C code to
+execute at each and every time the menu is displayed
+for processing.  If it is included, the format is:
+.Dl display <action> ;
+.Pp
+The bulk of the menu definition is the specification 
+of the menu items.  The general format of a menu
+item is:
+.Dl option <string>, <element_list> ;
+The 
+.Em <string>
+is the text displayed for the menu item.  There
+may be an arbitrary number of these items.  (If
+there are shortcuts in the menu, a practical limit
+of 51 should be recoginzed.  It produces shortcuts
+a to w, y, z and A to Z.  x is the shortcut for the
+exit item.)
+.Pp
+The 
+.Em <element_list>
+is a comma separated list of what to do when the
+item is selected.  They may appear in any order.
+.Pp
+The first element processed when a menu item
+is selected is the associated action.  The next
+element to be processed is the sub or next
+menu option.  They are declared as:
+.Dl next menu <name>
+.Dl sub menu <name>
+The difference between these two is that a sub
+menu will return to the current menu when exited.
+The next menu will just replace the current 
+menu and when exited, will return to where the
+current menu would have gone.  Only one of menu
+element may be used for each menu item.  Finally,
+after processing both the action and a sub menu,
+the current menu will be exited if the element
+.Dl exit
+is specified.  
+.Em Note:
+If 
+.Em exit
+is specified, next menu will not work because
+the menu system will exit the 
+.Em current
+menu, even if current has been set by 
+.Em next menu.
+.Pp
+After all menu items, the final two menu definition
+elements may appear.
+The exit action is optional and provides C code to
+execute in the process of exiting a menu.
+If it is included, the format is:
+.Dl exit <action> ;
+.Pp
+The final part of the menu definition is the optional
+help string.  The format is:
+.Dl help <text> ;