<HTML>
<HEAD>
<TITLE>VCard &lt;&#151;&gt; People</TITLE>
</HEAD>
<BODY bgcolor="Honeydew">
<center>
<H1>== VCard &lt;&#151;&gt; People ==</H1>
<img src="SOURCE/IMAGES/vpeople.gif">
<h4>[ Release 1.0.1 ]</h4>
</center>
<P>
The VCard format is a standard for storing personal contact data, recognized
by many programs on different platforms.  The two programs in this package
provide quick conversions between this format and BeOS 'Person' files.
<P>
This release is a bug-fix of <b>vcard2people</b> (v1.0.2) that tries to have it
do a better job of handling badly-formed VCard files. (It could crash, or simply
quit, if it encountered some bad or unmanageable entries.)
<P>
These first releases are definitely no-frills.  You have no choice as to where the
output is directed (though hopefully it is reasonably convenient).  Naturally
there are differences between Person file and VCard conventions, which these
programs attempt to handle gracefully, but you may have to edit the results
occasionally.
<P>
[Note to <B>Psion 5mx/Revo</B> users: You can use the Export/Import facility of the
Psion's <B>Contacts</B> application to generate and read VCard files.  Use
<a href="http://www.bebits.com/app/2813">PsiONtrack</a> to access the Psion files
from BeOS.]
<P><br>

<a name="cvard"><h2><img src="SOURCE/IMAGES/v-p.gif" hspace="15">VCard to People</h2></a>
The '<b>vcard2people</b>' app will accept files dropped on its icon and
generate corresponding Person files from the VCard entries they contain.
(It is not fussy about the type of files dropped, because they will probably
have been imported from platforms without attributes, but it ignores any that
do not contain valid VCards.)  You can also invoke it from a shell, and pass
VCard filenames as arguments; if invoked without arguments, it expects VCard
data to be piped to standard input.
<P>
Generated Person files are not placed directly in /boot/home/people, to prevent
overwriting possible older (better!) files of the same name.  Instead they are
written to /boot/home/people/Contacts, where they can be vetted and moved to
the main folder if desired. (The folder is "Contacts" because this is the name
of the program on the Psion handheld that these apps were originally written
to communicate with.)  If a file already exists in Contacts, only the
fields referenced by the VCard get updated: additional fields are left as is.
<P>
A single VCard file may contain any number of individual entries.  Each will
generate a corresponding Person file.  The filename is derived from the name
("N:") line in the VCard, and is of the form "&lt;first&gt; &lt;last&gt;".
The name actually entered in the Person Name field, though, is formed as
"&lt;last&gt;, &lt;first&gt; (&lt;middle&gt;)".
<P>
Other conversions include splitting the single VCard address ("ADR:") line
into Street, City, Region (State), PostCode (Zip), and Country.  Home and Work
phones will be recognized, as will fax and email (if there is more than one,
the first gets used).  VCard lines that have no reasonable Person equivalent
are discarded.
<P>
If you run this app from the shell, you will get information printed as to what
it thinks is in each entry.  If you are having trouble converting a particular
file, it is probably worth doing this to perhaps get some idea of what is going
wrong. When it does have a problem with an entry, it will note this in the print
out, but keep on going; if you have a lot of entries, you may want to redirect
this text to a file, and look for the error with an editor.
<P>
<br>

<a name="people"><h2><img src="SOURCE/IMAGES/p-v.gif" hspace="15">People to VCard</h2></a>
To generate VCard data from Person files, just drop them onto the
'<b>people2vcard</b>' icon.  (You can also call the program from a shell
command with Person files as arguments.)  The VCard data is written to the
file '/boot/home/people/People.vcf'.  That filename is fixed in the current
version, but it will be appended to if it exists already.  (If you convert
the same Person file twice, you'll get duplicate entries.)
<P>
As in the other direction, the program has to make certain decisions and
assumptions about the data it is converting.  It creates the VCard's name
line from the Person file Name field (it ignores the actual filename) by
splitting it into words and rearranging these into standard VCard form.
It assumes that if the first word is terminated with a comma it is the
Last Name, and will be followed by a First, and possibly Middle, in that order.
Otherwise it assumes that the first word is the First name and the last word
is the Last name; a third word will be taken as Middle.  If there are more
than three, it is going to get it wrong... (but the line will still be valid
format).
<P>
The VCard address line is assembled from the relevant attributes of the Person
file.  Other fields are transferred essentially as written.
<P>
A VCard is just text, so it can be viewed or edited with a text editor. One
important warning though.  Each line <i>must</i> end with both a &lt;return&gt;
and a &lt;linefeed&gt; (&lt;Enter&gt;), or other platforms may not be able to
read the file (vcard2people doesn't care).  So don't use an editor like Eddie,
which discards &lt;returns&gt;.  StyledEdit works OK.
<P><br>
The VCard protocol is described at the Internet Mail Consortium's site:
<blockquote><a href="http://www.imc.org/">http://www.imc.org/</a></blockquote>



<BR clear="all">
<P><br>

<div align=right>
					Pete Goodeve<br>
					May 2002
</div>


</BODY></HTML>

