<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN"
"dtd/kdex.dtd" [

  <!ENTITY kabcclient "<application>KABC-Client</application>">
  <!ENTITY kappname "KABCClient">
  <!ENTITY package "kdepim">
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % English "INCLUDE">
]>
<!-- The language must NOT be changed here. -->

<book id="kabcclient" lang="&language;">

<bookinfo id="kabcclientinfo">

<title>The &kabcclient; Handbook</title>

<authorgroup>
  <author>
    <firstname>Kevin</firstname>
    <surname>Krammer</surname>
    <affiliation>
      <address>
        <email>kevin.krammer@gmx.at</email>
      </address>
    </affiliation>
  </author>
  <!-- TRANS:ROLES_OF_TRANSLATORS -->
</authorgroup>

<copyright>
  <year>2008</year>
  <holder>Kevin Krammer</holder>
</copyright>

<legalnotice>&FDLNotice;</legalnotice>

<!-- Don't change format of date and version of the documentation -->

<date>2008-11-20</date>
<releaseinfo>1.1.1</releaseinfo>

<abstract>
  <para>&kabcclient; is a command line interface to &kde; address books.</para>
</abstract>


<keywordset>
  <keyword>KDE</keyword>
  <keyword>&package;</keyword>
  <keyword>&kappname;</keyword>
  <keyword>KAddressBook</keyword>
</keywordset>

</bookinfo>

<chapter id="introduction">
<title>Introduction</title>

<para>&kabcclient; is a command line interface to &kde; address book.
It lets you list, search, insert, remove, or merge contacts by way of
the command line or from a scripting language.
&kabcclient; can handle a variety of formats on both input and output, enabling
it to be used for import and export of whole &kde; address books.
</para>

<para>When invoked without arguments &kabcclient; will be put into search mode and try to match any input it can read from standard input to contact entries in the &kde; address book</para>

<para>Main features of &kabcclient;:
<itemizedlist>
  <listitem><para>List all contacts of the &kde; address book</para></listitem>
  <listitem><para>Search for contacts matching the input</para></listitem>
  <listitem><para>Insert (add) contacts</para></listitem>
  <listitem><para>Remove (delete) contacts</para></listitem>
  <listitem><para>Merge (change) matching contacts with new data</para></listitem>
</itemizedlist></para>

<para>&kabcclient; is <emphasis>not</emphasis> another graphical
user interface to the &kde; address book (i.e. &kaddressbook;).  &kabcclient;
is intended solely for uses where a graphical user interface is
not practical or possible.</para>

<para>&kabcclient; does <emphasis>not</emphasis> provide a full-featured
language for making queries of the user's address book nor is it the intention
of the authors to ever write such a capability.
Any such processing can be done through other command line tools or the script's own language's capabilities.
</para>

<para>To ease discoverability of its capabilities, any option requiring an argument can be called with the value <replaceable>help</replaceable>. This will then list all the valid values one can pass to that option.
</para>

</chapter>

<chapter id="features">
<title>Features</title>
<para>In this chapter you'll learn about the main features of
&kabcclient; and how to control them using the command line parameters
(remember that &kabcclient; is not a graphical user interface;
it is a command line program only).</para>

<para>
You'll learn about inserting, deleting, and searching for
contact data, and how to use different formats for input and output.
</para>

<sect1 id="listing">
<title>Listing the address book</title>

<para>This is the most basic operation mode, initiated using the <parameter>--list</parameter> or <parameter>-L</parameter>
option. &kabcclient; will list all contacts in the &kde; address book, writing the data to the program's standard output. Amount and format of the output will depend on the chosen output format.</para>

<para>
<informalexample><para>To list all contacts as standard vCard entries, simply run:</para>

<para>
<screen>
<prompt>%</prompt><userinput> <command>kabcclient <option>-L</option></command>
</userinput>
</screen>
</para>
</informalexample>
</para>

<para>
<informalexample><para>To get just one line per contact, &eg; for counting, simply run:</para>

<para>
<screen>
<prompt>%</prompt><userinput> <command>kabcclient <option>-L</option> <option>-of <replaceable>uid</replaceable></option></command>
</userinput>
</screen>
</para>
</informalexample>
</para>

<para>
<informalexample><para>In this next example, we list all email addresses:</para>

<para>
<screen>
<prompt>%</prompt><userinput> <command>kabcclient</command> <option>--list</option> <option>-of <replaceable>email</replaceable></option>
</userinput>
</screen>
</para>
</informalexample>
</para>

</sect1>

<sect1 id="searching">
<title>Searching for contacts matching the input data</title>

<para>&kabcclient; can take data from the command line or from the program's standard input and check it for similarities against all contacts in the &kde; address book. Searching is the default mode but it can be explicitly be chosen using the <parameter>--search</parameter> or <parameter>-S</parameter> command line argument.
</para>

<para>
<informalexample><para>In the following example, all contacts with <replaceable>jane</replaceable> as part of any name field or email address will be written to the program's standard output, formatted as vCards (since this is the default for the <option>--output-format</option> option):</para>

<para>
<screen><prompt>%</prompt><userinput> <command>kabcclient</command> <option>--search</option> <replaceable>jane</replaceable></userinput></screen>
</para>
</informalexample>
</para>

<para>
<informalexample><para>Same query again, this time reading the search string from the program's standard input:</para>

<para>
<screen><prompt>%</prompt><userinput> <command>echo</command> <replaceable>jane</replaceable> | <command>kabcclient</command> <option>--search</option></userinput></screen>
</para>
</informalexample>
</para>

<para>Case sensitivity of queries can be toggled using the <option>--match-case</option> option.</para>
</sect1>

<sect1 id="adding">
<title>Adding contacts</title>

<para>&kabcclient; supports adding new contacts to the &kde; address book using the <parameter>--add</parameter> or <parameter>-A</parameter> command line argument.
The data can either be passed as additional command line arguments or read from standard input. On success the resulting contacts will be written to the program's standard output. Since this is an operation which applies changes to the address book it can be run in a "Dry run" mode using the <option>--nosave</option> option.
</para>

<para>
<informalexample><para>Add a contact with name and email address by interpreting an additional command line argument as the input data:</para>

<para>
<screen><prompt>%</prompt><userinput> <command>kabcclient</command> <option>--add</option> <option>--input-format <replaceable>email</replaceable> </option><replaceable>"John Doe &lt;j.doe@example.com&gt;"</replaceable></userinput></screen>
</para>
</informalexample>
</para>

<para>
<informalexample><para>Add all contacts from a vCard file streamed into the program's standard input:</para>

<para>
<screen><prompt>%</prompt><userinput> <command>cat <replaceable>example-file.vcf</replaceable></command> | <command>kabcclient</command> <option>--add</option> <option>--input-format <replaceable>vcard</replaceable> </option></userinput></screen>
</para>
</informalexample>
</para>
</sect1>

<sect1 id="deleting">
<title>Deleting contacts</title>

<para>&kabcclient; supports deleting contacts from the &kde; address book using the <parameter>--remove</parameter> or <parameter>-R</parameter> command line argument. The input data is basically a query like when searching the address book.
On success the removed contacts will be written to the program's standard output. Since this is an operation which applies changes to the address book it can be run in a "Dry run" mode using the <option>--nosave</option> option.
</para>

<warning><para> When you delete something from the address book you
<emphasis>cannot</emphasis> undo it! In other words, when you delete a contact
you cannot reverse the deletion. It's gone for good.</para></warning>

<para>
<informalexample><para>Test removing all contacts with <replaceable>jane</replaceable> in any contact name field or any email address:</para>

<para>
<screen><prompt>%</prompt><userinput> <command>kabcclient</command> <option>--remove</option> <option>--nosave</option> <replaceable>jane</replaceable></userinput></screen>
</para>
</informalexample>
</para>

</sect1>

<sect1 id="formats">
<title>Input and Output Formats</title>

<para>
&kabcclient; can interpret input data and format output data according to various formatting rules. Depending on the actual usage scenario certain combinations will render the most useful result.
Some of the formats understand additional parameters for further customizing their behavior.
</para>

<para>
Since textual data can be encoded both input and output can be subjected to additional decoding or encoding respectively.
</para>

<para>All those command line options will react to the special value <replaceable>help</replaceable> by listing the allowed values.</para>

<sect2 id="vcard-format">
<title>vCard Format</title>

<para>vCard (<acronym>RFC</acronym> 2426) is the standard format for contact data and as such can present all information other address book applications such as &kaddressbook; can access. It is therefore the default format for output formatting.
</para>
</sect2>

<sect2 id="csv-format">
<title>Comma-Separated Values (<acronym>CSV</acronym>) Format</title>

<para>Comma-Separated Value Format can be used as input format to fill data into specific field of a contact entry and as an output format to reduce or re-order data for further processing. To allow for enough flexibility mapping of contact fields to CSV columns can be specified using CSV-template description files also used by &kaddressbook; for the same purpose.
</para>
</sect2>
</sect1>
</chapter>

<chapter id="features-commandline-options">
<title>Command Line Arguments</title>

<para>&kabcclient; supports the following options:</para>

<informaltable>
<tgroup cols="2">
<thead>
<row>
  <entry>Option</entry>
  <entry>Description</entry>
</row>
</thead>
<tbody>
<row>
  <entry><option>--help, --help-all</option></entry>
  <entry>Shows help about the program options.</entry>
</row>
<row>
  <entry><option>--author</option></entry>
  <entry>Shows the program author information.</entry>
</row>
<row>
  <entry><option>-v, --version</option></entry>
  <entry>Shows the program version information.</entry>
</row>
<row>
  <entry><option>--license</option></entry>
  <entry>Shows the program license information.</entry>
</row>
<row>
  <entry><option>--verbose</option></entry>
  <entry>Print helpful runtime messages.</entry>
</row>
<row>
  <entry><option>--nosave</option></entry>
  <entry>Print what would have been done, but do not execute.  Do not change anything in the &kde; address book; do not insert, remove, modify any existing contacts.</entry>
</row>
<row>
  <entry><option>--match-case</option></entry>
  <entry>Use case sensitive matching when comparing input data with contact data from the address book.</entry>
</row>
<row>
  <entry><emphasis>Major Operation Modes:</emphasis></entry>
</row>
<row>
  <entry><option>-L, --list</option></entry>
  <entry>Print all contacts in specified export format.</entry>
</row>
<row>
  <entry><option>-A, --add</option></entry>
  <entry>Insert contacts into the address book.</entry>
</row>
<row>
  <entry><option>-R, --remove</option></entry>
  <entry>Delete contacts from the address book.</entry>
</row>
<row>
  <entry><option>-M, --merge</option></entry>
  <entry>Merge data from the input with matching contacts from the address book.</entry>
</row>
<row>
  <entry><emphasis>Formatting and Encoding:</emphasis></entry>
</row>
<row>
  <entry><option>-if, --input-format</option>
  <replaceable>format</replaceable></entry>
  <entry>How to interpret the input data. Use <replaceable>help</replaceable> for a list of available values.</entry>
</row>
<row>
  <entry><option>-of, --output-format</option>
  <replaceable>format</replaceable></entry>
  <entry>How to format the output data. Use <replaceable>help</replaceable> for a list of available values.</entry>
</row>
<row>
  <entry><option>-if-opts, --input-format-options</option>
  <replaceable>options</replaceable></entry>
  <entry>Input format specific customization options. Use <replaceable>help</replaceable> for a list of available values.</entry>
</row>
<row>
  <entry><option>-of-opts, --output-format-options</option>
  <replaceable>options</replaceable></entry>
  <entry>Output format specific customization options. Use <replaceable>help</replaceable> for a list of available values.</entry>
</row>
<row>
  <entry><option>-ic, --input-codec</option>
  <replaceable>encoding</replaceable></entry>
  <entry>Text encoding used to present the input data. Use <replaceable>help</replaceable> for a list of available values.</entry>
</row>
<row>
  <entry><option>-oc, --output-codec</option>
  <replaceable>encoding</replaceable></entry>
  <entry>Text encoding which should be used to present the output data. Use <replaceable>help</replaceable> for a list of available values.</entry>
</row>

</tbody>
</tgroup>
</informaltable>

</chapter>

<chapter id="faq">
<title>Questions and Answers</title>

&reporting.bugs;
&updating.documentation;

<qandaset id="faqlist">
<qandaentry>
<question>
<para>What configuration files does &kabcclient; use?</para>
</question>
<answer>
<para>None.</para>
</answer>
</qandaentry>


<qandaentry>
<question>
<para>What are the application names of &kabcclient;?</para>
</question>
<answer>
<para>&kabcclient;'s application name is <application>kabcclient</application>.</para>
</answer>
</qandaentry>

<qandaentry>
<question>
<para>How do I have my question added to this <acronym>FAQ</acronym>?</para>
</question>
<answer>
<para>Send your questions to <email>kevin.krammer@gmx.at</email>.</para>
</answer>
</qandaentry>

</qandaset>
</chapter>


<chapter id="credits">

<title>Credits and License</title>

<para>&kabcclient; Program copyright 2005-2008:</para>

<itemizedlist>
<listitem><para>Kevin Krammer <email>kevin.krammer@gmx.at</email></para></listitem>
</itemizedlist>

<para>Documentation copyright 2008:</para>
<itemizedlist>
<listitem><para>Kevin Krammer <email>kevin.krammer@gmx.at</email></para></listitem>
</itemizedlist>

<!-- TRANS:CREDIT_FOR_TRANSLATORS -->

&underFDL;               <!-- FDL: do not remove -->

&underGPL;        	 <!-- GPL License -->

</chapter>

<appendix id="installation">
<title>Installation</title>

<sect1 id="obtaining-application">
<title>How to obtain &kabcclient;</title>

&install.intro.documentation;

<para>&kabcclient; comes included with &kde;4 and is not available separately.
</para>

</sect1>

<sect1 id="requirements">
<title>Requirements</title>

<para>&kabcclient; requires the standard &kde; libraries to be installed
(the <filename>kdelibs</filename> package and <filename>kdepimlibs</filename>).
To compile from source, you also need the &Qt;, <filename>kdelibs</filename> and
<filename>kdepimlibs</filename> development packages.</para>

<para>You can find a list of changes in the
<filename>ChangeLog</filename> file.</para>
</sect1>

<sect1 id="configuration">
<title>Configuration</title>

<para>No special configuration is required to set up &kabcclient; to run
on the &kde; desktop.</para>

</sect1>

</appendix>

&documentation.index;
</book>
<!--
Local Variables:
mode: sgml
sgml-minimize-attributes:nil
sgml-general-insert-case:lower
sgml-indent-step:0
sgml-indent-data:nil
End:
-->