# Modelos de Ficheiros

## Introdução

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 além disso, os modelos localizados nas directorias de modelos serão apresentados no item de menu Ficheiro Do Modelo...

O 'plugin' também fornece um método para criar um novo modelo a partir de um documento aberto.

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).

## Estrutura do Menu

Ficheiro Novo a Partir do Modelo Qualquer Ficheiro...

- Apresenta-lhe uma janela de Abertura de Ficheiros que lhe permite usar qualquer ficheiro como modelo. Se o ficheiro escolhido tiver a extensão `katetemplate`, ele será processado para a informação e as macros do modelo.

Ficheiro Novo a Partir do Modelo Usar um Recente

- Apresenta uma lista dos ficheiros usados recentemente como modelos, representados pelo seu URL.

Ficheiro Novo a Partir do Modelo

- 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.

Configuração Gerir os Modelos

- 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.

## Criar os seus próprios modelos

Para criar um modelo novo, use o item Configuração Gerir os Modelos para lançar a janela de gestão de modelos. Na mesma, carregue em Novo... 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.

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 `katetemplate`.

O menu do modelo é actualizado automaticamente se você optou por gravar o seu modelo na directoria respectiva.

## Editar os modelos

Para editar um modelo, use a opção Configuração Gerir os Modelos.... Seleccione o modelo com que deseja trabalhar e carregue em Editar..., 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.

## O Formato dos Modelos do Kate

Se você usar os ficheiros com a extensão `katetemplate`, eles serão processados no que respeita à informação do modelo, das macros e da posição do cursor.

### Informação do modelo

Ao ler o ficheiro, o analisador guarda as linhas que começam com a frase `katetemplate:` e procura nelas por informações do modelo no formato NOMEVARIAVEL=VALOR. A primeira linha que não começar por `katetemplate:` 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:

`Template`

- Este é o nome do modelo, mostrado no menu Ficheiro A Partir do Modelo.

`Group`

- O grupo coloca o modelo dentro de um sub-menu do Ficheiro A Partir do Modelo.

`Name`

- 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 `%N`, este será substituído por um número, o qual será incrementado se existir mais do que um documento com o mesmo nome.

`Highlight`

- 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 Ferramentas Realce .

`Description`

- 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.

Author

- Um texto que identifica o autor, por exemplo no formato `Nome <endereço de e-mail>`. 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.

### Macros do Modelo

Ao processar o conteúdo do modelo, as macros no formato `%TEXTO` são expandidas. São suportadas as seguintes macros:

%time

- Expande para a hora actual no seu formato regional, tal como é devolvido pelo método `QTime::currentTime().toString()`.

%date

- Expande para a data actual num formato longo, tal como é devolvido pelo `QDate::currentDate().toString()`.

%datetime

- 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 `QDateTime::currentDateTime().toString()`.

%year

- O ano actual, como um número de quatro algarismos.

%month

- O nome completo do mês actual, de acordo com a sua configuração regional.

%{date(FORMATO)}

- Isto irá expandir para um texto de data/hora, tal como está definido pelo `FORMATO`. O FORMATO é uma cadeia de caracteres, dentro do qual serão feitas as seguintes substituições:

  ### Entidades de formatação de datas

  h | a hora sem um zero inicial (0..23 ou 1..12 se for o formato AM/PM)
  hh | a hora com um zero inicial (00..23 ou 01..12 se for o formato AM/PM)
  m | os minutos sem um zero inicial (0..59)
  mm | os minutos com um zero inicial (00..59)
  s | os segundos sem um zero inicial (0..59)
  ss | os segundos com um zero inicial (00..59)
  z | os milisegundos sem os zeros iniciais (0..999)
  zzz | os milisegundos com os zeros iniciais (000..999)
  AP | usar a visualização AM/PM. O AP será substituído então por "AM" ou "PM".
  ap | usar a visualização am/pm. O ap será substituído então por "am" ou "pm".
  d | o dia como um número sem um zero inicial (1-31)
  dd | o dia como um número com um zero inicial (01-31)
  ddd | o dia da semana abreviado local (p.ex. 'Seg'..'Dom').
  dddd | o dia da semana comprimido local (p.ex. 'Segunda'..'Domingo').
  M | o mês como um número sem um zero inicial (1-12)
  MM | o mês como um número com um zero inicial (01-12)
  MMM | o nome abreviado do mês local (p.ex. 'Jan'..'Dez').
  MMMM | o nome do mês por extenso local (p.ex. 'Janeiro'..'Dezembro').
  YY | O ano como um número de dois algarismos (00-99).
  YYYY | O ano como um número de quatro algarismos (1752-8000).

  Isto permite-lhe controlar a data apresenta com bastante detalhe, usando os separadores normais entre os itens, como por exemplo: `h:m:s ap`.

%realname

- 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.

%username

- Expande para o nome do seu utilizador.

%email

- 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 `$USER@$HOST` em alternativa.

%organisation

- 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.

%VARIÁVEL

- 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 "WARNING <VARIÁVEL> is not set".

### Configurar a posição do cursor

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.

Se algum acento circunflexo escapado (precedido de uma barra invertida) for encontrado, a barra será removida.

## Agradecimentos e Reconhecimentos

'Plugin' do &kate; Modelos de Ficheiros copyright 2004 Anders Lund anders@alweb.dk.

Documentação copyright 2004 Anders Lund

Tradução de José Nuno Pires jncp@netcabo.pt

&underGPL;