Aren/NetBSD
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Ispell. Begin new sentences on a new line. mdoc fixes.

Browse Source
This commit is contained in:
wiz 2002-09-26 01:19:38 +00:00
parent 95882a7a34
commit 11b1026044
1 changed files with 111 additions and 85 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

196
usr.bin/menuc/menuc.1
View File

@ -1,4 +1,4 @@
.\" $NetBSD: menuc.1,v 1.10 2002/05/24 22:09:20 wiz Exp $
.\" $NetBSD: menuc.1,v 1.11 2002/09/26 01:19:38 wiz Exp $
.\"
.\" Copyright 1997 Piermont Information Systems Inc.
.\" All rights reserved.
@ -15,7 +15,7 @@
.\" documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\" must display the following acknowledgement:
.\" This product includes software develooped for the NetBSD Project by
.\" This product includes software developed for the NetBSD Project by
.\" Piermont Information Systems Inc.
.\" 4. The name of Piermont Information Systems Inc. may not be used to endorse
.\" or promote products derived from this software without specific prior
@ -44,8 +44,9 @@ menuc
.Op Fl o Ar name
.Ar file
.Sh DESCRIPTION
This implements a curses based menu system. A source file that describes
menus, their options, and how to process the options is given to
This implements a curses based menu system.
A source file that describes 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 base name of the files is
@ -66,10 +67,10 @@ The current location defaults to
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.
those menus.
It also contains comments, initial C code that is required to provide
for definitions and other code necessary for the menu system, and an
option declaration if dynamic menus are requested.
.Pp
Comments may appear anywhere in the input
.Ar file
@ -78,8 +79,8 @@ 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.
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 .
@ -87,7 +88,8 @@ All C code is passed verbatim to the C output file.
.Nm
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
the output.
The C comments are not recognized by
.Nm "" .
In all cases, C code starts with a left brace
.Em ({)
@ -99,8 +101,8 @@ will be counted, even if it is in a C comment inside the code.
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
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
@ -111,7 +113,8 @@ All other C code that will appear in an
.Em action .
This will be specified as
.Em \*[Lt]action\*[Gt]
in later text. Such an action will appear as:
in later text.
Such an action will appear as:
.Dl action \*[Lt]opt_endwin\*[Gt] \*[Lt]code\*[Gt]
in the
.Ar file .
@ -123,38 +126,43 @@ 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
code has been run.
The
.Em \*[Lt]code\*[Gt]
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.
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
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
screen can not be successfully 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
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
and exits.
This element may appear anywhere in the
.Ar file
but usually appers before any menus are defined.
but usually appears 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
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.
@ -172,33 +180,39 @@ The variables for the first form are
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
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
optional no) features of the menu system.
The
.Li box
option turns on a box around the menu window. The
option turns on a box around the menu window.
The
.Li exit
opton enables the standard exit option in the menus. The
option 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
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
The third sets text variables.
The variable
.Va title
sets the text title for the menus. The varible
sets the text title for the menus.
The variable
.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
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
@ -215,7 +229,8 @@ menu \*[Lt]name\*[Gt] \*[Lt]options\*[Gt] ;
.Ed
.Pp
Names are unquoted strings of alpha-numeric and underscore
characters. They must start with an alpha character.
characters.
They must start with an alpha character.
In C source, a menu named
.Dq foo
is appears as
@ -227,45 +242,47 @@ calling the function
.Pp
The options are a comma separated list of options as in the
.Dq default
declaration. These override the options from the most
recent default declaration.
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:
for processing.
If it is included, the format is:
.Dl display \*[Lt]action\*[Gt] ;
.Pp
The bulk of the menu definition is the specification
of the menu items. The general format of a menu
item is:
of the menu items.
The general format of a menu item is:
.Dl option \*[Lt]string\*[Gt], \*[Lt]element_list\*[Gt] ;
The
.Em \*[Lt]string\*[Gt]
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.)
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 recognized.
It produces shortcuts a to w, y, z and A to Z.
x is the shortcut for the exit item.)
.Pp
The
.Em \*[Lt]element_list\*[Gt]
is a comma separated list of what to do when the
item is selected. They may appear in any order.
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:
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 \*[Lt]name\*[Gt]
.Dl sub menu \*[Lt]name\*[Gt]
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,
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.
@ -286,7 +303,8 @@ If it is included, the format is:
.Dl exit \*[Lt]action\*[Gt] ;
.Pp
The final part of the menu definition is the optional
help string. The format is:
help string.
The format is:
.Dl help \*[Lt]text\*[Gt] ;
This text is displayed in a full page
help window if the question mark is typed.
@ -296,14 +314,14 @@ and ends with the matching right brace
.Em (}) .
The braces are not included in the
help string, but all other characters between
them are included. Newlines in the code
translate to newlines in the help text.
them are included.
Newlines in the code translate to newlines in the help text.
.Sh DYNAMIC MENUS
If requested,
.Nm
supports dynamic menus by allowing the user to create new
menus. The related definitions for using dynamic menus
are:
menus.
The related definitions for using dynamic menus are:
.Bd -literal
struct menudesc;
@ -355,39 +373,47 @@ void free_menu (int menu_no);
.Pp
The
.Ar title
is the title displayed at the top of the menu. The
is the title displayed at the top of the menu.
The
.Ar opts
is an array of menu entry definitions that has
.Ar numopts
elements. The programmer must build this array and
elements.
The programmer must build this array and
fill in all of the fields before processing calling
.Fn process_menu
for the new menu.
The fields of the
.Ar opts
may change at any time. For example,
may change at any time.
For example,
.Em opt_name
may change as a result of selecting that option. When
the menu is redisplayed, the new text is printed.
may change as a result of selecting that option.
When the menu is redisplayed, the new text is printed.
Arguments,
.Ar x, y, h
.Ar x , y , h ,
and
.Ar w
are the same as the options in the menu description.
.Ar mopt
is the boolean options. Note, box, exit and shortcuts are
enabled by default. You need to add option flags to turn
them off or turn on scrollable menus.
is the boolean options.
Note, box, exit and shortcuts are enabled by default.
You need to add option flags to turn them off or turn on scrollable menus.
The options
.Ar post_act ,
and
.Ar exit_act
are function pointers to the the display action and the exit
action. If they are NULL, no call will be made. And
finally,
action.
If they are
.Dv NULL ,
no call will be made.
And finally,
.Ar help
is the text to display in a help screen. A NULL help
pointer will disable the help feature for the menu.
is the text to display in a help screen.
A
.Dv NULL
help pointer will disable the help feature for the menu.
.Sh FILES
.Bl -item -width /usr/share/misc/menu_sys.def
.It
@ -397,8 +423,8 @@ pointer will disable the help feature for the menu.
The following is a simple menu definition file.
It is complete in that the output of
.Nm
may be compiled into a complete program. For example,
if the following was in a file called
may be compiled into a complete program.
For example, if the following was in a file called
.Pa example.mc ,
an executable program could be produced by the following
commands.
@ -458,6 +484,6 @@ menu othermenu, title "Sub/Next Menu", x=5, y=5, no box;
option "Do Nothing!", action { };
.Ed
.Sh AUTHORS
Philip A. Nelson for Piermont Information Systems Inc. Initial ideas
for this were developed and implemented in Pascal at the Leiden University,
Netherlands, in the summer of 1980.
Philip A. Nelson for Piermont Information Systems Inc.
Initial ideas for this were developed and implemented in Pascal at the
Leiden University, Netherlands, in the summer of 1980.