<chapter id="katefiletemplates">
<chapterinfo>

<title
>Modelos de Ficheiros</title>

<authorgroup>
<author
><firstname
>Anders</firstname
> <surname
>Lund</surname
> <affiliation
> <address
><email
>anders@alweb.dk</email
></address>
</affiliation>
</author>
</authorgroup
> <date
>Seg 16 Fev 2004</date
> <releaseinfo
>0.1</releaseinfo
> <abstract
> <para
></para>
</abstract>

<keywordset>
<keyword
>KDE</keyword>
<keyword
>kate</keyword>
<keyword
>kdeaddons</keyword>
<keyword
>modelo</keyword>
<keyword
>macro</keyword>
</keywordset>
</chapterinfo>

<title
>Introdução</title>

<para
>O 'plugin' de Modelos de Ficheiros permite-lhe criar ficheiros com base noutros ficheiros. Você poderá usar qualquer ficheiro como modelo, o que irá criar uma cópia do ficheiro com um URL vazio ou usar um ficheiro de modelo especial que poderá conter macros para preencher alguma informação como o seu nome e endereço de e-mail, a data actual e as variáveis de ambiente, posicionando o cursor numa posição conveniente do ficheiro novo.</para>
<para
>Para além disso, os modelos localizados nas directorias de modelos serão apresentados no item de menu <menuchoice
><guimenu
>Ficheiro</guimenu
><guimenuitem
>Do Modelo..</guimenuitem
></menuchoice
>.</para>
<para
>O 'plugin' também fornece um método para criar um novo modelo a partir de um documento aberto.</para>
<para
>As directorias dos modelos fazem parte do sistema de ficheiros do &kde; e consistem em, pelo menos, a KDEDIR/share/applications/kate/plugins/katefiletemplates/templates e a KDEHOME/share/applications/kate/plugins/katefiletemplates/templates. Se a sua variável de ambiente KDEDIRS contiver directorias adicionais, estas são pesquisadas por subdirectorias semelhantes. Se forem encontrados modelos com o mesmo nome, é escolhido o da directoria local (KDEHOME).</para>
<sect1 id="katefiletemplates-menu">
<title
>Estrutura do Menu</title>

<variablelist>
<varlistentry>
<term>
<menuchoice
><guimenu
>Ficheiro</guimenu
> <guimenu
>Novo a Partir do Modelo</guimenu
> <guimenuitem
>Qualquer Ficheiro...</guimenuitem
> </menuchoice>
</term>
<listitem
><para
>Apresenta-lhe uma janela de Abertura de Ficheiros que lhe permite usar qualquer ficheiro como modelo. Se o ficheiro escolhido tiver a extensão <filename
>katetemplate</filename
>, ele será processado para a informação e as macros do modelo.</para
></listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice
><guimenu
>Ficheiro</guimenu
> <guimenu
>Novo a Partir do Modelo</guimenu
> <guimenuitem
>Usar um Recente</guimenuitem
> </menuchoice>
</term>
<listitem
><para
>Apresenta uma lista dos ficheiros usados recentemente como modelos, representados pelo seu URL.</para
></listitem>
</varlistentry>

<varlistentry>
<term>
<menuchoice
><guimenu
>Ficheiro</guimenu
> <guimenuitem
>Novo a Partir do Modelo</guimenuitem
> </menuchoice>
</term>
<listitem
><para
>O resto dos sub-menus contém referências para os modelos. Carregue num item do menu para criar um ficheiro, tal como é descrito pelo texto do item do menu.</para
></listitem>
</varlistentry>

<!-- Settings menu -->

<varlistentry>
<term>
<menuchoice
><guimenu
>Configuração</guimenu
><guimenuitem
>Gerir os Modelos</guimenuitem
></menuchoice
></term>
<listitem
><para
>Isto irá lançar uma janela com uma lista com todos os modelos encontrados nas directorias de modelos, em conjunto com as opções para adicionar, editar ou remover os modelos.</para
></listitem>
</varlistentry>

</variablelist>

</sect1>
<sect1 id="katefiletemplates-create">
<title
>Criar os seus próprios modelos</title>
<para
>Para criar um modelo novo, use o item <menuchoice
><guimenu
>Configuração</guimenu
> <guimenuitem
>Gerir os Modelos</guimenuitem
></menuchoice
> para lançar a janela de gestão de modelos. Na mesma, carregue em <guibutton
>Novo...</guibutton
> para lançar o Assistente de Modelos de Ficheiros. Ser-lhe-á pedido um ficheiro opcional para transformar num modelo e a configuração dos dados do modelo, para que seja criado um ficheiro para si.</para>
<para
>Em alternativa, você poderá criar um modelo manualmente se adicionar a informação do modelo ao topo de qualquer ficheiro, adicionar o texto, as macros e o marcador da posição do cursor, gravando-o com a extensão <filename
>katetemplate</filename
>.</para>
<para
>O menu do modelo é actualizado automaticamente se você optou por gravar o seu modelo na directoria respectiva.</para>
</sect1>

<sect1 id="katefiletemplates-edit">
<title
>Editar os modelos</title>
<para
>Para editar um modelo, use a opção <menuchoice
><guimenu
>Configuração</guimenu
> <guimenuitem
>Gerir os Modelos...</guimenuitem
></menuchoice
>. Seleccione o modelo com que deseja trabalhar e carregue em <guibutton
>Editar...</guibutton
>, para que seja aberto o ficheiro de modelo. Feche a janela, edite o ficheiro de modelo como desejar, grave-o e feche-o. As alterações aos modelos têm efeito imediato e você poderá activar o modelo para testar as suas alterações depois de o gravar.</para>
</sect1>

<sect1 id="katefiletemplates-format">
<title
>O Formato dos Modelos do Kate</title>
<para
>Se você usar os ficheiros com a extensão <filename
>katetemplate</filename
>, eles serão processados no que respeita à informação do modelo, das macros e da posição do cursor.</para>

<sect2 id="katefiletemplates-template-info">
<title
>Informação do modelo</title>
<para
>Ao ler o ficheiro, o analisador guarda as linhas que começam com a frase <constant
>katetemplate:</constant
> e procura nelas por informações do modelo no formato NOMEVARIAVEL=VALOR. A primeira linha que não começar por <constant
>katetemplate:</constant
> será aceite como o início do conteúdo do modelo. O VALOR poderá conter qualquer carácter excepto o sinal de igual (=). Os nomes válidos de variáveis são: <variablelist>
<varlistentry>
<term
><varname
>Template</varname
></term>
<listitem
><para
>Este é o nome do modelo, mostrado no menu <menuchoice
><guimenu
>Ficheiro</guimenu
><guimenuitem
>A Partir do Modelo</guimenuitem
></menuchoice
>.</para
></listitem>
</varlistentry>
<varlistentry>
<term
><varname
>Group</varname
></term>
<listitem
><para
>O grupo coloca o modelo dentro de um sub-menu do <menuchoice
><guimenu
>Ficheiro</guimenu
><guimenuitem
>A Partir do Modelo</guimenuitem
></menuchoice
>.</para
></listitem>
</varlistentry>
<varlistentry
><term
><varname
>Name</varname
></term>
<listitem
><para
>Este é o nome que será atribuído ao documento e mostrado na lista de ficheiros e na barra de título. Se o nome contiver um <userinput
>%N</userinput
>, este será substituído por um número, o qual será incrementado se existir mais do que um documento com o mesmo nome.</para
></listitem>
</varlistentry>
<varlistentry>
<term
><varname
>Highlight</varname
></term>
<listitem
><para
>O 'plugin' irá tentar configurar o Highlight (realce) para o valor desta variável. O valor deverá ser o nome, tal como consta no menu <menuchoice
><guimenu
>Ferramentas</guimenu
><guimenuitem
>Realce</guimenuitem
> </menuchoice
>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term
><varname
>Description</varname
></term>
<listitem
><para
>Um breve descrição informativa do modelo. Este é usado de momento para definir um item O Que É Isto para o item do menu, mas poderá ser usado para mais fins no futuro.</para
></listitem>
</varlistentry>
<varlistentry
><term
>Author</term>
<listitem
><para
>Um texto que identifica o autor, por exemplo no formato <userinput
>Nome &lt;endereço de e-mail&gt;</userinput
>. Isto é usado de momento para definir um texto de O Que É Isto para o item do menu, mas poderá ser usado para mais fins no futuro.</para
></listitem>
</varlistentry>
</variablelist>
</para>

</sect2>

<sect2 id="katetemplates-macros">
<title
>Macros do Modelo</title>

<para
>Ao processar o conteúdo do modelo, as macros no formato <userinput
>%TEXTO </userinput
> são expandidas. São suportadas as seguintes macros: <variablelist>
<varlistentry
><term
>%time</term>
<listitem
><para
>Expande para a hora actual no seu formato regional, tal como é devolvido pelo método <userinput
>QTime::currentTime().toString()</userinput
>.</para
></listitem>
</varlistentry>
<varlistentry>
<term
>%date</term>
<listitem
><para
>Expande para a data actual num formato longo, tal como é devolvido pelo <userinput
>QDate::currentDate().toString()</userinput
>.</para
></listitem>
</varlistentry>
<varlistentry>
<term
>%datetime</term>
<listitem
><para
>Expande para a data e hora actuais, formatadas como uma cadeia de caracteres de acordo com a sua configuração regional, de acordo com o que é devolvido pelo <userinput
>QDateTime::currentDateTime().toString()</userinput
>.</para
></listitem>
</varlistentry>
<varlistentry>
<term
>%year</term>
<listitem
><para
>O ano actual, como um número de quatro algarismos.</para
></listitem>
</varlistentry>
<varlistentry>
<term
>%month</term>
<listitem
><para
>O nome completo do mês actual, de acordo com a sua configuração regional.</para
></listitem>
</varlistentry>
<varlistentry>
<term
>%{date(FORMATO)}</term>
<listitem
><para
>Isto irá expandir para um texto de data/hora, tal como está definido pelo <userinput
>FORMATO</userinput
>. O FORMATO é uma cadeia de caracteres, dentro do qual serão feitas as seguintes substituições:</para>
<table
><title
>Entidades de formatação de datas</title
><tgroup cols="2"
><tbody>
<row
><entry
><para
>h</para
></entry
><entry
><para
>a hora sem um zero inicial (0..23 ou 1..12 se for o formato AM/PM)</para
></entry
></row>
<row
><entry
>hh<para
></para
></entry
><entry
><para
>a hora com um zero inicial (00..23 ou 01..12 se for o formato AM/PM) </para
></entry
></row>
<row
><entry
><para
>m</para
></entry
><entry
><para
>os minutos sem um zero inicial (0..59) </para
></entry
></row>
<row
><entry
><para
>mm</para
></entry
><entry
><para
>os minutos com um zero inicial (00..59) </para
></entry
></row>
<row
><entry
><para
>s</para
></entry
><entry
><para
>os segundos sem um zero inicial (0..59)</para
></entry
></row>
<row
><entry
><para
>ss</para
></entry
><entry
><para
>os segundos com um zero inicial (00..59) </para
></entry
></row>
<row
><entry
><para
>z</para
></entry
><entry
><para
>os milisegundos sem os zeros iniciais (0..999) </para
></entry
></row>
<row
><entry
><para
>zzz</para
></entry
><entry
><para
>os milisegundos com os zeros iniciais (000..999) </para
></entry
></row>
<row
><entry
><para
>AP</para
></entry
><entry
><para
>usar a visualização AM/PM. O AP será substituído então por "AM" ou "PM". </para
></entry
></row>
<row
><entry
><para
>ap</para
></entry
><entry
><para
>usar a visualização am/pm. O ap será substituído então por "am" ou "pm". </para
></entry
></row>

<row
><entry
><para
>d</para
></entry
><entry
><para
>o dia como um número sem um zero inicial (1-31) </para
></entry
></row>
<row
><entry
><para
>dd</para
></entry
><entry
><para
>o dia como um número com um zero inicial (01-31) </para
></entry
></row>
<row
><entry
><para
>ddd</para
></entry
><entry
><para
>o dia da semana abreviado local (p.ex. 'Seg'..'Dom').</para
></entry
></row>
<row
><entry
><para
>dddd</para
></entry
><entry
><para
>o dia da semana comprimido local (p.ex. 'Segunda'..'Domingo').</para
></entry
></row>
<row
><entry
><para
>M</para
></entry
><entry
><para
>o mês como um número sem um zero inicial (1-12)</para
></entry
></row>
<row
><entry
><para
>MM</para
></entry
><entry
><para
>o mês como um número com um zero inicial (01-12) </para
></entry
></row>
<row
><entry
><para
>MMM</para
></entry
><entry
><para
>o nome abreviado do mês local (p.ex. 'Jan'..'Dez').</para
></entry
></row>
<row
><entry
><para
>MMMM</para
></entry
><entry
><para
>o nome do mês por extenso local (p.ex. 'Janeiro'..'Dezembro').</para
></entry
></row>
<row
><entry
><para
>YY</para
></entry
><entry
><para
>O ano como um número de dois algarismos (00-99).</para
></entry
></row>
<row
><entry
><para
>YYYY</para
></entry
><entry
><para
>O ano como um número de quatro algarismos (1752-8000).</para
></entry
></row>
</tbody
></tgroup
></table>
<para
>Isto permite-lhe controlar a data apresenta com bastante detalhe, usando os separadores normais entre os itens, como por exemplo: <userinput
>h:m:s ap</userinput
>. </para
></listitem>
</varlistentry>
<varlistentry
><term
>%realname</term>
<listitem
><para
>Expande para o seu nome completo, se puder ser encontrado. O analisador irá tentar primeiro a configuração de E-Mail do KDE no Centro de Controlo do KDE, depois à informação da conta do utilizador. Se não for encontrado nenhum nome completo, o seu nome de utilizador é preenchido.</para
></listitem>
</varlistentry>
<varlistentry>
<term
>%username</term>
<listitem
><para
>Expande para o nome do seu utilizador.</para
></listitem>
</varlistentry>
<varlistentry>
<term
>%email</term>
<listitem
><para
>Expande para o seu endereço de e-mail, se puder ser encontrado. O processador irá tentar procurar por ele na configuração de E-Mail do KDE no Centro de Controlo do KDE e, se não puder ser encontrado, irá usar o <userinput
>$USER@$HOST</userinput
> em alternativa.</para
></listitem>
</varlistentry>
<varlistentry>
<term
>%organisation</term>
<listitem
><para
>Esta é a sua organização, se estiver presente na configuração de E-Mail do KDE no Centro de Controlo do KDE. Se não for encontrado, é usado um texto em branco.</para
></listitem>
</varlistentry>
<!-- LAST ENTRY: %ENV -->
<varlistentry>
<term
>%VARIÁVEL</term>
<listitem
><para
>Todos os outros textos serão interpretados como variáveis de ambiente, e expandem para o valor dessa variável. Se não for conhecida nenhuma variável, ele expande para &quot;WARNING &lt;VARIÁVEL&gt; is not set&quot;.</para
></listitem>
</varlistentry>
</variablelist>
</para>
</sect2>

<sect2 id="katefiletemplates-cursor">
<title
>Configurar a posição do cursor</title>
<para
>O processador procura por um acento circunflexo (^) que não seja precedido de uma barra invertida (\) para decidir onde posicionar o cursor. Se for encontrado, é removido e o cursor é posicionado onde isto estava. Se forem encontrados mais acentos circunflexos, todos serão removidos e a posição do último será usada.</para>
<para
>Se algum acento circunflexo escapado (precedido de uma barra invertida) for encontrado, a barra será removida.</para>
</sect2>

</sect1>

<sect1 id="katefiletemplates-thanks-and-acknowledgements">
<title
>Agradecimentos e Reconhecimentos</title>

<para
>'Plugin' do &kate; <quote
>Modelos de Ficheiros</quote
> copyright 2004 Anders Lund <email
>anders@alweb.dk</email
>. </para>

<para
>Documentação copyright 2004 Anders Lund </para>

<para
>Tradução de José Nuno Pires <email
>jncp@netcabo.pt</email
></para
> 
&underGPL; </sect1>
</chapter>

<!-- kate: word-wrap on; -->