help/docs: update; notification: bugfixes.

8 files changed, 62 insertions, 416 deletions

diff --git a/data/zenity.1 b/data/zenity.1
index 465b580..d876044 100644
--- a/data/zenity.1
+++ b/data/zenity.1
@@ -1,4 +1,4 @@
-.TH ZENITY 1 "December 2011"
+.TH ZENITY 1 "January 2022"
 .SH NAME
 zenity \- display GTK+ dialogs
 .SH SYNOPSIS
@@ -12,342 +12,32 @@ from the user, from all manner of shell scripts.
 .PP
 For example, \fBzenity \-\-question\fP will return either 0, 1 or 5,
 depending on whether the user pressed \fIOK\fP, \fICancel\fP or timeout
-has been reached. \fBzenity --entry\fP will output on standard output
+has been reached. \fBzenity \-\-entry\fP will output on standard output
 what the user typed into the text entry field.
 .PP
-Comprehensive documentation is available in the GNOME Help Browser.
+Comprehensive documentation is also available in the GNOME Help Browser.
+
 .SH OPTIONS
 This program follows the usual GNU command line syntax, with long
 options starting with two dashes (`-').
 
-.PP
-Dialog options
-
-.TP
-.B \-\-calendar
-Display calendar dialog
-.TP
-.B \-\-entry
-Display text entry dialog
-.TP
-.B \-\-error
-Display error dialog
-.TP
-.B \-\-file\-selection
-Display file selection dialog
-.TP
-.B \-\-info
-Display info dialog
-.TP
-.B \-\-list
-Display list dialog
-.TP
-.B \-\-notification
-Display notification
-.TP
-.B \-\-progress
-Display progress indication dialog
-.TP
-.B \-\-question
-Display question dialog
-.TP
-.B \-\-text-info
-Display text information dialog
-.TP
-.B \-\-warning
-Display warning dialog
-.TP
-.B \-\-scale
-Display scale dialog
-.TP
-.B \-\-color-selection
-Display color selection dialog
-.TP
-.B \-\-password
-Display password dialog
-.TP
-.B \-\-forms
-Display forms dialog
-
-.PP
-General options
-
-.TP
-.B \-\-title=TITLE
-Set the dialog title
-.TP
-.B \-\-width=WIDTH
-Set the dialog width
-.TP
-.B \-\-height=HEIGHT
-Set the dialog height
-.TP
-.B \-\-timeout=TIMEOUT
-Set the dialog timeout in seconds
-.PP 
-Calendar options
-
-.TP
-.B \-\-text=STRING
-Set the dialog text
-.TP
-.B \-\-day=INT
-Set the calendar day
-.TP
-.B \-\-month=INT
-Set the calendar month
-.TP
-.B \-\-year=INT
-Set the calendar year
-.TP
-.B \-\-date-format=PATTERN
-Set the format for the returned date. The default depends on the user locale or be set with the strftime style. For example %A %d/%m/%y
-
-.PP
-Text entry options
-
-.TP
-.B \-\-text=STRING
-Set the dialog text
-.TP
-.B \-\-entry-text=STRING
-Set the entry text
-.TP
-.B \-\-hide-text
-Hide the entry text
-
-.PP
-Error options
-.TP
-.B \-\-text=STRING
-Set the dialog text
-.TP
-.B \-\-no\-wrap
-Do not enable text wrapping
-.TP
-.B \-\-no\-markup
-Do not enable pango markup
-
-.PP
-File selection options
-.TP
-.B \-\-filename=FILENAME
-Set the file or directory to be selected by default
-.TP
-.B \-\-multiple
-Allow selection of multiple filenames in file selection dialog
-.TP
-.B \-\-directory
-Activate directory-only selection
-.TP
-.B \-\-save
-Activate save mode
-.TP
-.B \-\-separator=SEPARATOR
-Specify separator character when returning multiple filenames
-.TP
-.B \-\-confirm\-overwrite
-Confirm file selection if filename already exists
-.TP
-.B \-\-file\-filter=NAME | PATTERN1 PATTERN2
-Sets a filename filter
-
-
-.PP
-Info options
-.TP
-.B \-\-text=STRING
-Set the dialog text
-.TP
-.B \-\-no\-wrap
-Do not enable text wrapping
-.TP
-.B \-\-no\-markup
-Do not enable pango markup
-
-.PP
-List options
-
-.TP
-.B \-\-text=STRING
-Set the dialog text
-.TP
-.B \-\-column=STRING
-Set the column header
-.TP
-.B \-\-checklist
-Use check boxes for first column
-.TP
-.B \-\-radiolist
-Use radio buttons for first column
-.TP
-.B \-\-separator=STRING
-Set output separator character
-.TP
-.B \-\-multiple
-Allow multiple rows to be selected
-.TP
-.B \-\-editable
-Allow changes to text
-.TP
-.B \-\-print-column=NUMBER
-Specify what column to print to standard output. The default is to return
-the first column. 'ALL' may be used to print all columns.
-.TP
-.B \-\-hide\-column=NUMBER
-Hide a specific column
-.TP
-.B \-\-hide\-header
-Hides the column headers
-
-.PP
-Notification options
-
-.TP
-.B \-\-text=STRING
-Set the notification text
-.TP
-.B \-\-listen
-Listen for commands on stdin. Commands include 'message', 'tooltip', 'icon', and 'visible' separated by a colon. For example, 'message: Hello world', or 'visible: false'.
-
-.PP
-Progress options
-
-.TP
-.B \-\-text=STRING
-Set the dialog text
-.TP
-.B \-\-percentage=INT
-Set initial percentage
-.TP
-.B \-\-auto\-close
-Close dialog when 100% has been reached
-.TP
-.B \-\-auto\-kill
-Kill parent process if cancel button is pressed
-.TP
-.B \-\-pulsate
-Pulsate progress bar
-.TP
-.B \-\-no\-cancel
-Hides the cancel button
+.SS
+Dialog Options
 
 .PP
-Question options
-
-.TP
-.B \-\-text=STRING
-Set the dialog text
-.TP
-.B \-\-no\-wrap
-Do not enable text wrapping
-.TP
-.B \-\-no\-markup
-Do not enable pango markup
-.TP
-.B \-\-ok\-label
-Set the text of the OK button
-.TP
-.B \-\-cancel\-label
-Set the text of the cancel button
+Options can be used in various combinations in order to craft many different
+types of dialogs.
 
 .PP
-Text options
-
-.TP
-.B \-\-filename=FILENAME
-Open file
-.TP
-.B \-\-editable
-Allow changes to text
-.TP
-.B \-\-checkbox=TEXT
-Enable a checkbox for use like a 'I read and accept the terms.'
-.TP
-.B \-\-ok\-label
-Set the text of the OK button
-.TP
-.B \-\-cancel\-label
-Set the text of the cancel button
+For a summary of options, run \fBzenity \-\-help\fP.  This will display the
+first hierarchy of options available. A separate series of help sub-categories
+for each of these options will be displayed.
 
 .PP
-Warning options
-
-.TP
-.B \-\-text=STRING
-Set the dialog text
-.TP
-.B \-\-no\-wrap
-Do not enable text wrapping
-.TP
-.B \-\-no\-markup
-Do not enable pango markup
+For a full and complete list of all options for your build and an explanation
+of these options, run \fBzenity \-\-help\-all\fP
 
-.PP
-Scale options
-
-.TP
-.B \-\-text=STRING
-Set the dialog text
-.TP
-.B \-\-value=VALUE
-Set initial value
-.TP
-.B \-\-min\-value=VALUE
-Set minimum value
-.TP
-.B \-\-max\-value=VALUE
-Set maximum value
-.TP
-.B \-\-step=VALUE
-Set step size
-.TP
-.B \-\-print\-partial
-Print partial values
-.TP
-.B \-\-hide\-value
-Hide value
-
-.PP
-Color selection options
-
-.TP
-.B \-\-color=VALUE
-Set the initial color
-.TP
-.B \-\-show\-palette
-Show the palette
-
-.PP
-Password dialog options
-
-.TP
-.B \-\-username
-Display the username field
-
-.PP
-Forms dialog options
-
-.TP
-.B \-\-add\-entry=FIELDNAME
-Add a new Entry in forms dialog
-.TP
-.B \-\-add\-password=FIELDNAME
-Add a new Password Entry in forms dialog
-.TP
-.B \-\-add\-calendar=FIELDNAME
-Add a new Calendar in forms dialog
-.TP
-.B \-\-text=STRING
-Set the dialog text
-.TP
-.B \-\-separator=STRING
-Set output separator character
-.TP
-.B \-\-forms\-date-format=PATTERN
-Set the format for the returned date. The default depends on the user locale or be set with the strftime style. For example %A %d/%m/%y
-
-.PP
+.SS
 Miscellaneous options
 
 .TP
@@ -360,17 +50,6 @@ Display an about dialog.
 .B \-\-version
 Show version of program.
 
-.PP
-Also the standard GTK+ options are accepted. For more information about the GTK+ options, execute following command.
-.IP
-zenity \-\-help\-gtk
-
-.SH ENVIRONMENT
-
-Normally, zenity detects the terminal window from which it was launched and
-keeps itself above that window.  This behavior can be disabled by unsetting the
-WINDOWID environment variable.
-
 .SH EXAMPLES
 
 Display a file selector with the title \fISelect a file to
@@ -395,7 +74,7 @@ and the text \fIFinding all header files...\fP.
 .IP
 find . \-name '*.h' | zenity \-\-list \-\-title "Search Results" \-\-text "Finding all header files.." \-\-column "Files"
 .PP
-Show a notification in the message tray
+Show a passive notification
 .IP
 zenity \-\-notification \-\-icon=update.png \-\-text "System update necessary!"
 .PP
diff --git a/help/C/l10n.txt b/help/C/l10n.txt
index f03a73f..d91b277 100644
--- a/help/C/l10n.txt
+++ b/help/C/l10n.txt
@@ -1,16 +1,6 @@
-Zenity Manual V2.0
-
-------------------------
-SUMMARY OF CHANGES
-------------------------
-
-Created by: Breda McColgan
-Date: July 2004
-Manual version: 2.0
-
-------------------------
-SCREENSHOT INSTRUCTIONS
-------------------------
+---------------------------------------
+SCREENSHOT INSTRUCTIONS FOR TRANSLATORS
+---------------------------------------
 
 To create the screenshots, perform the following steps:
 1. Create a directory called /tmp/l10n_scripts.
@@ -37,7 +27,6 @@ zenity-entry-screenshot.png
 <script-name> = text_entry.sh
 
 
-
 zenity-error-screenshot.png
 ===========================
 
@@ -62,6 +51,18 @@ zenity-list-screenshot.png
 <script-name> = list.sh
 
 
+zenity-notification-screenshot.png
+==========================
+
+<script-name> = notification.sh
+
+
+zenity-notification-listen-screenshot.png
+==========================
+
+<script-name> = notification-listen.sh
+
+
 zenity-progress-screenshot.png
 ==============================
 
@@ -78,8 +79,8 @@ zenity-text-screenshot.png
 ==========================
 
 <script-name> = text_info.sh
-Select cvs.txt from the File Selector dialog.
-Resize the window so that only the text appears -- no blank space.
+Before running, be prepared to open a text file of your choice (traditionally,
+COPYING has been used).
 
 
 zenity-warning-screenshot.png
diff --git a/help/C/l10n_scripts/cvs.txt b/help/C/l10n_scripts/cvs.txt
deleted file mode 100755
index f470f66..0000000
--- a/help/C/l10n_scripts/cvs.txt
+++ /dev/null
@@ -1,51 +0,0 @@
-Getting the most out of CVS in GNOME
-====================================
-
-Introductory Beginnings-
-
-Current Versions System, CVS, is a powerful
-method of allowing many developers
-to work on the same source code. It is used
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-                                                                                                     
diff --git a/help/C/l10n_scripts/notification-listen.sh b/help/C/l10n_scripts/notification-listen.sh
new file mode 100755
index 0000000..d773a89
--- /dev/null
+++ b/help/C/l10n_scripts/notification-listen.sh
@@ -0,0 +1,5 @@
+#!/bin/sh
+
+cat << EOH| zenity --notification --listen
+message: this is the message text
+EOH
diff --git a/help/C/l10n_scripts/notification.sh b/help/C/l10n_scripts/notification.sh
index b7de9ab..fe5e482 100755
--- a/help/C/l10n_scripts/notification.sh
+++ b/help/C/l10n_scripts/notification.sh
@@ -1,5 +1,4 @@
 #!/bin/sh
                                                                                                                                                              
-/gnome/head/cvs/zenity/src/zenity --notification \
---window-icon="info" \
+zenity --notification \
 --text="There are system updates necessary!"
diff --git a/help/C/notification.page b/help/C/notification.page
index 37a0d98..d458133 100644
--- a/help/C/notification.page
+++ b/help/C/notification.page
@@ -7,7 +7,7 @@
     <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" />
   </info>
   <title>Notification Icon</title>
-    <p>Use the <cmd>--notification</cmd> option to create a notification icon.</p>
+    <p>Use the <cmd>--notification</cmd> option to create a passive desktop notification.</p>
 
   <terms>
     <item>
@@ -15,15 +15,20 @@
       <p>Specifies the text that is displayed in the notification area.</p>
     </item>
     <item>
-      <title><cmd>--icon</cmd>=<var>text</var></title>
-      <p>Set the notification icon using a string containing either a filename, or a string conforming to the FreeDesktop.org Icon Naming Specification.</p>
+      <title><cmd>--icon</cmd>=<var>path</var></title>
+      <p>Set the notification icon using a string containing a path to a valid icon on the system.</p>
     </item>
     <item>
-      <title><cmd>--listen</cmd>=icon: '<var>text</var>', message: '<var>text</var>', tooltip: '<var>text</var>', visible: '<var>text</var>',</title>
+      <title><cmd>--listen</cmd></title>
       <p>Listens for commands at standard input. At least one command must be specified. Commands are comma separated. A command must be followed by a colon and a value. </p>
       <note style="tip">
-        <p>The <cmd>icon</cmd> command also accepts four stock icon values such as <var>error</var>, <var>info</var>, <var>question</var> and <var>warning</var>.</p>
+        <p>The <cmd>icon</cmd> command also accepts icon theme name values in accordance with the FreeDesktop.org Icon Naming Specification such as <var>dialog-error</var>, <var>dialog-info</var>, <var>security-high</var> and <var>starred</var>.</p>
       </note>
+      <p>Examples include:</p>
+      <code>
+      message: Hello, my name is Joe
+      icon: /usr/share/pixmaps/monitor.xpm
+      </code>
     </item>
   </terms>
 
@@ -32,7 +37,7 @@
   #!/bin/sh
 
   zenity --notification \
-    --icon="dialog-information" \
+    --icon="/usr/share/pixmaps/monitor.xpm" \
     --text="There are system updates necessary!"
   </code>
 
diff --git a/src/notification.c b/src/notification.c
index 78f26c2..75c3035 100644
--- a/src/notification.c
+++ b/src/notification.c
@@ -77,10 +77,16 @@ zenity_notification_new (char *message, char *icon_path)
 		if (g_file_query_exists (icon_file, NULL))
 		{
 			icon = g_file_icon_new (icon_file);
-			g_notification_set_icon (notif, icon);
 		}
 		else
-			g_printerr (_("Icon file not found: %s\n"), icon_path);
+		{
+			g_debug (_("Icon filename %s not found; trying theme icon."),
+					icon_path);
+			icon = g_themed_icon_new_with_default_fallbacks (icon_path);
+//			icon = g_themed_icon_new (icon_path);
+		}
+
+		g_notification_set_icon (notif, icon);
 	}
 
 	return g_steal_pointer (&notif);
@@ -102,7 +108,7 @@ static gboolean
 zenity_notification_handle_stdin (GIOChannel *channel, GIOCondition condition,
 		gpointer user_data)
 {
-	g_autofree char *icon_file = NULL;
+	static char *icon_file;
 
 	if ((condition & G_IO_IN) != 0)
 	{
@@ -157,6 +163,7 @@ zenity_notification_handle_stdin (GIOChannel *channel, GIOCondition condition,
 
 			if (! g_ascii_strcasecmp (command, "icon"))
 			{
+				g_free (icon_file);
 				icon_file = g_strdup (value);
 			}
 			else if (!g_ascii_strcasecmp (command, "message"))
@@ -171,6 +178,7 @@ zenity_notification_handle_stdin (GIOChannel *channel, GIOCondition condition,
 					g_autoptr(GNotification) notif = NULL;
 
 					notif = zenity_notification_new (value, icon_file);
+
 					if (notif == NULL)
 						continue;
 
diff --git a/src/option.c b/src/option.c
index 0daa493..5da6a8f 100644
--- a/src/option.c
+++ b/src/option.c
@@ -2006,8 +2006,8 @@ zenity_create_context (void)
 
 	/* Adds notification option entries */
 	a_group = g_option_group_new ("notification",
-		N_ ("Notification icon options"),
-		N_ ("Show notification icon options"),
+		N_ ("Notification options"),
+		N_ ("Show notification options"),
 		NULL,
 		NULL);
 	g_option_group_add_entries (a_group, notification_options);