                                  Xnew Modules
                                   2 Mar 1998


                                Table Of Contents

   I.......................................................Introduction
  II.......................................................Compiling
    A......................................................Quick Install
    B......................................................Detailed Install
 III.......................................................Running
  IV.......................................................Module Descriptions
    A......................................................get_backspace
    B......................................................get_editor
    C......................................................get_interrupt
    D......................................................get_kill
    E......................................................get_login
    F......................................................get_name
    G......................................................get_password
    H......................................................get_shell
    I......................................................verify_info
   V.......................................................Writing Modules


I. Introduction

This directory contains modules for use with the xnew program as well as
directions and tools for building your own modules.  Since xnew is in the
early stages of development, not much time has been spent on defining,
documenting, and writing modules and the way they interact with xnew.  Because
of that, you will not find much help here yet for writing your own modules or
explaining how they work in detail.

The modules themselves are in ALPHA testing stage which means they are
incomplete and may contain bugs.  If you want to use these modules in a non-
testing environment, please wait until version 1.0 of xnew is released.


II. Compiling

To compile the modules in this directory, follow these steps:

A. Quick Install

1. Edit Makefile and change the default installation directory if needed.
2. Type make.  You should not get any warnings or errors.
3. Type make install.

B. Detailed Install

1. Unpack all the modules you want to use into the module directory.
2. Edit the Makefile and put all the modules you want to compile in the
   line that says MODS=.  You may need to edit the makefile to add compile
   lines for any modules that are not distributed with xnew.
3. Edit the header files for the modules you want to install and change the
   defaults if you want.  Header files are named the same as the module source
   code file except they end in .h instead of .c.  For example, the header
   file for the get_editor module is get_editor.h.
4. Type make.  You should not get any warnings or errors.
5. Type make install to install the modules into the directory defined in
   the Makefile, (this should be the same as the module directory as defined
   in the config.h file for xnew).


III. Running

Move the compiled modules into the module directory defined by xnew in the
config.h file.  You may then call the modules from an xnew configuration
script, (see the xnew documentation for more details).


IV. Module List

This release of xnew contains the following modules:

get_backspace, get_editor, get_interrupt, get_kill, get_login, get_name,
get_password, get_shell, and verify_info.

The following files contain general functions that many of the modules use:

get_input.c, and mod_func.c.

A description of each of the modules follow.  To learn about the support
functions that the modules use, please see the source code of the supporting
functions, (which is documented heavily), or see Section V of this document.

A. get_backspace

This module prompts the user for their backspace key.  If the key they press
is standard, (^H or ^?), then the module returns that immediately.  If the
key pressed is not one of the two above, then the module requests that the
user press their backspace key again to confirm their selection.  If the key
the user presses at this point is different than the one they pressed before,
the module points that out and starts over again.

In order for the backspace key the user entered be defined in the current
session, a line like "set erase &get_backspace" should follow the
"get_backspace" call in the configuration file for xnew.  Please see the xnew
README for more information about the set command and the configuration file.

B. get_editor

The get_editor module prompts the user for their default editor.  If the
EDITOR_LIST file is defined in get_editor.h, the user's response is checked
for validity.  The EDITOR_LIST file can also be used to map an editor name to
an actual file, (i.e. you want a vi clone like vim to be used if the user
enters vi).  The format of the EDITOR_LIST file is as follows:

<editor> </path/to/editor>

Each definition must be on a seperate line and contain two entries seperated by
spaces or tabs.  Anything else on the line is considered to be a comment and is
ignored.  Comments can also appear as the first entry on a line by prefacing
them with a # character.

The <editor> argument is the name of the editor as displayed to the user.  The
</path/to/editor> argument is the name of the editor including the path leading
to it.  See the file example_editors for an example EDITOR_LIST file.

C. get_interrupt

This module prompts the user for their interrupt key.

D. get_kill

This module prompts the user for their kill key.

E. get_login

The get_login module prompts the user for a login name.  If the user enters
nothing, then the module asks them if they want to quit, (or press ENTER to
enter a login name).  Once a valid name is entered, the module attempts to
determine if it already exists on the system.  First, a password lookup is
made.  Then, if ALIASFILE is defined in get_login.h, a file containing
invalid names, (i.e. /etc/aliases), is parsed.  If the name is found, the
module informs the user and asks them to enter a new login name.

The ALIAS file must have the login names to search for as the first element on
a line.  An element is defined as a word ending in either a space, tab, new
line, or : character.

F. get_name

This module prompts the user for their full name.  If the word "strict" is
passed to the module as an argument, then a user must enter at least two
letters seperated by a space, (a first and last name).

G. get_password

The get_password module prompts the user for a password.  The minimum and
maximum length of the password is configured in get_password.h.  If the user
enters an invalid password, they are prompted to enter a new one.  If the user
enters a valid password, they are asked to enter it again to confirm.  If the
two passwords do not match, the user is warned and the module starts at the
begining.  Passwords are not echoed to the screen.

H. get_shell

The get_shell module prompts the user for their default shell.  If the
SHELL_LIST file is defined in get_shell.h, the user's response is checked
for validity.  The SHELL_LIST file can also be used to map a shell name to
an actual file, (i.e. you want tcsh to be used if the user enters csh).  The
format of the SHELL_LIST file is as follows:

<shell> </path/to/shell>

Each definition must be on a seperate line and contain two entries seperated by
spaces or tabs.  Anything else on the line is considered to be a comment and is
ignored.  Comments can also appear as the first entry on a line by prefacing
them with a # character.

The <shell> argument is the name of the shell as displayed to the user.  The
</path/to/shell> argument is the name of the editor including the path leading
to it.  See the file example_shells for an example SHELL_LIST file.

Keep in mind that many systems require that valid shells be entered into
/etc/shells or similar file.  In this case, you must map the shell to a valid
shell.

I. verify_info

This module displayes the user's responses to many of the questions asked by
other modules and allows the user to change their responses.  This module
needs heavy support from the xnew configuration file to be useful.  It is also
very static right now.  Since it will be changed in the near future to be
more flexable, it is not discussed here.


V. Writing Modules

A module is a normal C program that takes as its first argument the name of a
file to write the data it returns to.  A skeleton module is included as
mod_example.c; if you develop modules, please use this template.  A few
functions are also included to help design modules; they can be found in
get_input.c, (a multi-purpose input routine), and mod_func.c, (various other
functions that may or may not be useful).  Please see the source code for a
detailed description of the support functions.
