1 files changed, 252 insertions, 0 deletions
diff --git a/man/man1/pmquery.1 b/man/man1/pmquery.1
new file mode 100644
index 0000000..9644e84
--- /dev/null
+++ b/man/man1/pmquery.1
@@ -0,0 +1,252 @@
+.TH PMQUERY 1 "" "Performance Co-Pilot"
+.SH NAME
+\f3pmconfirm\f1, \f3pmmessage\f1, \f3pmquery\f1 \- general purpose dialog box
+.SH SYNOPSIS
+\f3pmconfirm\f1
+[\f3\-c\f1]
+[\f3\-b\f1 \f2button-name\f1]
+[\f3\-B\f1 \f2default-button-name\f1]
+[\f3\-t\f1 \f2string\f1]
+[\f3\-file\f1 \f2filename\f1]
+[\f3\-icon\f1 \f2icontype\f1]
+[\f3\-font\f1 \f2font\f1]
+[\f3\-header\f1 \f2titlebar-string\f1]
+[\f3\-useslider\f1]
+[\f3\-noslider\f1]
+[\f3\-noframe\f1]
+[\f3\-exclusive\f1]
+.br
+.PP
+\f3pmmessage\f1
+[\f3\-buttons\f1 \f2label1\f1[:\f2value1\f1][,\f2label2\f1[:\f2value2\f1][,...]]]
+[\f3\-center\f1]
+[\f3\-nearmouse\f1]
+[\f3\-default\f1 \f2button\f1]
+[\f3\-file\f1 \f2filename\f1]
+[\f3\-print\f1]
+[\f3\-timeout\f1 \f2sec\f1]
+.I message...
+.br
+.PP
+\f3pmquery
+[\f3\-input\f1]
+[\f3all above options...\f1]
+[\f2message...\f1]
+.SH DESCRIPTION
+.B pmquery
+provides a command-line-option compatible implementation of the
+.B xconfirm
+and
+.B xmessage
+tools, using a look-and-feel that is consistent with
+.BR pmchart .
+Several extensions to the functionality of the original tools have been made,
+in order to improve their specific utility for
+.BR pmchart ,
+but wherever possible the original semantics remain.
+.PP
+.B pmconfirm
+displays a line of text for each
+.I \-t
+argument specified (or a file when the
+.I \-file
+argument is used),
+and a button for each
+.I \-b
+argument specified.
+When one of the buttons is pressed, the label of that button is written to
+.B pmquery's
+standard output.
+This provides a means of communication/feedback from within shell
+scripts and a means to display useful information to a user from
+an application.
+.PP
+.B pmmessage
+displays a window containing a message from the command line, a file,
+or standard input.
+It additionally allows buttons to be associated with an exit status,
+and only optionally will write the label of the button to standard output.
+.PP
+.B pmquery
+extends the above tools to additionally support limited user input,
+as free form text.
+In this
+.B \-input
+mode, any text entered will be output when the default button is pressed.
+A default text can be entered using the same mechanisms as the other tools.
+.PP
+Command line options are available to specify font style, frame style,
+modality and one of several different icons to be presented for tailored
+visual feedback to the user.
+.TP 5
+.B \-c \f1or \f3\-center\f1
+Center the window on the display.
+.TP
+.B \-nearmouse
+Pop up the window near the mouse cursor.
+.TP
+.B \-b \f2button-name\f1
+Displays a button with the label
+.IR button-name .
+If
+.I button-name
+is the empty string, the button in that position is not displayed.
+If no
+.B \-b
+arguments are present, the default is a button with the label Continue.
+The exit status associated with
+.I button-name
+is zero.
+.TP
+.B \-B \f2button-name\f1
+Displays a button with the label
+.I button-name
+and specifies it as the button to be activated when enter is pressed.
+The exit status associated with
+.I button-name
+is zero.
+.TP
+.B \-buttons \f2button,button,.\|.\|.\f1
+This option will create one button for each comma-separated \f2button\f1
+argument.
+Each \f2button\f1 consists of a label optionally followed by a colon
+and an exit value.
+The exit value will be returned if that button is selected.
+The default exit value is 100 plus the button number.
+Buttons are numbered from the left starting with one.
+.TP
+.B \-default \fIlabel\fP
+Defines the button with a matching \fIlabel\fP to be the default.
+If not specified there is no default.
+The corresponding resource is \fBdefaultButton\fP.
+Pressing Return anywhere in the \fIxmessage\fP window will activate
+the default button.
+The default button has a wider border than the others.
+.TP
+.B \-t \f2message\f1
+Displays message.
+Any number of strings can be listed on the command line
+(each must be preceded with the
+.B \-t
+option).
+.TP
+.B \-file \f2filename\f1
+Displays the file
+.I filename.
+All
+.B \-t
+options will be ignored.
+A \f2filename\f1 of `\f2\-\f1' reads from standard input.
+.TP
+.B \-icon \f2icontype\f1
+Displays the icon
+.I icontype
+where icontype is one of:
+.IR info ,
+.IR error ,
+.IR question ,
+.IR warning ,
+.IR critical .
+.I action
+is also accepted as a synonym for
+.I error
+for backward compatibility.
+.BR pmquery
+introduces the additional
+.I archive
+and
+.I host
+icon types as well as the original 
+.BR xconfirm
+types listed earlier.
+.TP
+.B \-font \f2fontname\f1
+Use fontname as the font.
+This option is only available when using the X Window System.
+.TP
+.B \-header \f2string\f1
+Use string as the window title.
+.TP
+.B \-print
+This causes the program to write the label of the button pressed to
+standard output.
+It is the default behaviour for
+.B pmconfirm
+and
+.BR pmquery .
+.TP
+.B \-noprint
+This causes the program to not write the label of the button pressed to
+standard output.
+It is the default behaviour for
+.BR pmmessage .
+.TP
+.B \-geometry \f2geometry-string\f1
+This provides xconfirm with an X-compatible geometry string specification.
+This option is only available when using the X Window System.
+.TP
+.B \-useslider
+When displaying a file, always use a slider instead of determining
+automatically whether a slider is necessary.
+.TP
+.B \-noslider
+Do not create a slider, and clip text to the window size, instead of
+determining automatically whether a slider is necessary..
+.TP
+.B \-noframe
+Do not display a frame around the contents.
+.TP
+.B \-exclusive
+Grab the keyboard/pointer and do not allow further
+input until a button is pressed.
+.TP
+.B \-timeout \f2secs\f1
+Exit with status 0 after \fIsecs\fP seconds if the user has not
+clicked on a button yet.
+The corresponding resource is \fBtimeout\fP.
+.SH EXAMPLES
+The following shell script will display a window with an information icon,
+asking the user a yes or no question with "Yes" as the default.
+.PP
+.nf
+ #! /bin/sh
+ case `pmquery \-t "Really power down?" \-b No \-B Yes \-icon question
+ in
+   Yes) shutdown;;
+   No) ;;
+ esac
+.fi
+.PP
+A second example, which prompts for a hostname then starts a
+terminal with an ssh session connected to the requested host.
+.PP
+.nf
+ #! /bin/sh
+ host=`pmquery \-input \-icon host \-b Cancel \-B OK \\
+               \-header "Remote Terminal \- Secure Shell"
+ [ "$host" = "Cancel" \-o \-z "$host" ] && exit
+ gnome-terminal \-e "ssh $host"
+.fi
+.SH ENVIRONMENT
+.B pmquery
+is an excellent choice of utility for the "PCP_XCONFIRM_PROG"
+Performance Co-Pilot configuration parameter (refer to
+.BR pcp.conf (4)
+for details).
+.PP
+Note that PCP_XCONFIRM_PROG will be automatically set to
+.B pmquery
+inside tools like
+.BR pmchart ,
+unless PCP_XCONFIRM_PROG is already set in the environment.
+.SH "EXIT STATUS"
+If it detects an error,
+.B pmquery
+always returns 1, so this value should not be associated with a button.
+Unless \f2\-button\f1 option has not been used, the return code will be
+zero on success.
+.SH "SEE ALSO"
+.BR pmchart (1),
+.BR xconfirm (1),
+.BR xmessage (1),
+.BR pcp.conf (4).