X-Git-Url: https://git.distorted.org.uk/~mdw/xtoys/blobdiff_plain/2b6e1eca160e4ee835c26c4b1d6cf67552707413..4be8cb2b59106a6c55a235f713cc4ac2ba655df8:/xmsg.1

diff --git a/xmsg.1 b/xmsg.1
index 57cb3e1..debc926 100644
--- a/xmsg.1
+++ b/xmsg.1
@@ -3,23 +3,15 @@
 .SH NAME
 xmsg \- pops up a message box
 .SH SYNOPSIS
-.ll +5i
 .B xmsg
-.RB [ \-\-display
-.IR display ]
-.RB [ \-f ]
+.RI [ gtk-options ...]
+.RB [ \-EIQWm ]
+.RB [ \-d
+.IR headline ]
 .RB [ \-t
 .IR title ]
-.RB [ \-c | \-d
-.IR button ]
-.if n \{\
-.br
-\h'1i'
-..
-\}
 .I message
 .RI [ button ...]
-.ll -5i
 .SH DESCRIPTION
 The
 .B xmsg
@@ -29,55 +21,115 @@ one per argument, after the message.  If no buttons are requested, an
 .B OK
 button is provided anyway.
 .PP
-A button may be selected as being the default (i.e., may be chosen by
-pressing
-.IR enter ),
-using the
-.B \-d
-option: the argument must either match a button name, or be an index
-(zero-based) of the requested button.  If you don't select a default,
-the first (rightmost) button becomes the default anyway.
+The user dismisses the message window by activating one of the buttons
+or just closing the window using the window manager.  The
+.B xsmg
+program then writes a string to its standard output describing the
+user's action and exits.  The string written is, by default, the label
+of the activated button, though this can be overridden: see below.
+.SS "Message specifications"
+The
+.I message
+argument is usually just a text string to be displayed.  However, if the
+.I message
+is
+.RB ` \- '
+then, instead, the message to display is read from standard input.  If the
+first character of
+.I message
+is
+.RB ` ! '
+then that character is removed.  (Hence, if you really wanted to show
+the message
+.RB ` \- ',
+you need to pass
+.RB ` !\- '.)
+Conscientious script authors will prefix strings appropriately.
+.PP
+Pango markup may be used in message and headline strings if the
+.B \-m
+option is requested.
+.SS "Button specifications"
+A
+.I button
+argument has the form
+.RI [ opt \fB: opt \fB: ...] \c
+.RB [ ! ] \c
+.IR label .
+The
+.I label
+is either a text string, or a GTK stock-id (e.g.,
+.BR gtk-ok ).
+Mnemonic characters in button labels may be marked by prefixing them
+with underscores.  Write two underscores if you really want a literal
+underscore to appear.
+.PP
+Each
+.I opt
+may be one of the following.
+.TP
+.B default
+This should be the default button, activated when the user presses the
+.I enter
+or
+.I return
+key.
+.TP
+.B cancel
+This should be the cancel button, activated when the user presses the
+.I escape
+key or simply dismisses the window.
+.TP
+.BI = tag
+If the user activates this button, output the
+.I tag
+rather than the button's label.
 .PP
-Similarly, a button may be selected as being the `cancel' action (i.e.,
-may be chosen by closing the window or pressing
-.IR escape ),
-using
-the
-.B \-c
-option.  Again, the argument must either match a button name or be an
-index of a button.  If you don't select a cancel button, the last
-(leftmost) button because the cancel button.
+If no button is marked as the default, then the rightmost (first
+specified) is chosen automatically; similarly, if there is no specified
+cancel button then the last is chosen.  If several buttons are marked as
+default or cancel buttons then the behaviour is unspecified.
 .PP
-If there is more than one button, the name of the selected button is
-printed on standard output when the program exits.
+Button options are usually processed while colons remain in the button
+specification.  Processing stops early if an exclamation mark
+.RB ` ! '
+is reached.  For example,
+.B default:!cancel:button
+is parsed has specifying the
+.B default
+option and a label text of
+.BR cancel:button .
+.PP
+If no
+.I button
+arguments are given,
+.B xmsg
+automatically provides an OK button (it actually uses the GTK
+.B gtk-ok
+stock button) but produces no output.
 .SS Options
-.TP 5
-.BI "\-\-display " display
-Attempt to connect to
-.I display
-rather than the display named in the usual environment variable.
-.TP 5
-.B "\-f, \-\-focus "
-Sets a magical property to ensure that the window acquires the focus
-under a customized
-.BR fvwm (3)
-version I don't use any more.
-.TP 5
+.TP
+.BR \-E ", " \-I ", " \-Q ", " \-W
+Mark the message window as, respectively, reporting an error, providing
+information, asking a question, or giving a warning.
+.TP
+.BR "\-d, \-\-headline " headline
+Write the
+.I headline
+above the main message, in larger and bolder text.
+.TP
+.B "\-m, \-\-markup"
+Enable the use of Pango XML-like markup in the message and headline
+strings.  See the Pango documentation for a description of the markup
+tags available.
+.TP
 .BI "\-t, \-\-title " title
 Sets the title for the window.  If you don't specify a title, the window
 is labelled
 .RB ` xmsg '.
-.TP 5
-.BI "\-c, \-\-cancel " button
-Selects the given
-.I button
-as being the cancel button.
-.TP 5
-.BI "\-d, \-\-default " button
-Selects the given
-.I button
-as being the default button.
-.SH AUTHOR
-Mark Wooding (mdw@nsict.org).
 .SH BUGS
 None currently known.
+.SH SEE ALSO
+.BR gtk-options (7).
+.SH AUTHOR
+Mark Wooding (mdw@distorted.org.uk).