xprompt.1

speech signal process tools

.\" Copyright (c) 1986-1990 Entropic Speech, Inc.
.\" Copyright (c) 1991 Entropic Research Laboratory, Inc.; All rights reserved
.\" @(#)xprompt.1	1.9 6/21/91 ESI/ERL
.ds ]W (c) 1991 Entropic Research Laboratory, Inc.
.TH XPROMPT 1\-ESPS 6/21/91
.SH "NAME"
xprompt \- interactive ESPS parameter entry in a pop-up window
.SH "SYNOPSIS"
.B xprompt
[
.BI \-P
.I param_file
] [
.B \-n
] [
.BI \-c
.I checkfile
] [
.BI\-h
.I help_name
] [
.B \-z
] [
.BI \-x
.I debug_level
]
param_out
.SH "DESCRIPTION"
.PP
\fIXprompt\fP is an X Windows program that displays an interactive
form for entering ESPS parameters and produces a new parameter file
(for use in subsequent processing) based on the user's entries.  
For a version that also runs an ESPS program (after prompting 
for parameters), see \fIxpromptrun\fP (1\-\s-1ESPS\s+1).  
.PP
\fIXprompt\fR processes the ESPS parameter file \fIparam_file \fP and
(optionally) ESPS Common.  It then pops up a window containing an
entry for each of the indefinite paramaters in \fIparam_file\fP
(parameters with values assigned using the "?=" operator).  Each such
entry has the name of the parameter and a space for filling in the
desired value.  Default values from the parameter file are filled in
initially.  If a prompt string was included in the parameter file, the
string is displayed above the corresponding parameter entry.
.PP
If the parameter definition in the parameter file includes the
optional set of discrete choices, the window entry for the parameter
contains a set of screen buttons, one for each choice \- the user
selects the parameter value by clicking with the mouse on the desired
choice.  If discrete choices were not provided in the parameter file,
the window entry for the parameter contains space in which the user
can type the desired value.
.PP
Before displaying the interactive window, \fIxprompt\fP creates the
output parameter file \fIparam_out\fP, and fills it with definitions
for all of the parameters in \fIparam_file\fP and ESPS Common 
(if Common is processed).  The initial values in \fIparam_out\fP are
the default values from \fIparam_file\fP, perhaps modified by Common
processing.  
.PP
Whenever the user enters a valid new value for a parameter in the
\fIxprompt\fP window, the output file \fIparam_file\fP is updated.
Note that that data entry requires that a RETURN by typed at the end
of the entry string (See "BUGS"). Input parameters are checked for data type
format.  If limits are provided for numeric parameters in the
parameter file, the limits are checked.
.PP
Two or three screen buttons are provided in a panel at the top of the 
\fIxprompt\fP window.  The button DEFAULTS reverts all parameter
values to the defaults that were in the parameter file (as updated by
Common).  The button DONE causes \fIxprompt\fP to exit.  Use this when
you have finished entering values.  The state of the output parameter
file will correspond to the state of the window when DONE is selected 
(assuming that RETURNs have been typed as appropriate).  
.PP
If the \fB\-h\fP option was used, a HELP button is also provided.
Selecting it causes a help file to be displayed in a text window.  
If the \fIhelp_name\fP specified with \fB\-h\fP has a leading "." or
"/", it is interpreted as the path to a pure ASCII file containing
help information.  If there is no leading "." or "/", \fIhelp_name\fP
is interpreted as the name of an ESPS program for which the parameters
are intended.  In this case, HELP presents a copy of the corresponding
ESPS manual page in a text window.  (To obtain it, \fIeman\fP is run
and the output is stripped of format control strings.)  In both cases,
the text window includes a FIND button to facilitate string searching.
.SH OPTIONS
.PP
The following options are supported:
.TP
.BI \-P " param_file" " \fR[params]\fP"
Specifies the name of the ESPS parameter file to process.  If you want
to force the parameter to come only from ESPS common, use "\fB\-P\fP
/dev/null".  
.TP
.BI \-n 
Do not process ESPS Common (i.e., always get the parameter value from
the file specified by the \fB\-P\fP option).  (Within \fIxprompt\fP, the
effect of \fB\-n\fP is to have \fIread_params\fP (3\-\s-1ESPS\s+1)
called with the SC_NOCOMMON flag.)  Note also that Common processing 
can also be disabled by setting the unix environment variable
USE_ESPS_COMMON to "off".  It is an error to specify both \fB\-n\fP and
\fB\-c\fP.  
.TP
.BI \-c " checkfile"
If the ESPS Common file exists, this option specifies that the Common
file should be processed only if the \fIcheckfile\fP matches the value
of the \fIfilename\fP in the Common file.  This option will have no
effect if the unix environment variable USE_ESPS_COMMON is "off".  It
is an error to specify both \fB\-n\fP and \fB\-c\fP.
.TP
.BI \-h " help_name"
Causes a HELP button to be provided in the \fIxprompt\fP window.
Selecting this button brings up a help file in a text window.  If
\fIhelp_name\fP has a leading "." or "/", it is interpreted as the
path to a pure ASCII file containing help information.  If there is no
leading "." or "/", \fIhelp_name\fP is interpreted as the name of an
ESPS program for which the parameters are intended.  In this case,
HELP presents a copy of the corresponding ESPS manual page in a text
window.  (To obtain it, \fIeman\fP is run and the output is stripped
of format control strings.)  In both cases, the text window includes a
FIND button to facilitate string searching.
.TP
.B \-z
Specifies that \fIxprompt\fP operate silently; conditions such as 
"no parameters" or "no indefinite paramters" are not reported. 
.TP
.BI \-x " debug_level \fR[0]\fP"
If \fIdebug_level\fP is positive,
.I xprompt
outputs debugging messages. The messages proliferate as 
.I debug_level 
increases.  For level 0, there is no output.
.SH "ESPS PARAMETERS"
.PP
The ESPS parameter file specified by the \fB\-P\fP option is processed
only to obtain parameter specifications.  In this respect,
\fIxprompt\fP is quite different from most other ESPS programs, which
use the parameter file to pass parameter values that control the
operation of the program.
.SH ESPS HEADERS
.PP
No ESPS files are processed by \fIxprompt\fP.
.SH ESPS COMMON
.PP
Parameter processing by \fIxprompt\fP follows standard ESPS
conventions: Unless the parameter value is overridden by the value in
ESPS Common, the default value displayed by \fIxprompt\fP is the value
from the parameter file \fIparam_file\fP.  This default value will be
overridden by the value in Common (if the Common file exists and
contains a value for the parameter), provided that ESPS Common
processing is enabled and that the Common file is younger than the
parameter file.  If a \fIcheckfile\fP is specfied by means of the
\fB\-c\fP option, the parameter file value for \fIparam_name\fP will be
overridden by the value in Common only if \fIcheckfile\fP is identical
to the \fIfilename\fP entry in the Common file.
.PP
ESPS Common processing is enabled unless the unix environment variable
USE_ESPS_COMMON is "off" or the \fB\-n\fP is specified.  The default
ESPS Common file is .espscom in the user's home directory.  This may
be overridden by setting the environment variable ESPSCOM to the
desired path.  User feedback from parameter and Common file processing
(by the library \fIread_params\fP and \fIgetsym\fP functions) is
determined by the environment variable ESPS_VERBOSE, with 0 causing no
feedback and increasing levels causing increasingly detailed feedback.
If ESPS_VERBOSE is not defined, a default value of 3 is assumed.
.PP
It is an error to give both \fB\-n\fP and \fB\-c\fP.
.SH EXAMPLES
.PP
\fIXprompt\fP is used to create parameter files interactively, with
the output file intended as the parameter file for some ESPS
processing program.  This is particularly useful in writing shell
scripts.  For example, the sequence 
.nf

	xprompt \-h fft \-P/usr/esps3/lib/Pfft fft.params
	fft \-P fft.params input.sd \- | plotspec \- 

.fi
will display a window in which the user fills in FFT parameters; after
the user clicks on DONE, the fft is performed and the results plotted.
Suppose the following script is called "xparam":
.nf

	#! /bin/sh
	xprompt \-h $1 \-P/usr/esps3/lib/P$1 temp.param
	$1 \-P temp.param $2 $3

Then 

        xparam fft input.sd output.fspec

.fi
will result in the interactive execution of \fIfft\fP
(1\-\s-1ESPS\s+1).  Thus, "xparam" is the X Windows equivalent of
\fIeparam\fP (1\-\s-1ESPS\s+1).  For an alternative, see
\fIxpromptrun\fP (1\-\s-1ESPS\s+1).  
.SH "FUTURE CHANGES"
.PP
\fIxprompt\fP will be modified to test whether or not it is being run
under X Windows; if not, the indefinite parameters will be determined 
by means of prompts using stdin and stdout.  
.SH "SEE ALSO"
.PP
\fIgetparam\fP (1\-\s-1ESPS\s+1), \fIespsenv\fP (1\-\s-1ESPS\s+1),
\fIread_params\fP (3\-\s-1ESPS\s+1), \fIxpromptrun\fP (1\-\s-1ESPS\s+1)
.SH "REFERENCE"
.PP
"Parameter and Common Files in ESPS",  ETM-S-86-12
.SH "BUGS"
.PP
Array parameters (float and int arrays) are not supported yet.  
.PP
Data entry in any numeric or text field does not take effect until a
RETURN is typed; in a later version we will modify the action taken
when "Done" is selected to check and write all fields.
.PP
Vertical and horizontal scrollbars are provided (their use may be
necessary in the case of large parameter files).  Owing to bugs in the
current version of the xview library, however, their behavior is not 
reliable.  For example, joining a split vertical scrollbar can cause 
a core dump.  
.SH "AUTHOR"
.PP
Manual page and code by John Shore.