man page update from current sources (tl-update-man)

git-svn-id: svn://tug.org/texlive/trunk@15745 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 1184 insertions, 154 deletions

diff --git a/Master/texmf/doc/man/man1/tcdialog.1 b/Master/texmf/doc/man/man1/tcdialog.1
index 59ff38ede32..c99e4fbd8ce 100644
--- a/Master/texmf/doc/man/man1/tcdialog.1
+++ b/Master/texmf/doc/man/man1/tcdialog.1
@@ -1,154 +1,973 @@
-.TH DIALOG 1 "10 January 1994"
+'\" t
+.\" $Id: dialog.1,v 1.115 2008/07/27 22:49:40 tom Exp $
+.\" Copyright 2005-2007,2008  Thomas E. Dickey
+.\"
+.\" This program is free software; you can redistribute it and/or modify
+.\" it under the terms of the GNU Lesser General Public License, version 2.1
+.\" as published by the Free Software Foundation.
+.\"
+.\" This program is distributed in the hope that it will be useful, but
+.\" WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+.\" Lesser General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU Lesser General Public
+.\" License along with this program; if not, write to
+.\"	Free Software Foundation, Inc.
+.\"	51 Franklin St., Fifth Floor
+.\"	Boston, MA 02110, USA.
+.de ES
+.ne 8
+.IP
+..
+.de EX
+.RS +10
+.nf
+..
+.de EE
+.fi
+.RE
+..
+.
+.TH DIALOG 1 "" "$Date: 2008/07/27 22:49:40 $"
 .SH NAME
 dialog \- display dialog boxes from shell scripts
 .SH SYNOPSIS
-.B dialog --clear
+\fBdialog --clear\fP
 .br
 .BI "dialog --create-rc " file
 .br
-.B dialog
-[
-.B \-\-title
-.I title
-]
-[
-.B \-\-clear
-]
-.B box-options
+\fBdialog --print-maxsize\fP
+.br
+\fBdialog\fP
+\fIcommon-options\fP
+\fIbox-options\fP
 .SH DESCRIPTION
-.B Dialog
+\fBDialog\fP
 is a program that will let you to present a variety of questions or
-display messages using dialog boxes from a shell script. Currently,
-these types of dialog boxes are implemented: 
+display messages using dialog boxes from a shell script.
+These types of dialog boxes are implemented
+(though not all are necessarily compiled into \fBdialog\fR):
+.RS
 .LP
-.BR yes/no " box," " menu" " box," " input" " box,"
-.BR message " box," " text" " box," " info" " box, and"
-.BR checklist " box."
+.nh
+.na
+.BR calendar ", "
+.BR checklist ", "
+.BR dselect ", "
+.BR editbox ", "
+.BR form ", "
+.BR fselect ", "
+.BR gauge ", "
+.BR infobox ", "
+.BR inputbox ", "
+.BR inputmenu ", "
+.BR menu ", "
+.BR mixedform ", "
+.BR mixedgauge ", "
+.BR msgbox " (message), "
+.BR passwordbox ", "
+.BR passwordform ", "
+.BR pause ", "
+.BR progressbox ", "
+.BR radiolist ", "
+.BR tailbox ", "
+.BR tailboxbg ", "
+.BR textbox ", "
+.BR timebox ", and "
+.BR yesno " (yes/no)."
+.ad
+.hy
+.RE
+.PP
+You can put more than one dialog box into a script:
+.TP 5
+-
+Use the "\fB--and-widget\fP" token to force Dialog to proceed to the next
+dialog unless you have pressed ESC to cancel, or
+.TP 5
+-
+Simply add the tokens for the next dialog box, making a chain.
+Dialog stops chaining when the return code from a dialog is nonzero,
+e.g., Cancel or No (see DIAGNOSTICS).
+.PP
+Some widgets, e.g., checklist, will write text to \fBdialog\fP's output.
+Normally that is the standard error, but there are options for
+changing this: "\fB--output-fd\fP", "\fB--stderr\fP" and "\fB--stdout\fP".
+No text is written if the Cancel button (or ESC) is pressed;
+\fBdialog\fP exits immediately in that case.
+.
+.\" ************************************************************************
 .SH OPTIONS
-.TP
-.B \-\-clear
-The screen will be cleared to the
-.BR "screen attribute" " on exit."
-.TP
-.BI \-\-create-rc " file"
-.RB "Since " dialog " supports run-time configuration,"
+All options begin with "\fB--\fP"
+(two ASCII hyphens,
+for the benefit of those using systems with deranged locale support).
+.PP
+A "\fB--\fP" by itself is used as an escape,
+i.e., the next token on the command-line is not treated as an option.
+.RS
+.B dialog --title -- --Not an option
+.RE
+.PP
+The "\fB--args\fP" option tells \fBdialog\fP to list the command-line
+parameters to the standard error.
+This is useful when debugging complex scripts using
+the "\fB--\fP" and "\fB--file\fP",
+since the command-line may be rewritten as these are expanded.
+.PP
+The "\fB--file\fP" option tells \fBdialog\fP to read parameters from
+the file named as its value.
+.RS
+.B dialog --file \fIparameterfile
+.RE
+Blanks not within double-quotes are discarded
+(use backslashes to quote single characters).
+The result is inserted into the command-line,
+replacing "\fB--file\fP" and its option value.
+Interpretation of the command-line resumes from that point.
+If \fIparameterfile\fP begins with "&", \fBdialog\fP
+interprets the following text as a file descriptor number
+rather than a filename.
+.
+.SS \fBCommon Options\fP
+.
+.IP "\fB--ascii-lines
+Rather than draw graphics lines around boxes,
+draw ASCII "+" and "-" in the same place.
+See also "\fB--no-lines\fR".
+.
+.IP "\fB--aspect \fIratio"
+This gives you some control over the box dimensions when using auto
+sizing (specifying 0 for height and width).
+It represents width / height.
+The default is 9, which means 9 characters wide to every 1 line high.
+.
+.IP "\fB--backtitle \fIbacktitle"
+Specifies a
+\fIbacktitle\fP
+string to be displayed on the backdrop, at the top of the screen.
+.
+.IP "\fB--begin \fIy x"
+Specify the position of the upper left corner of a dialog box on the screen.
+.
+.IP "\fB--cancel-label \fIstring"
+Override the label used for "Cancel" buttons.
+.
+.IP "\fB--clear"
+Clears the widget screen, keeping only the screen_color background.
+Use this when you combine widgets with "\fB--and-widget\fR" to erase the
+contents of a previous widget on the screen, so it won't be seen
+under the contents of a following widget.
+Understand this as the complement of "\fB--keep-window\fR".
+To compare the effects, use these:
+.
+.ES
+All three widgets visible, staircase effect, ordered 1,2,3:
+.EX
+dialog                         --begin 2 2 --yesno "" 0 0 \\
+    --and-widget               --begin 4 4 --yesno "" 0 0 \\
+    --and-widget               --begin 6 6 --yesno "" 0 0
+.EE
+.
+.ES
+Only the last widget is left visible:
+.EX
+dialog           --clear       --begin 2 2 --yesno "" 0 0 \\
+    --and-widget --clear       --begin 4 4 --yesno "" 0 0 \\
+    --and-widget               --begin 6 6 --yesno "" 0 0
+.EE
+.
+.ES
+All three widgets visible, staircase effect, ordered 3,2,1:
+.EX
+dialog           --keep-window --begin 2 2 --yesno "" 0 0 \\
+    --and-widget --keep-window --begin 4 4 --yesno "" 0 0 \\
+    --and-widget               --begin 6 6 --yesno "" 0 0
+.EE
+.
+.ES
+First and third widget visible, staircase effect, ordered 3,1:
+.EX
+dialog           --keep-window --begin 2 2 --yesno "" 0 0 \\
+    --and-widget --clear       --begin 4 4 --yesno "" 0 0 \\
+    --and-widget               --begin 6 6 --yesno "" 0 0
+.EE
+.IP
+Note, if you want to restore original console colors and send your
+cursor home after the dialog program has exited, use the \fBclear\fR\ (1)
+command.
+.
+.IP "\fB--colors"
+Interpret embedded "\\Z" sequences in the dialog text
+by the following character,
+which tells \fBdialog\fP to set colors or video attributes:
+0 through 7 are the ANSI used in curses:
+black,
+red,
+green,
+yellow,
+blue,
+magenta,
+cyan and
+white respectively.
+Bold is set by 'b', reset by 'B'.
+Reverse is set by 'r', reset by 'R'.
+Underline is set by 'u', reset by 'U'.
+The settings are cumulative, e.g., "\\Zb\\Z1" makes the following text
+bold (perhaps bright) red.
+Restore normal settings with "\\Zn".
+.
+.IP "\fB--column-separator \fIstring"
+Tell \fBdialog\fP to split data for radio/checkboxes and menus on the
+occurrences of the given string, and to align the split data into columns.
+.
+.IP "\fB--cr-wrap"
+Interpret embedded newlines in the dialog text as a newline on the screen.
+Otherwise, \fBdialog\fR will only wrap lines where needed to fit inside the text box.
+Even though you can control line breaks with this,
+\fBdialog\fR will still wrap any lines that are too long for the width of the box.
+Without cr-wrap, the layout of your text may be formatted to look nice
+in the source code of your script without affecting the way it will
+look in the dialog.
+.IP
+See also the "\fB--no-collapse\fP" and "\fB--trim\fP" options.
+.
+.IP "\fB--create-rc \fIfile"
+When
+\fBdialog\fP
+supports run-time configuration,
 this can be used to dump a sample configuration file to the file specified
 by
 .IR file "."
-.TP
-.BI \-\-title " title"
+.
+.IP "\fB--defaultno"
+Make the default value of the
+\fByes/no\fP
+box a
+.BR No .
+Likewise, make the default button of widgets that provide "OK" and "Cancel"
+a \fBCancel\fP.
+If "\fB--nocancel\fP" or "\fB--visit-items\fP" are given
+those options overrides this,
+making the default button always "Yes" (internally the same as "OK").
+.
+.IP "\fB--default-item \fIstring"
+Set the default item in a checklist, form or menu box.
+Normally the first item in the box is the default.
+.
+.IP "\fB--exit-label \fIstring"
+Override the label used for "EXIT" buttons.
+.
+.IP "\fB--extra-button"
+Show an extra button, between "OK" and "Cancel" buttons.
+.
+.IP "\fB--extra-label \fIstring"
+Override the label used for "Extra" buttons.
+Note: for inputmenu widgets, this defaults to "Rename".
+.
+.IP "\fB--help"
+Prints the help message to \fBdialog\fP's output.
+The help message is printed if no options are given.
+.
+.IP "\fB--help-button"
+Show a help-button after "OK" and "Cancel" buttons,
+i.e., in checklist, radiolist and menu boxes.
+If "\fB--item-help\fR" is also given, on exit
+the return status will be the same as for the "OK" button,
+and the item-help text will be written to \fBdialog\fP's output after the token "HELP".
+Otherwise, the return status will indicate that the Help button was pressed,
+and no message printed.
+.
+.IP "\fB--help-label \fIstring"
+Override the label used for "Help" buttons.
+.
+.IP "\fB--help-status"
+If the help-button is selected,
+writes the checklist, radiolist or form information
+after the item-help "HELP" information.
+This can be used to reconstruct the state of a checklist after processing
+the help request.
+.
+.IP "\fB--ignore"
+Ignore options that \fBdialog\fP does not recognize.
+Some well-known ones such as "\fB--icon\fP" are ignored anyway,
+but this is a better choice for compatibility with other implementations.
+.
+.IP "\fB--input-fd \fIfd"
+Read keyboard input from the given file descriptor.
+Most \fBdialog\fR scripts read from the standard input,
+but the gauge widget reads a pipe (which is always standard input).
+Some configurations do not work properly when
+\fBdialog\fP tries to reopen the terminal.
+Use this option (with appropriate juggling of file-descriptors)
+if your script must work in that type of environment.
+.
+.IP "\fB--insecure"
+Makes the password widget friendlier but less secure,
+by echoing asterisks for each character.
+.
+.IP "\fB--item-help"
+Interpret the tags data for checklist, radiolist and menu boxes
+adding a column which is displayed in the bottom line of the
+screen, for the currently selected item.
+.
+.IP "\fB--keep-tite"
+Normally \fBdialog\fP checks to see if it is running in an \fBxterm\fP,
+and in that case tries to suppress the initialization strings that
+would make it switch to the alternate screen.
+Switching between the normal and alternate screens
+is visually distracting in a script which runs \fBdialog\fP
+several times.
+Use this option to allow \fBdialog\fP to use those initialization strings. 
+.
+.IP "\fB--keep-window"
+Normally when \fBdialog\fR performs several \fBtailboxbg\fR widgets
+connected by "\fB--and-widget\fR",
+it clears the old widget from the screen by painting over it.
+Use this option to suppress that repainting.
+.IP
+At exit, \fBdialog\fR repaints all of the widgets which have been
+marked with "\fB--keep-window\fR", even if they are not \fBtailboxbg\fR widgets.
+That causes them to be repainted in reverse order.
+See the discussion of the "\fB--clear\fR" option for examples.
+.
+.IP "\fB--max-input \fIsize"
+Limit input strings to the given size.
+If not specified, the limit is 2048.
+.
+.IP "\fB--no-cancel"
+.IP "\fB--nocancel"
+Suppress the "Cancel" button in checklist, inputbox and menu box modes.
+A script can still test if the user pressed the ESC key to cancel to quit.
+.
+.IP "\fB--no-collapse"
+Normally \fBdialog\fR converts tabs to spaces and reduces multiple
+spaces to a single space for text which is displayed in a message boxes, etc.
+Use this option to disable that feature.
+Note that \fBdialog\fR will still wrap text,
+subject to the "\fB--cr-wrap\fR" and "\fB--trim\fR" options.
+.
+.IP "\fB--no-kill"
+Tells
+\fBdialog\fP
+to put the
+\fBtailboxbg\fP
+box in the background,
+printing its process id to \fBdialog\fP's output.
+SIGHUP is disabled for the background process.
+.
+.IP "\fB--no-label \fIstring"
+Override the label used for "No" buttons.
+.
+.IP "\fB--no-lines
+Rather than draw lines around boxes, draw spaces in the same place.
+See also "\fB--ascii-lines\fR".
+.
+.IP "\fB--no-ok"
+.IP "\fB--nook"
+Suppress the "OK" button in checklist, inputbox and menu box modes.
+A script can still test if the user pressed the "Enter" key to accept the data.
+.
+.
+.IP "\fB--no-shadow"
+Suppress shadows that would be drawn to the right and bottom of each dialog box.
+.
+.IP "\fB--ok-label \fIstring"
+Override the label used for "OK" buttons.
+.
+.IP "\fB--output-fd \fIfd"
+Direct output to the given file descriptor.
+Most \fBdialog\fR scripts write to the standard error,
+but error messages may also be written there, depending on your script.
+.
+.IP "\fB--separator \fIstring"
+.IP "\fB--output-separator\fIstring"
+Specify a string that will separate the output on \fBdialog\fP's output from
+checklists, rather than a newline (for --separate-output) or a space.
+This applies to other widgets such as forms and editboxes which normally
+use a newline.
+.
+.IP "\fB--print-maxsize"
+Print the maximum size of dialog boxes, i.e., the screen size,
+to \fBdialog\fP's output.
+This may be used alone, without other options.
+.
+.IP "\fB--print-size"
+Prints the size of each dialog box to \fBdialog\fP's output.
+.
+.IP "\fB--print-version"
+Prints \fBdialog\fR's version to \fBdialog\fP's output.
+This may be used alone, without other options.
+.
+.IP "\fB--separate-output"
+For checklist widgets, output result one line at a time, with no quoting.
+This facilitates parsing by another program.
+.
+.IP "\fB--separate-widget \fIstring"
+Specify a string that will separate the output on \fBdialog\fP's output from
+each widget.
+This is used to simplify parsing the result of a dialog with several widgets.
+If this option is not given,
+the default separator string is a tab character.
+.
+.IP "\fB--shadow"
+Draw a shadow to the right and bottom of each dialog box.
+.
+.IP "\fB--single-quoted"
+Use single-quoting as needed (and no quotes if unneeded) for the
+output of checklist's as well as the item-help text.
+If this option is not set, \fBdialog\fP uses double quotes around each item.
+That requires occasional use of backslashes to make the output useful in
+shell scripts.
+.
+.IP "\fB--size-err"
+Check the resulting size of a dialog box before trying to use it,
+printing the resulting size if it is larger than the screen.
+(This option is obsolete, since all new-window calls are checked).
+.
+.IP "\fB--sleep \fIsecs"
+Sleep (delay) for the given number of seconds after processing a dialog box.
+.
+.IP "\fB--stderr"
+Direct output to the standard error.
+This is the default, since curses normally writes screen updates to
+the standard output.
+.
+.IP "\fB--stdout"
+Direct output to the standard output.
+This option is provided for compatibility with Xdialog,
+however using it in portable scripts is not recommended,
+since curses normally writes its screen updates to the standard output.
+If you use this option, \fBdialog\fR attempts to reopen the terminal
+so it can write to the display.
+Depending on the platform and your environment, that may fail.
+.
+.IP "\fB--tab-correct"
+Convert each tab character to one or more spaces
+(for the \fBtextbox\fP widget; otherwise to a single space).
+Otherwise, tabs are rendered according to the curses library's interpretation.
+.
+.IP "\fB--tab-len \fIn"
+Specify the number of spaces that a tab character occupies if the
+"\fB--tab-correct\fP" option is given.
+The default is 8.
+This option is only effective for the \fBtextbox\fP widget.
+.
+.IP "\fB--timeout \fIsecs"
+Timeout (exit with error code)
+if no user response within the given number of seconds.
+This is overridden if the background "\fB--tailboxbg\fP is used.
+A timeout of zero seconds is ignored.
+.
+.IP "\fB--title \fItitle"
 Specifies a
-.I title
+\fItitle\fP
 string to be displayed at the top of the dialog box.
-.TP
-.B Box Options
-.TP
-.BI \-\-yesno " text height width"
-.RB A " yes/no" " dialog box of size"
-.I height
-rows by
-.I width
-columns will be displayed. The string specified by
-.I text
-is displayed inside the dialog box. If this string is too long to be fitted
-in one line, it will be automatically divided into multiple lines at
-appropriate places. The
-.I text
-string may also contain the sub-string
-.I
-"\en"
-or newline characters
-.I `\en\'
-to control line breaking explicitly.  This dialog box is useful for
-asking questions that require the user to answer either yes or no.
-.RB "The dialog box has a" " Yes" " button and a " No
-button, in which the user can switch between by pressing the
-.IR TAB " key."
-.TP
-.BI \-\-msgbox " text height width"
-.RB A " message" " box is very similar to a" " yes/no" " box."
-The only difference between a
-.B message
-box and a
-.B yes/no
-box is that a
-.B message
-box has only a single
-.B OK
-button. You can use this dialog box to display any message you like.
-After reading the message, the user can press the
-.I ENTER
-key so that
-.B dialog
-will exit and the calling shell script can continue its operation.
-.TP
-.BI \-\-infobox " text height width"
-.RB An " info" " box is basically a" " message" " box."
-However, in this case,
-.B dialog
-will exit immediately after displaying the message to the user. The
-screen is not cleared when
-.B dialog
+.
+.IP "\fB--trace \fIfilename"
+logs keystrokes to the given file.
+Use control/T to log a picture of the current dialog window.
+.
+.IP "\fB--trim"
+eliminate leading blanks,
+trim literal newlines and repeated blanks from message text.
+.
+.IP
+See also the "\fB--cr-wrap\fR" and "\fB--no-collapse\fR" options.
+.
+.IP "\fB--version"
+Same as "\fB--print-version\fP".
+.
+.IP "\fB--visit-items"
+Modify the tab-traversal of checklist, radiobox, menubox and inputmenu
+to include the list of items as one of the states.
+This is useful as a visual aid,
+i.e., the cursor position helps some users.
+.IP
+When this option is given, the cursor is initially placed on the list.
+Abbreviations (the first letter of the tag) apply to the list items.
+If you tab to the button row, abbreviations apply to the buttons.
+.
+.IP "\fB--yes-label \fIstring"
+Override the label used for "Yes" buttons.
+.
+.\" ************************************************************************
+.SS Box Options
+All dialog boxes have at least three parameters:
+.TP 5
+\fItext\fP
+the caption or contents of the box.
+.TP 5
+\fIheight\fP
+the height of the dialog box.
+.TP 5
+\fIwidth\fP
+the width of the dialog box.
+.PP
+Other parameters depend on the box type.
+.
+.
+.IP "\fB--calendar \fItext height width day month year"
+A \fBcalendar\fP box displays
+month, day and year in separately adjustable windows.
+If the values for day, month or year are missing or negative,
+the current date's corresponding values are used.
+You can increment or decrement any of those using the
+left-, up-, right- and down-arrows.
+Use vi-style h, j, k and l for moving around the array of days in a month.
+Use tab or backtab to move between windows.
+If the year is given as zero, the current date is used as an initial value.
+.IP
+On exit, the date is printed in the form day/month/year.
+.
+.
+.IP "\fB--checklist \fItext height width list-height \fR[ \fItag item status \fR] \fI..."
+A
+\fBchecklist\fP
+box is similar to a
+\fBmenu\fP
+box; there are
+multiple entries presented in the form of a menu.
+Instead of choosing
+one entry among the entries, each entry can be turned on or off by the user.
+The initial on/off state of each entry is specified by
+.IR status "."
+.IP
+On exit, a list of the \fItag\fP
+strings of those entries that are turned on
+will be printed on \fBdialog\fP's output.
+If the "\fB--separate-output\fP" option is not given,
+the strings will be quoted to make it simple for scripts to separate them.
+See the "\fB--single-quoted\fP" option, which modifies the quoting behavior.
+.
+.
+.IP "\fB--dselect \fIfilepath height width\fR"
+The directory-selection dialog displays a text-entry window in which you can type
+a directory, and above that a windows with directory names.
+.IP
+Here
+\fBfilepath\fP
+can be a filepath in which case the directory window
+will display the contents of the path and the text-entry window will contain
+the preselected directory.
+.IP
+Use tab or arrow keys to move between the windows.
+Within the directory window, use the up/down arrow keys
+to scroll the current selection.
+Use the space-bar to copy the current selection into the text-entry
+window.
+.IP
+Typing any printable characters switches focus to the text-entry window,
+entering that character as well as scrolling the directory
+window to the closest match.
+.IP
+Use a carriage return or the "OK" button to accept the current value
+in the text-entry window and exit.
+.IP
+On exit, the contents of the text-entry window are written to \fBdialog\fP's output.
+.
+.IP "\fB--editbox \fIfilepath height width\fR"
+The edit-box dialog displays a copy of the file.
+You may edit it using 
+the \fIbackspace\fP, \fIdelete\fP and cursor keys
+to correct typing errors.
+It also recognizes pageup/pagedown.
+Unlike the \fB--inputbox\fP,
+you must tab to the "OK" or "Cancel" buttons to close the dialog.
+Pressing the "Enter" key within the box will split the corresponding line.
+.IP
+On exit, the contents of the edit window are written to \fBdialog\fP's output.
+.
+.nf
+.IP "\fB--form \fItext height width formheight \fR[ \fIlabel y x item y x flen ilen \fR] \fI..."
+.fi
+The \fBform\fP dialog displays a form consisting of labels and fields,
+which are positioned on a scrollable window by coordinates given in the script.
+The field length \fIflen\fR and input-length \fIilen\fR tell how long
+the field can be.
+The former defines the length shown for a selected field,
+while the latter defines the permissible length of the data entered in the
+field.
+.RS
+.TP 3
+-
+If \fIflen\fR is zero, the corresponding field cannot be altered.
+and the contents of the field determine the displayed-length.
+.TP 3
+-
+If \fIflen\fR is negative, the corresponding field cannot be altered,
+and the negated value of \fIflen\fR is used as the displayed-length.
+.TP 3
+-
+If \fIilen\fR is zero, it is set to \fIflen\fR.
+.RE
+.IP
+Use up/down arrows (or control/N, control/P) to move between fields.
+Use tab to move between windows.
+.IP
+On exit, the contents of the form-fields are written to \fBdialog\fP's output,
+each field separated by a newline.
+The text used to fill non-editable fields
+(\fIflen\fR is zero or negative)
+is not written out.
+.
+.
+.IP "\fB--fselect \fIfilepath height width\fR"
+The \fBfselect\fP (file-selection) dialog displays a text-entry window in which you can type
+a filename (or directory), and above that two windows with directory
+names and filenames.
+.IP
+Here
+\fBfilepath\fP
+can be a filepath in which case the file and directory windows
+will display the contents of the path and the text-entry window will contain
+the preselected filename.
+.IP
+Use tab or arrow keys to move between the windows.
+Within the directory or filename windows, use the up/down arrow keys
+to scroll the current selection.
+Use the space-bar to copy the current selection into the text-entry
+window.
+.IP
+Typing any printable characters switches focus to the text-entry window,
+entering that character as well as scrolling the directory and filename
+windows to the closest match.
+.IP
+Typing the space character forces \fBdialog\fP to complete the current
+name (up to the point where there may be a match against more than one
+entry).
+.IP
+Use a carriage return or the "OK" button to accept the current value
+in the text-entry window and exit.
+.IP
+On exit, the contents of the text-entry window are written to \fBdialog\fP's output.
+.
+.
+.IP "\fB--gauge \fItext height width [percent]\fR"
+A
+\fBgauge\fP
+box displays a meter along the bottom of the box.
+The meter indicates the percentage.
+New percentages are read from
+standard input, one integer per line.
+The meter is updated
+to reflect each new percentage.
+If the standard input reads the string "XXX",
+then the first line following is taken as an integer percentage,
+then subsequent lines up to another "XXX" are used for a new prompt.
+The gauge exits when EOF is reached on the standard input.
+.IP
+The \fIpercent\fR value denotes the initial percentage shown in the meter.
+If not specified, it is zero.
+.IP
+On exit, no text is written to \fBdialog\fP's output.
+The widget accepts no input, so the exit status is always OK.
+.
+.
+.IP "\fB--infobox \fItext height width"
+An \fBinfo\fP box is basically a \fBmessage\fP box.
+However, in this case, \fBdialog\fP
+will exit immediately after displaying the message to the user.
+The screen is not cleared when \fBdialog\fP
 exits, so that the message will remain on the screen until the calling
-shell script clears it later. This is useful when you want to inform
+shell script clears it later.
+This is useful when you want to inform
 the user that some operations are carrying on that may require some
 time to finish.
+.IP
+On exit, no text is written to \fBdialog\fP's output.
+Only an "OK" button is provided for input,
+but an ESC exit status may be returned.
+.
+.
+.IP "\fB--inputbox \fItext height width [init]"
+An
+\fBinput\fP
+box is useful when you want to ask questions that
+require the user to input a string as the answer.
+If init is supplied
+it is used to initialize the input string.
+When entering the string,
+the \fIbackspace\fP, \fIdelete\fP and cursor keys
+can be used to correct typing errors.
+If the input string is longer than
+can fit in the dialog box, the input field will be scrolled.
+.IP
+On exit, the input string will be printed on \fBdialog\fP's output.
+.
+.
+.IP "\fB--inputmenu \fItext height width menu-height \fR[ \fItag item \fR] \fI..."
+An \fBinputmenu\fP box is very similar to an ordinary \fBmenu\fP box.
+There are only a few differences between them:
+.RS
+.TP 4
+1.
+The entries are not automatically centered but left adjusted.
 .TP
-.BI \-\-inputbox " text height width"
-.RB "An " input " box is useful when you want to ask questions that"
-require the user to input a string as the answer. When inputing the
-string, the
-.I BACKSPACE
-key can be used to correct typing errors. If the input string is longer than
-can be fitted in the dialog box, the input field will be scrolled. On exit,
-the input string will be printed on
-.IR stderr "."
+2.
+An extra button (called \fIRename\fP) is implied to rename
+the current item when it is pressed.
 .TP
-.BI \-\-textbox " file height width"
-.RB A " text" " box lets you display the contents of a text file in a"
-dialog box. It is like a simple text file viewer. The user can move
-through the file by using the
-.IR UP/DOWN ", " PGUP/PGDN
-.RI and " HOME/END" " keys available on most keyboards."
-If the lines are too long to be displayed in the box, the
-.I LEFT/RIGHT
-keys can be used to scroll the text region horizontally. For more
-convenience, forward and backward searching functions are also provided.
-.IP "\fB\-\-menu \fItext height width menu-height \fR[ \fItag item \fR] \fI..."
+3.
+It is possible to rename the current entry by pressing the
+\fIRename\fP
+button.
+Then \fBdialog\fP will write the following on \fBdialog\fP's output.
+.IP
+RENAMED <tag> <item>
+.RE
+.
+.
+.IP "\fB--menu \fItext height width menu-height \fR[ \fItag item \fR] \fI..."
 As its name suggests, a
-.B menu
+\fBmenu\fP
 box is a dialog box that can be used to present a list of choices in
-the form of a menu for the user to choose. Each menu entry consists of a
-.IR tag " string and an " item " string. The"
-.I tag
+the form of a menu for the user to choose.
+Choices are displayed in the order given.
+Each menu entry consists of a \fItag\fP string and an \fIitem\fP string.
+The \fItag\fP
 gives the entry a name to distinguish it from the other entries in the
-menu. The
-.I item
-is a short description of the option that the entry represents. The
-user can move between the menu entries by pressing the
-.I UP/DOWN
-keys, the first letter of the
-.I tag
+menu.
+The \fIitem\fP is a short description of the option that the entry represents.
+The user can move between the menu entries by pressing the
+cursor keys, the first letter of the \fItag\fP
 as a hot-key, or the number keys
 .IR 1-9 ". There are"
-.I menu-height
+\fImenu-height\fP
 entries displayed in the menu at one time, but the menu will be
-scrolled if there are more entries than that. When
-.B dialog
-exits, the
-.I tag
-of the chosen menu entry will be printed on
-.IR stderr "."
-.IP "\fB\-\-checklist \fItext height width list-height \fR[ \fItag item status \fR] \fI..."
-.RB "A " checklist " box is similar to a " menu " box in that there are"
-multiple entries presented in the form of a menu. Instead of choosing
-one entry among the entries, each entry can be turned on or off by the
-user. The initial on/off state of each entry is specified by
-.IR status "."
-On exit, a list of the
-.I tag
-strings of those entries that are turned on will be printed on
-.IR stderr "."
+scrolled if there are more entries than that.
+.IP
+On exit the \fItag\fP
+of the chosen menu entry will be printed on \fBdialog\fP's output.
+If the "\fB--help-button\fR" option is given, the corresponding help
+text will be printed if the user selects the help button.
+.
+.nf
+.IP "\fB--mixedform \fItext height width formheight \fR[ \fIlabel y x item y x flen ilen itype \fR] \fI..."
+.fi
+The \fBmixedform\fP dialog displays a form consisting of labels and fields,
+much like the \fB--form\fP dialog.
+It differs by adding a field-type parameter to each field's description.
+Each bit in the type denotes an attribute of the field:
+.RS
+.TP 5
+1
+hidden, e.g., a password field.
+.TP 5
+2
+readonly, e.g., a label.
+.RE
+.
+.IP "\fB--mixedgauge \fItext height width percent \fR[ \fItag1 item1 \fR] \fI..."
+A
+\fBmixedgauge\fP
+box displays a meter along the bottom of the box.
+The meter indicates the percentage.
+.IP
+It also displays a list of the \fItag\fP- and \fIitem\fP-values at the
+top of the box.
+See dialog(3) for the tag values.
+.IP
+The \fItext\fP is shown as a caption between the list and meter.
+The \fIpercent\fR value denotes the initial percentage shown in the meter.
+.IP
+No provision is made for reading data from the standard input as \fB--gauge\fP
+does.
+.IP
+On exit, no text is written to \fBdialog\fP's output.
+The widget accepts no input, so the exit status is always OK.
+.
+.IP "\fB--msgbox \fItext height width"
+A \fBmessage\fP box is very similar to a \fByes/no\fP box.
+The only difference between a \fBmessage\fP box and a \fByes/no\fP
+box is that a \fBmessage\fP box has only a single \fBOK\fP button.
+You can use this dialog box to display any message you like.
+After reading the message, the user can press the \fIENTER\fP key so that
+\fBdialog\fP will exit and the calling shell script can continue its operation.
+.IP
+If the message is too large for the space,
+\fBdialog\fP may allow you to scroll it,
+provided that the underlying curses implementation is capable enough.
+In this case, a percentage is shown in the base of the widget.
+.IP
+On exit, no text is written to \fBdialog\fP's output.
+Only an "OK" button is provided for input,
+but an ESC exit status may be returned.
+.
+.IP "\fB\-\-pause \fItext height width seconds\fR"
+A
+\fBpause\fP
+box displays a meter along the bottom of the box.
+The meter indicates how many seconds remain until the end of the pause.
+The pause exits when timeout is reached
+or the user presses the OK button
+(status OK)
+or the user presses the CANCEL button
+or Esc key.
+.IP "\fB--passwordbox \fItext height width [init]"
+A \fBpassword\fP box is similar to an input box,
+except that the text the user enters is not displayed.
+This is useful when prompting for passwords or other
+sensitive information.
+Be aware that if anything is passed in "init", it
+will be visible in the system's process table to casual snoopers.
+Also, it
+is very confusing to the user to provide them with a default password they
+cannot see.
+For these reasons, using "init" is highly discouraged.
+See "\fB--insecure\fP" if you do not care about your password.
+.IP
+On exit, the input string will be printed on \fBdialog\fP's output.
+.
+.
+.nf
+.IP "\fB--passwordform \fItext height width formheight \fR[ \fIlabel y x item y x flen ilen \fR] \fI..."
+.fi
+This is identical to \fB--form\fP except that all text fields are
+treated as \fBpassword\fP widgets rather than \fBinputbox\fP widgets.
+.
+.
+.IP "\fB--progressbox \fItext height width"
+.IP "\fB--progressbox \fIheight width"
+A \fBprogressbox\fP is similar to an \fBtailbox\fP,
+except that it will exit when it reaches the end of the file.
+If three parameters are given, it displays the text under the title,
+delineated from the scrolling file's contents.
+If only two parameters are given, this text is omitted.
+.
+.
+.IP "\fB--radiolist \fItext height width list-height \fR [ \fItag item status \fR] \fI..."
+A
+\fBradiolist\fP
+box is similar to a
+\fBmenu\fP
+box.
+The only difference is
+that you can indicate which entry is currently selected, by setting its
+.IR status " to " on "."
+.IP
+On exit, the name of the selected item is written to \fBdialog\fP's output.
+.
+.
+.IP "\fB--tailbox \fIfile height width"
+Display text from a file in a dialog box, as in a "tail -f" command.
+Scroll left/right using vi-style 'h' and 'l', or arrow-keys.
+A '0' resets the scrolling.
+.IP
+On exit, no text is written to \fBdialog\fP's output.
+Only an "OK" button is provided for input,
+but an ESC exit status may be returned.
+.
+.
+.IP "\fB--tailboxbg \fIfile height width"
+Display text from a file in a dialog box as a background task,
+as in a "tail -f &" command.
+Scroll left/right using vi-style 'h' and 'l', or arrow-keys.
+A '0' resets the scrolling.
+.IP
+Dialog treats the background task specially if there are other
+widgets (\fB--and-widget\fP) on the screen concurrently.
+Until those widgets are closed (e.g., an "OK"),
+\fBdialog\fP will perform all of the tailboxbg widgets in the same process,
+polling for updates.
+You may use a tab to traverse between the widgets on the screen,
+and close them individually, e.g., by pressing \fIENTER\fP.
+Once the non-tailboxbg widgets are closed, \fBdialog\fP forks a copy of itself
+into the background, and prints its process id if the "\fB--no-kill\fP" option
+is given.
+.IP
+On exit, no text is written to \fBdialog\fP's output.
+Only an "EXIT" button is provided for input,
+but an ESC exit status may be returned.
+.IP
+NOTE:
+Older versions of \fBdialog\fP forked immediately and attempted to
+update the screen individually.
+Besides being bad for performance,
+it was unworkable.
+Some older scripts may not work properly with the polled scheme.
+.
+.
+.IP "\fB--textbox \fIfile height width"
+A
+\fBtext\fP
+box lets you display the contents of a text file in a dialog box.
+It is like a simple text file viewer.
+The user can move through the file by using the
+cursor, page-up, page-down
+and \fIHOME/END\fR keys available on most keyboards.
+If the lines are too long to be displayed in the box,
+the \fILEFT/RIGHT\fP
+keys can be used to scroll the text region horizontally.
+You may also use vi-style keys h, j, k, l in place of the cursor keys,
+and B or N in place of the page-up and page-down keys.
+Scroll up/down using vi-style 'k' and 'j', or arrow-keys.
+Scroll left/right using vi-style 'h' and 'l', or arrow-keys.
+A '0' resets the left/right scrolling.
+For more convenience,
+vi-style forward and backward searching functions are also provided.
+.IP
+On exit, no text is written to \fBdialog\fP's output.
+Only an "EXIT" button is provided for input,
+but an ESC exit status may be returned.
+.
+.
+.IP "\fB--timebox \fItext height [width hour minute second]"
+A dialog is displayed which allows you to select hour, minute and second.
+If the values for hour, minute or second are missing or negative,
+the current date's corresponding values are used.
+You can increment or decrement any of those using the
+left-, up-, right- and down-arrows.
+Use tab or backtab to move between windows.
+.IP
+On exit, the result is printed in the form hour:minute:second.
+.
+.
+.IP "\fB--yesno \fItext height width"
+A \fByes/no\fP dialog box of
+size \fIheight\fP rows by \fIwidth\fP columns will be displayed.
+The string specified by
+\fItext\fP
+is displayed inside the dialog box.
+If this string is too long to fit
+in one line, it will be automatically divided into multiple lines at
+appropriate places.
+The
+\fItext\fP
+string can also contain the sub-string
+.I
+"\en"
+or newline characters
+\fI`\en'\fP
+to control line breaking explicitly.
+This dialog box is useful for
+asking questions that require the user to answer either yes or no.
+The dialog box has a
+\fBYes\fP
+button and a
+\fBNo\fP
+button, in which the user can switch between by pressing the
+.IR TAB " key."
+.IP
+On exit, no text is written to \fBdialog\fP's output.
+In addition to the "Yes" and "No" exit codes (see DIAGNOSTICS)
+an ESC exit status may be returned.
+.IP
+The codes used for "Yes" and "No" match those used for "OK" and "Cancel",
+internally no distinction is made.
+.
+.\" ************************************************************************
+.SS "Obsolete Options"
+.\" from cdialog 0.9a (Pako)
+.IP "\fB--beep"
+This was used to tell the original cdialog that it should make a beep
+when the separate processes of the tailboxbg widget would repaint the screen.
+.
+.\" from cdialog 0.9a (Pako)
+.IP "\fB--beep-after"
+Beep after a user has completed a widget by pressing one of the buttons.
+.
+.\" ************************************************************************
 .SH "RUN-TIME CONFIGURATION"
 .TP 4
 1.
@@ -159,59 +978,270 @@ Create a sample configuration file by typing:
 .TP 4
 2.
 At start,
-.B dialog
+\fBdialog\fP
 determines the settings to use as follows:
 .RS
 .TP 4
 a)
 if environment variable
-.B DIALOGRC
-is set, it's value determines the name of the configuration file.
+\fBDIALOGRC\fP
+is set, its value determines the name of the configuration file.
 .TP 4
 b)
-if the file in (a) can't be found, use the file
-.I $HOME/.dialogrc
+if the file in (a) is not found, use the file
+\fI$HOME/.dialogrc\fP
 as the configuration file.
 .TP 4
 c)
-if the file in (b) can't be found, use compiled in defaults.
+if the file in (b) is not found, try using the GLOBALRC file determined at
+compile-time, i.e., \fI/etc/dialogrc\fP.
+.TP 4
+d)
+if the file in (c) is not found, use compiled in defaults.
 .RE
 .TP 4
 3.
 Edit the sample configuration file and copy it to some place that
-.B dialog
+\fBdialog\fP
 can find, as stated in step 2 above.
+.
+.\" ************************************************************************
+.SH "KEY BINDINGS"
+You can override or add to key bindings in \fBdialog\fP
+by adding to the configuration file.
+\fBDialog\fP's \fBbindkey\fP command maps single keys to its internal coding.
+.EX
+bindkey \fIwidget\fP \fIcurses_key\fP \fIdialog_key\fP
+.EE
+The \fIwidget\fP name can be "*" (all widgets), or
+specific widgets such as \fBtextbox\fP.
+Specific widget bindings override the "*" bindings.
+User-defined bindings override the built-in bindings.
+.PP
+The \fIcurses_key\fP can be any of the names derived from
+\fBcurses.h\fP, e.g., "HELP" from "KEY_HELP".
+\fBDialog\fP also recognizes ANSI control characters such as "^A", "^?",
+as well as C1-controls such as "~A" and "~?".
+Finally, it allows any single character to be escaped with a backslash.
+.PP
+\fBDialog\fP's internal keycode names correspond to the
+\fBDLG_KEYS_ENUM\fP type in
+\fBdlg_keys.h\fP, e.g., "HELP" from "DLGK_HELP".
+.
+.\" ************************************************************************
 .SH ENVIRONMENT
 .TP 15
-.B DIALOGRC
+\fBDIALOGOPTS\fP
+Define this variable to apply any of the common options to each widget.
+Most of the common options are reset before processing each widget.
+If you set the options in this environment variable,
+they are applied to \fBdialog\fP's state after the reset.
+As in the "\fB--file\fP" option,
+double-quotes and backslashes are interpreted.
+.IP
+The "\fB--file\fP" option is not considered a common option
+(so you cannot embed it within this environment variable).
+.TP 15
+\fBDIALOGRC\fP
 Define this variable if you want to specify the name of the configuration file
 to use.
+.TP 15
+\fBDIALOG_CANCEL\fP
+.TP 15
+\fBDIALOG_ERROR\fP
+.TP 15
+\fBDIALOG_ESC\fP
+.TP 15
+\fBDIALOG_EXTRA\fP
+.TP 15
+\fBDIALOG_HELP\fP
+.TP 15
+\fBDIALOG_ITEM_HELP\fP
+.TP 15
+\fBDIALOG_OK\fP
+Define any of these variables to change the exit code on
+Cancel (1),
+error (-1),
+ESC (255),
+Extra (3),
+Help (2),
+Help with --item-help (2),
+or OK (0).
+Normally shell scripts cannot distinguish between -1 and 255.
+.TP 15
+\fBDIALOG_TTY\fP
+Set this variable to "1" to provide compatibility with older versions
+of \fBdialog\fP which assumed that if the script redirects the standard output,
+that the "\fB--stdout\fP" option was given.
 .SH FILES
 .TP 20
-.I $HOME/.dialogrc
+\fI$HOME/.dialogrc\fP
 default configuration file
+.SH EXAMPLES
+The \fBdialog\fP sources contain several samples
+of how to use the different box options and how they look.
+Just take a look into the directory \fBsamples/\fP of the source.
 .SH DIAGNOSTICS
-Exit status is 0 if
+Exit status is subject to being overridden by environment variables.
+Normally they are:
+.TP 5
+0
+if
 .BR dialog " is exited by pressing the " Yes " or " OK
-button, and 1 if the
+button.
+.TP 5
+1
+if the
 .BR No " or " Cancel
-button is pressed. Otherwise, if errors occur inside
-.B dialog
-or
-.B dialog
-is exited by pressing the
-.I ESC
-key, the exit status is -1.
+button is pressed.
+.TP 5
+2
+if the
+.BR Help
+button is pressed.
+.TP 5
+3
+if the
+.BR Extra
+button is pressed.
+.TP 5
+-1
+if errors occur inside \fBdialog\fP
+or \fBdialog\fP is exited by pressing the \fIESC\fP key.
+.
+.\" ************************************************************************
+.SH COMPATIBILITY
+You may want to write scripts which run with other \fBdialog\fP "clones".
+.SS ORIGINAL DIALOG
+First, there is the "original" \fBdialog\fP program to consider (versions
+0.3 to 0.9).
+It had some misspelled (or inconsistent) options.
+The \fBdialog\fP program maps those deprecated options to the preferred ones.
+They include:
+.RS
+.TS
+l l
+_ _
+l l.
+\fIOption\fR	\fITreatment\fR
+\fB--beep-after\fP	ignored
+\fB--guage\fP	mapped to \fB--gauge\fP
+.TE
+.RE
+.SS XDIALOG
+Technically, "\fBXdialog\fP",
+this is an X application.
+With some care, it is possible to write useful scripts that work
+with both \fBXdialog\fP and \fBdialog\fP.
+.PP
+The \fBdialog\fP program ignores these options which are recognized
+by \fBXdialog\fP:
+.RS
+.TS
+l l
+_ _
+l l.
+\fIOption\fR	\fITreatment\fR
+\fB--allow-close\fP	ignored
+\fB--auto-placement\fP	ignored
+\fB--fixed-font\fP	ignored
+\fB--icon\fP	ignored
+\fB--keep-colors\fP	ignored
+\fB--no-close\fP	ignored
+\fB--no-cr-wrap\fP	ignored
+\fB--screen-center\fP	ignored
+\fB--separator\fP	mapped to \fB--separate-output\fP
+\fB--smooth\fP	ignored
+\fB--under-mouse\fP	ignored
+\fB--wmclass\fP	ignored
+.TE
+.RE
+.PP
+\fBXdialog\fP's manpage has a section discussing its compatibility with \fBdialog\fP.
+.SS WHIPTAIL
+Then there is \fBwhiptail\fP.
+For practical purposes, it is maintained by Debian.
+Its documentation claims
+.RS
+.sp
+.nf
+whiptail(1) is a lightweight replacement for dialog(1),
+to provide dialog boxes for shell scripts. It is built on the 
+newt windowing library rather than the ncurses library, allowing
+it to be smaller in embedded enviroments such as installers,
+rescue disks, etc.
+.sp
+whiptail is designed to be drop-in compatible with dialog, but
+has less features: some dialog boxes are not implemented, such
+as tailbox, timebox, calendarbox, etc.
+.fi
+.RE
+.PP
+Comparing actual sizes (Debian testing, 2007/1/10):
+The total of sizes for \fBwhiptail\fP, the newt, popt and slang libraries is 757kb.
+The comparable number for \fBdialog\fP (counting ncurses) is 520kb.
+Disregard the first paragraph.
+.PP
+The second paragraph is misleading, since \fBwhiptail\fP
+also does not work for common options of dialog, such as the gauge box.
+\fBwhiptail\fP is less compatible with \fBdialog\fP than the decade-old
+original dialog 0.4 program.
+.PP
+\fBwhiptail\fP's manpage borrows features from \fBdialog\fP, e.g.,
+\fB--default-item\fP, \fB--output-fd\fP,
+but oddly cites only \fBdialog\fP versions up to 0.4 as a source.
+That is, its manpage refers to features which
+were borrowed from more recent versions of \fBdialog\fP, e.g.,
+the \fB--gauge\fP and \fB--password\fP boxes,
+as well as options such as \fB-separate-output\fP.
+Somewhat humorously, one may note that the \fBpopt\fP feature
+(undocumented in its manpage)
+of using a "--" as an escape was documented in \fBdialog\fP's manpage about
+a year before it was mentioned in \fBwhiptail\fP's manpage.
+\fBwhiptail\fP's manpage incorrectly attributes that to \fBgetopt\fP
+(and is inaccurate anyway).
+.PP
+Debian uses \fBwhiptail\fP for the official \fBdialog\fP variation.
+.PP
+The \fBdialog\fP program ignores or maps these options which are recognized
+by \fBwhiptail\fP:
+.RS
+.TS
+l l
+_ _
+l l.
+\fIOption\fR	\fITreatment\fR
+\fB--fb\fP	ignored
+\fB--fullbutton\fP	ignored
+\fB--nocancel\fP	mapped to \fB--no-cancel\fP
+\fB--noitem\fP	ignored
+.TE
+.RE
+.\" ************************************************************************
 .SH BUGS
-Text files containing
-.I tab
-characters may cause problems with
-.B text
-box.
-.I Tab
-characters in text files must first be expanded to spaces before being
-.RB "displayed by " text " box."
-.TP
-Screen update is too slow.
+Perhaps.
 .SH AUTHOR
-Savio Lam <lam836@cs.cuhk.hk>
+.LP
+Thomas E. Dickey (updates for 0.9b and beyond)
+.SH CONTRIBUTORS
+Kiran Cherupally - the mixed form and mixed gauge widgets.
+.LP
+Tobias C. Rittweiler
+.LP
+Valery Reznic - the form and progressbox widgets.
+.LP
+Yura Kalinichenko adapted the gauge widget as "pause".
+.PP
+This is a rewrite (except as needed to provide compatibility)
+of the earlier version of \fBdialog 0.9a\fP,
+which lists as authors:
+.RS
+.LP
+Savio Lam - version 0.3, "dialog"
+.LP
+Stuart Herbert - patch for version 0.4
+.LP
+Marc Ewing - the gauge widget.
+.LP
+Pasquale De Marco "Pako" - version 0.9a, "cdialog"
+.RE