


1. NAG.


Welcome to the document that explains how to NAG (tm). NAG, "Not A GUI" but
nice none the less, is a simple, but stylish and consistent interface for
those situations where a bit mapped GUI is not practical nor possible.

The NAG interface features hyper-text linked menus, list manager, easy system
call access, hooks to C object modules, and much more (NOTE - TOC at end!)



1.1. Why NAG?

The presention layer is the most ignored function in UNIX applications.
Typical presentation functions are coded ad hoc into an application; this
results in non uniformity nor great style. Yet a good presentation system is
needed to service less sophisticated users.

In general, a respectable presentation system is:

    + Consistent in it's form, function, and commands

    + Easy to use; no cryptic number to function translation

    + User friendly; intuitive; copious on line help

    + Flexible, programmable, and application independent.

Modern GUIs have the preceding characterisitics; NAG offers these same
characterisitics but with an interface that's suitable for even simple, line
mode operation.

1.1.1.    History

NAG was originally developed as a UNIX system dial up shell. The first
criteria it had to meet was support reasonable presentations for both simple
ANSI terminals, but also for users so dumb they couldn't figure out how to
run their terminal program in ANSI mode. If not running in ANSI mode, NAG
runs in line mode; NAG's line mode is an exact presentation of the ANSI mode
but without features such as bold chars or screen clear.

Since that time, NAG has been used in many situations where a nice but not
GUI based interface is needed. This includes telnet/rlogin sessions along
with dial-up.

NAG has evolved not as pretty code or SW architecture but as an experiment in
the development of a nice, simple, interface. NAG presentation meets this
goal; the code in some cases is hacked, old, and poor style; an early version
of NAG was partly written in awk. No more need be said.





CopyRight (C) G.R.Gircys/Oesterreich & Assc. 1992,1993                 1





1.2. NAG Overview

The NAG interface is simple and intuitive. When a NAG session starts, an
application dependent menu is presented. Valid commands are displayed in bold
characters (or curly bracket marked if running in line mode).
Emboldened/marked words in a NAG menu are called TOPICS.

A user has only two choices: enter an emboldened word (TOPIC), or a <CR>. If
a TOPIC is entered, the action associated with that TOPIC is executed. An
action can be either the display of a hyper linked menu, execution of a
command, or invocation of the list manager. If the action displays a menu,
enterng only a <CR> brings the user back t the previous menu. It is
impossible for users to get lost; the natural reaction of hitting <CR> will
always bring them back to the home menu.

Just as the presetnation is NAG consistent, the interface to list, and system
commands is also consistent. You can now develop line mode based UNIX
applications that all have the same interface. Application specific functions
can be either shell/perl scripts; C program code can also be accessed.

1.2.1.    NAG Uses

NAG has potentially zillions of uses. Any place where an organized
presentation complete with copiuos on line help is needed is a possible NAG
solution.

Some suggestions:

    + DIAL up BBS for UNIX

    + Turnkey UNIX boxes (such as server/routers)

    + Frontend to MH

    + Frontend to any application wanting to be user friendly

    + System administration shell

    + A boot shell to a more sophisticated env.

In general, a NAG presentation, if properly embellished with online help, can
reduce support calls to virtually nothing. An since NAG is easily
programmable, it's trivial to add new help information as need becomes
apparent.



1.3. Covered Topics

This document explains how to program your own NAG presentation.



CopyRight (C) G.R.Gircys/Oesterreich & Assc. 1992,1993                 2



1.3.1.    Caveat

The information in this document is preliminary and subject to change without
notice.

There is NO guarantee that the information in this document is free from
errors or inconsistencies though every attempt has been made to insure it is
correct, relevant and useful.

Use of this document is AT YOUR OWN risk. If this is not acceptable, do not
use this document; do not use NAG.



1.4. Supported Environments

NAG has been compiled and used extensively on BSDI 1.0. Though older versions
have been ported to other platforms, this version has not. An old version was
even running under DOS, though porting this new version is probably not
useful since DOS already has so many ANSI and pointing device capable
alternatives.

Porting to other platforms is relatively easy; only tty functions have to be
changed to set tty in raw/cbreak mode.



1.5. Nag Support, Suggestions, Etc.

Send suggestions, enhancements (as context diffs) to rich@oester.com.

























CopyRight (C) G.R.Gircys/Oesterreich & Assc. 1992,1993                 3



2.NAG BASICS


NAG is as simple to program as it is to use. This chapter explains all
considerations for properly setting up and using NAG.



2.1. Getting Started

This section is for those that can't wait to use NAG and don't read all of
the documentation before playing with software (like me).

First, make sure you have the NAG executable ready to go and in your path.
Now, in a handy directory, use an editor to create the following file called
'menumess':

    {HOME}
            Welcome to this {HOME} menu.

                Do an {LS} command
    {_END}
    {LS}
    {_POPEN} ls
    {_END}

The preceding is a simple NAG menu message file. You can now execute NAG and
the HOME menu will be displayed followed by the default prompt (note: in the
file you edit, do NOT include leading spaces prior to the { curly bracket;
the { must be the first character in the line).

Any topic word enclosed in curly brackets is a "link tag". A tag all by
itself on a line defines the start of a menu; a tag within a menus body
defines a link. Tags that begin with an underscore are specials.

You can invoke NAG either as:

    1. nag -d :runs in line mode

    2. nag -d -a :runs in ANSI mode

    3. nag -d -t :tests terminal for ANSI capability; runs accordingly

Whenever possible, use ANSI mode; it's much nicer. If in doubt, try the nag -
t to see if your terminal supports ANSI. Note that the -d option specified
debug mode. This is needed for the following examples.

Nag will display the simple menumess file as follows:







CopyRight (C) G.R.Gircys/Oesterreich & Assc. 1992,1993                 4



            Welcome to this {HOME} menu.

               Do an {LS} command
    Enter a {TOPIC}, or type {HELP} for instructions:
    --> _


The first point to notice is that NAG does NO formatting; what you enter into
the menumess file is what you get (Hint: avoid/do not use tabs in the
menumess file).

An immediate improvement to this simple demo would be to have a line prior to
the prompt. Hopefully you are using a multi window environment of some sort;
edit the menumess file and add a line after the {LS} line. Now you do NOT
have to exit and start NAG again. At the prompt enter '0reload'. The -d
option is used to allow the 0reload command. If the -d was not entered, a bad
command error would be displayed.

After the 0reload command is entered, the menu now shows the added line. Use
the secret 0reload command to easily tune/debug your menumess file. Be sure
to invoke nag with -d if you want to debug. Note that the 0reload command
should always be entered at the HOME menu.

2.1.1.    NAG Terminology

The basic NAG terminoloy (hopefully used consistently in this doc):

    TAG : Any word enclosed in curly brackets; defines a hyper link

    TOPIC : Any tag is also a topic. It makes more sense from the user
    abstract perspective to say 'Enter a TOPIC' as opposed to enter a TAG.

    MENU : A unit of presentation; consists of text and most likely some
    TAGS

    HOME : The starting menu in a NAG presentation; all NAG presentations
    must have a home menu; it does not have to be named HOME (that's the
    default)

    Tag DEFINITION : A tag is defined by starting a curly bracketed topic at
    column one in a line; this defines the start of a menu; a menu ends with
    the special tag {_END}.

    Tag REFERENCE : A curly bracketed topic that does NOT start at column
    one (or is properly escaped); in this case TOPIC is a link to a tag
    DEFINITION.

2.1.2.    Summary

The preceding are the basic basics; you'll have to read this doc for
additional useful details.




CopyRight (C) G.R.Gircys/Oesterreich & Assc. 1992,1993                 5



2.1.3.    Caveats

In developing NAG menus, you must be very careful to observe tag format
exactly as described in this document. Typically be sure to observe
whitespace placement; NAG per se is robust and should not crash, but it's
interpreter is pretty dumb/simple in some cases, and an extra space can lead
to undesired results or a menu that just doesn't come up.

Also, this document embraces a NAG design/coding style. Nag being a
flexible/programable interface does NOT enforce the style, and many key
stroke saving shortcuts are possible. However, ignoring the style is a good
way to create potentially ambiguous menus and in some cases (esp. list
manager) completely break a function.



2.2. Implementing A NAG Presentation

Before starting to write zillions of lines of NAG menus, you should roughly
design what you what the presentation to look like. To do this, prototype
some notes using the basic NAG objects described in this section.

2.2.1.    NAG Menu Objects

All NAG menu objects are indentified by a tag: a word enclosed in curly
brackets.

A tag can be a link to one of the following:

    + Another menu

    + An application command

    + A data field

    + The list manager

Roughly decide on the hierarchy of menus you want to present; place these in
the {HOME} menu. Eventually a menu might require user input. For example,
within a menu you might have a tag called {EMAIL}; create an empty menu for
this tag:

    {USERDATA}
           Your {EMAIL} address:
    {_END}
    {EMAIL}
    this will be a data input field when done
    {_END}

NAG basically follows the same event driven style of any modern GUI. After a
user would type EMAIL and fill in the data field, you need the equivalent of
the ubiquitous [ OK ] button. For example, a more complete menu would look as
follows:


CopyRight (C) G.R.Gircys/Oesterreich & Assc. 1992,1993                 6



    {USERDATA}
           Your {EMAIL} address:

           {OK}, add me to your mailing list!
    {_END}
    {EMAIL}
    this will be a data input field when done
    {_END}
    {OK}
    when done, the script to add email addr to list goes here
    {_END}

At this point in the menu design, please note the following:

    1. additional formatting/presentation issues are described latter as
    well as nice embellishments such as custom prompts.

    2. tags must be unique! Does this mean you can't use {EMAIL} in another
    menu? No! Tags should (MUST for proper style) be bound to their menu;
    how this is done is shown within a few paragraphs (realistically, every
    menu can have a HELP topic).

    3. if you also want to provide an INDEX or global HELP menu, leave that
    till last; first get the basics done, then easy enought to add INDEX or
    global HELP menu.

Depending on how complex an application is and how much online documentation
you provide, the menumess file can get large. The menumess file can be broken
into smaller pieces; how and when to do this is described in the following
section on partioning tasks.

The remainder of the sections here provide useful initial design information
on the topics covered so far.

2.2.1.1.  Binding Tags To Menus

Binding tags to menus is a way of generating unique link tags while allowing
the tag word that's seen by the user to be non unique (such as a HELP topic
in all menus). Though NAG doesn't enforce binding syntax, you should use
binding if you want data fields, lists, and trouble free operation in
general.

A simple tag consists of a word enclosed within curly brackets; binding
information is appended to the end of the word. For example:

    Not bound; maybe not unique == {READ}

    Bound; hopefully unique == {READ[unique]}

When displayed, the user will see only {READ}; NAG will not display the
square brackets nor the 'unique' word. The convention to follow in developing
'unique' ids is as follows:



CopyRight (C) G.R.Gircys/Oesterreich & Assc. 1992,1993                 7



    + In the tag reference, include within the square brackets the tag of
    the menu which contains the tag reference.

For example:

    {HOME}
        Go {DEEPER[home]} ...
    {_END}
    {DEEPER[home]}
    ....

In the preceding example, the tag reference to DEEPER is bound to the menu
it's used in by adding the id [home] to the tag. When the DEEPER tag is
defined, it must include the [home] id in it as shown in the line after
{_END}.

The unique ids can be concatenated in the following form:

    {HOME}
        Go {DEEPER[home]} ...
    {_END}

    {DEEPER[home]}
               and {DEEPER[deeper][home]} ....
    {_END}

    {DEEPER[deeper][home]}
                        {ENOUGH[deeper][deeper][home]}
    {_END}

    {ENOUGH[deeper][deeper][home]}
                                ...
    {_END}

This unique id binding based on menu hierarchy results in tag definitions
which are unique and easily tracable. Conceptually the binding rule defines
what can be considered 'primary references'. Obviously you can have only one
bound primary reference, but at the same time it's often desirable to
reference a tag multiple times (from more than one menu).

If you reference a tag that's not bound to a menu, that's a secondary
reference. Typically this is used in the creation of an INDEX or global HELP
topic.

For example, an INDEX topic could include:

    {INDEX[home]}

      How to begin descent: {DEEPER[home]}
      End of descent: {ENOUGH[deeper][deeper][home]}

    {_END}



CopyRight (C) G.R.Gircys/Oesterreich & Assc. 1992,1993                 8



Note that within the {INDEX} menu, secondary references MUST be unique - you
cannot have both {DEEPER[...]} tags in the INDEX menu. Also note that data
field or list topics work only when accessed as a primary reference (that is,
don't secondary reference topics that are data fields or lists).

2.2.1.2.  Partioning The Menumess File

Depending on the application, a menumess file might get large, or the
application might hint at breaking up the tasks into discrete modules. Either
way, the implications are that multiple menumess files are needed.

At this point in your NAG design, just be aware that:

1. a NAG presentation can consist of multiple menumess files

2. Any TAG defnition can be declared to be treated as the HOME page.

So go ahead and plan accordingly. However, do note that global data such as
an INDEX would have to be duplicated in each menumess file. However, if you
find this is needed, reconsider the partitions cause style wise, you
shouldn't have to have a global index on every menu.

2.2.1.3.  Data Fields

You can plan on using the following types of data fields:

    read only - used to display information only

    writable - user can define whatever is appropriate; note that a default
    value can be initially shown.

Additionally, data fields can be either bound to a menu (context dependent)
or global. Typically plan on using context dependent fields; they are more
flexible. Global fields should only be used to store account information,
setup info, and so forth.

Writable data fields are modified by entering a topic; read only fields do
NOT have a topic associated with them.

Users can modify a field in one of two ways:

    1. enter a topic; this invokes a field entry menu. The field entry menu
    can have an approriate prompt defined for it.

    2. enter a topic followed by an '=' eqaul sign, followed by the value of
    the field. For example: FIRSTNAME = john.

NAG does no input checking; this is a function of the script that would
require input.

2.2.1.4.  List Manager

You can plan on using the following types of lists:


CopyRight (C) G.R.Gircys/Oesterreich & Assc. 1992,1993                 9



    pick list - used to display items from which a user can select any that
    are appropriate

    writable - user can define whatever is appropriate.

In both cases, the user enters the list manager menu by enter the lists'
topic. NAG has default list titles and prompts; custom titles and promts are
supported.

Pick list items are selected by entering a displayed item; writable items are
entered free form. Selected items are toggled; enter first time to select;
change of mind, enter again to de-select. Selected items in pick list are
displayed emboldened (or within curly brackets for line mode operation)

The pick list presentation is quite flexible. In addition to custom
titles/prompts, the pick list can be made to emulate a numbered list; the
user simply enters a number to select/de-select an item.



2.3. Invocation And Operation Options

NAG has a number of useful invocation/operation options. This section not
only describes these options, but also explains when to use them (how novel).

Each option is presented; multiple options are allowed and order is not
important (case is!). Defaults and mutually exclusive options are described
as needed. Also note that though this section is fairly detailed, look into
the example directory for commented nag scripts for more detail.

2.3.1.    Locking/Inactivity/Timeout

Nag does no lock checking; it is possible for multiple users to
simultaneously use a single account. If a single account (such as a sign up
or intro presentation) is used, each login instance MUST be assigned a unique
context directory (description in following section), or additional logins
must be aborted with a message saying something like 'try later'.

Either lockout or context dir assignment can easily be achieved by wrapping
or preparing the nag invocation with either a shell or perl script. User
shell Nag presentations normally would be locked.

Nag also does not include functionality to detect inactivity nor login time
limit. These functions can also be readily implemented using scripts (early
versions had this capability, but code complexity mandated the process per
task approach common in Unix arcitexctures.

2.3.2.    Debug Mode

The invocation usage of this option is as follows:

    nag -d



CopyRight (C) G.R.Gircys/Oesterreich & Assc. 1992,1993                 10



Use this option while you are debugging/tuning a Nag script. The -d enables
the 0reload command so you can easily see changes to the script without
having to EXIT/restart nag evey time a change is made.

Never release a production presentation with the -d option. If use -d, always
enter the 0reload command from the home menu.

2.3.3.    Context Directory

The invocation usage of this option is as follows:

    nag -c contextdir

Contextdir is any valid path/filename. Upon invocation, Nag will validate the
directory and abort/print an error should there be a problem.

The default is ./, the current directory.

The contextdir is used to hold all data field and list files, and as such
must be unique per Nag presentation.

For user shell Nag presentations, a workable convention is to have a
directory called 'context' in the users home directory. In this case the
following home directory relative contextdir would work:

    nag -c context

For a sharable Nag presentation, have a script prepare a random name (in the
style of the mktemp C lib function) temp dir under something lile
/var/tmp/nag/... and invoke nag with that as the contextdir; use whatever you
prefer to clean the directory after logout - cron jobs or shell traps.

2.3.4.    Menumess Directory

The invocation usage of this option is as follows:

    nag -m menumess

Menumess is any valid path/filename of a Nag menumess file. Upon invocation,
Nag will validate the menumess file and abort/print an error should there be
a problem.

The default is 'menumess' in the current directory.

The menumess file is the Nag script that defines a Nag presentation. This
presentation can be shared by many Nag instances. The default is not useful
nor advised except for testing/devloping Nag scripts. Nag scripts should be
organized and permission protected (read only).

2.3.5.    Terminal Setup

Nag supports a number of simple terminal functions: screen clear, bold on,
and bold off. This section describe the various options that are supported.


CopyRight (C) G.R.Gircys/Oesterreich & Assc. 1992,1993                 11



Nag has built in test to verify ansi terminal mode. In keeping with the Nag
objective of supporting completely brain dead situations, Nag doesn't even
trust/nor rely on a terminal query, but instead walks the user through 2
simple test; the user must respond in the affirmative that a terminal
function such a clear or bold has indeed worked. See following section on
generic support for more philosophical details.

Note: the terms bold on/off are historical; the more technically correct term
might be stand out mode/reset.

2.3.5.1.  Default Mode

If Nag is invoked without any terminal setup/control options, it runs in line
mode: no screen clear, and topics are enclosed within curly brackets (as
opposed to being in bold).

2.3.5.2.  Generic Terminal Support

Any generic terminal capable of screen clear, bold on/off can be supported by
setting the following three environment variables prior to invoking Nag:

    BOLDON

    BOLDOFF

    CLEAR

The easiest way to set these is in a shell script that uses the tput command.
This is useful only if you have absolute confidence and control over the
terminals that will be used.

If all three of these variables are set, they WILL over ride the nag -a and -
t command line options (described shortly).

Note that the only valid way to expand generic support consistent with
original Nag objectives is to let a user select a terminal type, then test
the results. This added functionality would require coding additions to the
terminfo function. However, in over three years of operation, this was never
needed. Ansi covers most popular situations such as the dec vt's and xterm
(is vt102). Note that in some cases, if vt100 works it's either non standard
or wrong; vt100 is not equivalent to ansi; vt102 is.

2.3.5.3.  Running In Ansi Mode

The invocation usage of this option is as follows:

    nag -a

Nag will run in ansi mode; it will use ansi screen clear and bold on/off. Use
of this option assumes that the connections is ansi capable.

The default is not to run in ansi mode.



CopyRight (C) G.R.Gircys/Oesterreich & Assc. 1992,1993                 12



Note that if ALL 3 environment variables, BOLDON, BOLDOFF, and CLEAR are set,
they take precedence and the -a flag is ignored silently.

Following section provides more usage details.

2.3.5.4.  Testing For Ansi Mode

The invocation usage of this option is as follows:

    nag -t

At invocation, the user will be asked to verify that screen clear and bolding
works. If BOTH functions are verified, Nag will run in ansi mode and will do
the following:

    Nag will update the global config file by either adding or modifying it
    to contain the following line:

    TERM~ansi

    If the global config file does not exists, it is created. More info on
    global config file is presented shortly.

A useful and proven technique for using this global config file information
is to initally set up a Nag shell account WIHTOUT the TERM~ansi in the global
config file. Now a shell can prepare nag invocation as follows:

    #!/bin/sh
    if grep 'TERM~ansi' .nagrc
    then
    #    Yes, been set so run in ansi
    nag -a ....
    else
    #    User didn't specify ansi; do a terminal setup test
    nag -t ....
    fi

You don't have to run Nag with -t if ansi mode grep fails. You could simply
inoke nag in line mode (no -t) and instead in the home menu include a
TERMINFO topic. TERMINFO is a built in topic that will run the screen test
and enable ansi as much as possible.

Note that if ALL 3 environment variables, BOLDON, BOLDOFF, and CLEAR are set,
they take precedence and the -t flag is ignored silently.

2.3.6.    Multiple Menumess File Operation

The options in this section are used when you partition a Nag presentation
into multiple menumess files. The two controlled functions are the HOME page
and how nag exits.

By default, a nag presentation looks for the tag {HOME} as the starting
point. This default is good for the primary/master nag (though you can use


CopyRight (C) G.R.Gircys/Oesterreich & Assc. 1992,1993                 13



anything else if you wish). Also by default, when nag exits, it prompts for
verification.

When a nag script invokes another nag session, you would tell it to use an
the home page of the invoked script and most likely flow is better is nag
doesn't prompt on exit. The following options control the home page and exit
action.

2.3.6.1.  Exit Without Verify Prompt

The invocation usage of this option is as follows:

    nag -x

When nag processes the EXIT topic, it will not prmpt for exit verification.

The default is to verify exit with an appropriate prompt.

The next section shows basic usage example.

2.3.6.2.  Specify A Home Page

The invocation usage of this option is as follows:

    nag -h TOPIC

Nag will use TOPIC as the HOME page. TOPIC is case sensitive; consistent with
nag style, all TOPICS should be upper case. TOPIC must not be enclosed in
curly brackets; that's done internally by Nag.

The default home page topic is HOME.

For example, to invoke a Nag session that implements email, you would do
something as follows:

    {DOEMAIL}
    {_SYSTEM} nag -h EMAIL -x -m EmailMenus ...
    {_POP}

The _SYSTEM nag builtin topic invokes another nag session using the EMAIL
topic as home page; the -x says no exit verification. The _POP nag topic
returns to the menu from which the DOEMAIL tag is referenced as opposed to
it's definition; this is the desired result. Try without the _POP to see the
difference (_POP sis explained later on).

2.3.7.    Global Data File

The invocation usage of this option is as follows:

    nag -i initfile

Initfile is a valid path/name for nag's global data file; nag checks the
initfile and if there are problems, prints an error and exits.


CopyRight (C) G.R.Gircys/Oesterreich & Assc. 1992,1993                 14



The default is .nagrc in the current (home) directory.

This option has only been used while developing/testing nag scripts. In real
use, try to use the default name and location.

2.3.8.    Check Uid

The invocation usage of this option is as follows:

    nag -u uid

Uid is any valid user ID. Upon invocation, Nag will do a 'getuid'; if the uid
does not match the passed value, nag prints an error message and exits.

The default is NO uid checking.

This option is archaic, but maybe still useful. It originally was used to
prevent normal user invocation of root privilidged nag presentations (that
is, nag -u 0). Ideally, normal user access should be prevented by using
system permissions rather than this type of trick.



































CopyRight (C) G.R.Gircys/Oesterreich & Assc. 1992,1993                 15



3.   NAG I/O SYSTEM


The Nag input/output system consists of the following elements:

    + menu prompts and user input

    + data field/list prompt and user input

    + data field/list files for use by scripts/C funcs.

This section explains details relating to all three.



3.1. Prompt Basics

In general, a Nag prompt consists of two elements:

    1. A prompt title, and

    2. Prompt characters.

The title is appropriate text; the prompt characters set off the user entry
point. Both title and characters are definabe on a per menu basis. By
default, the title and characters are on their own line.

The following Nag builtin tags control prompt titles:

    1. {_PROMPTTITLE} - Prompt for a menu

    2. {_SETFIELD} - Prompt for context dependent data field/list

    3. {_SETRC} - Prompt for global data field.

Prompt characters are defined using the the {_PROMPTCHARS} Nag builtin tag.
The default prompt chars line is "\n-->  ". To define new prompt chars, use
the {_PROMPTCHARS} tag as follows:

    {_PROMPTCHARS} \n=

The prompt chars are now "=="; the \n says start the promptchars on their own
line. Addtional details provided in relevant section.



3.2. Menu Prompt

After a menu is displayed, Nag outputs a prompt and waits for user input. The
default prompt is as follows:

    Enter a {TOPIC}, or type {HELP} for instructions:
    --> _


CopyRight (C) G.R.Gircys/Oesterreich & Assc. 1992,1993                 16



The first line (with the words TOPIC and HELP) is the prompt title; the
second line '--> ' is the prompt characters. To set the prompt title to
whatever you wish, use the Nag builtin tag {_PROMPTTITLE}. For example:

    {USERDATA}
           Your {EMAIL} address:

           {OK}, add me to your mailing list!

    {_PROMPTTITLE} Enter your {EMAIL} addr then {OK}
    {_END}


The USERDATA menu will now display the defined prompt using the default
prompt chars. The prompt chars could easily be changed using the
{_PROMPTCHARS} tag. Note that the location of the {_PROMPTxxxx} tag is not
important - it can be placed anywhere within the menu.

Basic {_PROMPTTITLE} details:

    + Any word within curly brackets is emboldened; use for emphasis to
    display valid topics

    + The prompt must begin at least one space after the {_PROMPTTITLE} tag
    (that is, leading/trailing spaces are displayed)

Additional style related issues are discussed in the MENU section.

3.2.1.    Menu Input Parsing

Valid menu input consists of any topic displayed in the menu. Menu input is
parsed as follows:

    + Leading/trailing whitespace is ignored

    + Input is not case sensitive; lowercase input will match an all upper
    case topic.

    + Input only has to be long enough to avoid ambiguity. For example, to
    match the topic TRANSMISSION, a user would only have to enter a solitary
    'T' if TRANSMISSION was the only topic beginning with T in the menu.

    + Ambiguous input is resolved as follows: exact matches are never
    ambiguous; otherwise if after parsing all topics in a menu there is more
    than one match possible, and ambiguous error is displayed.

For example, suppose there are two topics: ABCD and ABC. Is user enters ABC,
that matches the topic ABC; entering only AB is ambiguous.

Be careful is topics are ambiguous since a user might get something they
don't expect.




CopyRight (C) G.R.Gircys/Oesterreich & Assc. 1992,1993                 17



3.2.1.1.  The EXIT Command

Nag supports one and only one builtin command. This is the EXIT command.

Exit is not case sensitive and may be entered at any menu. By default, EXIT
reuls in a verification prompt. If Nag was invoked with the -x option, EXIT
is immediate.

3.2.1.2.  Special Input

Nag supports two special input characters as follows:

    - (minus sign) - entered alone to a menu prompt will redisplay the
    current menu.

    <ESC> - when entered alone is equivalent to <CR>; the display goes to
    the calling menu. <ESC> at other times when so noted in display comment
    will return to the HOME menu.



3.3. List/Data Field Prompts

There is no default for list/data field prompts; a prompt must be defined.

The prompt is defined as the last argument in the list/data field Nag builtin
tag. There are two Nag builtin tags: one for global data ( _SETRC }, and one
for context dependent data ( _SETFIELD ).

An example use of the _SETFIELD Nag builtin is as follows:

    {_SETFIELD} datafile thefield 1 Enter a value for THEFIELD:

The prompt begins at the space after the 1; details on _SETFIELD are provided
in the relevant section.

If the user enters the topic associated with THEFIELD, the following prompt
is displayed:

    Enter a value for the THEFIELD:
    -->

Note that there are minor details regarding list/data field prompts that are
explained in the relevant sections. The prompt chars, "-->", can be changed
using the {_PROMTCHARS} tag.

3.3.1.    List Display Lines

By default, lists are displayed within a 24 row screen. However, this is a
function of the ROWS environement variable. List will always be displayed to
maximize screen use based either on the default or the ROWS specified value
(see section on 'Number Of Lines' for more detail).



CopyRight (C) G.R.Gircys/Oesterreich & Assc. 1992,1993                 18



3.3.2.    List/Data Field Parsing

List/Data Field input is parsed as follows:

    + Leading/trailing whitespace is ignored.

    + Input is free form. Almost anything is allowed!

    + The tilde character, '~', is NOT allowed!

    + Input to a pick list must match EXACTLY in chars and case.

Since data field/list input is basically free form, be sure that any scripts
you write do data input verification! Detils provided in relevant sections.

If an <ESC> is entered as a field value, the current field value, if any, is
cleared.



3.4. List Titles

All list are introduced by a title. The default title is:

    - NAG List Manager -

Should this be to mundane, you can set a list's title using the {_LISTTITLE}
builtin Nag tag. For example:

    {LIST}
    {_LISTTITLE} ---Ha, Ha, My Own Title---
    {_SETFIELD} home thelist ....

To set a list title, simple precede and _SETFIELD or _SETRC tag with
_LISTTITLE. The specified title WILL BE centered automatically.




















CopyRight (C) G.R.Gircys/Oesterreich & Assc. 1992,1993                 19



4. MENU DETAILS


This section explains some important and useful Nag menu details. This
includes a listing and introductory explanation of all Nag builtin tags.
Precise usage details for data field/list related Nag builtin tags is
presented in relevant sections.



4.1. Elements Of Style

Nag alone cannot insure that a presentation is successful (in the sense that
support questions are minimized). Nag is simply a tool that helps organize
menu text and actions. Poor organization and sparse help/guidance text can
result in a Nag presentation that confuses the user.

Proper design and help text are essential to a good Nag presentation. The
following elements of style have shown to be very relevant:

1. Be concise. Users don't read instructions; they first try things and then
read instructions if all else fails.

2. Expect users to simply try things; be sure any scripts that act on user
input are ROBUST! and output approriate and USEFUL error messages!
(scripts/error handling described in relevant section).

3. Since users will simply try things first, don't try to documnet complete
help and actions in one menu; create relevant help topics as needed.

4. Carefully select topics that avoid ambiguity and relate to desired
actions. As a rule of thumb, verbs typically make better topics than nouns,
especially if the topic results in some action. Nouns have been shown t work
fine for menu links and index topics.

5. Don't put too much in any single menu! Organize hierarchically using hyper
links.

6. Avoid multipage menus (menus > 24 lines); also avoid using the {_CRPAUSE}.
If a certain explanation requires > 24 lines, consider breaking it up and
using hyper links (if appropriate).

7. Avoid excessive link depths. Though Nag supports up to 32 levels of hyper
link indirection, experience has shown users can tolerate only 3 - 4 levels.

8. All topics should be upper case. Though technically not required, it is
strongely recommended to follow this style!

Like all elements of style, the preceding are subjective and their are cases
where deviation might be appropriate. But in general, observe these
guidelines for an effective Nag presentation.




CopyRight (C) G.R.Gircys/Oesterreich & Assc. 1992,1993                 20





4.2. Debugging A Nag Presentation

While developing a Nag presentation, you will be modifying the Nag script
until it works as desired. You do not have to constantly EXIT and restart Nag
whenever a script is modified. To run a new script, do the following:

    1. Return to the HOME menu

    2. At the prompt, enter 0reload (the word reload preceded by a zero)

The script as defined at invocation is reloaded.

Note that this is a secret command - not meant for use by users. The 0reload
command works only if nag was invoked with the -d, debug, option.



4.3. Comments

Nag menus can contain comments; comments are NOT displayed as part of the
menu.

A comment is any line that begins with a #, the pound sign. The # MUST be the
first character on the line!



4.4. Escapes

Within a Nag menu, the following characters usually must be escaped. All
escapes consist of the backslash, '\', follwed by the desired character.

    ~, tilde - to display a tilde, you must precede it with a backslash

    $, dollar sign - to display a dollar sign, you must precede it with a
    backslash

    \, backslash - to display a backslash, enter \\, double backslash

    # as first character of line - must be escaped by preceding it with a
    backslash

    [ ], square brackets - must be escaped

    { }, curly brackets - must be escaped








CopyRight (C) G.R.Gircys/Oesterreich & Assc. 1992,1993                 21





4.5. Basic Menu Format

A menu begins with a tag; the tag must begin at column 1 of the line. The
following shows a complete menu:

    {AMENU}

    Bunch of text and tags.

    {_END}

ALL menus MUST end with the {_END} Nag builtin tag. Nag does no formatting on
the text other than processing escapes and automatically inserting a pause if
the number of lines is greater than what can be displayed.

4.5.1.    Number Of Lines

By default, Nag works with a 24 row display. The number of rows can be
changed by setting the environment variable ROWS to a value between 18 to 50.

In general, you should limit the number or rows of text in a menu to ROWS - 3
(21 lines for the default display). Menu row 1 is the first line after the
defining tag - the last menu row is the line preceding the {_END} tag - blank
lines count; comment lines do not.

Nag will automatically insert a CR pause prompt every ROWS - 2 lines. Note
that an end case can produce a CR pause followed by only the prompt. You can
overide the default CR pause behaviour by using the {_CRPAUSE} Nag builtin
tag as needed.

4.5.2.    Line Width

Since Nag does no formatting, line width is a function of the Nag menumess
file and whether the displaying terminal does auto wrap.

In general plan on a line width of 80 chars. Though menumess files can be
written beyond this limit, Nag prompt input currently works with a 80 char
wide line.

Support for variable line widths might be a future enhancement.



4.6. Tags/Topics

In writing Nag presentations, several rules must/should be followed regarding
tags/topics.

In general, ALL tags/topics should be uppercase.




CopyRight (C) G.R.Gircys/Oesterreich & Assc. 1992,1993                 22



4.6.1.    Reserved Tags

All Nag builtin (reserved) tags begin with an underscore. You should avoid
defining presentation dependent tags with an underscore.

4.6.2.    Tag Binding

All tags should be bound as described in the 'Binding Tags To Menus' section.



4.7. Home Menu

All Nag presentation must have a home menu. The default home menu tag is
{HOME}. When Nag is started, it will start the display at the HOME menu.

The home menu can be changed by using the invocation option -h TAG (as
described).

Note that specifying a home tag will result in appropriate display
modification (such as the CRPAUSE will mention return to new home).



4.8. Partitioning A Presentation

Multiple Nag menumess files can be used as needed to partition a presentation
into appropriate functional components. The basic technique is described in
the 'Multiple Menumess File Operation' section.



4.9. Exiting A Nag Presentation

To exit a Nag presentation, a user enters EXIT to any menu prompt. EXIT is
NOT case sensitive; and you shouldn't define a label that conflicts.

By default, user if promted to verify exit; to exit without prompt, invoke
Nag with the -x option.



4.10.     Text Alignment Issues

Note that bound tags contain characters that are not displayed. This means
that should you wish to column align tags (as would be desirable for data
fields), you must discount the non-displayed characters while developing the
Nag script.

For example, the following tags would NOT align exactly under the embedded
'V-Clown-data-starts-here' title:




CopyRight (C) G.R.Gircys/Oesterreich & Assc. 1992,1993                 23



    {CLOWNS}
                      V-Clown-data-starts-here.

    {CLOWN[circus][tent]} : ~clown
    {BOZO[circus][tent]}  : ~bozo

Since the tag binding data is not displayed, the colons would actually appear
much further to the left that the simple text anticipated spot. Make
adjustments as needed to properly align text.

Note that the ~clown and ~bozo are the field names; they are not relevant in
alignment and descrbed in detail in the relevant section.

4.10.1.   Data Field Formatting

The following style suggestions has been popular with users. In general,
allocate one line to the field description; allocate the following line to
actually display the field contents. The modified previous example would be
written as follows:

    {CLOWNS}

    {CLOWN[circus][tent]} - The name of any valid clown
    [~clown]

    {BOZO[circus][tent]} - Red or blue haired bozo
    [~bozo]

If the fields were undefined/empty, only the [] would be displayed; when user
entered input, it would be displayed within the square brackets.



4.11.     Don't Use Tabs

Don't use tabs in Nag scripts, and be careful of trailing whitespace in menu
lines.

The preceding two situations don't cause catostrophic problems. However, not
all connection links handle tabs as you would expect, and unseen trailing
whitespace could cause an unexpected line wrap.

In fact, it's useful to run Nag scripts through simple awk/perl script that
eliminates tabs and trailing whitespace. Using perl is probably better; in
the case of the {_PROMPTxxx} tags, you might want to leave trailing space
alone, and perl can easily skip these lines.

Experience has shown over and over again, if you want a flawless/perfect
presentation, avoid tabs and trailing whitespace.






CopyRight (C) G.R.Gircys/Oesterreich & Assc. 1992,1993                 24





4.12.     Help

It is generally recommended that Nag presentations include a global HELP
topic. A sample of such a presentation is included in the examples directory.



4.13.     Builtin Tags

Nag builtin tags perform special functions. This sections lists all of the
builtin tags and their uses. Additional usage and example information on data
field and list related builtins are presented in the relevant section.

All builtin tags begin with an underscore. In the Nag script, all builtins
must be specified at column one of the line. Be carefull to observe builtin
argument format exactly as documented. Arguments are separated by a single
space; extra whitespace can cause problems.

4.13.1.   {_BREAK}

Usage:

    {_BREAK}

Arguments:

    None.

The _BREAK tag is a safety check. You can put it into any menu. When Nag
processes the _BREAK tag, it outputs the following message:

    Type y (or Y) to continue; anything else cancels.

If the response is cancel, Nag displays the calling menu. Otherwise, the
current menu continues. Be sure to take into account the displayed continue
line if need be.

In general, this tag is seldom used, and normally used within menus that
perform some action. If the user decides to go on, you can follow the _BREAK
tag by an _CLEARS tag to clear the screen of the continue message.

4.13.2.   {_CLEARCONTEXT}

This command appears in the source; it is not implmented and currently
impossible to make work given the current Nag logic.

4.13.3.   {_CLEARS}

Usage:

    {_CLEARS}


CopyRight (C) G.R.Gircys/Oesterreich & Assc. 1992,1993                 25



Arguments:

    None.

When Nag processes the _CLEARS tag, it clears the screen. You can use this
tag anywhere as needed though typical Nag screen clearing convention makes
this a seldom used tag.

_CLEARS is useful within menus that perform actions and display output from
scripts. In this case you can arrange for neat presentation by clearing the
screen as needed.

4.13.4.   {_CRPAUSE}

Usage:

    {_CRPAUSE}

Arguments:

    None.

When Nag processes the _CRPAUSE tag, it outputs the following message:

    Type <CR> to continue, or <ESC> to return to %s menu.

The effects of using _CRPAUSE are as follows:

    + Nag automatic line counting is reset; _CRPAUSE takes precedence and
    Nag will now try to output another ROWS number of lines before automatic
    _CRPAUSE

    + To be consistent with automatic _CRPAUSE, you should precede this tag
    with a blank line

    + the %s string is replaced with the name of the home menu (by default
    HOME)

You can use this tag anywhere as needed. However, good style would typically
avoid _CRPAUSE.

4.13.5.   {_END}

Usage:

    {_END}

Arguments:

    None.





CopyRight (C) G.R.Gircys/Oesterreich & Assc. 1992,1993                 26



All menu definitions must end with this tag. Note that _POP doesn't
technically require an _END after it though for future consistency check
tools, ALL menus must end in _END.

4.13.6.   {_ERROR}

Usage:

    {_ERROR} string

Arguments:

    A string that defines an error output from a script run by the {_POPEN}
    tag. One and only one space must separate string from the right curly
    bracket; string is treated in a case sensitive comparison. String MUST
    be specified. If the _ERROR tag is not used, the default string is
    ERROR:

This tag is used only in conjunction with the _POPEN tag. When _ERROR tag
precedes a _POPEN, the default string is replaced with the specified string.
The replacement is NOT global; only for menu specified.

If the script that's run by _POPEN outputs a line that begins with the error
string, Nag will display the message. Addtional details and techniques are
described in the System Commands section.

4.13.7.   {_POP}

Usage:

    {_POP}

Arguments:

    None.

This tag may be used only in conjunction with the _POPEN and _SYSTEM tag. A
menu that implements some action uses either _POPEN or_SYSTEM to run a
script. Very often it's desirable that the user is returned to the calling
menu rather than getting a prompt from the menu where the the script is run.

The following shows a simple nag script that runs the UNIX ls command:

    {FILES}
            Do an {LS}
            A {LONG} listing.
    {_END}


    {LS}
    {_POPEN} ls
    {_CRPAUSE}



CopyRight (C) G.R.Gircys/Oesterreich & Assc. 1992,1993                 27



    {_POP}
    {_END}

When the user enters the LS topic, the LS menu is processed; at that point
the ls command is run and menu is paused. After the user enters a CR, they
return to the calling menu, {FILES} rahter than getting the standard Nag
prompt.

Note that the use of _POP is a style issue; you can develop very nice
presentations without it.













































CopyRight (C) G.R.Gircys/Oesterreich & Assc. 1992,1993                 28



5. SYSTEM COMMANDS


Nag has two builtin tags for running other utilities and scripts. In general,
two types of system commands are supported: interactive and output only.



5.1. Running Interactive Utilities

Run interactive utilities such as editors, mail, more, and other nag sessions
by using the _SYSTEM tag. Be sure that the specified utility is in the PATH
or specify full path.

If you use _SYSTEM to start another nag session (presentation partition), you
would normally specify a home menu and exit without prompt. For example:

    {DOEMAIL}
    {_SYSTEM} nag -h EMAIL -x -m EmailMenus ...
    {_POP}

The -h specifies the home menu in the EmailMenus file; -x says don't prompt
at exit. Note that other others/info might be needed (such as contextdir and
relative/full path for menumess files.

5.1.1.    Security Considerations

Note that many interactive utilities such as editors, more, mail, all support
shell escapes. In many cases it's not appropriate for the user to get a
shell. To prevent users getting shell access, be sure that at login, the
SHELL environment variable is set to something appropriate such as
/bin/false.

Though convievably SHELL could be set to nag, the invocation would result in
nag running with defaults; not a very useful case, and potentially very
confusing to the user. Best not to allow shell access.

5.1.2.    Passing Field/List Data

Arguments to _SYSTEM can include Nag presentation data fields and lists. The
interface/techniques is explained in the section on Lists/Data Fields.



5.2. Output Only Scripts

Output only scripts are launched by the _POPEN tag. In general, the primary
requirement for a Nag script is robustness; it must either do what's expected
or report an error.

Stylewise you can implement scripts that run in verbose mode, always
outputting progress/status information, or you can run scripts that are
silent and output only error messages. It's a matter of preference and


CopyRight (C) G.R.Gircys/Oesterreich & Assc. 1992,1993                 29



application. A system admin nag presentation might output progress
information; system admins like that type of thing. However, user oriented
script should be either silent or output messages that are MEANINGFUL to the
user.

5.2.1.    Error Redirection

Scripts designed for Nag presentation need not redirect stderr to stdout. All
_POPEN run scripts redirect stderr to stdout.

5.2.2.    Silent Script Basics

A silent script will do its thing then return the user to the menu from which
the script was called. A silent script should do the following:

    1. If the script will take some time to run, it might first output a
    "Working...\n" message so the user is not left staring at a blank screen
    too long. This might be considered a standard; put it into all scripts,
    long or short execution time. (Should include \n in the working message
    otherwise might not get displayed immediately.)

    2. If the script encounters an error, it should output an error message
    that begins with a defined error string. The error string is set using
    the _ERROR tag.

Make sure that if {_ERROR} sets a error string, it's defined in the menu that
actually calls the script, and not in the menu from which the script is
called:

    {FILES}

    {DELETE} junk files.

    {_END}
    {DELETE}
    {_ERROR} No files
    {_POPEN} DeleteFiles.sh
    {_POP}
    {_END}
















CopyRight (C) G.R.Gircys/Oesterreich & Assc. 1992,1993                 30



6.DATA FIELDS AND LISTS


Data fields and lists are stored in specially named and formated files. Every
menu can have only once such file, but the file can contain any number of
fields or lists. The filenames are context bound to the menu name.

Data field/list manipulation is a simple 3 step process:

    1. first, define a reference for a field/list in a menu

    2. make sure an appropriately named files exists to hold the contents of
    the field/list

    3. make sure that in the file the field exists (if its not null).

The following shows how to display current time from a menu using a field:

    {TIME}
    {_POPEN} GetTime.sh context.time

    The time is: ~time

    {_END}

In some other menu has a reference to TIME; when the user enters that topic,
the {TIME} menu is displayed. The important points to note are as follows:

    1. The _POPEN system call runs a shell script that places the time in a
    file named context.time. The script puts the time into an appropriate
    format in the file. A simple script as follows would suffice:

    #!/bin/sh

    echo "TIME~`date`" > $1


    2. Note the format: the field in the TIME menu is defined by ~time; in
    the contextfile it's represented by TIME~the time.

That's basically it. Details provided in subsequent sections.



6.1. Field/List File Conventions

All _POPEN script calls MUST follow the convention:

    {_POPEN} Field-List-Script context.filename

Script can be whatever: shell, perl, etc. The format of the context.filename
is as follows:



CopyRight (C) G.R.Gircys/Oesterreich & Assc. 1992,1993                 31



    FIELDNAME~field-data

FIELDNAME is a field reference in a menu; must be uppercase in the file;
lower case in the menu (old history).

6.1.1.    Field Versus List Data

If there is only one FIELDNAME, its a field; if there are more than one
FIELDNAME fields, it's a list.

For example, the following shows a context file of several user login IDs:

    USER~joe
    USER~kitty
    USER~mice

When the ~user field is displayed, it will be appended with (...) indicating
that it's a list. The list can be viewed by using the nag list manager as
described shortly.

Note that if the intended use is a field, it's your scripts responsibility to
make sure only a single instance exists in the context file. Otherwise user
might be confused why (...) is displayed but list manager is not invoked when
the field is to be set.

6.1.2.    Filename

Note that field/list dat file MUST is name bound to the menu where the field
is defined. For example, note the name of the file for the following menu:

    {KITTY[litter][smell]}

    This litter prevents odor for ~weeks weeks.

    {_END}

The context filename for the ~weeks field is context.kitty[litter][smell].



6.2. User Defined List

User defined lists do not present choices for selection, rather they allow
the user to completely define the contents of the list. A user defined list
is exactly the same a a field with one small exception in the SETFIELD tag
arguments. The following shows a user defined list:









CopyRight (C) G.R.Gircys/Oesterreich & Assc. 1992,1993                 32



    {LIST}
    Do the {SPECIAL} list: ~special
    {_END}
    {SPECIAL}
    {_SETFIELD} list special * Enter a thing.
    {_POP}
    {_END}

_SETFIELD arguments descriptions as follows:

list - this is the name of the file that will contain items added by user;
specifically, the file will be named context.list in the context directory.
Note that to items in user defined lists toggle; enter first time to add;
enter again to remove; must enter exactly as the first time.

special - this is the field ID used for the list in the file. In the file,
you can have 0 to any number of SPECIAL~xxxxx entries.

* - means this is a list; not a field

Enter ... - the prompt used in the list manager.

Note that user can enter either SPECIAL to invoke the list manager, or
SPECIAL=something. In the latter case, something is added if not already in
list, else it's removed. If there are multiple SPECIAL fileds in the context
file, the field is displayed with (...) after the first value.

User defined list input is processed by using _POPEN to run and appropriate
script; pass the context file as an argument to the script.



6.3. Pick List

Pick list present a list of objects to choose from. They are setup exactly as
user defined lists and contain a special list file which holds the
selections. The name of the list file is list.xxxxx where xxxxx is the
context.

Prior to list manager invocation, a _POPEN launched script should create a
list.xxxxx file.

What the user selects from the list is stored in the context.xxxxx file. Like
user defined lists, first entry of an object selects it; entering again
deselects.

Note that the list file supports two fields. The optional format of the list
file is:

    FIELDID~selector~description

To select/deselect an item, the user need only enter the selector portion
while enjoying a complete description in the description section.


CopyRight (C) G.R.Gircys/Oesterreich & Assc. 1992,1993                 33



Some topics to add:



Private Functions (hooks.c)

Utilities (c lib and perl scripts to munge nag style files)
















































CopyRight (C) G.R.Gircys/Oesterreich & Assc. 1992,1993                 34



1. NAG...................................................1

    1.1.Why NAG?........................................1

    1.1.1.History..................................1

    1.2.NAG Overview....................................2

    1.2.1.NAG Uses.................................2

    1.3.Covered Topics..................................2

    1.3.1.Caveat...................................3

    1.4.Supported Environments..........................3

    1.5.Nag Support, Suggestions, Etc...................3

2.NAG BASICS ............................................4

    2.1.Getting Started.................................4

    2.1.1.NAG Terminology..........................5

    2.1.2.Summary..................................5

    2.1.3.Caveats..................................6

    2.2.Implementing A NAG Presentation.................6

    2.2.1.NAG Menu Objects.........................6

         2.2.1.1.Binding Tags To Menus.............7

         2.2.1.2.Partioning The Menumess File......9

         2.2.1.3.Data Fields.......................9

         2.2.1.4.List Manager......................9

    2.3.Invocation And Operation Options................10

    2.3.1.
         Locking/Inactivity/Timeout................10

    2.3.2.Debug Mode...............................10

    2.3.3.Context Directory........................11

    2.3.4.Menumess Directory.......................11

    2.3.5.Terminal Setup...........................11



CopyRight (C) G.R.Gircys/Oesterreich & Assc. 1992,1993                 35



         2.3.5.1.Default Mode......................12

         2.3.5.2.Generic Terminal Support..........12

         2.3.5.3.Running In Ansi Mode..............12

         2.3.5.4.Testing For Ansi Mode.............13

    2.3.6.Multiple Menumess File Operation.........13

         2.3.6.1.Exit Without Verify Prompt........14

         2.3.6.2.Specify A Home Page...............14

    2.3.7.Global Data File.........................14

    2.3.8.Check Uid................................15

3.NAG I/O SYSTEM ........................................16

    3.1.Prompt Basics...................................16

    3.2.Menu Prompt.....................................16

    3.2.1.Menu Input Parsing.......................17

         3.2.1.1.The EXIT Command..................18

         3.2.1.2.Special Input.....................18

    3.3.List/Data Field Prompts.........................18

    3.3.1.List Display Lines.......................18

    3.3.2.List/Data Field Parsing..................19

    3.4.List Titles.....................................19

4.MENU DETAILS ..........................................20

    4.1.Elements Of Style...............................20

    4.2.Debugging A Nag Presentation....................21

    4.3.Comments........................................21

    4.4.Escapes.........................................21

    4.5.Basic Menu Format...............................22

    4.5.1.Number Of Lines..........................22

    4.5.2.Line Width...............................22


CopyRight (C) G.R.Gircys/Oesterreich & Assc. 1992,1993                 36



    4.6.Tags/Topics.....................................22

    4.6.1.Reserved Tags............................23

    4.6.2.Tag Binding..............................23

    4.7.Home Menu.......................................23

    4.8.Partitioning A Presentation.....................23

    4.9.Exiting A Nag Presentation......................23

    4.10.Text Alignment Issues..........................23

    4.10.1.Data Field Formatting...................24

    4.11.Don't Use Tabs.................................24

    4.12.Help...........................................25

    4.13.Builtin Tags...................................25

    4.13.1.{_BREAK}................................25

    4.13.2.{_CLEARCONTEXT}.........................25

    4.13.3.{_CLEARS}...............................25

    4.13.4.{_CRPAUSE}..............................26

    4.13.5.{_END}..................................26

    4.13.6.{_ERROR}................................27

    4.13.7.{_POP}..................................27

5.SYSTEM COMMANDS .......................................29

    5.1.Running Interactive Utilities...................29

    5.1.1.Security Considerations..................29

    5.1.2.Passing Field/List Data..................29

    5.2.Output Only Scripts.............................29

    5.2.1.Error Redirection........................30

    5.2.2.Silent Script Basics.....................30

6.DATA FIELDS AND LISTS .................................31

    6.1.Field/List File Conventions.....................31


CopyRight (C) G.R.Gircys/Oesterreich & Assc. 1992,1993                 37



    6.1.1.Field Versus List Data...................32

    6.1.2.Filename.................................32

    6.2.User Defined List...............................32

    6.3.Pick List.......................................33
















































CopyRight (C) G.R.Gircys/Oesterreich & Assc. 1992,1993                 38

