From 4b351267d37f18a48991c0252cf43316967d3d8f Mon Sep 17 00:00:00 2001 From: fvogel Date: Thu, 12 Nov 2020 21:45:09 +0000 Subject: Fix man pages, clearly state what is optional and what is not (respect usual conventions for this). --- doc/sysnotify.n | 8 +++----- doc/systray.n | 40 +++++++++++++++++++++++----------------- 2 files changed, 26 insertions(+), 22 deletions(-) diff --git a/doc/sysnotify.n b/doc/sysnotify.n index b2988f9..559d1df 100644 --- a/doc/sysnotify.n +++ b/doc/sysnotify.n @@ -10,14 +10,14 @@ .SH NAME sysnotify \- Creates a notification window with a title and message. .SH SYNOPSIS -\fBtk sysnotify\fP \fItitle\fP \fImessage\fR +\fBtk sysnotify\fR \fItitle\fR \fImessage\fR .BE .SH DESCRIPTION .PP -The \fBtk sysnotify\fP command creates a platform-specific system notification alert. Its intent is to provide a brief, unobtrusive notification to the user by popping up a window that briefly appears in a corner of the screen. +The \fBtk sysnotify\fR command creates a platform-specific system notification alert. Its intent is to provide a brief, unobtrusive notification to the user by popping up a window that briefly appears in a corner of the screen. .SH EXAMPLE .PP -Here is an example of the \fBtk sysnotify\fP code: +Here is an example of the \fBtk sysnotify\fR code: .CS tk sysnotify "Alert" "This is just a test of the Tk System Notification Code." .CE @@ -29,7 +29,6 @@ falls back to a Tcl-only implementation if libnotify is not installed. On each platform the notification includes a platform-specific default image to accompany the text. .PP - The macOS version embeds two separate under-the-hood implementations using different notification APIs. The choice of which one to use depends on which version of the OS is being run and the state of the @@ -48,6 +47,5 @@ ineffective. To re-enable notifications the application must be deleted from Apple's System Preferences Notifications section. (There is no removal button, so this is done by selecting the application and pressing the Delete key.) - .SH KEYWORDS notify, alert \ No newline at end of file diff --git a/doc/systray.n b/doc/systray.n index 879849c..7120b51 100644 --- a/doc/systray.n +++ b/doc/systray.n @@ -10,41 +10,47 @@ .SH NAME systray \- Creates an icon display in the platform-specific system tray. .SH SYNOPSIS -\fBtk systray create \fI-image \fR?\fIimage\fR?\fI -text \fR?\fItext\fR?\fI -button1 \fR?\fIcallback\fR?\fI -button3 \fR?\fIcallback\fR? +\fBtk systray create \fI-image image\fR \fI?-text text\fR? \fI?-button1 callback?\fR \fI?-button3 callback?\fR .sp -\fBtk systray configure \fI option \fR?\fIoption\fR? +\fBtk systray configure \fI?option? ?value option value ...?\fR .sp \fBtk systray destroy\fR .BE .BE .SH DESCRIPTION .PP -The \fBtk systray\fP command creates an icon in the platform-specific tray. -The widget is configured with a Tk image for the icon display, a string -for display in a tooltip, and callbacks that are bound to and -. +The \fBtk systray create\fR command creates an icon in the platform-specific +tray. The widget is configured with a Tk image for the icon display, an +optional string for display in a tooltip, and optional callbacks that are +bound to and . +.PP +The \fBtk systray configure\fR command sets one or more options of the systray +icon. Configurable options are the same as for the \fBcreate\fR subcommand. When +a single option name is given, the command returns the current valus of this +option. When no option is given this command returns the list of all options and +their current value. +.PP + The \fBtk systray destroy\fR command removes the icon from display and +deallocates it. +.PP +From a user-interface standpoint, only one icon per interpreter is +supported; attempts to create additional icons will return an error. The +existing tray icon can be modified with different images and +strings to indicate app state. Loading additional interpreters into a +running instance of Wish will allow additional icons to be displayed. .SH EXAMPLE .PP -Here is an example of the \fBtk systray\fP code: +Here is an example of the \fBtk systray\fR code: .CS image create photo book -data R0lGODlhDwAPAKIAAP//////AP8AAMDAwICAgAAAAAAAAAAAACwAAAAADwAPAAADSQhA2u5ksPeKABKSCaya29d4WKgERFF0l1IMQCAKatvBJ0OTdzzXI1xMB3TBZAvATtB6NSLKleXi3OBoLqrVgc0yv+DVSEUuFxIAOw== tk systray create -image book -text "tk systray sample" -button1 {puts "Here is the tk systray output"} -button3 {puts "here is alternate output"} .CE .PP -Here is an example of modifying the \fBtk systray\fP icon: +Here is an example of modifying the \fBtk systray\fR icon: .CS image create photo book_page -data R0lGODlhCwAPAKIAAP//////AMDAwICAgAAA/wAAAAAAAAAAACwAAAAACwAPAAADMzi6CzAugiAgDGE68aB0RXgRJBFVX0SNpQlUWfahQOvSsgrX7eZJMlQMWBEYj8iQchlKAAA7 tk systray configure -image book_page -text "Updated sample" -button1 {puts "Different output from the tk systray"} -button3 {puts "and more different output from the tk systray"} .CE -.PP - The \fBtk systray\fP destroy command removes the icon from display and -deallocates it. -.PP -From a user-interface standpoint, only one icon per interpreter is -supported; attempts to create additional icons will return an error. The -existing tray icon can be modified with different images and -strings to indicate app state. Loading additional interpreters into a -running instance of Wish will allow additional icons to be displayed. .SH PLATFORM NOTES .PP The X11 implementation is supported on a "best efforts" basis because it is dependent on the window manager. The "text" -- cgit v0.12