<?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 % Portuguese "INCLUDE">
]>
<!-- The language must NOT be changed here. -->

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

<bookinfo id="kabcclientinfo">

<title
>O Manual do &kabcclient;</title>

<authorgroup>
  <author
><firstname
>Kevin</firstname
> <surname
>Krammer</surname
> <affiliation
> <address
> <email
>kevin.krammer@gmx.at</email>
      </address>
    </affiliation>
  </author>
  <othercredit role="translator"
><firstname
>José</firstname
><surname
>Pires</surname
><affiliation
><address
><email
>zepires@gmail.com</email
></address
></affiliation
><contrib
>Tradução</contrib
></othercredit
> 
</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
>O &kabcclient; é uma interface para a linha de comandos para os livros de endereços do &kde;.</para>
</abstract>


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

</bookinfo>

<chapter id="introduction">
<title
>Introdução</title>

<para
>O &kabcclient; é uma interface para a linha de comandos do livro de endereços do &kde;. Permite-lhe listar, procurar, inserir, remover ou reunir contactos através da linha de comandos ou de uma linguagem de programação. O &kabcclient; pode lidar com uma grande variedade de formatos à entrada ou à saída, permitindo a sua utilização para a importação ou exportação de livros de endereços do &kde; inteiros. </para>

<para
>Quando é invocado sem argumentos, o &kabcclient; será colocado no modo de pesquisa e tentará corresponder todo o texto que possa ler do 'standard input' com os itens de contactos no livro de endereços do &kde;</para>

<para
>Funcionalidades principais do &kabcclient;: <itemizedlist>
  <listitem
><para
>Listar todos os contactos do livro de endereços do &kde;</para
></listitem>
  <listitem
><para
>Procurar por contactos que correspondam aos dados introduzidos</para
></listitem>
  <listitem
><para
>Inserir (adicionar) contactos</para
></listitem>
  <listitem
><para
>Remover (apagar) contactos</para
></listitem>
  <listitem
><para
>Reunir (modificar) os contactos correspondentes com os dados novos</para
></listitem>
</itemizedlist
></para>

<para
>O &kabcclient; <emphasis
>não é</emphasis
> outra interface gráfica para o livro de endereços do &kde; (i.e. &kaddressbook;). O &kabcclient; pretende apenas ser usado quando não é prático ou possível a utilização de uma interface gráfica.</para>

<para
>O &kabcclient; <emphasis
>não</emphasis
> oferece uma linguagem de programação completa para efectuar pesquisas sobre o livro de endereços do utilizador, nem sequer é tal a intenção dos autores. Todos esses processamentos poderão ser efectuados a partir de outras ferramentas da linha de comandos ou das capacidades da própria linguagem de programação do programa. </para>

<para
>Para facilitar a descoberta das suas capacidades, qualquer opção que necessite de argumentos poderá ser invocada com o valor <replaceable
>help</replaceable
>. Isto irá então apresentar todos os valores válidos que possam ser passados a essa opção. </para>

</chapter>

<chapter id="features">
<title
>Características</title>
<para
>Neste capítulo, irá conhecer as funcionalidades principais do &kabcclient; e saber como controlá-las com os parâmetros da linha de comandos (lembre-se que o &kabcclient; não é uma interface gráfica; é um programa apenas para a linha de comandos).</para>

<para
>Irá aprender como inserir, apagar e procurar por dados de contactos, assim como usar diferentes formatos para a entrada e para a saída. </para>

<sect1 id="listing">
<title
>Listar o livro de endereços</title>

<para
>Este é o modo mais básico de operação, sendo iniciado com a opção <parameter
>--list</parameter
> ou <parameter
>-L</parameter
>. O &kabcclient; irá listar todos os contactos no livro de endereços do &kde;, escrevendo os dados para o 'standard output' do programa. A quantidade e formato dos resultados à saída irá depender do formato escolhido.</para>

<para>
<informalexample
><para
>Para listar todos os contactos como itens em vCard-padrão, basta executar:</para>

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

<para>
<informalexample
><para
>Para obter apenas uma linha por contacto, p.ex. para contagens, basta executar:</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
>No exemplo seguinte, serão listados todos os endereços de e-mail:</para>

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

</sect1>

<sect1 id="searching">
<title
>Procurar por contactos correspondentes aos dados introduzidos</title>

<para
>O &kabcclient; pode retirar os dados da linha de comandos ou a partir do 'standard input' do programa, verificando as suas semelhanças com todos os contactos no livro de endereços do &kde;. A pesquisa é o modo por omissão, mas podê-lo-á escolher de forma explícita com os argumentos da linha de comandos <parameter
>--search</parameter
> ou <parameter
>-S</parameter
>. </para>

<para>
<informalexample
><para
>No exemplo seguinte, todos os contactos que tenham <replaceable
>josé</replaceable
> como parte de qualquer campo de nome ou endereço de e-mail serão impressos no 'standard output' do programa, formatados como vCards (dados que este é o valor por omissão da opção <option
>--output-format</option
>):</para>

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

<para>
<informalexample
><para
>A mesma pesquisa de novo, só que desta vez o texto a procurar é lido do 'standard input' do programa:</para>

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

<para
>Poderá activar ou desactivar a pesquisa com distinção de maiúsculas com a opção <option
>--match-case</option
>.</para>
</sect1>

<sect1 id="adding">
<title
>Adicionar contactos</title>

<para
>O &kabcclient; suporta a adição de contactos novos ao livro de endereços do &kde;, utilizando o argumento da linha de comandos <parameter
>--add</parameter
> ou <parameter
>-A</parameter
>. Os dados poderão ser passados como argumentos adicionais da linha de comandos ou lidos a partir do 'standard input'. Em caso de sucesso, os contactos resultantes serão apresentados no 'standard output' do programa. Dado que esta é uma operação que aplica alterações ao livro de endereços, poderá ser executada num modo de "Execução de testes" com a opção <option
>--nosave</option
>. </para>

<para>
<informalexample
><para
>Adicione um contacto com o nome e o e-mail, interpretando um argumento adicional da linha de comandos como dados de entrada:</para>

<para>
<screen
><prompt
>%</prompt
><userinput
> <command
>kabcclient</command
> <option
>--add</option
> <option
>--input-format <replaceable
>e-mail</replaceable
> </option
><replaceable
>"Zé Povinho &lt;ze.povinho@exemplo.com&gt;"</replaceable
></userinput
></screen>
</para>
</informalexample>
</para>

<para>
<informalexample
><para
>Para adicionar todos os contactos de um ficheiro vCard em sequência para o 'standard input' do programa:</para>

<para>
<screen
><prompt
>%</prompt
><userinput
> <command
>cat <replaceable
>ficheiro-exemplo.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
>Apagar contactos</title>

<para
>O &kabcclient; suporta a remoção de contactos do livro de endereços do &kde;, utilizando o argumento da linha de comandos <parameter
>--remove</parameter
> ou <parameter
>-R</parameter
>. Os dados de entrada são basicamente uma pesquisa para procurar os itens a remover. Em caso de sucesso, os contactos resultantes serão apresentados no 'standard output' do programa. Dado que esta é uma operação que aplica alterações ao livro de endereços, poderá ser executada num modo de "Execução de testes" com a opção <option
>--nosave</option
>. </para>

<warning
><para
>Quando apagar algo do livro de endereços, <emphasis
>não poderá</emphasis
> voltar atrás! Por outras palavras, quando apagar um contacto, não poderá anular a remoção; será removido em definitivo.</para
></warning>

<para>
<informalexample
><para
>Para testar a remoção de todos os contactos que tenham <replaceable
>josé</replaceable
> em qualquer campo do nome do contacto ou do seu e-mail:</para>

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

</sect1>

<sect1 id="formats">
<title
>Formatos de Entrada e Saída</title>

<para
>O &kabcclient; pode interpretar os dados à entrada e formatar os dados à saída, de acordo com várias regras de formatação. Dependendo do cenário de utilização actual, certas combinações poderão representar o resultado mais útil. Alguns dos formatos aceitam parâmetros adicionais, de modo a personalizar ainda mais o seu comportamento. </para>

<para
>Dado que os dados textuais poderão ser codificados, tanto a entrada como a saída poderão estar sujeitos a descodificações ou codificações, respectivamente. </para>

<para
>Todas estas opções da linha de comandos irão reagir ao valor especial <replaceable
>help</replaceable
>, que irá listar os valores permitidos.</para>

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

<para
>O vCard (<acronym
>RFC</acronym
> 2426) é o formato-padrão para os dados de contactos e, como tal, poderá apresentar todas as informações que outras aplicações de livros de endereços, como o &kaddressbook;, podem aceder. Como tal, é o formato por omissão para a formatação de saída. </para>
</sect2>

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

<para
>O formato de valores separados por vírgulas (CSV) poderá ser usado como formato de entrada para preencher os dados em campos específicos de um item de contacto e como um formato de saída para reduzir ou reordenar os dados para processamentos futuros. Para permitir um mapeamento mais flexível dos campos de contactos com colunas do CSV, poderá usar os ficheiros de descrição de modelos CSV do &kaddressbook; para esse fim. </para>
</sect2>
</sect1>
</chapter>

<chapter id="features-commandline-options">
<title
>Argumentos da Linha de Comandos</title>

<para
>O &kabcclient; suporta as seguintes opções:</para>

<informaltable>
<tgroup cols="2">
<thead>
<row>
  <entry
>Opção</entry>
  <entry
>Descrição</entry>
</row>
</thead>
<tbody>
<row>
  <entry
><option
>--help, --help-all</option
></entry>
  <entry
>Mostra ajuda acerca das opções do programa.</entry>
</row>
<row>
  <entry
><option
>--author</option
></entry>
  <entry
>Mostra informações acerca do autor do programa.</entry>
</row>
<row>
  <entry
><option
>-v, --version</option
></entry>
  <entry
>Mostra informações da versão do programa.</entry>
</row>
<row>
  <entry
><option
>--license</option
></entry>
  <entry
>Mostra informações da licença do programa.</entry>
</row>
<row>
  <entry
><option
>--verbose</option
></entry>
  <entry
>Imprime mensagens úteis durante a execução.</entry>
</row>
<row>
  <entry
><option
>--nosave</option
></entry>
  <entry
>Imprime o que seria feito, mas não executa nada de facto. Não altera nada de todo no livro de endereços do &kde;; não remove, insere ou modifica nenhuns dos contactos.</entry>
</row>
<row>
  <entry
><option
>--match-case</option
></entry>
  <entry
>Use a pesquisa com distinção de maiúsculas/minúsculas, caso queira comparar os dados introduzidos com os contactos no livro de endereços.</entry>
</row>
<row>
  <entry
><emphasis
>Modos Principais de Operação:</emphasis
></entry>
</row>
<row>
  <entry
><option
>-L, --list</option
></entry>
  <entry
>Imprime todos os contactos no formato de exportação indicado.</entry>
</row>
<row>
  <entry
><option
>-A, --add</option
></entry>
  <entry
>Insere contactos no livro de endereços.</entry>
</row>
<row>
  <entry
><option
>-R, --remove</option
></entry>
  <entry
>Remove contactos do livro de endereços.</entry>
</row>
<row>
  <entry
><option
>-M, --merge</option
></entry>
  <entry
>Junta os dados à entrada com os contactos correspondentes no livro de endereços.</entry>
</row>
<row>
  <entry
><emphasis
>Formatação e Codificação:</emphasis
></entry>
</row>
<row>
  <entry
><option
>-if, --input-format</option
> <replaceable
>formato</replaceable
></entry>
  <entry
>Como interpretar os dados à entrada. Use o <replaceable
>help</replaceable
> para obter uma lista com os valores disponíveis.</entry>
</row>
<row>
  <entry
><option
>-of, --output-format</option
> <replaceable
>formato</replaceable
></entry>
  <entry
>Como formatar os dados à saída. Use o <replaceable
>help</replaceable
> para obter uma lista com os valores disponíveis.</entry>
</row>
<row>
  <entry
><option
>-if-opts, --input-format-options</option
> <replaceable
>opções</replaceable
></entry>
  <entry
>Define um conjunto de opções de personalização específicas do formato de entrada. Use o <replaceable
>help</replaceable
> para obter uma lista dos valores disponíveis.</entry>
</row>
<row>
  <entry
><option
>-of-opts, --output-format-options</option
> <replaceable
>opções</replaceable
></entry>
  <entry
>Define um conjunto de opções de personalização específicas do formato à saída. Use o <replaceable
>help</replaceable
> para obter uma lista dos valores disponíveis.</entry>
</row>
<row>
  <entry
><option
>-ic, --input-codec</option
> <replaceable
>codificação</replaceable
></entry>
  <entry
>A codificação de texto usada para apresentar os dados à entrada. Use o <replaceable
>help</replaceable
> para obter uma lista com os valores disponíveis.</entry>
</row>
<row>
  <entry
><option
>-oc, --output-codec</option
> <replaceable
>codificação</replaceable
></entry>
  <entry
>A codificação de texto usada para apresentar os dados à saída. Use o <replaceable
>help</replaceable
> para obter uma lista com os valores disponíveis.</entry>
</row>

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

</chapter>

<chapter id="faq">
<title
>Perguntas e Respostas</title>
&reporting.bugs; &updating.documentation; <qandaset id="faqlist">
<qandaentry>
<question>
<para
>Que ficheiros de configuração usa o &kabcclient;?</para>
</question>
<answer>
<para
>Nenhum.</para>
</answer>
</qandaentry>


<qandaentry>
<question>
<para
>Quais são os nomes da aplicação &kabcclient;?</para>
</question>
<answer>
<para
>O nome da aplicação &kabcclient; é <application
>kabcclient</application
>.</para>
</answer>
</qandaentry>

<qandaentry>
<question>
<para
>Como é que posso adicionar a minha dúvida a esta <acronym
>FAQ</acronym
>?</para>
</question>
<answer>
<para
>Envie as suas questões para <email
>kevin.krammer@gmx.at</email
>.</para>
</answer>
</qandaentry>

</qandaset>
</chapter>


<chapter id="credits">

<title
>Créditos e Licença</title>

<para
>&kabcclient; Programa com 'copyright' 2005-2008:</para>

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

<para
>Documentação com 'copyright' de 2008:</para>
<itemizedlist>
<listitem
><para
>Kevin Krammer <email
>kevin.krammer@gmx.at</email
></para
></listitem>
</itemizedlist>

<para
>Tradução de José Nuno Pires <email
>zepires@gmail.com</email
></para
> 
&underFDL; &underGPL; </chapter>

<appendix id="installation">
<title
>Instalação</title>

<sect1 id="obtaining-application">
<title
>Como obter o &kabcclient;:</title>
&install.intro.documentation; <para
>O &kabcclient; vem incluído no &kde;4 e não está disponível em separado. </para>

</sect1>

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

<para
>O &kabcclient; necessita de ter instaladas as seguintes bibliotecas-padrão do &kde; (o pacote <filename
>kdelibs</filename
> e o <filename
>kdepimlibs</filename
>). Para compilar a partir do código-fonte, também precisa do &Qt; e dos pacotes de desenvolvimento <filename
>kdelibs</filename
> e <filename
>kdepimlibs</filename
>.</para>

<para
>Pode encontrar uma lista de modificações no ficheiro <filename
>ChangeLog</filename
>.</para>
</sect1>

<sect1 id="configuration">
<title
>Configuração</title>

<para
>Não é necessária nenhuma configuração especial para ter o &kabcclient; a executar no ambiente de trabalho do &kde;.</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:
-->