(* The maximum duration value is defined to be 1000 hours. *)
value MAX_DURATION:Duration = {1000,0};

(*
 * The value range for item duration is 0 to MAX_DURATION, the latter being a
 * constant with some reasonable value.  Allowing a value of 0 means that a
 * scheduled item can a one-shot deal, like picking someone up somewhere.
 *)
axiom DurationBounds
    forall (d:Duration) 0 <= d <= MAX_DURATION;

Finish Section 2.5.2.5 and the changes to Section 2.5.3.5.

2.17.3. Items that Need to Be Checked for Fixing as Necessary (11jul04)

• Figure out what to do with duration arrows when they span a day break or would cross over another item. I'd say an ellipses would be just right, either horz or vert. Related to this, be sure to figure out what the display should look like in extreme cases for all display options, such as a screen too small to show fine day-view increments, such as every 10 minutes.
• creating distributions in the admin section, to make things crystal clear about what's in Settings versus what's part of the application. Also clear up bit about exactly now Distribution name is used, and the "any other necessary installation support files"
• Base Defaults subsection in options, in particular figuring out whether a custom distribution overrides base defaults in the app itself, or puts them in the distributed Settings file (it needs to be the latter if (c) is going to be the choice in the next item (which I really think it should be))
• Somewhere, if anywhere, in the options section, figure out if we want a `restore base defaults option settings' command. It could be (a) a button in the options dialog (yuck); (b) the bottommost item in the Options menu (sort of yuck); (c) nowhere (I think I like this the best). The good argument for (c) is that the user can simply remove or rename the Settings file to get back the base defaults (see second choice in immediately preceding bullet). NO -- simply removing the Settings file to restore base default options is messed up, because it also gets rid of other non-option settings that the user may well want to keep. So, we're back to some kind of `restore base defaults' command, resumably in the bottom part of the menu.
• UPDATE: we are not going to lose the start-up calendar field in the distribtuion, since we've fixed things in the revised options section; we do still need to deal with the issue of the user ID of the distribution- supplied file becoming that of the user, but we've already started to deal with this in the File section. OLD THINGS, NOW NOT HAPPENING: I think we should lose the `start-up calendar' in the distribution dialog, since the (newly explained) way it's effected is convoluted, and if it's there the installation should include a calendar of that name (which is a pain and pretty useless); if we care, we can have some sample calendars around to include at some web site or make part of the larger "distribution" of the thing. But we can forget about this for now.
• Check out any other things in the new file section, as it relates to the dmin and options sections in particular.
• Fix all refs to the Local Files section to whatever new name it ends up with.
• Deal with the one new item at bottom of options menu in ui-overview and options sections.

Allow use of delete key on selected item in a larger-grain view. There should be a related toggle option `warn on delete via short cut', perhaps just an option `warn on delete'.

2.17.5. Cut Bit from Options Section

Remember the bit about the initialization file and how it deals with the default view level always happening, including how a "no window" option value affects things initialization-filewise.

2.17.6. Global Date Update

Turns out, 2009 has the same day config as 1998, so we should globally replace all occurances of "1998" and "98" (as a year) with "[20]09". Fun.

2.17.7. HTML Links

Allow them in the Title and Details. In particular, just allow any HTML tags to appear in Title and Details, a la Javadoc. Thinking this through a bit more, there may need to be some limitation on what tags can appear in the Title field, since it's just a one- liner. Also, we need to think through just how HTML will be displayed versus edited.

This is starting to feel like a pretty big can-o-worms, actually, particularly if we want to provide text formating in the fields. We may want to take a cue from the way Apple Mail works, where there is an explicit distinction between plain text versus HTML content. We might have a few commands to set fonts and text properties in some menu somewhere, or we may just have a 'view source' command to allow the HTML content of messages to be edited. Or maybe we could do this: have a radio button selector for how to view the content of the fields -- `Plain Text' versus `HTML'. When `Plain Text' is selected, the fields show as that, including the raw HTML commands if they're present. This allows such commands to be edited directly in the field. When `HTML' is selected, then the field content is rendered as HTML, with the special feature that any fully plain text content is rendered properly as HTML filled text paragraphs (not just as <pre> ... </pre>). When `HTML' is selected and there are HTML tags present, then they're properly rendered. Also, it seems that it may be appropriate to disallow editing when `HTML' is selected, to avoid having to lapse into WYSIWIG editing. This may feel a little funky, unless, say, a quick little message pops up when the user tries to edit when in HTML display mode. Or perhaps we could have it that (controllable as an option) as soon as the user tries to edit in HTML display mode, the system automatically switches to plain text mode, and attempts to place the cursor as close to the click location as it can (which could get tricky in terms of have figuring out the proper char position with all of the tags "not counting", as it were. This is starting to sound a lot like future work.

Implementationwise, I'm hoping that we can just use a JTextEditorPane to make this happen easily, including some kind of forced one-line version for the Title field.

2.17.8. ``Obvious'' Minimum GUI Requiremets

Drag feedback; no flashing visual artifacts; all displays with text-entry fields and areas must be resizable, all windows must have title bars as shown in the scenarios, all icons (minized forms) must have platform-appropriate abbreviated text/graphics. These requirements fit very well under the heading ``things that experienced programmers/analysts know that can go wrong with typical implementations''.

2.17.9. Product Evolution

Somewhere it needs to be defined that as the product evolves, new releases will always be able to read files saved with any previous release.

2.17.10. Reminder

Don't forget to finish up the last bit of detail in the Filter section. Search for "Todo item".

2.17.11. Bug

In the possible meeting times list, the year should be displayed if the dates span a year. DONE.

2.17.12. The Term ``Client''

Consider changing the term "local host" to "client" or "local client".

2.17.13. Window ``Banner'' versus ``Title''

Think seriously about replacing the term "[window] banner" with "[window] title", or vice versa, or at minimum making certain that the two different terms are used consistently. The potential difference in meaning is that "banner" refers to the physical part of the top of a display window and "title" refers to the string that appears within the "banner". The reason "banner" might be better is that "Title" is already used for scheduled items, and it's potentially confusing to use the term "title" for windows as well. Anyway, think about it an MUYFM.

Also make sure that the terms "current" (for calendars (?files?) and windows) and "active" (for windows (?calendars?)) are used 100% correctly and consistently.

2.17.14. Filtering Todo Items

Go here and here.

2.17.15. Options Section Wording Fodder that Will Probably Be Nuked

Calendar Tool options ?exist? at three levels: local, standard Options file, and hard-wired into the Calendar Tool itself as it was configured for distribution.

2.17.16. Possible Fix Needed

In a paragraph of Section 2.4.1.1 just above Figure 89 there are references to sections where it's claimed that viewing of meeting minutes is covered, but a quick scan of those sections seems to reveal that meeting minutes viewing may not be all that well covered there (or anywhere, perhaps). So, check this out, to make sure that the correct sections are in fact referenced, and that there's a decent explanation of meeting minutes viewing there, or somewhere else that can be referenced.

2.17.17. Fix Links in Admin Section

Once the admin section is done, read it carefully to make sure all of the links point at the best possible places. In particular, there's currently a link to 2.14 (Multi-User Op Environment) in 2.6.2 (User DB). Depending on how much of the host computer discussion goes in 2.6 versus 2.14, the link to 2.14 may or may not be best.

2.17.18. Filtering Update Needed

To be fully consistent, the new `Scheduled By' and Scheduled By' on fields should be listed in the custom filter dialog.

2.17.19. Tree Viewer for Groups and Other Admin-Related Discussion

Immediately below list of groups in the group DB dialog, add a small-text button labeled "Tree View ...". This brings up tree-style viewer with group and user IDs as tree node labels. There are View and Cancel buttons at the bottom of the tree viewer. The View button zooms in on a group or user record.

In the book, if not here, discuss how the collection ops for the user DB are spread over two dialogs. Viz., Add and Find are in the DB-level dialog; Change and Delete are in the record-level dialog. The rationale is that for Change and Delete, the user should be looking at the record in order to do either of these operations. In particular for delete, we want the user to see the entire details of the group record before deleting.

2.17.20. External Operating Environment Issues

I think we need to add a new 2.X-level section to deal with the interface to the outside operating environment. The section needs to address, if not among other points:

• launching the tool, for each of its launch points
• initially configuring the tool, as necessary
• details of multi-user operation

From a 205 example perspective, this proposed new "Launch and Config" or "Dealing with the Underlying Operating Environment" section really needs to be there. For the cal tool, the current "Multi-User Operating Environment" rather muddies the waters, in particular since it's not applicable to all tools. Be that as it may, we do need the "Operating Environment" section in in the cal tool requirements. A sweet way to integrate the current "Multi-User" section in this context might be to make it a subsection of "Operating Environment", so in fact the three bullets above comprise the three subsections. I think this has potential and should get to it.

2.17.21. Custom Filter Menu Options

I think we need to add a None element to the custom filter menu, since the reselection of the name is clumsy, particularly if we implement with Java- style radio button menu items.

2.17.22. Misc

Make sure list views of fac mtg show it at biweekly, not weekly intervals.

Get rid of "audible beep only" in any figure, if any, where it appears.

Say that the initial default file name for a save is the path defined by the user's home dir concatenated with the default Cal Tool file name set by the admin.

Make sure "Staff Meeting" versus "Computer Science Staff Meeting" titles are in the right places.

Move the scroll handle down in Figure 109.

Add a Close item to the windows menu and describe it. To whit, Close removes any non-modal window from the screen as well as from the windows list. Any pending action in the removed window is canceled. The definition of modal versus non-modal display window is covered in section ... .

2.17.23. Make Sure Button and Menu Item States are Accurate

I'm pretty sure it's already in here, but don't forget to go through all dialogs and make sure the state of each button is correct. In particular, I notice today that state of the `Clear' button in Figure 91 should be disabled, given the newly clarified meaning of `Clear' in a dialog context such as this. Viz., `Clear' is only enabled after at least one edit has been made, since it does not clear out all data, but only edits made since the initial display. We may want to make sure that this not entirely uniform behavior of clear makes good sense. I think it does, since even the most work-doing cases, `Clear' does not clear everything to empty, but to some default values, or perhaps back to the most recently confirmed values, or to some well-defined "cleared" values. In the case of things like confirmation dialogs, the "default" values are those that were computed rather than seemingly more static option values. However, I think the principle can be considered effectively the same in both case, which means we're OK here rationalewise.

2.17.24. Quick Note

Consider adding the list of example items as an appendix, the rationale being that it was helpful during development and may therefore be helpful for the requirements reader.

2.17.25. Hmm, Centralized Server Architecture Rears Its Ugly Head

I'm inclined at this point to think that we need to add a new level-2 functional subsection that addresses the issues discussed in the next couple paragraphs. Call it something like "Inter-User Data Access". The requirements relate to all Cal Tool commands that require access to other user's calendar's and system-wide administrative information, which are: `View Other User', `Schedule Meeting', all admin commands.

Well, we need to deal with the issue of where not-yet-accepted meetings go. I think we want to prohibit any write access to any other users calendar. This means that not-yet-accepted items need either to go in the scheduler's place or the central place, or perhaps some combo of the two. Perhaps we should craft requirements that allow any form of implementation. One problem with being too vague about whether there's a central server is that when a user fires up the tool, he should be told if the central server is down so he can know that there may be pending meetings that he cant see. This is getting very complicated.

So here's some more on this. In order for things to work, everyone needs to have access to everyone else's files and/or to a centralized repository. So, we need to assume some form of network where the files stay accessible at all times. When the user logs on, if there is a server problem for one or more users, then the logging on user will get a message to that effect. This way, we may well be able to get away with not specifying exactly how many central servers there are. Here's what we do say: (1) users own their own calendar files and no one else can write on them, including the central Cal Tool server; (2) user files are stored in such a way that they remain accessible, even if their local computer is turned off.

If we want to do a more explicit design, here's one that I think works:

1. Every user owns a local file that's her calendar.
2. There's a central Cal Tool site that has a hot copy of all publicly- accessible portions of the local file.
3. The central site contains the admin databases.

OK, here's a bit more refinement (next morning) on the (hopefully abstract) model of inter-user data access. The `File Save' op saves both a local copy of the full calendar and a central copy. Need to think more about this, obviously.

2.17.26. Nuked These Things and Think They Can Stay Nuked

We may want to discuss the issue that if the scheduler fills in the scheduling criteria is such a way that there can be only one possible meeting time, that the system displays it in some other form than a list. Or if it's in a list, we'll just mention that the system does not distinguish this particular case from others, but just proceeds to show a list of length one. I think this is reasonable, given that there may be some who can't attend, so a length of list one seems fine. Nuff said here.

Include an "trailer" message that can be added to the "you're double booked" message that the cal tool sends to all double-booked attendees.

2.17.27. Scripting Language Derived from UI Command

I think the best place for this is in an appendix. It will be ref'd initially from the appropriate subsection of the file section.

2.17.28. A Couple More Todo Items

Need to have a discussion somewhere about invoking the tool from the command line. See where it's done in the Rolodex doc.

Consider adding a command that will save the current screen configuration. Alternately, this could be done with a .ini script file. I think I like the latter better, because the former requires some way to save the config and invoke it from the command line or icon, and we get into a bunch of OS-specific stuff. But wait -- maybe they're really the same idea. Viz., a config file is internally rep'd as a script, and can be invoked from an icon. So, we probably do as a convenience want a `Save Config' command added to the `File' menu.

-- OK, the save config thing is done. We'll see if we can live with it.

2.17.29. Prev/Next Arrow Issue

According to the rule that says the upper left corner of a window stays put, the left/right arrows in the full date bannerlette wont be aligned under each other when the size of the banner string changes, e.g., when the length of the month name changes. This is pretty clearly why claris put these buttons on the far left, and next to each other for convenient access. We really need to do the same. This might in fact be a cool thing to put in an SCO.

OK, here's a cool way to do it -- leave them on either side of the date label, but make the date label a fixed size, wide-enough to hold the widest possible entry, at all levels. That way the buttons stay put. Wait, that won't work if we keep the rule that the upper left corner of the window stays put,

2.17.30. Make Sure that Disabled (Greyed) State of All Buttons is Correct

The deal is we should use the concept of disabled (greyed out) means precond is not (fully) met. That's a cool formal basis, I think, but we need to make sure all the screen shots are correct with respect to it. I think in particular that the custom list dialog screen shots at the end of Section 2.3.3.6 may not be exactly correct wrt when Change and Delete are enabled and disabled.

2.17.31. Consider Where To Put Dialog State Details

The issue was raised to prominence when finishing up the list-viewing section. The current thinking is that as a matter of style, we'll factor out such lower- level details to the data-entry-details section. Here are the pros and cons of doing so:

• Pros:
  • relieves clutter from main scenario sections, in keeping with error-message-at- the-end philosophy
  • clutter relief makes for better reading
• Cons:
  • defers things unnecessarily; it might be better just to embed things in the scenario sections, or put the details at the end, either way not waiting until a later section
  • the data-entry details section may become unnecessarily complex, effectively becoming a clone of earlier scenario sections
  • the data-entry details section may be confusing in its back references, such as to detail tables in earlier scenarios; e.g., the ref to list- viewing.html#Table Fields applicable to each type of scheduled item in the description of custom list dialog details

OK, here's some bolstering for the Pro side -- in exploring the idea of view modeling in some new text writings, I had a bit of a sick feeling that having discovered something new about view modeling during the course of writing the custom list dialog requirements, I may have to go to the appt-scheduling section and add some refinements about initial dialog states. That was quite a sickening thought indeed, given that we're trying desperately at this point to get some closure on things. What lessened, if not eliminated altogether, this sickening feeling was that we don't need (or most likely want) to put any further dialog state discussion in the appt-scheduling section, but rather wait to do this in data-entry-details. And I do reasonably honestly believe that I'm saying this with keeping the requirements "best", not because I'm being lazy about going back to update the appt-scheduling section. I.e., it really would crud up the appt-scheduling section, I believe, if we went back and put in a bunch of details about initial dialog states.

Now what we might say about structuring a requirements document is that the very early scenarios are clean and simple, without, e.g., dialog state requirements discussed. In subsequent sections we could add in such discussion incrementally. E.g., we could put the custom-lists section, and maybe (probably also) in data-entry details. HOWEVER, the (potential) problems with this incremental approach are the following:

1. If we rely on the initial scenarios to present concrete information, even though they're not covering all possible cases initially, then we eventually need to cover dialog state details somewhere. Since we likely will not have some section like "More Appt Scheduling Details" (witness that we don't currently in the Calendar requirements, nor do I think we need one), there's no place else for such details to go.
2. So, continuing with the previous point, it doesn't seem to make good structural sense to have dialog details presented like this:
   1. early scenario(s) free of dialog state details
   2. later scenarios incrementally add some or all dialog state details
   3. data-entry-details section does dialog details missing from early scenario(s) and some or no details for later scenarios that had some or all dialog details there.

[Also do some another kind of example that we'll apply to all items, and do some sorting -- some example that I might actually find useful.]

2.17.33. Consider adding Emacs to list of related systems in section 1.5

Do it.

2.17.34. Complete Clear Statement for Item Uniqueness Criteria

At present, I believe the only place that it's stated explicitly is in (Ah "structural-viewing.html#item uniqueness" this paragraph of Section 2.3.1.2 This is hard way to obscure a place to have such a significant piece of specification. Hence, I suggest that we state it quite clearly in the data- entry details section, if not elsewhere, such as in some appropriate intro spot.

Related to this, here's a bit of verbiage that was removed from the list- viewing section when sorting orders were fully clarified, but it may come in handy at some point when we're spec'ing item uniqueness, and how that applies to sorting:

The date/time key consists of both a date and time for appointments and meetings. Lists of the other three types of scheduled items (meetings, tasks, and events) are very similar to appointment lists. Section ??? covers the scheduling as well as the listing formats for the three additional types of items.

Since the task listing section is being completed before the task scheduling and viewing section, once the latter is fully done we need to go back to the former to make sure that we got all of the details right.

2.17.36. Default Task Priority

DONE 27jul02, given all-encompassing style of default settings.

Needs to be in the options. Also, it's a good place, if one does not show up elsewhere, to illustrate what a non-typable combo-box menu looks like when its middle item is selected. OK, it looks like we'll use the Swing style of combo boxes, where the menu never comes up centered, or otherwise relative to what's selected, but rather always below the initial box item.

2.17.37. Color

The current Figure 10 shows an `Edit ...' item at the end of the category colors menu. We have to show an example of this or get rid of it. While it's a cool example to have, it's (a) not part of Claris, (b) of potentially limited actual utility, and (c) a bit much given that we're struggling just to get the basics done. Whatever, we'll probably leave it.

2.17.38. Beware (potentially) of automatic rescheduling

Our long-held notion of automatic rescheduling of optional items may have an impact on the list order of overlapping items, if we decide to allow the idea of preempting instead of rescheduling. In general, here seem to be at least some of the user-selectable alternatives for how/if auto resched is performed:

• move rescheduled item to the next available time slot
• move rescheduled item to the next available time slot, based on the normal hours setting
• preempt optional item(s) by moving them to the optional end of the overlaps list
• alert user when items are rescheduled or preempted (this is an on/off option by itself

12dec00 (DONE).Add precise explanation of the next/previous order of scheduled items, based on the afore-mentioned sorting order of start-time, duration, title. There's a potential problem with the total ordering of all items, given that events and tasks don't have durations. This needs to be firmed up and perhaps explained earlier in the daily and/or weekly sections. It may not have to go earlier, since in the daily and weekly views, events and tasks are displayed in separate panes, whereas with Prev/Next nav, all four item types are in one list (effectively). Anyway, it does need to be ironed out.

3oct00. In gui-details, add discussion for details of proportional placing of items in day display. Specifically, describe what happens when an item starts at say 55 minutes after the hour, in which case proportional spacing requires that the either the item is placed as far down as possible or the box is enlarged vertically. I think I like the latter.

1oct00. Fix Figure 6 by changing the `End Date' label to greyed out, as it appears in the immediately preceding Figure 5. Also fix the `outside appt' string in Figure 9 to be consistent with its capitalization used in the text, viz. `Outside Appt'. (Done, since this category has been nuked entirely.)

2jun00. Add a Text menu item between Find ... and Command ... on the Edit menu. Selecting the Text item brings up a simple text editor on the currently active calendar. An alternative to opening the current calendar as text would be to have an ellipses (Text ...) menu item which brings up a file chooser to select which calendar to open as text. Yet another would be to make "plain text" an option of the Open command. I lean towards the first, since opening a calendar as plain text is likely to be a pretty unusual option, that's mostly being considered since it provides a useful MVP design and implementation example. Also, from a strictly "right thinking" end users perspective, since it is an infrequently-used command, it goes better at the end of the Edit menu than as a regularly seen item in the very frequently used File->Open command.

Make sure there's a +/- zooming control in the Help contents viewer, and the index viewer as well if the index is greater than one level deep.

Make sure there's a "Trouble Shooting" section at the end of the users manual.

Add a screen road map section.

See www.sun.com/calendaring for another related system. In particular, a page under this URL mentions the following about calendaring standards, into which we should look further:

Support for IETF Calendar Standards -- iCalendar

Sun Calendar Server adheres to IETF calendar standards (iCalendar). Its standards-based features makes it easier for users to share calendaring information across the network. And as standards continue to evolve and emerge, Sun plans to continue to provide support for these new and emerging IETF standards:

• iTIP (iCalendar Transport-Independent InteroperabilityProtocol)
• iMIP (iCalendar Message-Based Interoperability Protocol)
• iRIP (iCalendar Real-Time Interoperability Protocol)

By specifying a duration rather than an end time, we have to deal with events that span multiple days, and in particular how to display them in the various views. This could be a pain, which might mean that we want to go to start- time/end-time format rather than star-time/duration format. Think about this.

Having thought at some length about the end-time versus duration tradeoff, I think we've pretty much settled on duration. A discussion of this issue is in the rationale section. The current thinking for how to display items that span a day (i.e., go past midnight) is to put a small down-pointing and up-pointing arrows all the way to the left of the item titles in the display. The down- pointing arrow goes with the starting title and the up-pointing arrow goes with the ending title. I think this will work nicely and it is consistent with the small right- and left-pointing in overlapping item displays.

2.17.41. Commands with No Effect

27jul02 Note: I'm just about ready to rework this so there's no such thing as a command with no effect, but rather any time there's a command that would have no effect, it's activation element in the GUI is disabled.

This needs to go somewhere. When the user performs an command that has no effect, such as 'View Item' when there is no current item to view, the systems responds by default with an audible beep. The user has the the option to change this alert to one of the following alternatives: (a) Visible bell (platform-specific screen blink); (b) context-specific alert dialog; (c) no action. For alt b, we need to list fully all of the context-specific alert dialog messages.

2.17.42. Trimming

I think it's time to get rid of the multi-week, and multi-month view ideas. These were going to allow the user to select two or more (but not a lot) of weeks or months to display in a single window. I don't really think they're necessary, given we can have as many individual windows open at a time as we want. Plus it helps with simplicity. This is a good item to put in the rationale.

2.17.43. Uniform Effect of the 'Cancel' Command

This must be explained somewhere and clearly we must make sure that the effect of `Cancel' truly is uniform.

2.17.44. Explanatory Error and Confirmation Dialogs

We should use the term "explanatory" error dialog throughout, and then in one section show what the generic such dialog looks like and enumerate a specific error message for each place where the term "explanatory error dialog" was used. Putting the list in chronological order of term use is probably best.

2.17.45. Help

27jul02 note: For simplicity, screw these.

Consider adding an option scroll-contents-on-index-display, which if on automatically scrolls the Contents pane to the topic in which the most recently selected index term appears. Note that this rule affects the requirement for historical context of the help information, in that "last selected by user" must be changed to "last selected by user or automatically displayed by the system".

Similar to the previous, consider adding option scroll-contents-on-search- display.

We might also consider auto-scrolling the Index pane as the Search selections are made. However, this sounds potentially confusing, given how exactly we'd match a search string to an index topic. Hence, at this point what sounds good is just auto-scrolling the Contents pane on Index and/or Search display.

NOTE WELL that these options may be more confusing and trouble than they're worth. A hint at this is that no existing help system, including Mac, does it this way. BUT, given that they're options that are off by default, they're probably OK, if not good.

2.17.45.2. Paragraph (from Rolodex) about Quick Help Activation Area

Consider moving this paragraph to the gui-details section. In the Rolodex, it's currently in the help section. We need to consider carefully the criteria from when something goes in a main scenario versus when it gets relegated to the gui-details section.