source: trunk/Cocoa/Pester/Documentation/index.rst @ 540

Last change on this file since 540 was 540, checked in by Nicholas Riley, 10 years ago

With updated index.rst to fix restructured text issues

Signed-off-by: Nicholas Riley <com-github@…>

File size: 14.9 KB
Line 
1.. Pester documentation master file, created by
2   sphinx-quickstart on Mon Jun  1 22:57:22 2009.
3   You can adapt this file completely to your liking, but it should at least
4   contain the root `toctree` directive.
5
6Welcome to Pester's documentation!
7==================================
8
9=============
10Pester  1.1b8
11=============
12UNRELEASED—do not distribute
13
14A simple alarm clock and timer for Mac OS X.
15
16Written by Nicholas Riley <pester@sabi.net>.
17Obtain updates from <http://web.sabi.net/nriley/software/>.
18
19Note: This documentation is not yet updated for version 1.1, though most of it
20should still apply; please read the release notes at the end for a listing of
21what has changed in this version. This beta version of Pester 1.1 is not yet
22feature-complete; some user interface elements from earlier betas are missing
23because they don’t work yet.
24
25-----------
26What is it?
27-----------
28
29Don’t want to miss the bus or train? Have a meeting coming up soon and want to
30be reminded of it? Too much trouble to create an appointment in Palm Desktop,
31iCal or Entourage? Pester can help.
32
33
34
35------------
36Installation
37------------
38
39Pester should work on Mac OS X 10.4 or later; it has been tested on Mac OS X
4010.4.11 and 10.5.1.
41
42To install Pester, simply drag the Pester icon to your Applications folder or
43another convenient location. If you use Pester often, drag it to the Dock or
44add it to your Login Items.
45
46If for some reason you find Pester not to your liking, remove it by dragging
47its icon to the Trash. Pester’s preferences file is named
48“net.sabi.Pester.plist” and is located in the Library/Preferences subfolder of
49your Home folder.
50
51------------
52Usage
53------------
54
55Use Pester to set alarms for times in the future. Alarms that are scheduled to
56expire after you quit Pester are saved automatically. Pester must be running
57in order to notify you that an alarm has expired. If an alarm expires while
58Pester isn’t running, you will not be notified, but the alarm’s time will be
59“«expired»” in Pester’s alarm list.
60
61To set an alarm, click the Pester icon, choose “Set Alarm…” from the Alarm
62menu, or press ⌘N, and the Set Alarm window (shown above) will appear.
63
64First type a message if you wish, otherwise the rather unimaginative “Alarm!”
65will be used. Recent messages you’ve used appear in the menu; if you mistype
66or want to remove a message, click the “–” button. To remove the all recent
67messages from the menu, click “– All”.
68
69To specify the alarm time in seconds, minutes or hours from now, click the
70“in” radio button, then type a number and pick a unit from the popup menu. To
71quickly pick one of the units from the keyboard, type S, M or H after typing a
72number.
73
74To specify an absolute time, click the “at” radio button, type a time and
75date. If you’re outside the US, the time format may not be what you expect;
76I’m sorry, but a multitude of date-related Cocoa bugs make supporting
77localization very difficult. In addition to typing numbers, you can select a
78relative date from the menu to the right of the date field, or type words such
79as:
80
81Time: “morning”, “noon”, “afternoon”, “dinner”, “midnight”
82Date: “today”, “tomorrow”, “next Thursday”, “November”
83
84The text at the bottom left corner of the window changes as you type to
85indicate whether the date and time you’re typing is valid.
86
87When an alarm expires, Pester’s Dock icon bounces once, your Mac beeps, and
88Pester displays a dialog box:
89
90
91To view or remove alarms, choose “All Alarms…” from the Alarm menu or press
92⌘L.
93
94Alarms shown as “«expired»” expired while Pester was not running. As alarms
95are set, they appear in the list; alarms which expire while Pester is running
96are removed from the list. To remove one or more alarms, select them and click
97Remove.
98
99-------------
100More features
101-------------
102
103Pester includes a Dock menu, which you can access by Control (⌃)-clicking
104Pester’s icon.
105
106From this menu, you can view information about the next alarm, open the Set Alarm window, or open the Alarms window.  The number of alarms is shown in parentheses.
107
108Pester’s Dock icon displays the time until the next alarm expires.
109
110Pester is also fully Y3K-compliant. It can be comforting to know that even if you won’t be around then, if your Mac still works, so will Pester.
111
112--------------------------
113Frequently asked questions
114--------------------------
115
116Q. Why isn’t Pester a full-featured calendar/scheduling program? What use is it otherwise?
117
118A. I wrote and use Pester on my Mac for the same reason I use programs such as BigClock and TikTok on my Palm, the built-in clock on my Newton and the alarm on my cellular phone. Sometimes all you want is an alarm to go off in 5 minutes, not an “appointment” or “meeting” entry that survives in perpetuity and is synchronized with your phone, PDA and iPod. On the other hand, if you’re happy with what you’re using, stick with it.
119
120Q. OK, but why doesn’t Pester have feature X?
121
122A. I didn’t need it. I have looked at (and even registered) some similar programs such as Alarm Clock Pro, Alarm Clock S.E., CountDown, Tea Timer and the like. None of them did what I wanted. Please check out those other programs first; if Pester comes closest to your ideal but is missing a key feature, let me know and I’ll consider adding it.
123
124Q. Under what conditions is the source code licensed?
125
126A. Please see my Web page for details. Essentially: don’t pass it off as your own, and give me credit if you use all or part of it in your own software.
127
128--------------------------
129Version history
130--------------------------
131
1321.1 / forthcoming
133-----------------
134•       Requires Mac OS X 10.4 or later (Universal Binary).
135•       Fixed small memory leaks on alarm creation and with the “Remove” button in the alarm list window.
136•       Fixed vertical resizing of the alarm list window.
137•       Fixed ‘s’, ‘m’, ‘h’, ‘d’ and ‘w’ shortcuts for selecting alarm interval so they work regardless of the insertion point position.
138•       Fixed time remaining in the Dock being wrong by one second, or showing «expired».
139•       Fixed empty messages appearing in the alarm message combo box.
140•       Fixed display of time intervals between 1 and 59 minutes: now “#m” instead of “0h #m”.
141•       Fixed display of time intervals between 24 and 48 hours: now “One day” instead of “1 days”.
142•       Fixed alarms not expiring after you put your Mac to sleep and wake it up again.
143•       Better indicate when a duration is out of range (okay, Nat?)
144•       Added more keyboard navigation, type-selection, sorting and iTunes-like row coloring to the alarm list window.
145• Added daily and weekly
146•       View alerts for scheduled alarms as help tags in the alarm list window.
147•       Customizable alerts: the previously-mandatory notification dialog box, alert sound and Dock bouncing are now all optional, and speech is new.
148•       Ellipsize long alarm messages in the alarm list window.
149•       Added Delete keyboard shortcut for removing alarms to the alarm list window.
150•       Alarm removal in the alarm list window is now undoable.
151•       Added in-application read me viewer with section navigation, instead of opening TextEdit.
152•       Retain highlighted alarms in the alarm list window when alarms are added, removed or resorted.
153•       Removed horizontal scroll bar from the alarm list window because it wasn’t ever available.
154•       Replaced buggy and deprecated Cocoa natural language date parser with the Perl Date::Manip module.
155•       Updated to new Cocoa date formatters, better supporting international date and time formats.
156•       Fixed text display with non-Roman languages.
157•       Added Preferences, with optional systemwide keyboard shortcut for set alarm window.
158•       Only show set alarm window when Pester comes to the front if an alarm isn’t in the process of expiring.
159•       Only bring Pester to the front if needed for the type of alert selected; if Pester was hidden or not in front before an alarm expired, it switches back and hides if necessary after the alarm is dismissed. (This means you can dismiss an alarm by clicking or pressing the return key and go right back to work.)
160•       Added simple repeating alarms. When the “Display message and time” alert is selected, each time an alarm expires you have an opportunity to stop it repeating; otherwise, remove alarms from the alarm list between expirations to stop them from repeating. This works well for things like “remind me every 15 minutes to take a break”. An alarm won’t start to repeat until the alerts have finished going off and you dismiss it, so you won’t come back to several thousand alerts!
161•       Added a “snooze” feature; works similarly to editing an alarm interval, with an additional “until…” option (‘u’ shortcut).
162•       Added a popup calendar to the Set Alarm window and the “snooze until” sheet.
163•       Added ⇧⌘T shortcut to switch between “in” and “at”.
164•       Default to today’s date in the “at” section.
165•       Reduced Pester’s processor usage while alarms are pending, and while the “Set Alarm” window is open but hidden.
166•       Changed alarm storage to be more reliable, expandable and human-readable, if a bit slower. Conversion occurs at startup and is one-way (if you really need it to be two-way, the feature would not be hard to add).  The alarm list should no longer become lost with a message such as “2002-11-18 00:31:24.461 Pester[8545] An error occurred while attempting to restore the alarm list: \*\*\* Incorrect archive: unexpected byte”.
167•       Switched to apple-generic versioning (agvtool, etc.).  Xcode 2.4 or later is required to build Pester 1.1.
168•       Incorporated Sparkle for automatic updates.
169•       Creator code is now Pest instead of Pstr (the latter was already registered).
170
171--------------------------
172Still to be fixed for 1.1:
173--------------------------
174
175•       Dock bouncing doesn’t work when Pester is frontmost.
176•       Customizable alerts: AppleScript, playback of sounds, images and movies (anything QuickTime can handle).
177•       Sometimes Pester will not open the Set Alarm window when you bring it to the front and no other window is open.
178•       Sometimes, alarms stay as expired, end up in the 'expired' section of the alarm list, and never get removed.
179•       Handle alarm—mostly alert—restoration failure (finish implementing PSError, test cases).
180•       The Dock icon still sometimes displays «expired» briefly; this is an artifact of the new timer implementation.
181•       Write documentation.
182•       Alarm times can be off by up to one second in certain cases.
183•       Extremely delayed alarm times can be huge (4....... years)
184
185----------------------------------------------------
186Known bugs in this version (not to be fixed by 1.1):
187----------------------------------------------------
188•       Type-selection of alarms by their dates and times in the alarm list only works well when the items in the list are in approximate alphabetical order; this breaks with certain date and time formats.
189
190-----------------------------------------------
191Additional features planned for later versions:
192-----------------------------------------------
193•       Better repeating alarms, such as a “real time” option so you can schedule an alarm to go off every hour, on the hour, for example.
194•       Better handling of non-repeating expired alarms—offer the option to have the alarms go off when Pester is restarted?
195•       Alarms (unscheduled ones, at least) as documents.
196•       Notifications before an alarm goes off, as in xalarm.
197•       Full localization of all text in the application, not just date and time formats.
198•       User interface overhaul (Philippe, I am not forgetting :-)
199
200[Two rereleases of 1.0 had no changes in the Pester application itself; they fixed problems with double-clicking the Read Me, so the version number was not changed.]
201
2021.0 / 14 October 2002
203---------------------
204Added alarm list, saved alarms, Dock icon/menu, live alarm time, other features.
205
2061.0d1 / 9 October 2002
207----------------------
208First public release.
209
210---------------------
211Acknowledgments
212---------------------
213
214Pester uses Andy Matuschak’s Sparkle, for which the following conditions apply:
215
216Copyright (c) 2006 Andy Matuschak
217
218Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
219
220The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
221
222THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
223
224Pester uses Sullivan Beck’s Date::Manip module.
225
226Pester uses code from Dan Wood’s TableTester examples.
227
228Pester uses BDAlias, for which the following conditions apply:
229
230Copyright © 2001, bDistributed.com, Inc.
231All rights reserved.
232
233Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
234
235•       Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
236•       Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
237•       Neither the name of bDistributed.com, Inc. nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
238
239THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
240
241Pester includes software developed by The Omni Group. Unmodified versions of this software are available at http://www.omnigroup.com/developer/.
242
243
244Contents:
245
246.. toctree::
247   :maxdepth: 2
248
249Indices and tables
250==================
251
252* :ref:`genindex`
253* :ref:`modindex`
254* :ref:`search`
255
Note: See TracBrowser for help on using the repository browser.