Cover in as OS-independent way as possible how to install the system, and how it's invoked from the OS. I think the best way to do this is to define what files have to go where, and then say that the installation process can use whateve helpful installation aids may exist, and we assume that the installer has any privileges necessary for installation in system-protected places.

Don't forget to discuss how the server is installed along with the admin program, and that system-level administrator priveleges may be necessary to install such a server. What's described here is the behavior the server must execute -- it's up to the implementors to figure out if such behavior requires system administrator privileges, and if so deal with it accordingly.

2.15.1. Installing the Calendar Tool

Talk (again, as necessary) about the Calendar Tool user directory, the default name and location of which are ".CalendarTool", stored in the user's home directory. Say home how directory is a platform- specific idea, and if there is no such thing on the installed platform, then the user will be asked to specify the name and location of the CalendarTool working directory the very first time the Calendar Tool is invoked.

Bottom line -- when the app is invoked, it must know where to look for the user's CalendarTool directory. Upon initial invocation, if such a directory is not found, it will ask the user to create one. The generic default place for this is ~/.CalendarTool, where "~" designates the platform-dependent "home" directory for the user. This location can be explicitly specified in an adminstirator-created distribution. If at initial invocation the app cannot determine such a location for the invoking user, or if such a location exists but is not read/write accessible to the user, then it prompts the user for the directory path of where to put the CalendarTool directory (with an appropriate msg indicating why it's asking (i.e., cannot figure out where "home" is or the distribution-supplied (or expected) home does not exists or is not read/write accessible)).

Since the user can subsequently change the location of her CalendarTool directory, the app has to be built in such a way to make this possible. The implementors can accomplish in any of the following ways, or some other way of their choosing:

• put a file containing the location of the user's CalendarTool directory at some well-known, platform-depdendent, e.g., ~/Library/Preferences/caltool.init
• allow the application itself to be modified to contain the changed location of the CalendarTool directory, as long as such a location is user-specific

Also, given that the `Admin->Distribution' command is gone now, explain how an installer, admin or otherwise, can run the regular cal tool, create calendars and/or a settings files, and include those with an installation. These requirements don't say anything about fancy, easy-to-use install tools, but if they're used, they can do shit like copy installation- provided calendars or Settings files into the user's caltool dir. What we can do in these requirements is explain the manual installation of extra shit, by desribinng the OS-level file commands the the stupid motherfucking user can do to copy the installer-supplied files to his caltool dir.

In conjunction with the precedinig paragraph, we may want to mention that all of the place in the preceding scenarios where it says "by default, there are no ..." is overridden with the installer provides a calenar or Settings file that does define some pre-defined stuff. This is pretty much a duh, but it's probably worth mentioning, just to keep the motherfucking implementors aware and on the hook.

Probably old crap: When installed, the app is additionally configured with the following info:

• the user's calendar tool directory

The application must be compiled for installation following appropriate platform-dependent conventions as necessary.

To create an installable version of the program, these things are needed:

• a compiled version of the application that is configurable to allow the location of the settings directory to be installed within the application, or have the location of a file that contains the location settings directory be in a well-known and accessible place.
• write access to the directory where the app will be installed

OK, here are the user-level steps to install the cal tool raw, with no administrator-supplied distribution having been provided:

1. copy the Calendar Tool application program to the desired directory
2. invoke it

Deal with the conflict resolution issues if one or more of items in a custom distribution conflicting with extant items the user already has defined; I think the best way to deal with that is to give the user an itemized list of precisely what the conflicts are, and let her choose what to do about it.

Want to keep prompts to a minimum. I think these are they, er, this is it:

1. "Enter the name of the directory where the Calendar Tool will store its standard files. _______________"

You are a confirmed registered user on the
Calendar Tool central host computer host name.

You can use the `Admin->Central Host' command
to change your central host or disconnect from the host
to run in stand-alone mode.


-- or --

This installation of the Calendar Tool is configured
to run as a stand-alone program that is not initially
connected to a Calendar Tool central host computer.

If you are a registered user on a Calendar Tool central host,
you can use the `Admin->Central Host' command to connect to the host.

If you are not a registered and want to become one,
please contact your local Calendar Tool administrator.

When the app is built by the implementors or configured by an adminstrator, it contains the following hard-wird information:

• a set of default option values

Talk about conventions that may exist for standard placement of application data files, and how platform-specific installation documentation must be produced for any delivered product. Whatever platform-specific conventions may exist, the following minimum file requirements must be met for all installed platforms: ... (things like the names of files, and the general types of dirs they must go in, e.g. "preferences" dirs).

2.15.2. Invoking the Calendar Tool

Points to include:

• Cover all uncovered points about the order in which things get done at start- up, particularly wrt command-line (or equiv) file args. Do this in conjunction with what's already done in Section 2.8.5, where there's a discussion of the what happens with `Settings' at start-up, and also in conjuntion with Section 2.7.4.3, where there's a discussion of the "Effects of initial view settings when tool is invoked with file arguments" (this is the title of a table there).

  Here's a somewhat-outdated list of points on the order in which files are handed at start-up, the outdatedness being in the mention of the no-longer- existent Config and Init files:

  1. Any command-line files that do not exist are created as new Calendar Tool files, with the contents of the Options file copied into them.
  2. Any command-line files that exist as valid Calendar Tool files are opened, and their default view windows are opened at window-manager-controlled positions.
  3. Any command-line files that are not valid Calendar Tool files or not otherwise readable are ignored, with a warning dialog to this effect displayed on the screen.
  4. If there's a Configuration file and it requires opening any of the command-line files, these files a considered already opened. Even if multi- window mode is on in a file's options, there is at most one default view window opened for each file. If the positions of any of the command-line file default view windows are specified in the Configuration file, the windows are placed at those positions. The system then proceeds to process the rest of the configuration file. In this way, the start-up configuration is the union of the command-line files and the Configuration file.
  5. If there's an Initialization file, it is executed last. This means that the Initialization file can override any of the configuration performed as a result of command-line file specification and Configuration file processing. E.g., the initialization file could contain the command CloseAll to undo all of the command-line and Configuration file processing. Since there are no window placement commands in the Calendar Tool command language, there's no way to duplicate the window-placement functionality of Configuration file.
  Treat this list like fodder to be groomed as necessary, then off it to the rationale, as usual. Also, most likely bill this section as a summary, given that major points have been covered already in earlier sections. (There is in fact a new text section on this summary/redundancy idea -- pretty cool, actually.)
• OK, one more motherfucking time. We really do need a global `Initial View for New Calendars' in the global options dialog, because there is no ``intial view for new calendars ... saved in the calenar-specific component of the `Settings' file'' as it's phrase in the next (bullshit) bullet. What I was thinking was that the cal-specific setting for `Iniital View When Open' could be used for new calendars, but that doesn't work, not least because we describe explicitly in the options section that the initial-view-when-open setting happens for a (presumably) extant calendar when it's opened, not for a calenar that is non-existent before the New operation is complete. Get it, motherfucker??
• Bulshit Bullet: Hmm, lemmie see if I can get this right, and if so the next two bullets are both bullshit. We don't need to include `Initial View for New Calendars' in the (now new) global options dialog, because the intial view for new calendars is whatever is saved in the calenar-specific component of the `Settings' file. I think this is right.
• Non-Bulshit Bullet: The immediately following bullet is bullshit, because the now global setting for `Initial View for New Calendars' works perfectly well for the new calendar created with when the cal tool is invoked with no args. I.e., the new calendar created at argless invocation is exactly the same kind of calendar as that created by `File->New', and thereby subject to exactly the same rules for using `Settings'.
• Bullshit Bullet: When invoked with no file arg(s), the initial view is the month view for a new calendar, period. There are no options to change the view level in the no-arg case. I think it's fine to say that having an option for the view level really only makes useful sense when the user invokes with a specific calendar, for which there is a settable initial view option.
• Init file only invoked one time at start-up, not at each file open
• Prev rule means no init file happens when other user's calendars are open.
• Allow (?provide?) both command line and GUI invocation; with command line, args specify files and options. With GUI invocation, calendar files are the one or more selected for invocation. In either case, all open files are opened by the tool.
• The initial default calendar is an empty calendar named "unnamed"; this is overridden by icon-based file invocation, command-line arg, or option setting.
• If no Settings file in caltool dir, ask user if she wants to create one. Cal-specific values in the settings file are described in File section for creating a new cal when no Settings file exists.
• Deal with invocation after tool is already running, including double clicking on an icon while tool is running. This seems to be quite environment-specific, and we may want to say as much and keep things generic in these requirements.

Some directory needs to be designated as a user's caltool directory, and this directory must be that specified in a register's user's central host user database record. The default name for this directory in the standard Calendar Tool distribution is .CalendarTool. System installers and adminstrators must take care that the following conditions do not cause confusion or problems for users:

1. the installation script, by some funky OS convention, puts the user's cal tool dir is some place like c:336e user's cal tool database record says the user's cal tool dir is someplace else
2. a user is registered on more than one calendar tool central host, with different cal tool directories, or other different user-record information on thoses hosts

OK, I think we probably need to talk about the potentially user-visible platform dependenncies here, not just, or maybe not at all, in the development overview section. See the NOTE at the top of that section.

Among other things, there are the following issues:

1. command-line args versus clicking on icons
2. environment vars, particularly ones that define default paths, as in, even more particularly, the path to the start-up Setttings file
3. the ways files are identified in different environments, including the whole Windoze registry bullshit (if it still exists in XP or whatever the latest POS is)

Note that the value of the local files directory path, user settable via the `File->Local Files' command, is stored in the application program itself, not in a file. There's chicken-and-egg thing going on here [which I'll explain a bit more in due course]. OK, fuck this shit, it's time to explain it now. I think the way it has to work is for at installation time, and never thereafter, the app is configured to look in a specific place for the local-files file, which in turn has enough information to get things boot strapped. It seems most akin to THE ~/.mh_profile, or ~/.emacs, or ~/Library/Preferences/com.apple.mail.plist files. Now in UNIX, we can do things like (1) have a list of places that an app will look, in addition to just the "~" place; (2) use a command-line switch to override the default. I think we should skip the command-line thing, and just say that at installation time, the app is configured with the location of the local-files file, which must stay there forever (for as long as a particular installation is to work), which bootstraps into where the other local files are. Hence, I think the only thing the the installation-time-established "known" file needs to have in it is whatever info is settable by the Local Files command, i.e., either just a directory path or a table that defines one-by-one where each necessary file is; I'm leaning towards the former right about now, not the least reason for such leaning being simplicity and cleanliness.