[Tcladdressbook-commits] Help TclAddressBookHelp,1.16,1.17

SourceForge Headquarters 1320 Columbia Street Suite 310 San Diego, CA 92101 +1 (858) 422-6466

Update of /cvsroot/tcladdressbook/Help
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv4522/Help

Modified Files:
	TclAddressBookHelp 
Log Message:
More [identifier] doc and examples

Index: TclAddressBookHelp
===================================================================
RCS file: /cvsroot/tcladdressbook/Help/TclAddressBookHelp,v
retrieving revision 1.16
retrieving revision 1.17
diff -u -d -r1.16 -r1.17

--- TclAddressBookHelp	29 Jul 2004 20:14:55 -0000	1.16
+++ TclAddressBookHelp	30 Jul 2004 13:07:58 -0000	1.17
@@ -5,7 +5,7 @@
 					Abstract
 
 This is a manual page for the Tcladdressbook extension for Tcl. It 
-documents version 1.1b2.
+documents version 1.1b3.
 
 
    1. NAME
@@ -20,7 +20,10 @@
           addressbook export personID
           addressbook getme ?-id?
           addressbook groups ?-ids? ?-ingroup groupID?
-          addressbook identifier personID groupID propName ?label?
+          addressbook identifier count personID propName
+          addressbook identifier get personID propName index
+          addressbook identifier primary personID propName
+          addressbook identifier set groupID personID propName ?ident?
           addressbook image personID ?imageData?
           addressbook import vCardData
           addressbook parents ?-ids? recordID
@@ -36,15 +39,16 @@
           addressbook set recordID propertyName ?value?
           addressbook setme recordID
           addressbook type recordID
-   5. INSTALLATION
-   6. VERSION HISTORY
-   7. REQUIREMENTS AND PORTABILITY
-   8. KNOW ISSUES
-   9. SOURCE CODE
-   10. CONTRIBUTIONS
-   11. LICENSE AND DISCLAIMER
-   12. SEE ALSO
-   13. KEYWORDS
+   5. DISTRIBUTION LIST AND IDENTIFIERS
+   6. INSTALLATION
+   7. VERSION HISTORY
+   8. REQUIREMENTS AND PORTABILITY
+   9. KNOW ISSUES
+   10. SOURCE CODE
+   11. CONTRIBUTIONS
+   12. LICENSE AND DISCLAIMER
+   13. SEE ALSO
+   14. KEYWORDS
 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 
 
@@ -120,22 +124,44 @@
 -ingroup option is specified, only the subgroups contained in the group
 with ID groupID will be returned.
 
- addressbook identifier personID groupID propName ?label?
+ addressbook identifier count personID propName
+This command returns the number of items in a multi-value list property
+(such as Phone, Email, MSNInstant etc.). 
+
+ addressbook identifier get personID propName index
+This command gets the unique identifier of an item in a multi-value list
+property (such as Phone, Email). It returns the identifier of the
+item at index index in the multi-value list of property 
+propName for the record corresponding to personID. One can
+get the count of identifiers using the addressbook identifier count
+command. Identifiers are used by the addressbook identifier set
+command. See the section Distribution list and identifiers <#dist> 
+below for explanations about identifiers.
+
+ addressbook identifier primary personID propName
+This command returns the primary identifier of property propName in
+the record personID. This is the identifier which will be used by
+default if no distribution identifier has been specified using the
+addressbook identifier set command. Property propName must
+be a multi-value list property (such as Phone, Email).
+
+ addressbook identifier set groupID personID propName ?ident?
 This command lets you get or set the distribution identifier for a
-multi-value list property of a person in a group. 
- Used without a label argument, this will return the
+multi-value list property of a person in a group. See the section
+Distribution list and identifiers <#dist> below for 
+explanations about identifiers.
+ Used without the ident argument, the command will return the
 distribution identifier for the person personID belonging to the
 group groupID concerning property propName if it was set,
-otherwise the property¹s primary identifier. Property propName must
-be a multi-value list property
- If the label argument is specified, this will assign a
-specific distribution identifier for the person¹s multi-value list property
-so that the group can be used as a distribution list (a mailing list for
-instance, in the case of an email property). This value must be a label
-used by the multi-value list (such as home for an address
-property). If label is an empty string, this command resets the
-distribution identifier to its default, i-e the multi-value list¹s primary
-identifier.
+otherwise the property's primary identifier. Property propName must
+be a multi-value list property (such as Phone, Email).
+ If the ident argument is specified, this will assign a
+specific distribution identifier for the person's multi-value list
+property so that the group can be used as a distribution list (a mailing
+list for instance, in the case of an email property). This value must be a
+valid identifier used by the multi-value list: one can get the identifiers
+of any element of a multi-value list using the addressbook identifier
+get command.
 
  addressbook image personID ?imageData?
 If no imageData argument is specified, this command returns the
@@ -323,8 +349,24 @@
 This command returns the type (ABPerson or ABGroup) of the record with 
 unique ID recordID.
 
+ 
+5. DISTRIBUTION LIST AND IDENTIFIERS
+Identifiers are necessary when one wants to use a group as a distribution
+list, that is send something to all the members of the group. The members
+can be addressed by Phone, Email etc. For instance, a group could
+be used as a mailing list. The Phone, Email properties are
+multi-value list properties: since a person can have several e-mail
+addresses, one must specify which one is to be used in the distribution list.
+Labels (such as Home, Work etc.) are not sufficient to specify precisely an
+e-mail because they are not unique: one can have several e-mails with the
+label Work. Here the identifiers come in: each value of a multi-value list
+property has an identifier. One of them can be designated as the distribution identifier. The AddressBook database also has a notion of
+a primary identifier: it is the identifier which will be used by
+default by the distribution list if no distribution identifier as
+been specified.
 
-5. INSTALLATION
+
+6. INSTALLATION
 The extension is made of two files: the dynamic library (called
 addressbook1.0.dylib in version 1.0) and a file pkgIndex.tcl necessary for
 Tcl to be able to locate the extension upon request. Both files are
@@ -337,28 +379,30 @@
 application. 
 
 
-6. VERSION HISTORY
+7. VERSION HISTORY
      1.0b1 -- 2004/01/25 -- First public release.
      1.1b1 -- 2004/07/28 -- New commands [add] and [remove]. Modified
-[delete] command. New command [identifier]. Modified [property remove]
+[delete] command. Modified [property remove]
 command.
      1.1b2 -- 2004/07/29 -- New command [setme].
+     1.1b3 -- 2004/07/30 -- New command [identifier] to handle 
+distribution lists.
 
 
 
-7. REQUIREMENTS AND PORTABILITY
+8. REQUIREMENTS AND PORTABILITY
 This extension is only useful on Macintosh platforms. Version 10.2 or
 greater of the system is required: the AddressBook framework was introduced
 in version 10.2 of the System (aka Jaguar).
 
 
-8. KNOW ISSUES
+9. KNOW ISSUES
 Tcladdressbook was written by Bernard Desgraupes. 
 Please e-mail any bug or problem you encounter: 
 <bde...@us...>
 
 
-9. SOURCE CODE
+10. SOURCE CODE
 Tcladdressbook is an Open Source Project. Its source code is public and can 
 be found on the SourceForge site at the following address:
  <http://sourceforge.net/projects/tcladdressbook>
@@ -375,29 +419,29 @@
  You can also browse the cvs repository online at
  <http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/tcladdressbook> 
 
-10. CONTRIBUTIONS
+11. CONTRIBUTIONS
 Code contributions (Tcl scripts making use of the Tcladdressbook extension)
 are very welcome. There is a "Contribs"  directory  in  the  Tcladdressbook
 project on SourceForge for code contributions. They must be free  software,
 distributed under an Open Source license acceptable by the SourceForge site
 (for instance, the same licensing terms as the Tcl language itself).
 
-11. LICENSE AND DISCLAIMER
+12. LICENSE AND DISCLAIMER
 This software is free software and distributed under the same licensing terms 
 as the Tcl language itself. See license.terms in the Tcl distribution.
 
  © Copyright Bernard Desgraupes 2003-2004
 
-12. SEE ALSO
+13. SEE ALSO
 See the TclX extension for  keyed  lists: TclX(n).  See  the  Mk4Tcl  extension  for
 commands to open directly the database file.
 
-13. KEYWORDS
+14. KEYWORDS
 Address book, data base.
 
 
 ----------------------------------------------------------------------
- Last updated 2004-07-29 22:00:33
+ Last updated 2004-07-30 14:44:48
 
 
 



