DML(1)

NAME
dml - shell dialogs with HTML-like syntax

SYNOPSIS
dml [-pec] [-f input_file] [-o output_file]
    [-C config_file] [-t title_string] [program...]

DESCRIPTION
DML is a cmdline tool which can be used to create interactive shell scripts. It is somewhat similar to dialog(1) tool, but is much more powerful.

DML is shorthand for Dialog Markup Language. As name suggests it uses several markups to donate specific widgets. DML program is much like HTML page with form. However there are several differences:

* tabs and newlines are generally ignored

* spaces are not, so if you write 'foo bar' you will get 'foo bar' not 'foo bar'

* input is not automagicly wrapped. you need explicit <br> tags (except inside <text> </text>)

* there is no <p> tag (use <br><br>)

There are three ways of passing programs to DML. First is to specify program in command line, like this

 $ dml 'Hello world<br><button>'

second is to specify file with program with -f option, and third is to pass program to dml's stdin. I found 3rd method most convenient, using here doc, like this:

 $ dml <<EOF
 > <input id=a>
 > <br>
 > <button>
 > EOF

Tags are specified inside <>. Tags which are not recognized are left untouched, this is useful when you're debugging scripts. Most of tags can have attributes in form name=value. If value contains spaces it should be specified in single or double quote. All tags which produce input widgets can get id= attribute. It's used to identify given widget. After dialog is executed DML dumps id_of_widget="state_or_caption_of_widget" pairs to stdout (unless overridden with -o option). This can be used in shell, like this

 eval `dml <<EOF
 Name: <input id=name caption="Franek">
 <br>
 <button res=1 caption="_Ok"> <button res=2 caption="Oo_ps">
 EOF`

After this 3 variables are set: res to 1 or 2 depending on whatever user pressed. name to whatever was entered in input box. And undef since there was no id given for some widgets (two buttons). If you're wondering about "_Ok" then O is highlighted, and some day there will be some shortcut available to use it ;^)

I found useful to define function for it (backticks quoting problems etc.) like this:

 dial()
 {
         eval `dml -t '_Some title' "$@"`
 }

And then use it like this:

 dial <<EOF
 Hello world
 EOF

OPTIONS

* -e reopen from stdErr
    When dml is started it may need to read program from its STDIN and then write output to its STDOUT. But it also has to read and write console. STDERR is assumed to be connected with terminal, and is used for this purpose in case we cannot use STD{IN,OUT}. That's why you should never do 'dml 2> anything'. This option can be used to always use STDERR.

* -c clobber output file
    If file specified as output already exists dml won't overwrite it, this option may change this.

* -p poor man frames
    Use +, - and | characters for frames, instead of vt100 semigraphics. Sometimes needed for bogus fonts.

* -C config_file
    Use alternate configuration file instead of /etc/dml.conf.

* -t title_string
    This string is displayed in top-left corner of screen, it can contain '_'s which highlight next character.

* -f input_file
    Read program from file.

* -o output_file
    Send output to file. It's not overwritten unless -c.

TAGS REFERENCE
All attributes are optional. Some default are assumed. id always defaults to "undef". width and height are computed. caption has synonymous text in most cases.

* <meta>
    set some meta-information for form. Attributes: title -- set title displayed in top of form. res -- set modal result on start, this defaults to 0, and is useful to display some information like 'Scanning...' and then scan. If you set it, dml call won't block - it will just display dialog and return. width, height -- can be used to set fixed size window. active -- can be used to set which widget should initially have focus. Note that you *have to* use it before you define actual widget.

* <br>
    breaks line. No attributes (yet ;).

* <input>
    display one line input box. Attributes: id, width -- defaults to 30, caption, res, pass=1 -- don't display caption, just single 'x', pass=2 -- mask input characters with '*'s. There is few more attributes for file selector inputs, see FILESELECTOR section for details. It is also possible to provide user with optional list of choices in the input box, see POPUP MENUS for details.

    Since 0.1.1 you can prevent user from changing value of input box with ghosted=1. It is mainly useful with popup menu.

* <button>
    display button that can be selected and pressed. Attributes: id, width, caption, res -- modal result, if set to 0 (not useful), pressing this button won't close the window, sets shell variable res to this modal result, dml command returns with status res - 1. Button sets id to 'yes' or 'no' depending on whatever it was pressed when closing dialog, res is more convenient anyway. text_res attribute can also be used. It takes string as argument, this string is placed in output variable text_res.

* <check>
    display checkbox ([X] or [ ]). Text describing it has to be entered outside (like this: '<check id=foo> Set foo'). Attributes: id, checked=1 -- if you want it to be marked per default. Sets id to 'yes' or 'no'.

* <text> ... </text>
    textarea, multiline widget that can be scrolled. Text inside it can contain <br>'s, and two font tags: <i> ... </i> and <b> ... </b>, first being italics (blue ;) and second bold (yellow). Text is wrapped. Attributes: width which defaults to 40, height which defaults to 8.

* <menu> ... </menu>
    multiline menu of options. It contains <item> tags. <item> can have only one attribute id, followed by actual menu item caption, like this:

     <menu id=m>
     <item id=del>_Remove the file
     <item id=mv>_Move the file away
     </menu>

    id of menu should not be confused with id of items. After dialog is done id of menu contains id of item. So after executing our example in shell variable $m there is either 'del' or 'mv'.

    'R' and 'M' characters are highlighted. They will be used for shortcuts in future.

    In 0.0.4 support for multiple selection menus has been added. They are done using checked attribute to menu. It can be 0 or 1. If it is not passed -- given menu item is normal (i.e. doesn't have [X]). You can safely mix items with and without checked tag within the same menu. If there is at least single item with checked attribute, return value of menu is special. In normal case it contains id's of checked items. However, when menu has res set and you press enter on item without checked attribute, result of menu is id of selected item. There is also additional attribute for <menu>: checked - it contains whitespace separated list of items that should be selected. When item is listed there it is marked as checked, if it's not, and has checked=1 -- it's checked nevertheless.

    group attribute can be used along with checked to make radio-button group. When item belonging to named group is checked all other items in that group are unchecked.

    When ghosted attribute is set to 1, item cannot be selected. When nohl attribute is set to 1, _ sequences are not interpreted.

    Attributes: id, width -- defaults to widest entry, height -- defaults to 8 or number of entries, whichever is smaller, res -- menus can be assigned modal results, just like buttons, window is closed when Enter is pressed inside the menu, selected -- id of preselected item, by default first one is selected.

FILESELECTORS
If you need user to enter some path, it's nice to allow him to choose from whatever she has on his disk. So you add additional attribute to your <input> tag: fs. It should be set to string of letters, which describe which types of files can be selected.

* d -- directories
* b -- broken (non-existing) files
* r -- regular files
* v -- devices
* o -- other files (fifos, sockets etc)
* a -- all files, equivalent to 'dbrvo'

You can also pass title attribute to <input> tag to specify title of fileselector window, and label to set caption of button (which defaults to '_...'). Example:

 <input id=dir title='Choose dir' fs=d label='_Search'>

POPUP MENUS
Similarly to file selectors, since 0.0.17 it is possible to provide list of predefined strings for input box, and present it in form of menu. To do that you need to add menu attribute to <input ...>. Its value should be id of some menu with hidden attribute set to 1. title and label has the same meaning as with file selectors.

NLS
There is no NLS support in dml anymore. You can use $(gettext ...).

FILES

/etc/dml.conf
    Color definitions overriding default colors

    Example:

        pi_color_window white red
        pi_color_button cyan black

    For full list of available options and colors, refer to source code (file slang.c)

BUGS
Well, possibly lot of undetected...

While '_' highlights next character in button caption and menus, it has no practical meaning -- it should be used for shortcuts.

LICENSE
This program is distributed under the terms of GNU General Public License, version 2.

AUTHOR
Michal Moskal <malekith@pld-linux.org>

CONTACT
Please send comments, bug reports, etc to the author.

SEE ALSO
sh(1), dialog(1)