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

<book lang="&language;">

<bookinfo>

<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
>Marcus</firstname
><surname
>Gama</surname
><affiliation
><address
><email
>marcus.gama@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 comando 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 comando do livro de endereços do &kde;. Permite-lhe listar, procurar, inserir, remover ou mesclar contatos através da linha de comando ou de uma linguagem de programação. O &kabcclient; pode lidar com uma grande variedade de formatos de entrada ou de 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 contatos no livro de endereços do &kde;</para>

<para
>Funcionalidades principais do &kabcclient;: <itemizedlist>
  <listitem
><para
>Listar todos os contatos do livro de endereços do &kde;</para
></listitem>
  <listitem
><para
>Procurar por contatos que correspondam aos dados inseridos</para
></listitem>
  <listitem
><para
>Inserir (adicionar) contatos</para
></listitem>
  <listitem
><para
>Remover (apagar) contatos</para
></listitem>
  <listitem
><para
>Mesclar (modificar) os contatos 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 efetuar pesquisas no livro de endereços do usuário, nem sequer é esta a intenção dos autores. Todos esses processamentos poderão ser efetuados a partir de outras ferramentas da linha de comando 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
>Recursos</title>
<para
>Neste capítulo, você irá conhecer as funcionalidades principais do &kabcclient; e saber como controlá-las com os parâmetros da linha de comando (lembre-se que o &kabcclient; não é uma interface gráfica; é um programa apenas para a linha de comando).</para>

<para
>Irá aprender como inserir, apagar e procurar por dados de contatos, 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 contatos no livro de endereços do &kde;, escrevendo os dados para o 'standard output' do programa. A quantidade e formato dos resultados de saída irá depender do formato escolhido.</para>

<para>
<informalexample
><para
>Para listar todos os contatos 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 contato, 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 a seguir, 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 contatos correspondentes aos dados inseridos</title>

<para
>O &kabcclient; pode retirar os dados da linha de comando ou a partir do 'standard input' do programa, verificando as suas semelhanças com todos os contatos no livro de endereços do &kde;. A pesquisa é o modo padrão, mas isto poderá ser selecionado de forma explícita com os argumentos da linha de comando <parameter
>--search</parameter
> ou <parameter
>-S</parameter
>. </para>

<para>
<informalexample
><para
>No exemplo a seguir, todos os contatos que tenham <replaceable
>joão</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 (uma vez que este é o valor padrão da opção <option
>--output-format</option
>):</para>

<para>
<screen
><prompt
>%</prompt
><userinput
> <command
>kabcclient</command
> <option
>--search</option
> <replaceable
>joão</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
>joão</replaceable
> | <command
>kabcclient</command
> <option
>--search</option
></userinput
></screen>
</para>
</informalexample>
</para>

<para
>A pesquisa com distinção de maiúsculas poderá ser ativada ou desativada com a opção <option
>--match-case</option
>.</para>
</sect1>

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

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

<para>
<informalexample
><para
>Adicione um contato com o nome e o e-mail, interpretando um argumento adicional da linha de comando 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
>"João da Silva &lt;joao.silva@exemplo.com.br&gt;"</replaceable
></userinput
></screen>
</para>
</informalexample>
</para>

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

<para>
<screen
><prompt
>%</prompt
><userinput
> <command
>cat <replaceable
>arquivo-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 contatos</title>

<para
>O &kabcclient; suporta a remoção de contatos do livro de endereços do &kde;, utilizando o argumento da linha de comando <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 contatos resultantes serão apresentados no 'standard output' do programa. Uma vez 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, você <emphasis
>não poderá</emphasis
> voltar atrás! Em outras palavras, quando apagar um contato, não poderá anular a remoção; ele será removido em definitivo.</para
></warning>

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

<para>
<screen
><prompt
>%</prompt
><userinput
> <command
>kabcclient</command
> <option
>--remove</option
> <option
>--nosave</option
> <replaceable
>joão</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 de entrada e formatar os dados de saída, de acordo com várias regras de formatação. Dependendo do cenário de utilização atual, 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
>Uma vez que os dados textuais poderão ser codificados, tanto a entrada como a saída poderão estar sujeitos a decodificações ou codificações, respectivamente. </para>

<para
>Todas estas opções da linha de comando 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 contatos e, como tal, poderá apresentar todas as informações que outros aplicativos de livros de endereços, como o &kaddressbook;, podem acessar. Como tal, é o formato padrã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 contato 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 contatos com colunas do CSV, poderão ser usados os arquivos de descrição de modelos CSV do &kaddressbook;. </para>
</sect2>
</sect1>
</chapter>

<chapter id="features-commandline-options">
<title
>Argumentos da linha de comando</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 sobre as opções do programa.</entry>
</row>
<row>
  <entry
><option
>--author</option
></entry>
  <entry
>Mostra informações sobre o 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 fato. Não altera nada no livro de endereços do &kde;; não remove, insere ou modifica nenhum dos contatos.</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 inseridos com os contatos 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 contatos no formato de exportação indicado.</entry>
</row>
<row>
  <entry
><option
>-A, --add</option
></entry>
  <entry
>Insere contatos no livro de endereços.</entry>
</row>
<row>
  <entry
><option
>-R, --remove</option
></entry>
  <entry
>Remove contatos do livro de endereços.</entry>
</row>
<row>
  <entry
><option
>-M, --merge</option
></entry>
  <entry
>Mescla os dados de entrada com os contatos 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 de 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 de 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 de 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 de 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 de 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 arquivos de configuração usa o &kabcclient;?</para>
</question>
<answer>
<para
>Nenhum.</para>
</answer>
</qandaentry>


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

<qandaentry>
<question>
<para
>Como 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 Marcus Gama<email
>marcus.gama@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 separadamente. </para>

</sect1>

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

<para
>O &kabcclient; necessita que estejam 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, você também precisa do &Qt; e dos pacotes de desenvolvimento <filename
>kdelibs</filename
> e <filename
>kdepimlibs</filename
>.</para>

<para
>Você pode encontrar uma lista de modificações no arquivo <filename
>ChangeLog</filename
>.</para>
</sect1>

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

<para
>Não é necessária nenhuma configuração especial para rodar o &kabcclient; 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:
-->