rtsi.com/2014.01.www.rtsi.com.tar/www.rtsi.com/OS9/TOP/USR/MAN/mmenu.prf

Text File | 2009-11-06 | 17KB | 642 lines

.fill
.justify
.offset 5
.rightmargin 70
.pagesize 72
.m1 3
.m2 2
.m3 2
.m4 5
.ec \
.header /Mmenu/Tools/Mmenu
.footer /Page #//Printed (%)/
.in +5
.define topic
.bold
.in -5
$1 $2 $3 $4 $5
.in +5
.en
.define endtopic

.en
.define noform
.nojustify
.nofill
.en
.define noformend
.justify
.fill
.en
.! Manual created with MWB
.! END-OF-MACRO
.topic NAME
Mmenu - A very friendly Userinterface
.endtopic
.topic SYNOPSIS
.noform
mmenu <-f=startmenu> [<-k>] [<-l=logoff_command>] [<-c=mark>]
      [<-m=left_right>] [<-p=prompt>] [<-s=logon_command>]
      [<-a>] [<-r>] [<-z=logfile>]
.noformend
.endtopic
.topic DESCRIPTION
    MMenu offers you a simple to handle and powerful userinterface.
If a user shouldn't have access to system functions is it a good idea
not to give her/him a shell. A typical usage of such menus is a BBS.
You can give several options for this menu, these are
.in +5
-f=startmenu
.in +5
This option must be given and tells
.bold
MMenu
which menu it should use at startup time. The directory where the menu
files are located are specified by
.bold
sysinfo
and/or the enviroment. The firstmenu (from now called mainmenu) will be
displayed and the user can choose whatever you gave her/him.

.in -5
-k
.in +5
.bold
MMenu
offers a special form of displaying the menu, called shortmenu. This
means that the user gets only the name of the current menu and the
prompt. The user can switch everwhere in
.bold
MMenu
between these display forms. If someone uses
.bold
MMenu
the first time it is not very good to give her/him shortmenus.

.in -5
-l=logoff command
.in +5
When a user logs off incorrect (e.g. hang up) then there is perhaps some
work to clear up his session. This can be done by this option.

.in -5
-c=mark
.in +5
All selectable menuentries are marked by an asterik. if you want to
change this to another character you can use this option.

.in -5
-m=right_left
.in +5
If you use entries which may be tagged, here you can give the two
tag-charackter, the left and the right, e.g. you start mmenu using -m=()
and you have an entry to be taged, the `*` is marked as `(*)`.

.in -5
-p=prompt
.in +5
If you don't like the defaultprompt or if some user should get a special
prompt, use this option.

.in -5
-s=logon command
.in +5
When logging on in
.bold
MMenu
you want perhaps execute a program, e.g. to show the user that she/he
has new mail etc.

.in -5
-a
.in +5
When you offer a BBS or a user often changes her/his terminal type you
can
.bold
MMenu
make to ask every time for her/his terminal when starting up.

.in -5
-r
.in +5
This is for restricted mode. The only feature that is implemented is
that the user can't save his settings when displaying a directory.

.in -5
-z=logfile
.in +5
If you want a logfile of all executed programs by the user you can start
mmenu with this option. While the user is logged on, his logfile is
written to a temp-file and is appended to
.ul
logfile
before mmneu exits. To use this, a directory
.ul
/dd/TMP
must exist to stroe the temp file.
.in -10

    On startup time mmenu examines the user's .login file in her/his
home directory to get various settings (such as terminaltype, menu
directory, etc.). There is also a system wide file for enviroment
settings. This is placed in /dd/SYS and called
.ul
mmenu.environ
each line has the form <variable>=<value>, e.g. EDITOR=smile. This is
also read on startup time.

    Let's assume you want to create a new menu. First edit your
.bold
sysinfo
file to add the entry
.ul
mmenu.datadir
and set it to a directory to which you like. Or set your
enviroment variable
.ul
MENUDATA
just for testing. Decide the name of your mainmenu, in this example call
it main. So you edit first the files
.ul
main, main.cfg, main.cmd, main.hlp
and
.ul
main.jmp
to create a base. An example for the file 'main':
.nf
.nj
.in +10
Main Menu
This is the main menu
Online,#online
Information,#info
System,#system

Help,:help
Logoff,:logoff
.in -10
.fill
.justify

    The first line is the title of this menu and will be displayed
at the headline of the menu. The next line is a short explanation of
the contents of the menu. This line can be left empty. Then there are the
selectable menuentries. For an exact description of all possibilities
see later.

    Next create main.cfg. In this file you can put in a lot of
messages which will be displayed under some circumstance. If you don't
mind you can skip this file. For details see later.

    Now have a look at main.cmd. In there you can put some commands
which should be available in the whole menu tree. As an example:
.in +10
.nf
.nj
date
who=who -s
.fill
.ju
.in -10

    When writing a line like 'date' then the command date will be
executed everytime the user types it. When the user now types who then
'who -s' will be executed.

    In main.hlp you can write some help information. It is a simple
textfile.

    When you have created a lot of menus it may be a bit boring for
the user to go through to whole menu tree. So you can create the file
menu.jmp. In there are all menus listen which can be called direct by
name.

    Every other submenu of main needs an own file, but only the file
for that menu, no extra files like .jmp etc. Every menu is build as
shown above. Every selectable entry can have a maximum of five commands.
Commands can be a normal program. As a program has been executed and
returns to
.bold
MMenu
then there is displayed a line like 'Press Return..' or so and the user
have to hit the RETURN key. If the command don't makes any screenoutput
you can prefix a minus '-' to the program.

    But there are also a lot of built-in commands. You can access
them by giving one of the following commands:

.in +5
#<menu>
.in +5
This command will call the menu <menu> to be displayed. Any further
commands will be ignored.

.in -5
:logoff
.in +5
When executing this command the user will leave the
.bold
MMenu
and normally the system. This command should be available in every
system. Without this option there is no way to leave the system.

.in -5
:help
.in +5
This is normally the entry for a help file. The help file for this menu
have to have the same name as the menu with a postfix
.ul
\.hlp
and have to be public readable.

.in -5
:back
.in +5
With this option this menu is left and the previous is displayed again.
If you are yet in the mainmenu nothing will happen.

.in -5
:quit
.in +5
This will drop you back in the mainmenu. This can be
reached form every part of the menu by typing quit.

.in -5
:setup
.in +5
With this option you can change the enviroment of the user. This
implicits that the change is saved in his homedirectory in the file
\.login. As an example:
.br
Termtype VT100,:setup TERM vt100

.in -5
:relogin
.in +5
If you want to offer a way that the user can make a second login then
you can use this command. But this includes that you are have the program
.ul
logon
which will be called.

.in -5
:dir
.in +5
This is the most powerful built-in command. For example, you want to
display in a menu all the Files in a homedirectory and give the user the
chance to tack some entries and then download or delete them this option
has been added. The command looks like this:
.br
:dir <directory>|<action> or
.br
:dir <directory>|:flag|<entry>|<action>
.br

The first version will generate a menu with every filename and as
command <action>.  The second will generate a menu with all filenames
and the possibilitiy of toggling each filename as on or off.  Then there
is a new menuentry be added, titeled <entry> and the command <action>.
To insert a choosen (or even several) filenames in the <action> line you
can insert expressions in '[' and ']'.  The expression [dir] will insert
all selected filenames without the full path, [fulldir] will include the
full path in front of every filename.  There are some more commands in
'[', ']', see below.  If there are some more files you want to ignore
you can create a file in the menudata directory named
.ul
mmenu.<dir>
where <dir> is the last component of the path to that direcotry, e.g.
when using the path /h0/SPOOL/NOTES the file is called mmenu.notes.

.in -5
:chd [<dir>]
.in +5
After mmenu has started the user's data directory is his home directory.
If you like to change it to access files without full pathname, you can
use this command. The line
.br
Databases,:chd /h0/USR/DATABASES/EXAMPLE,database culture,:chd
.br
will first change ths user's data directory to the database directory,
then execute the database program and the return to the user's home
directory.

.in -5
:more <file>
.in +5
Shows <file> using the very simple builtin pager. To continue viewing
the file, just type return, to stop it, just type 'q' and return while
you are prompted for input.
.in -10

In every command line you can make
.bold
MMenu
insert some enviroment variables. If you set a string between '\$' then
this will be replaced by th value or none if this variable is not
definied.

    There are also some direct commands which the user can invoke
from whereever she/he wants. The first one has been mentioned is the
.ul
quit
command which will put the user in the mainmenu. The other powerful
built-in command starts with a '!' and you can send a message to another
user using the syste, at the same time as you. The syntax is
.ul
!<user> <msg>
which will send the message <msg> to the user <user> if she/he is logged
on and is allowing flashing. Three other commands are implemented as
control codes. The first is control-k to switch between short- and
fullmenus, the second is control-l and control-r which redraws the
screen. Using control-u will switch between using an emulation or not
using it. This may be useful if you log on and you are now using a
complete different terminal. Now the menu will be shown as if it is
corrupted.

    You may have different userlevel in your system. And you don't
want to create more than one menutree. Therefor you can put in front of
each line in the mneuentries and <main>.cmd a permission word. These
permissions are enclosed by brackets '[' and ']'. You can make the
different userlevel using enviroment variables or the special words
.ul
group
and
.ul
user
looking at the uid/gid of the user. There is alsoa special entry if you
want to offer some entries at a specified time. With the
.ul
hour
and
.ul
time
expressions is this possible, e.g. [(time > 20.30) && (time < 23.00)].
A permission word is a boolean expression which may be as complex as you
want (or the stack).  Enviroment variuables can be compared to a string
or only if they exists, e.g.  you want to enable the games only if the
user has TERM definied and TERM have to be other than dumb.  So you will
put an expression like
.ul
[TERM & TERM!=dumb] Games,#games
to make this clear. If you put a '1' in front of an expression, the
expression will be inverted, e.g.
.ul
[!(TERM & TERM!=dumb)]
is the exact oposite of the expression above. When using the special
words
.ul
group
and
.ul
user
you have more features. You can use the operaters '<' (less), '<=' (less
or equal), '=' (equal), '>=' (greater or equal) and '>' (greater). As
the second argument you can put a number (as the group- or userid) or a
valid group- or username, e.g.
.ul
[group<=stff] Adm,#adm
will only allow the members of the group adm or less (in groupid) to
access this menu.

    You can also combinate the expressions with the boolean
operators '&' (and), '|' (or) and '^' (exclusive or). And you should use
brackets '(' and ')' set the priorities of working down the expressions.

    When a user chooses an entry and appended to this command a
space and some other arguments you can get them to insert in the
command. all these commands are enclosed in '[' and ']'. Following
expressions are possible:
.in +5
[dir]
.in +5
This is used when examinig a directory. All taged directory entries of
the last examined directory are inserted (just the filenames).
.in -5
[fulldir]
.in +5
Like [dir], but the absolute pathname is inserted instead of just the
filenames.
.in -5
[opt]
.in +5
The user may just type in an option beginning with a dash ('-').
.in -5
[filename]
.in +5
Just a filename without slashes is allowed.
.in -5
[relpath]
.in +5
A relative path is accepted.
.in -5
[fullpath]
.in +5
A complete valid pathname is accepted.
.in -5
[everything]
.in +5
Every kind of input is accepted.
.in -5
[]
.in +5
Just alphanumeric input is accepted.
.in -10
In every case where input is accepted only one argument (terminated by
the end-of-line or a space) will be used. If you want to allow to use
all arguments in the inputline you can insert a `M` in fornt of every
expression, e.g. [Meverything].

    The next chapter explains the valid values for the <main>.cfg.
The following expressions are allowed (the '=' must be follow directly
to the value) :
.in +5
return=
.in +5
This string will be displayed when the user should press the RETURN key.
.in -5
previous=
.in +5
Using the ':dir' command, this string will be displayed for the
automatic generated entry to go back to the previous menu.
.in -5
+page=
.in +5
Using ':dir', this text is displayed to go to the next page of the
directory menu.
.in -5
-page=
.in +5
Like '+page', but to select the previous page (NOT the previous menu!).
.in -5
save_sel=
.in +5
Using ':dir' and ':flag', you can tack some files and save your setting
for later use. This is the text to be shown for this option.
.in -5
prompt=
.in +5
This is the prompt for that menu if you require an own one.
.in -5
clear=
.in +5
Using ':dir' and ':flag', with this optin you can clear out all marks
yet set, this will NOT affect the saved setting.
.in -5
nohelp=
.in +5
If you have anywgere the command ':help' included, but there isn't any
help file for this menu, this text will be displayed.
.in -5
non_selected=
.in +5
Using the expressions [dir] or [fulldir] you have to select at least
one. This will be displayed, it none is selected.
.in -5
no_argument=
.in +5
If you want some input using a '[', ']' expression and the user doesn't
typed in any, this message is displayed.
.in -5
no_receiver=
.in +5
Using the built-in message system this is the errormessage if no
receiver is given.
.in -5
no_message=
.in +5
This is if no message had been written.
.in -5
cant_send=
.in +5
If the receiver had disabled the reception of a message, this text is to
be shown.
.in -5
not_logged_on=
.in +5
If the user is not logged on now.
.in -5
send_msg=
.in +5
As a confirmation for you.
.in -5
empty_dir=
.in +5
Using ':dir' and the directory is empty, this text is displayed to give
the user a hint.
.in -5
full_dir=
.in +5
If there are some entries in the directory, this message is displayed in
the second line. It is in a 'printf' format such as
.ul
%d file (%d %%)
to get a well output.
.in -5
no_slash=
.in +5
When giving an pathname, the user isn't allowed to put slashes in his
arguments. This is the errormessage.
.in -5
online=
.in +5
When the user logs off correct his online time will be displayed. To
change the message, use this entry. It is in the printf fromat with two
integer variables.
.in -5
termtypes=
.in +5
When using the command line option -a for mmenu you are asked for your
terminaltype. You can change the prompt for the input wuth this line. If
you insert a '%s', then the actual terminaltype is displayed as a
default value.
.in -5
missdash=
.in +5
If you want to force the user to type in only an option starting with a
dash ('-') and he didn't, this message will be displayed.
.in -5
goon=
.in +5
This is the prompt for the internal pager.
.in -5
no_file=
.in +5
This will be displayed when the builtin pager couldn't access the given
file.
.in -10
.endtopic
.topic FILES
.noform
<menudir>/main
<menudir>/main.cfg
<menudir>/main.jmp
<menudir>/main.hlp
<menudir>/main.cmd
<homedir>/.login
/dd/SYS/mmenu.environ
.noformend
.endtopic
.topic SYSINFO
.noform
mmenu.datadir
.in +5
The directory where the menus are located
.in -5
.noformend
.endtopic
.topic ENVIROMENT
.noform
MENUDATA=<directory>
.in +5
In this directory are the menu descriptions.
.in -5
MENUFORM=<form>
.in +5
If <form> is "short" then shortmenues are selected as default.
.in -5
TERM=<terminaltype>
.in +5
The terminal of the user.
.in -5
HOME=<directory>
.in +5
The home directory of the user.
.in -5

.noformend
.endtopic
.topic EXAMPLES
.noform
.fill
.justify
To start the
.ul
MMenu
it is a good idea to put this line as the user's shell in the password
file:
.br
shell ex mmenu -f=main
.br
to be sure that the .login will be read in.
.br
A possible mainmenu may look like this:
.nf
.nj
.in +10
Mainmenu
System of gladness
[group=guests] Order Account,acc_order
[group!=guests] Change Enviroment,#change_env
[TERM!=dumb] Games,#games
[group<=user_l2] Local Mail,loc_mail
[group<=user_l1] Remote and Local Mail,oxm
[group=staff] Shell escape,shell

Help,:help
Logoff,:logoff
.in -10
.fill
.justify
.noformend
.endtopic