Identities Help

Name:	Identities
Version:	0.5
Last update:	2020-06-16 10:49:12

This package allows you to create multiple identities when using Alpha. Inspect the Alpha ↣ Preferences ↣ Identities menu for the commands which allow you to create new and edit current identities. These identities are used by other AlphaTcl features to create window templates, such as the package Document Projects.
This feature was designed to make it easier for other AlphaTcl packages share information amongst each other, such as the name of the current project defined by the package Document Projects, or the path/name of the active window. This information is often used in electric templates. Click here to see what is currently available.

Identity settings

Click on this hyperlink to create a new identity. Alpha will offer to pre-fill the identity fields using an entry from the OS X AddressBook.
Click on this hyperlink to change the settings of an identity. Use the dialog's popup menu to select an identity.
Once you have defined multiple identities, the current one is marked in the Alpha ↣ Preferences ↣ Identities menu. Selecting a different identity will make that one current.
You don't need to suffer from any multiple personality disorder in order to make use of multiple identities. You might use the same author name, but work on projects for different organisations, with different e-mail addresses or contact information...
Note: There always exists one Default identity; you can edit its values but you cannot delete it.
The menu item called "Set from AddressBook" lets you set the fields of an identity using a record in the OS X AddressBook.

Developers help

Here is more information for developers about how to use this package in their own code.
The identities package is an always-on package (the user will never be offered this package in the list of those which can be uninstalled). It creates the Alpha ↣ Preferences ↣ Identities submenu, allowing the user to define Default identity information, and to create new identities. Source code is in the identities.tcl file.
The proc [userInfo::getInfo] is the preferred method for obtaining user information, specifying one of the six default fields:

author

organisation

address

email

www

author_initials

When the user adjusts the Current Identity using the Alpha ↣ Preferences submenu, this will automatically update [userInfo::getInfo] results. Note that both the email and www fields will always be returned _without_ any angle brackets, even if the user included them in the preference values.
This library also makes it easier for different packages to add their own user information fields beyond those listed above, information that a third package might want to use, by using the proc [userInfo::addInfo] .
For example, the package Document Projects will define a license owner or license organisation related to the user's current project, and these could be used by the package Electric Menu to insert user-specific license templates into the active window. This could be done with

userInfo::addInfo "owner_org" "Princeton University"

The code which creates the template could then use

userInfo::getInfo "owner_org" [userInfo::getInfo "organisation"]

to obtain this information, defaulting to the primary organisation defined by the user's identity. Using this protocol, the license template procedure doesn't need to be aware of the activation of Document Projects and simply accepts whatever information is available. This allows AlphaTcl packages to be more agnostic about the existence of their brethren, reducing package dependencies and the need to constantly rename procedures in order to ensure that the proper information is passed back and forth among them.
As an example, here is how you could define a new year field:

userInfo::addInfo "year" [clock format [clock seconds] -format "%Y"]

By the way, the identities package maintains two fields called tail and path which are always set to the tail and path of the active window.
Click here to see what is currently available.
Two global variables are created by this package:

identity	the name of the Current Identity
identities	an array of all identity information

These variables should, however, be considered internal to this package. Again, only the procedures

should be called outside of the identities.tcl file.

Known problems

Please report any problem or bug you encounter to Alpha's Bug Tracker.

License and Disclaimer

Copyright (c) 2005-2020, Craig Barton Upright.
All rights reserved.
The identities package is free software and distributed under the terms of the new BSD license:
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
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.
Neither the name of Craig Barton Upright nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS 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 CRAIG BARTON UPRIGHT 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.