[Tcladdressbook-commits] Help TclAB_QuickStart.html,1.3,1.4

[<bde...@us...>]

Update of /cvsroot/tcladdressbook/Help
In directory sc8-pr-cvs1:/tmp/cvs-serv3346/Help

Modified Files:
	TclAB_QuickStart.html 
Log Message:
Update syntax before beta

Index: TclAB_QuickStart.html
===================================================================
RCS file: /cvsroot/tcladdressbook/Help/TclAB_QuickStart.html,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -d -r1.3 -r1.4
--- TclAB_QuickStart.html	28 Dec 2003 07:47:18 -0000	1.3
+++ TclAB_QuickStart.html	5 Jan 2004 05:38:25 -0000	1.4
@@ -12,14 +12,14 @@
 <!--  :Author:		Bernard Desgraupes <A HREF="mailto:bde...@ea...">bde...@ea...</A> -->
 <!--  :Homepage:		<A HREF="http://webperso.easyconnect.fr/bdesgraupes/">http://webperso.easyconnect.fr/bdesgraupes/</A> -->
 <!--  :Created: 		2003-12-14 18:26:47 -->
-<!-- :Modified:	 	2003-12-16 11:47:23 -->
+<!-- :Modified:	 	2004-01-04 21:10:51 -->
 <!--  :Keywords:		Address book, data base -->
 <!-- :TclCmd:                set currentversion [package require addressbook] --><P><!--  logo -->
 <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 file is a tutorial that demonstrates the [addressbook] command 
-defined by the Tcladdressbook extension for Tcl. It 
-documents version 1.0d12.
+defined by the Tcladdressbook extension for Tcl. It documents 
+version 1.0d12.
 For a detailed and complete description of the syntax of each subcommand, 
 refer to the <A href="TclAddressBookHelp.html">help file</A>.
 </I></P></BLOCKQUOTE><HR>
@@ -31,10 +31,10 @@
 <UL><LI><A HREF="#M5">The [getme] command</A></UL>
 <UL><LI><A HREF="#M6">The [record] command</A></UL>
 <UL><LI><A HREF="#M7">The [type] command</A></UL>
-<UL><LI><A HREF="#M8">The [property names] command</A></UL>
-<UL><LI><A HREF="#M9">The [remove] command</A></UL>
-<UL><LI><A HREF="#M10">The [parents] command</A></UL>
-<UL><LI><A HREF="#M11">The [create] command</A></UL>
+<UL><LI><A HREF="#M8">The [remove] command</A></UL>
+<UL><LI><A HREF="#M9">The [parents] command</A></UL>
+<UL><LI><A HREF="#M10">The [create] command</A></UL>
+<UL><LI><A HREF="#M11">The [property names] command</A></UL>
 <UL><LI><A HREF="#M12">The [property type] command</A></UL>
 <UL><LI><A HREF="#M13">The [property add] command</A></UL>
 <UL><LI><A HREF="#M14">The [property remove] command</A></UL>
@@ -49,15 +49,15 @@
 	package require addressbook
 </PRE><P><H2><A NAME="M1"></A> Using the commands</H2>
 <H3><A NAME="M2"></A> The [groups] command</H3>
-List the groups (name and ID)
+List all the groups (ID and name)
 <PRE>
 	addressbook groups
 </PRE>
-List the groups (only ID)
+List all the groups (only ID)
 <PRE>
 	addressbook groups -ids
 </PRE>
-List the subgroups of a specific group (name and ID)
+List the subgroups of a specific group (ID and name)
 <PRE>
 	set groupid [lindex [addressbook groups -ids] 2]
 	addressbook groups -ingroup $groupid
@@ -66,68 +66,49 @@
 <PRE>
 	addressbook groups -ids -ingroup $groupid
 </PRE><P><H3><A NAME="M3"></A> The [persons] command</H3>
-List the person records (name and ID)
+List all the persons records (ID and name)
 <PRE>
 	addressbook persons
 </PRE>
-List the person records (only ID)
+List all the persons records (only ID)
 <PRE>
 	addressbook persons -ids
 </PRE><P><H3><A NAME="M4"></A> The [count] command</H3>
-Count the existing groups and person records
+Count the existing groups and persons records
 <PRE>
 	addressbook count -groups
 	addressbook count -persons
 	addressbook count -persons -ingroup [lindex [addressbook groups -ids] 0]
 </PRE><P><H3><A NAME="M5"></A> The [getme] command</H3>
-Store the info about "me" in the variable myrecord. 
+Store the info about "me" in the variable <I>myrecord</I>. 
 <PRE>
 	set myrecord [addressbook getme]
 </PRE>
-The value of myrecord is a keyed list. One can use the usual Tcl list 
-commands or the special keylist commands defined in the TclX extension
-like this:
-<PRE>
-	keylkeys myrecord
-	keylget myrecord Email.work
-	keylget myrecord Address.home.ZIP
-	clock format [keylget myrecord Birthday]
-</PRE><P><H3><A NAME="M6"></A> The [record] command</H3>
-Store the ID of the first record in the variable theid
+The value of <I>myrecord</I> is a keyed list. One can use the usual Tcl list 
+commands to parse this value or special commands defined in the TclX 
+extension (see section <I>Using keyed lists</I> below).<P><H3><A NAME="M6"></A> The [record] command</H3>
+Store the ID of the first record in the variable <I>theid</I>
 <PRE>
 	set theid [lindex [addressbook persons -ids] 0]
 </PRE>
-Store the info about this record in the variable "person". The syntax is 
-the same as with the [getme] command.
+Store the info about this record in the variable <I>person</I>. The 
+returned value has the same keyed list format as with the [getme] command.
 <PRE>
 	set person [addressbook record $theid]
-	keylkeys person
-	keylget person Email.work
-	keylget person Address.home.ZIP
-	clock format [keylget person Birthday]
-</PRE><P>Store the ID of the first group in the variable theid
+</PRE><P>Similarly with a group: store the ID of the first group in the variable <I>theid</I>
 <PRE>
 	set theid [lindex [addressbook groups -ids] 0]
 </PRE>
-Store the info about this group in the variable grp and display the
- results with the [parray] command
+Store the info about this group in the variable <I>grp</I>
 <PRE>
 	set grp [addressbook record $theid]
-	keylkeys grp
-	keylget grp GroupName
-	clock format [keylget grp Modification]
 </PRE><P><H3><A NAME="M7"></A> The [type] command</H3>
-Find the type (ABPerson or ABGroup) of the object corresponding 
-to the ID $theid
+Find the type (<I>ABPerson</I> or <I>ABGroup</I>) of the object corresponding 
+to the ID <I>$theid</I>
 <PRE>
 	addressbook type $theid
-</PRE><P><H3><A NAME="M8"></A> The [property names] command</H3>
-Get the list of all existing properties for groups or persons
-<PRE>
-	addressbook property names -groups
-	addressbook property names -persons
-</PRE><P><H3><A NAME="M9"></A> The [remove] command</H3>
-Remove the record corresponding to the ID $theid from the database
+</PRE><P><H3><A NAME="M8"></A> The [remove] command</H3>
+Remove from the database the record corresponding to the ID <I>$theid</I>
 <PRE>
 	addressbook delete $theid
 </PRE>
@@ -138,16 +119,15 @@
 Save the changes to make them permanent
 <PRE>
 	addressbook save
-</PRE><P>Remove the record corresponding to the ID $theid from a specific group: 
+</PRE><P>Remove from a specific group the record corresponding to the ID <I>$theid</I>: 
 it is removed as member of this subgroup but will be removed from the 
 database only if it does not belong to other groups.
 <PRE>
 	set groupid [lindex [addressbook groups -ids] 0]
 	set theid [lindex [addressbook persons -ids] 0]
 	addressbook delete $theid -fromgroup $groupid
-</PRE><P><H3><A NAME="M10"></A> The [parents] command</H3>
+</PRE><P><H3><A NAME="M9"></A> The [parents] command</H3>
 List the parents of a person record (the various groups it belongs to). 
-One can also find the parents of a group with this command.
 <PRE>
 	set theid [lindex [addressbook persons -ids] 0]
 	addressbook parents $theid
@@ -155,33 +135,40 @@
 List the parents of a person record (only ID)
 <PRE>
 	addressbook parents -ids $theid
-</PRE><P><H3><A NAME="M11"></A> The [create] command</H3>
- (group|person)<P><H3><A NAME="M12"></A> The [property type] command</H3>
-Get the name of a particular property
+</PRE><P>One can also find the parents of a group using this command.<P><H3><A NAME="M10"></A> The [create] command</H3>
+ (group|person)<P><H3><A NAME="M11"></A> The [property names] command</H3>
+Get the list of all existing properties for groups or for persons
+<PRE>
+	addressbook property names -groups
+	addressbook property names -persons
+</PRE><P><H3><A NAME="M12"></A> The [property type] command</H3>
+Get the type of a particular property
 <PRE>
 	addressbook property type -groups UID
 	addressbook property type -persons Address
-</PRE><P><H3><A NAME="M13"></A> The [property add] command</H3>
-Add a new property of type String called Instrument
+</PRE>
+For the two examples above, the result is respectively 
+<I>String</I> and <I>MultiDictionary</I>.<P><H3><A NAME="M13"></A> The [property add] command</H3>
+Add a new person's property called <I>Instrument</I> with type <I>String</I>
 <PRE>
 	addressbook property add -persons Instrument String
-</PRE><P>Add a new property of type Date called Meeting
+</PRE><P>Add a new group's property called <I>Meeting</I> with type <I>Date</I>
 <PRE>
 	addressbook property add -groups Meeting Date
 </PRE><P><H3><A NAME="M14"></A> The [property remove] command</H3>
-Remove the properties created above
+Remove the properties created above:
 <PRE>
 	addressbook property remove -persons Instrument
 	addressbook property remove -groups Meeting
 </PRE><P><H3><A NAME="M15"></A> The [export] command</H3>
-Create a VCard corresponding to a particular record.
+Create a VCard corresponding to a particular record:
 <PRE>
 	set theid [lindex [addressbook persons -ids] 0]
-</PRE>
-The data returned is binary. You can store it in a file.
-<PRE>
 	set vcardData [addressbook export $theid]
-</PRE><P><H3><A NAME="M16"></A> The [import] command</H3>
+</PRE>
+The data returned is binary. You can store it in a file for instance.<P><H3><A NAME="M16"></A> The [import] command</H3>
+Import in the database some information stored in a .vcf file. A new 
+record containing this info, is created in the database:
 <PRE>
 	set fname [file join /Users bernardo someVcard.vcf]
 	set fid [open $fname r]
@@ -189,69 +176,110 @@
 	close $fid
 	addressbook import $vcard
 </PRE><P><H3><A NAME="M17"></A> The [image] command</H3>
+Get the custom image corresponding to a particular record:
 <PRE>
 	set theid [lindex [addressbook persons -ids] 0]
 	set img [addressbook image $theid]
-</PRE><P><H3><A NAME="M18"></A> The [set] command</H3>
+</PRE>
+The data returned is binary. You can store it in a file for instance.
+An error is raised if there is no custom image for this record.<P><H3><A NAME="M18"></A> The [set] command</H3>
+This command lets you get or set the value of a particular field. For 
+instance, to get the first name, dates and address fields of the first record:
 <PRE>
 	set theid [lindex [addressbook persons -ids] 0]
 	addressbook set $theid First
-</PRE><P><PRE>
+	addressbook set $theid ABDate
+	addressbook set $theid Address
+</PRE>
+To change the first name of the first record:
+<PRE>
 	addressbook set $theid First Georgios
 	addressbook changed
 	addressbook save
-</PRE><P><PRE>
-	addressbook set $theid First Johann-Sebastian
 </PRE>
-<!--      Multi string value -->
+Note that the <B>addressbook save</B> command must be invoked to make the changes 
+permanent. 
+<P> When setting the value of a field it is important that the new value 
+be formatted correctly with respect to the type of the property, as explained 
+in the <A href="TclAddressBookHelp.html">help file</A>. Here are a few 
+examples corresponding to various property types:
+<UL>
+	<LI> Multi string value
 <PRE>
-	addressbook set $theid Email {{Work wo...@ha...} {Concerts DD...@su...}}
-	addressbook set $theid Email {{Work op...@or...} {Concerts BW...@CA...}}
-</PRE><P><!--      Date value -->
+	addressbook set $theid Email {{Work BW...@ha...} {Concerts op...@so...}}
+</PRE>
+ 
+	<LI> Date value
 <PRE>
 	addressbook set $theid Birthday [clock scan "1 Apr 1985"]
-</PRE><P><!--      Multi date value -->
+</PRE><P>	<LI> Multi date value
 <PRE>
-	addressbook set $theid ABDate
 	addressbook set $theid ABDate [list [list "birthday Franny" 621597600] [list "birthday Zooey" 816692400]]
-</PRE><P><!--      Multi dictionary value -->
-<PRE>
-	addressbook set $theid Address
-	addressbook set $theid Address [list [list Home [list {CountryCode fr} {City Paris} {Country France} {ZIP 75001} {Street "1, avenue de l'Opéra"}] ] ]
-</PRE><P><H3><A NAME="M19"></A> The [search] command</H3>
+</PRE><P>	<LI> Multi dictionary value
 <PRE>
-	addressbook search -persons -ids -nocase Last == "Bach"
+	addressbook set $theid Address [list [list Home [list {CountryCode fr} {City Paris} {Country France} {ZIP 75001} {Street "1, avenue de l'Opéra"}]]]
+</PRE><P></UL><P><H3><A NAME="M19"></A> The [search] command</H3>
+This command can be used to report the IDs of the records corresponding to 
+a single criterion. The criterion is expressed by a three elements list: 
+the first element is the name of a property, the second is a comparison operator and 
+the third is the value to search for. Refer to the help file for a complete 
+description of the possible comparison operators. A few options are available 
+(-persons, -ids and -nocase). Here are a few simple examples:<P><PRE>
+	addressbook search Last == "Bach"
 	addressbook search -persons -ids -nocase Last > "Ba"
-</PRE><P><PRE>
-	addressbook search -persons -nocase Modification >= 1070199949
-	addressbook search -persons -nocase Modification < 1070199949
-</PRE><P><!--      Multi string value. It searches one value at a time. -->
+	addressbook search -persons Modification >= 1070199949
+	addressbook search -persons Modification < 1070199949
+</PRE><P><P> When searching on a particular property, it is important that the 
+searched value be formatted correctly with respect to the type of the property, 
+as explained in the <A href="TclAddressBookHelp.html">help file</A>. Specify 
+an empty label or an empty key to search on all possible labels or keys 
+respectively. Here are a few examples corresponding to various property types:
+<UL>
+	<LI> Multi string value. This instruction searches one value at a time.
 <PRE>
 	addressbook search -persons Phone == {Work "01 02 03 04 05"}
 </PRE>
-<!--      Empty label --&gt; to search on all phones -->
+	<LI> Empty label to search on all phone numbers
 <PRE>
 	addressbook search -persons Phone >= {"" "01 02 03 04 05"}
-</PRE><P><!--      Multi dict value. It searches one key in one dictionary at a time. -->
+</PRE>
+	<LI> Multi dictionary value. This instruction searches one key 
+in one dictionary at a time.
 <PRE>
 	addressbook search -persons -nocase Address == {Home {ZIP 98765}}
 	addressbook search -persons -nocase Address >= {Home {ZIP 98}}
 </PRE>
-<!--      Empty label --&gt; to search on all labels -->
+	<LI> Empty label to search on all labels
 <PRE>
 	addressbook search -persons -nocase Address >= {"" {City Paris}}
 </PRE>
-<!--      Empty key --&gt; to search on all keys -->
+	<LI> Empty key to search on all keys
 <PRE>
 	addressbook search -persons -nocase Address >= {home {"" abc}}
 </PRE>
-<!--      Empty label and key --&gt; to search on all labels and keys -->
+	<LI> Empty label and key to search on all labels and keys
 <PRE>
 	addressbook search -persons -nocase Address >= {"" {"" abc}}
-</PRE><P><H2><A NAME="M20"></A> Using keyed lists</H2>
+</PRE><P></UL><P><H2><A NAME="M20"></A> Using keyed lists</H2>
+Keyed lists can be easily manipulated using the <B> keylget </B>  and  
+<B>keylset</B> commands defined by the TclX extension. For instance, if  a
+record has been stored in some variable <I>myrecord</I>, one  can  extract
+various fields like this:
 <PRE>
 	package require tclx
+	keylkeys myrecord
+	keylget myrecord Email.work
+	keylget myrecord Address.home.ZIP
+	clock format [keylget myrecord Birthday]
+</PRE>
+Similarly, with a group, one can invoke:
+<PRE>
+	set theid [lindex [addressbook groups -ids] 0]
+	set grp [addressbook record $theid]
+	keylkeys grp
+	keylget grp GroupName
+	clock format [keylget grp Modification]
 </PRE><P><HR>
-<P> Last updated 2003-12-28 08:21:01<P>
+<P> Last updated 2004-01-04 21:19:33<P>
 </BODY>
 </HTML>