[Tcladdressbook-commits] Help TclAddressBookHelp.html,1.20,1.21

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-serv31667/Help

Modified Files:
	TclAddressBookHelp.html 
Log Message:
Doc and examples for the [identifier index] command

Index: TclAddressBookHelp.html
===================================================================
RCS file: /cvsroot/tcladdressbook/Help/TclAddressBookHelp.html,v
retrieving revision 1.20
retrieving revision 1.21
diff -u -d -r1.20 -r1.21

--- TclAddressBookHelp.html	30 Jul 2004 13:08:26 -0000	1.20
+++ TclAddressBookHelp.html	30 Jul 2004 21:31:13 -0000	1.21
@@ -8,7 +8,7 @@
 <P><IMG SRC="Images/TclAB_logo.gif " ALT="TclAB Logo" ALIGN=bottom></P>
 <P> <A HREF="TclAB.html"> Home Page</A> | <A HREF="http://sourceforge.net/projects/tcladdressbook"> Project Page at SourceForge</A><P><HR><BLOCKQUOTE><P><I> 
 This is a manual page for the Tcladdressbook extension for Tcl. It 
-documents version 1.1b3.
+documents version 1.1b4.
 </I></P></BLOCKQUOTE><HR>
 <UL>
 <LI><A HREF="#M1">NAME</A>
@@ -25,33 +25,34 @@
 <UL><UL><LI><A HREF="#M12">addressbook groups ?-ids? ?-ingroup <I>groupID</I>?</A></UL></UL>
 <UL><UL><LI><A HREF="#M13">addressbook identifier count <I>personID</I> <I>propName</I></A></UL></UL>
 <UL><UL><LI><A HREF="#M14">addressbook identifier get <I>personID</I> <I>propName</I> <I>index</I></A></UL></UL>
-<UL><UL><LI><A HREF="#M15">addressbook identifier primary <I>personID</I> <I>propName</I></A></UL></UL>
-<UL><UL><LI><A HREF="#M16">addressbook identifier set <I>groupID</I> <I>personID</I> <I>propName</I> ?<I>ident</I>?</A></UL></UL>
-<UL><UL><LI><A HREF="#M17">addressbook image <I>personID</I> ?<I>imageData</I>?</A></UL></UL>
-<UL><UL><LI><A HREF="#M18">addressbook import <I>vCardData</I></A></UL></UL>
-<UL><UL><LI><A HREF="#M19">addressbook parents ?-ids? <I>recordID</I></A></UL></UL>
-<UL><UL><LI><A HREF="#M20">addressbook persons ?-ids? ?-ingroup <I>groupID</I>?</A></UL></UL>
-<UL><UL><LI><A HREF="#M21">addressbook property names (-groups | -persons)</A></UL></UL>
-<UL><UL><LI><A HREF="#M22">addressbook property type (-groups | -persons) <I>propName</I></A></UL></UL>
-<UL><UL><LI><A HREF="#M23">addressbook property add (-groups | -persons) <I>propName</I> <I>propType</I></A></UL></UL>
-<UL><UL><LI><A HREF="#M24">addressbook property remove (-groups | -persons | recordID) <I>propName</I></A></UL></UL>
-<UL><UL><LI><A HREF="#M25">addressbook record <I>recordID</I></A></UL></UL>
-<UL><UL><LI><A HREF="#M26">addressbook remove <I>recordID</I> <I>groupID</I></A></UL></UL>
-<UL><UL><LI><A HREF="#M27">addressbook save</A></UL></UL>
-<UL><UL><LI><A HREF="#M28">addressbook search ?(-groups | -persons)? ?-ids? ?-nocase? <I>property op value</I></A></UL></UL>
-<UL><UL><LI><A HREF="#M29">addressbook set <I>recordID propertyName</I> ?<I>value</I>?</A></UL></UL>
-<UL><UL><LI><A HREF="#M30">addressbook setme <I>recordID</I></A></UL></UL>
-<UL><UL><LI><A HREF="#M31">addressbook type <I>recordID</I></A></UL></UL>
-<LI><A HREF="#M32">DISTRIBUTION LIST AND IDENTIFIERS</A>
-<LI><A HREF="#M33">INSTALLATION</A>
-<LI><A HREF="#M34">VERSION HISTORY</A>
-<LI><A HREF="#M35">REQUIREMENTS AND PORTABILITY</A>
-<LI><A HREF="#M36">KNOW ISSUES</A>
-<LI><A HREF="#M37">SOURCE CODE</A>
-<LI><A HREF="#M38">CONTRIBUTIONS</A>
-<LI><A HREF="#M39">LICENSE AND DISCLAIMER</A>
-<LI><A HREF="#M40">SEE ALSO</A>
-<LI><A HREF="#M41">KEYWORDS</A>
+<UL><UL><LI><A HREF="#M15">addressbook identifier index <I>personID</I> <I>propName</I> <I>ident</I></A></UL></UL>
+<UL><UL><LI><A HREF="#M16">addressbook identifier primary <I>personID</I> <I>propName</I> ?<I>ident</I>?</A></UL></UL>
+<UL><UL><LI><A HREF="#M17">addressbook identifier set <I>groupID</I> <I>personID</I> <I>propName</I> ?<I>ident</I>?</A></UL></UL>
+<UL><UL><LI><A HREF="#M18">addressbook image <I>personID</I> ?<I>imageData</I>?</A></UL></UL>
+<UL><UL><LI><A HREF="#M19">addressbook import <I>vCardData</I></A></UL></UL>
+<UL><UL><LI><A HREF="#M20">addressbook parents ?-ids? <I>recordID</I></A></UL></UL>
+<UL><UL><LI><A HREF="#M21">addressbook persons ?-ids? ?-ingroup <I>groupID</I>?</A></UL></UL>
+<UL><UL><LI><A HREF="#M22">addressbook property names (-groups | -persons)</A></UL></UL>
+<UL><UL><LI><A HREF="#M23">addressbook property type (-groups | -persons) <I>propName</I></A></UL></UL>
+<UL><UL><LI><A HREF="#M24">addressbook property add (-groups | -persons) <I>propName</I> <I>propType</I></A></UL></UL>
+<UL><UL><LI><A HREF="#M25">addressbook property remove (-groups | -persons | recordID) <I>propName</I></A></UL></UL>
+<UL><UL><LI><A HREF="#M26">addressbook record <I>recordID</I></A></UL></UL>
+<UL><UL><LI><A HREF="#M27">addressbook remove <I>recordID</I> <I>groupID</I></A></UL></UL>
+<UL><UL><LI><A HREF="#M28">addressbook save</A></UL></UL>
+<UL><UL><LI><A HREF="#M29">addressbook search ?(-groups | -persons)? ?-ids? ?-nocase? <I>property op value</I></A></UL></UL>
+<UL><UL><LI><A HREF="#M30">addressbook set <I>recordID propertyName</I> ?<I>value</I>?</A></UL></UL>
+<UL><UL><LI><A HREF="#M31">addressbook setme <I>recordID</I></A></UL></UL>
+<UL><UL><LI><A HREF="#M32">addressbook type <I>recordID</I></A></UL></UL>
+<LI><A HREF="#M33">DISTRIBUTION LISTS AND IDENTIFIERS</A>
+<LI><A HREF="#M34">INSTALLATION</A>
+<LI><A HREF="#M35">VERSION HISTORY</A>
+<LI><A HREF="#M36">REQUIREMENTS AND PORTABILITY</A>
+<LI><A HREF="#M37">KNOW ISSUES</A>
+<LI><A HREF="#M38">SOURCE CODE</A>
+<LI><A HREF="#M39">CONTRIBUTIONS</A>
+<LI><A HREF="#M40">LICENSE AND DISCLAIMER</A>
+<LI><A HREF="#M41">SEE ALSO</A>
+<LI><A HREF="#M42">KEYWORDS</A>
 </UL>
 <P><H2><A NAME="M1"></A>NAME</H2>
 addressbook - manipulate the Macintosh OSX Address Book database<P><H2><A NAME="M2"></A>SYNOPSIS</H2>
@@ -106,16 +107,27 @@
 <I>propName</I> for the record corresponding to <I>personID</I>. One can
 get the count of identifiers using the <B>addressbook identifier count</B>
 command. Identifiers are used by the <B>addressbook identifier set</B>
-command. See the section <A HREF="#dist">Distribution list and identifiers</A> 
-below for explanations about identifiers.<P><H4><A NAME="M15"></A>addressbook identifier primary <I>personID</I> <I>propName</I></H4>
-This command returns the primary identifier of property <I>propName</I> in
-the record <I>personID</I>. This is the identifier which will be used by
-default if no <I>distribution identifier</I> has been specified using the
-<B>addressbook identifier set</B> command. Property <I>propName</I> must
-be a multi-value list property (such as <I>Phone, Email</I>).<P><H4><A NAME="M16"></A>addressbook identifier set <I>groupID</I> <I>personID</I> <I>propName</I> ?<I>ident</I>?</H4>
+command. See the section <A HREF="#dist">Distribution lists and identifiers</A> 
+below for explanations about identifiers.<P><H4><A NAME="M15"></A>addressbook identifier index <I>personID</I> <I>propName</I> <I>ident</I></H4>
+This command returns the index in a multi-value list corresponding to the
+identifier given in the <I>ident</I> argument. If <I>ident</I> is not a
+valid identifier, the command raises an error. The valid identifers are the
+values obtained by the <B>addressbook identifier get</B> command.<P><H4><A NAME="M16"></A>addressbook identifier primary <I>personID</I> <I>propName</I> ?<I>ident</I>?</H4>
+This command lets you get or set the primary identifier of property 
+<I>propName</I> in the record <I>personID</I>. This is the identifier
+which will be used by default if no <I>distribution identifier</I> has
+been specified using the <B>addressbook identifier set</B> command.
+Property <I>propName</I> must be a multi-value list property (such as 
+<I>Phone, Email</I>). ((nl Used without the <I>ident</I> argument, the
+command will return the <I>primary identifier</I> concerning property 
+<I>propName</I> for the person <I>personID</I>.
+<P> If the <I>ident</I> argument is specified, the command will set the
+primary value to be the value for the given identifier <I>ident</I>. 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 <B>addressbook identifier get</B> command.<P><H4><A NAME="M17"></A>addressbook identifier set <I>groupID</I> <I>personID</I> <I>propName</I> ?<I>ident</I>?</H4>
 This command lets you get or set the <I>distribution identifier</I> for a
 multi-value list property of a person in a group. See the section
-<A HREF="#dist"> Distribution list and identifiers</A> below for 
+<A HREF="#dist"> Distribution lists and identifiers</A> below for 
 explanations about identifiers.
 <P> Used without the <I>ident</I> argument, the command will return the
 <I>distribution identifier</I> for the person <I>personID</I> belonging to the
@@ -128,36 +140,36 @@
 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 <B>addressbook identifier
-get</B> command.<P><H4><A NAME="M17"></A>addressbook image <I>personID</I> ?<I>imageData</I>?</H4>
+get</B> command.<P><H4><A NAME="M18"></A>addressbook image <I>personID</I> ?<I>imageData</I>?</H4>
 If no <I>imageData</I> argument is specified, this command returns the
 custom image associated with the record corresponding to the unique ID 
 <I>personID</I>. The returned bytes are binary data. If no image exists, it
 raises an error. If an <I>imageData</I> argument is specified, it should
 contain valid binary data defining an image which will be associated the
-record with unique ID <I>personID</I>.<P><H4><A NAME="M18"></A>addressbook import <I>vCardData</I></H4>
+record with unique ID <I>personID</I>.<P><H4><A NAME="M19"></A>addressbook import <I>vCardData</I></H4>
 This command imports data in VCard format. The data specified by the 
 <I>vCardData</I> argument must be valid data in VCard format: a new record is
 created in the database corresponding to the information contained in the
-VCard. Note that the data can be binary if the VCard contains an image.<P><H4><A NAME="M19"></A>addressbook parents ?-ids? <I>recordID</I></H4>
+VCard. Note that the data can be binary if the VCard contains an image.<P><H4><A NAME="M20"></A>addressbook parents ?-ids? <I>recordID</I></H4>
 This command returns a list of all the groups the record with unique ID 
 <I>recordID</I> belongs to. The elements of this list are sublists made of one
 or two items: the unique ID and, possibly, the name of the record if this
 field exists. If the <I>-ids</I> option is specified, only IDs are
-returned. <P><H4><A NAME="M20"></A>addressbook persons ?-ids? ?-ingroup <I>groupID</I>?</H4>
+returned. <P><H4><A NAME="M21"></A>addressbook persons ?-ids? ?-ingroup <I>groupID</I>?</H4>
 This command returns a list of all the existing person records: if no
 option is specified, it is a list whose elements are sublists made of one
 or two items: the unique ID and, possibly, the name of the record if this
 field exists. If the <I>-ids</I> argument is specified, the returned list
 will contain only the unique IDs. If the <I>-ingroup</I> option is
 specified, only the members belonging to the group with ID <I>groupID</I>
-will be returned.<P><H4><A NAME="M21"></A>addressbook property names (-groups | -persons)</H4>
+will be returned.<P><H4><A NAME="M22"></A>addressbook property names (-groups | -persons)</H4>
 This command returns a list of all the properties defined in the database
 for group or person records. New properties can be created or removed with
-the <B>addressbook property add</B> and <B>addressbook property remove</B> commands.<P><H4><A NAME="M22"></A>addressbook property type (-groups | -persons) <I>propName</I></H4>
+the <B>addressbook property add</B> and <B>addressbook property remove</B> commands.<P><H4><A NAME="M23"></A>addressbook property type (-groups | -persons) <I>propName</I></H4>
 This command returns the type of the property specified by the
 <I>propName</I> argument. The returned type is one of the values
 listed with the <B>addressbook property add</B> command below 
-or <I>Unknown</I>. <P><H4><A NAME="M23"></A>addressbook property add (-groups | -persons) <I>propName</I> <I>propType</I></H4>
+or <I>Unknown</I>. <P><H4><A NAME="M24"></A>addressbook property add (-groups | -persons) <I>propName</I> <I>propType</I></H4>
 This command lets you add a new property to the database, either for person
 or for group records. The name of the new property is specified by the 
 <I>propName</I> argument: it must be unique. One can get the list of all the
@@ -165,7 +177,7 @@
 The type of the property is specified by the <I>propType</I> argument.
 This argument can have one of the following values: <I>Array, Data, Date,
 Dictionary, Integer, Real, String, MultiArray, MultiData, MultiDate,
-MultiDictionary, MultiInteger, MultiReal, MultiString.</I><P><H4><A NAME="M24"></A>addressbook property remove (-groups | -persons | recordID) <I>propName</I></H4>
+MultiDictionary, MultiInteger, MultiReal, MultiString.</I><P><H4><A NAME="M25"></A>addressbook property remove (-groups | -persons | recordID) <I>propName</I></H4>
 This command lets you remove a property from the database, either for
 person or for group records. The name of the property is specified in the
 <I>propName</I> argument. If the third argument is either <B>-groups</B> or
@@ -176,7 +188,7 @@
 property is removed for this record only and the command returns an 
 empty string.
 <P> One can get the list of all the existing
-properties with the <B>addressbook property names</B> command.<P><H4><A NAME="M25"></A>addressbook record <I>recordID</I></H4>
+properties with the <B>addressbook property names</B> command.<P><H4><A NAME="M26"></A>addressbook record <I>recordID</I></H4>
 This command returns all the data available in the database concerning
 the record with unique ID <I>recordID</I>.  The returned value
 takes the form of a keyed list.
@@ -206,16 +218,16 @@
 00:00:00 CET 1970".
 <P> Note that keyed lists can be easily manipulated 
 using the <B>keylget</B> and <B>keylset</B> commands defined in the TclX 
-extension.<P><H4><A NAME="M26"></A>addressbook remove <I>recordID</I> <I>groupID</I></H4>
+extension.<P><H4><A NAME="M27"></A>addressbook remove <I>recordID</I> <I>groupID</I></H4>
 This command lets you remove an already existing item (person or group) 
 designated by its unique ID <I>recordID</I> from the group with ID 
-<I>groupID</I>.<P><H4><A NAME="M27"></A>addressbook save</H4>
+<I>groupID</I>.<P><H4><A NAME="M28"></A>addressbook save</H4>
 This command lets you save the changes made in the database. Commands such
 as <B>addressbook set</B>, <B>addressbook create</B> or <B>addressbook
 delete</B> modify the data in memory: to make the changes definitive in the
 database, one must call explicitely the <B>addressbook save</B> command.
 To check whether there has been changes in the database, use the 
-<B>addressbook changed</B> command.<P><H4><A NAME="M28"></A>addressbook search ?(-groups | -persons)? ?-ids? ?-nocase? <I>property op value</I></H4>
+<B>addressbook changed</B> command.<P><H4><A NAME="M29"></A>addressbook search ?(-groups | -persons)? ?-ids? ?-nocase? <I>property op value</I></H4>
 This command returns all the records corresponding to the criterion 
 described by the last three arguments:
 <UL>
@@ -271,18 +283,18 @@
 that no distinction be made between uppercase and lowercase letters.
 <P> To get a list of all possible properties, use the <B>addressbook 
 property names</B> command. To know the type of a particular property, use 
-the <B>addressbook property type</B> command.<P><H4><A NAME="M29"></A>addressbook set <I>recordID propertyName</I> ?<I>value</I>?</H4>
+the <B>addressbook property type</B> command.<P><H4><A NAME="M30"></A>addressbook set <I>recordID propertyName</I> ?<I>value</I>?</H4>
 This command lets you get or set the value of a particular property for the
 record with unique ID <I>recordID</I>. If the <I>value</I> argument is
 not specified, it returns the current value of the property specified in
 the <I>propertyName</I> argument. If <I>value</I> is specified, the
 property <I>propertyName</I> will be set to this value. See the 
 <B>addressbook record</B> command for a description of the format used for the
-various kinds of properties.<P><H4><A NAME="M30"></A>addressbook setme <I>recordID</I></H4>
-This command sets the record that represents the logged-in user. <P><H4><A NAME="M31"></A>addressbook type <I>recordID</I></H4>
+various kinds of properties.<P><H4><A NAME="M31"></A>addressbook setme <I>recordID</I></H4>
+This command sets the record that represents the logged-in user. <P><H4><A NAME="M32"></A>addressbook type <I>recordID</I></H4>
 This command returns the type (<I>ABPerson</I> or <I>ABGroup</I>) of the record with 
 unique ID <I>recordID</I>.<P><A NAME="dist"></A>
-<H2><A NAME="M32"></A>DISTRIBUTION LIST AND IDENTIFIERS</H2>
+<H2><A NAME="M33"></A>DISTRIBUTION LISTS AND IDENTIFIERS</H2>
 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 <I>Phone, Email</I> etc. For instance, a group could
@@ -295,7 +307,7 @@
 property has an identifier. One of them can be designated as the <I>distribution identifier</I>. The AddressBook database also has a notion of
 a <I>primary identifier</I>: it is the identifier which will be used by
 default by the distribution list if no <I>distribution identifier</I> as
-been specified.<P><H2><A NAME="M33"></A>INSTALLATION</H2>
+been specified.<P><H2><A NAME="M34"></A>INSTALLATION</H2>
 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
@@ -305,7 +317,7 @@
 <B>auto_path</B> Tcl variable. If you use the extension within the AlphaX
 editor (version 8.0b11 or greater), you can also install it in the 
 <I>Tclextensions</I> folder which is located at the same level as the
-application. <P><H2><A NAME="M34"></A>VERSION HISTORY</H2>
+application. <P><H2><A NAME="M35"></A>VERSION HISTORY</H2>
 <UL>
 	<LI> 1.0b1 -- 2004/01/25 -- First public release.
 	<LI> 1.1b1 -- 2004/07/28 -- New commands [add] and [remove]. Modified
@@ -314,13 +326,13 @@
 	<LI> 1.1b2 -- 2004/07/29 -- New command [setme].
 	<LI> 1.1b3 -- 2004/07/30 -- New command [identifier] to handle 
 distribution lists.
-</UL><P><H2><A NAME="M35"></A>REQUIREMENTS AND PORTABILITY</H2>
+</UL><P><H2><A NAME="M36"></A>REQUIREMENTS AND PORTABILITY</H2>
 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).<P><H2><A NAME="M36"></A>KNOW ISSUES</H2>
+in version 10.2 of the System (aka Jaguar).<P><H2><A NAME="M37"></A>KNOW ISSUES</H2>
 Tcladdressbook was written by Bernard Desgraupes. 
 Please e-mail any bug or problem you encounter: 
-<A HREF="mailto:bde...@us...">bde...@us...</A><P><H2><A NAME="M37"></A>SOURCE CODE</H2>
+<A HREF="mailto:bde...@us...">bde...@us...</A><P><H2><A NAME="M38"></A>SOURCE CODE</H2>
 Tcladdressbook is an Open Source Project. Its source code is public and can 
 be found on the SourceForge site at the following address:
 <P> <A HREF="http://sourceforge.net/projects/tcladdressbook">http://sourceforge.net/projects/tcladdressbook</A><P><P> Tcladdressbook binary releases are available at
@@ -329,17 +341,17 @@
 <P>  <A HREF="http://webperso.easyconnect.fr/bdesgraupes/tcl.html">http://webperso.easyconnect.fr/bdesgraupes/tcl.html</A><P><P> The code is under CVS control. You can retrieve the latest stage of 
 development using any CVS client. See instructions at:
 <P> <A HREF="http://sourceforge.net/cvs/?group_id=96169">http://sourceforge.net/cvs/?group_id=96169</A><P><P> You can also browse the cvs repository online at
-<P> <A HREF="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/tcladdressbook">http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/tcladdressbook</A> <P><H2><A NAME="M38"></A>CONTRIBUTIONS</H2>
+<P> <A HREF="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/tcladdressbook">http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/tcladdressbook</A> <P><H2><A NAME="M39"></A>CONTRIBUTIONS</H2>
 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).<P><H2><A NAME="M39"></A>LICENSE AND DISCLAIMER</H2>
+(for instance, the same licensing terms as the Tcl language itself).<P><H2><A NAME="M40"></A>LICENSE AND DISCLAIMER</H2>
 This software is free software and distributed under the same licensing terms 
-as the Tcl language itself. See license.terms in the Tcl distribution.<P><P> © Copyright Bernard Desgraupes 2003-2004<P><H2><A NAME="M40"></A>SEE ALSO</H2>
+as the Tcl language itself. See license.terms in the Tcl distribution.<P><P> © Copyright Bernard Desgraupes 2003-2004<P><H2><A NAME="M41"></A>SEE ALSO</H2>
 See the TclX extension for  keyed  lists: TclX(n).  See  the  Mk4Tcl  extension  for
-commands to open directly the database file.<P><H2><A NAME="M41"></A>KEYWORDS</H2>
+commands to open directly the database file.<P><H2><A NAME="M42"></A>KEYWORDS</H2>
 Address book, data base.<P><HR>
-<P> Last updated 2004-07-30 14:43:34<P>
+<P> Last updated 2004-07-30 23:21:29<P>
 </BODY>
 </HTML>
\ No newline at end of file



