Add documentation for tree functions.

Submitted by:	Anatoly A. Orehovsky <tolik@mpeks.tomsk.su>

gnu/usr.bin/dialog/dialog.1

@@ -1,4 +1,4 @@
-.TH DIALOG 1 "10 January 1994"
+.TH DIALOG 1 "2 October 1998"
 .SH NAME
 dialog \- display dialog boxes from shell scripts
 .SH SYNOPSIS
@@ -28,7 +28,8 @@ types of dialog objects are currently supported:
 .LP
 .BR yes/no " box," " menu" " box," " input" " box,"
 .BR message " box," " text" " box," " info" " box,"
-.BR checklist " box and" " program" " box."
+.BR checklist " box," " program" " box,"
+.BR ftree " and " tree " boxes."
 .SH OPTIONS
 .TP
 .B \-\-clear
@@ -168,6 +169,68 @@ On exit, a list of the
 .I tag
 strings of those entries that are turned on will be printed on
 .IR stderr "."
+.IP "\fB\-\-ftree \fIfile FS text height width menu-height"
+.B ftree 
+box is a dialog box showing the tree described by the data from the file 
+.IR file "." 
+The data in the file should look like find(1)  output. For the
+find output, the field separator 
+.I FS 
+will be 
+.IR \'/\' ". If"
+.IR height " and"
+.IR width " are"
+positive numbers, they set the absolute size of the whole 
+.BR ftree " box. If"
+.IR height " and"
+.IR width " are negative numbers, the size of the"
+.B ftree 
+box will be
+selected automatically. 
+.I menu-height 
+sets the height of the tree subwindow inside the 
+.B ftree 
+box and must be set. 
+.I text 
+is shown inside the 
+.B ftree 
+box above the tree subwindow and can contain newline characters 
+.I '\en\' 
+to split lines. One can navigate in the tree by pressing 
+.IR UP/DOWN " or " \'+\'/\'-\' ", " PG_UP/PG_DOWN " or " \'b\'/SPACE
+.RI "and " HOME/END " or " \'g\'/\'G\' "."
+A leaf of the tree is selected by pressing 
+.IR TAB " or " LEFT/RIGHT
+the 
+.B OK 
+button and pressing 
+.IR ENTER "." 
+The selected leaf (to be more
+exact, the full path to it from the root of the tree) is printed to 
+.IR stderr "."
+If 
+.B Cancel 
+and then 
+.I ENTER 
+is pressed, nothing is printed to 
+.IR stderr "."
+.I file 
+may contain data like find(1) 
+output, as well as like the output of find(1) with
+.I -d 
+option. Some of the transient paths to the leaves of the tree may be
+absent. Such data is corrected when fed from file.
+.IP "\fB\-\-tree \fIFS text height width menu-height \fR[ \fIitem \fR] \fI..."
+.B tree 
+box is like 
+.B ftree 
+box with some exceptions. First, the data is not
+entered from a file, but from the command line as 
+.I item item ... 
+Second, the data thus entered is not corrected in any way. 
+Thus, the data like the output of find(1) with
+.I -d 
+option will look incorrectly.
 .SH "RUN-TIME CONFIGURATION"
 .TP 4
 1.
@@ -222,8 +285,7 @@ is exited by pressing the
 .I ESC
 key, the exit status is -1.
 .SH SEE ALSO
-.Xr dialog 3
-
+dialog(3)
 .SH BUGS
 Text files containing
 .I tab
@@ -233,7 +295,19 @@ box.
 .I Tab
 characters in text files must first be expanded to spaces before being
 .RB "displayed by " text " box."
-.TP
+.sp 1
 Screen update is too slow.
+.sp 1
+The 
+.B ftree 
+and 
+.B tree
+boxes do not allow the tree to be moved to the left or to
+the right. Thus, if there are many levels of data, some of the leaves can be
+rendered invisible. A standard display with 80 characters allows for 17
+levels to be visible. Deeper levels are invisible. However, the navigation
+in the tree and selection of leaves do work.
 .SH AUTHOR
 Savio Lam (lam836@cs.cuhk.hk)
+.sp 1
+Changes by Anatoly A. Orehovsky (tolik@mpeks.tomsk.su) (ftree and tree boxes)