gnu/usr.bin/dialog/README

   1
   2           dialog - Display dialog boxes in shell script (version 0.3)
   3           ===========================================================
   4
   5 This is a program that will enable you to present a variety of questions or
   6 display messages using dialog boxes from a shell script. Currently, these
   7 types of dialog boxes are implemented: yes/no box, menu box, input box,
   8 message box, text box, info box, checklist box. The idea of writing this
   9 program came from the fact that most questions asked in a shell script (and
  10 many interactive programs as well) can be classified into these few types:
  11
  12
  13     1)  One that requires the user to answer either yes or no.
  14
  15     2)  One that presents a number of options for the user to choose.
  16
  17     3)  One that requires the user to input a string.
  18
  19     4)  One that displays a message and optionally wait for a key press
  20         before continuing.
  21
  22     5)  One that presents a list of options that can be turned on or off.
  23
  24
  25 The program 'dialog' can, say for example, be called in a shell script to
  26 present the first type of questions like this:
  27
  28
  29         if dialog --yesno <question text> <height> <width>
  30         then
  31           ...
  32         fi
  33
  34
  35         e.g.  if dialog --yesno "Do you want to continue?" 7 51
  36               then
  37                 echo "Continuing..."
  38               else
  39                 echo "Aborting..."
  40               fi
  41
  42
  43 I've included a sample shell script for each type of boxes in the directory
  44 samples. The program requires ncurses to compile. Running 'dialog' without
  45 arguments will display the usage.
  46
  47
  48
  49 FEATURES
  50 --------
  51
  52         *  Friendly dialog box interface with buttons, etc.
  53
  54         *  Auto wrap around of question text if it's too long to fit on
  55            one line.
  56
  57         *  "\n" can be inserted in question text to control line breaking
  58            explicitly. The real newline character '\n' can also be used.
  59
  60         *  run-time configruation of color settings and other options using
  61            a configuration file.
  62
  63
  64
  65 WHAT'S NEW SINCE VERSION 0.21?
  66 ------------------------------
  67
  68         *  some changes for faster screen update.
  69
  70         *  much more flexible color settings. Can use all 16 colors
  71            (8 normal, 8 highlight) of the Linux console.
  72
  73         *  added run-time configuration using configuration file.
  74
  75         *  some minor bug fixes and cleanups for menubox, checklist and
  76            textbox.
  77
  78         *  added a man page.
  79
  80         *  some changes for easier porting to other Unix systems (tested
  81            on Ultrix, SunOS and HPUX)
  82
  83
  84
  85 INSTALLATION
  86 ------------
  87
  88         1.  cd ./src
  89
  90         2.  Go to step 3 if your system has ncurses (e.g. Linux).
  91             Edit Makefile and remove -DHAVE_NCURSES from DEFS. Also
  92             remove rc.c from SRCS and rc.o from OBJS. Change LIBS as
  93             appropriate (Usually, it should be '-lcurses -ltermcap').
  94             Go to step 6.
  95
  96         3.  Edit Makefile and remove -DBROKEN_WSCRL from DEFS if you
  97             are using ncurses 1.8.3 or newer. Menu scrolling should
  98             be faster. DON'T REMOVE IT IF YOU ARE NOT USING AT LEAST
  99             VERSION 1.8.3 OF NCURSES.
 100
 101         4.  Edit dialog.h and change USE_SHADOW to FALSE if you don't
 102             want shadowed dialog boxes. Also change USE_COLORS to
 103             FALSE if you don't want colors. Note that 'dialog' will
 104             check if the terminal supports colors, and will use mono
 105             settings if it doesn't, so USE_COLORS won't do any harm
 106             even if you have a mono display. Also note that USE_SHADOW
 107             implies USE_COLORS. These two options can be changed at
 108             run-time using the run-time configuration file (see below).
 109
 110         5.  Edit colors.h to change default color definitions if you
 111             don't like the defaults. These are only compiled in defaults,
 112             you can change them at run-time using the run-time
 113             configuration file.
 114
 115         6.  'make depend; make install' will compile and install the
 116             binaries in /usr/local/bin (change BINDIR in Makefile if
 117             you want to install elsewhere).
 118
 119         7.  'make install.man' will install the man page to
 120             /usr/local/man (change MANDIR in Makefile if you want to
 121             install elsewhere).
 122
 123         8.  You can then try the sample shell scripts in the samples
 124             directory (make sure the environment variable DIALOG is
 125             not set, the scripts use it to find the dialog binary, if
 126             it's not set, "../src/dialog" will be used).
 127
 128         9.  Don't forget to mail me (mail address at end of this file)
 129             if you find any bugs, have some good color settings to
 130             contribute or just want to tell me that you like it, Don't
 131             mail me if you don't like it :-)
 132
 133
 134
 135 RUN-TIME CONFIGURATION
 136 ----------------------
 137
 138         1.  Create a sample configuration file by typing:
 139
 140                 "dialog --create-rc <file>"
 141
 142         2.  At start, 'dialog' determines the settings to use as follows:
 143
 144               a)  if environment variable DIALOGRC is set, it's value
 145                   determines the name of the configuration file.
 146
 147               b)  if the file in (a) can't be found, use the file
 148                   $HOME/.dialogrc as the configuration file.
 149
 150               c)  if the file in (b) can't be found, use compiled in
 151                   defaults.
 152
 153         3.  Edit the sample configuration file and copy it to some place
 154             that 'dialog' can find, as stated in step 2 above.
 155
 156
 157
 158
 159 Comments and bug reports welcome.
 160
 161 - Savio Lam (lam836@cs.cuhk.hk)