Txt2tags -- Guia do Usuário

Aurelio, Sun Aug 15 17:31:57 2004
Tradução para o português: César A. K. Grossman



Sobre este documento

"Olá, eu sou o manual do txt2tags!

Aqui você encontra toda a informação disponível sobre a ferramenta de conversão de textos txt2tags.

Minha versão atualizada pode ser encontrada em http://txt2tags.sf.net/userguide/

Para mais informações e versões recentes, visite o website do txt2tags.

Bom proveito!"


Parte I - Introdução ao Txt2tags

Suas Primeiras Questões

Este capítulo apresenta o txt2tags, introduzindo as funcionalidades e objetivo do programa.


O Que É?

O txt2tags é uma ferramenta de formatação e conversão de texto.

O txt2tags converte um arquivo texto com algumas marcas para qualquer um dos tipos de arquivos suportados:


Por Quê Eu Devo Usá-lo?

Você achará o txt2tags bastante útil se você:

E a motivação principal é:


Quais vantagens oferece em relação a outras ferramentas?

O txt2tags possui uma forma bem direta de crescimento, seguindo alguns conceitos básicos. Os conceitos a seguir se destacam:

Arquivo fonte legível As marcações do txt2tags são bastante simples, quase naturais.
Documento destino legível Da mesma forma que o arquivo fonte, o arquivo documento também é legível, com indentação e linhas curtas.
Consistência na Marcação As marcações txt2tags são únicas o suficiente para atender todos os tipos de documentos e não são confundidas com o conteúdo do documento.
Regras Consistentes Da mesma forma que as marcas, as regras que se aplicam às mesmas estão ligadas umas às outras, não há "exceções" ou "casos especiais".
Estruturas Simples Toda a formatação suportada é simples, sem opções extra ou modificadores complexos de comportamento. Uma marcação é só uma marcação, sem opções adicionais.
Fácil de aprender Com marcações simples e o código fonte legível, a curva de aprendizado é bem amigável
Bons Exemplos Os arquivos de exemplo incluídos com o pacote dão exemplos reais de documentos simples e super-complicados escritos no formato txt2tags.
Ferramentas Valiosas Os arquivos de sintaxe incluídos com o pacote (para os editores vim e emacs) ajudam a escrever documentos sem erros sintáticos
Três interfaces ao usuários Há uma interface Gráfica Tk que é bastante amigável, uma inteface Web para usá-lo remotamente ou na intranet, e uma interface de Linha de Comando, para usuários avançados e scripts.
Suporte a Scripts Com o modo completo de linha de comando, um usuário experiente pode automatizar tarefas e efetuar pós-edições nos arquivos convertidos
Download e Execução / Multiplataforma O txt2tags é apenas um script Python. Não há necessidade de compilar o mesmo ou carregar módulos extras. Assim, ele pode ser executado sem problemas em máquinas *NIX, Linux, Windows e Macintosh
Atualizações Freqüentes O programa possui uma lista de discussões com usuários ativos que sugerem correções e melhoramentos. O próprio autor é um usuário extensivo em casa e no trabalho, por isto o desenvolvimento não irá parar tão cedo.


Tenho que pagar por ele?

Absolutamente NÃO!

O txt2tags é um programa gratuito, GPL, open source, domínio público, etc...

Você pode copiar, usar, modificar, vender, liberar como o seu. As políticas de software e copyright não são uma das maiores preocupações do autor.


Estruturas de Formatação Suportadas

Segue uma lista de todas as estruturas suportadas pelo txt2tags.


Formatos Suportados

SGML

O SGML é um formato de documento comum que possui aplicações de conversão, as sgmltools. De um arquivo sgml pode-se gerar documentos html, pdf, ps, info, latex, lyx, rtf e xml. As ferramentas sgml2* também criam TOC e quebra de seções em subpáginas (sgml2html).

O txt2tags gera arquivos SGML válidos para a DTD linuxdoc, prontos para serem convertidos com uma ferramenta sgml2* sem qualquer arquivo de catálogo extra ou outras exigências incômodas do SGML.
HTML
Todo mundo sabe o que o HTML é (dica: internet).

O txt2tags gera documentos HTML limpos, que tem boa apresentação e cujo código fonte é legível. Ele NÃO USA javascript, frames ou outras técnicas de formatação fúteis, que não são necessárias para documentos técnicos simples. Mas um arquivo CSS separado pode ser utilizado, se for desejado.

LATEX
TODO.

PM6
Eu acho que você não sabe, mas o Adobe PageMaker 6.0 tem sua própria linguagem de marcação! Estilos, tabelas de cores, embelezadore, e a maior parte das funcionalidades acessíveis via cliques de mouse também estão disponíveis em sua linguagem de marcação. Você só precisa acessar o item de menu "Import tagged text". Apenas para registro, é um formato de marcação semelhante ao HTML.

O txt2tags gera todas as tags e já define um cabeçalho extenso e funcional, configurando os estilos de parágrafo e formatações. Esta é a parte difícil. GOTCHA: Sem quebras de linha! Um parágrafo deve ser uma única linha.

Nota do Autor: Todo meu livro em português sobre expressões regulares foi escrito no vi, convertido para o formato do PageMaker com o txt2tags e então impresso.
MGP

O Magic Point é uma ferramenta de apresentação bastante útil (dica: Microsoft PowerPoint), que usa uma linguagem de marcação para definir todas as telas. Desta forma, você pode criar apresentações complexas no vi/emacs/notepad.

O Txt2tags gera um arquivo .mgp pronto para ser usado, definindo todos os cabeçalhos necessários para as definições de fontes e aparência, bem como o suporte aos caracteres acentuados da página de código ISO-8859.

Observação 1 os arquivos .mgp criados pelo t2t usam as fontes Type1 do XFree86! Desta forma, não é necessário incluir fontes TrueType com sua apresentação.

Observação 2 as definições de cor para as fontes são limpas, de forma que mesmo com uma paleta de cores de sistema pobre (como em startx -- -bpp 8), a apresentação vai ter boa aparência.

A chave é: converta e use. Não há necessidade de remendos ou de outros requisitos.

MAN
As páginas man do UNIX resistiram pelos anos. Formatos de documento vem e vão, e elas estão aí, imbatíveis.

Existem outras ferramentas para gerar documentos man, mas o t2t tem uma vantagem: uma fonte, múltiplos formatos destino. Assim, o conteúdo da mesma página man pode ser convertido para uma página HTML, uma apresentação Magic Point, etc.

MOIN
Você não sabe o que é o MoinMoin? Ele é um WikiWiki!

A sintaxe do Moin é um pouco chata, quando você tem que ficar {{{'''''acrescentando chaves e plicas'''''}}}, mas o t2t vem com as marcações simplificadas e uma solução unificada: uma fonte, múltiplos formatos destino.

TXT
TXT é texto. O único tipo de formatação verdadeiro.

Apesar das marcações do t2t serem bem intuitivas e discretas, pode-se removê-las ao converter o arquivo para TXT puro.

Os títulos são sublinhados, e o texto é basicamente deixado como está no código fonte.

Situação dos Formatos-Destino para as Estruturas Suportadas

Estrutura txt html sgml tex mgp pm6 moin man
cabeçalhos S S S S S N N S
título de seções S S S S S S S S
parágrafos S S S S S S S S
negrito - S S S S S S S
itálico - S S S S S S S
negrito-itálico - S S S S S S S
sublinhado - S - S S S ? -
pré-formatado - S S S S S S -
linha pré-formatada - S S S S S S S
área pré-formatada - S S S S S S S
área cotada S S S S S S ? N
links internet - S S - - - S -
links e-mail - S S - - - S -
links locais - S S N - - S -
links nomeados - S S - - - S -
lista não-numerada S S S S S S S S
lista numerada S S S S S S S N
lista de definições S S S S N N N S
linha horizontal S S - S S N S -
imagem - S S S S N S -
tabela N S S S N N S N

Legenda
S suportada
N não suportada (talvez em uma versão futura)
- não suportada (não pode ser feita neste formato)
? não suportada (não estou bem certo se pode ou não ser feito)


As Três Interfaces ao Usuário: GUI, Web e Linha de Comando

Assim como diferentes usuários possuem diferentes necessidades e ambientes, o t2t é bastante flexivel na forma de ser usado.

Existem três Interfaces de Usuário para o programa, cada uma atendendo a um objetivo definido e com funcionalidades próprias.


Interface Gráfica Tk

Desde a versão 1.0, há uma Interface Gráfica bonita, que funciona do Linux, Windows e Mac (e outros).

Ela é bastante simples e fácil de usar:

E também tem a capacidade de colocar o arquivo resultante em uma janela, em vez de escrever em um disco, de forma que podem ser feitos testes rápidos antes de salvar o resultado do comando em um arquivo:


Interface Web

A Interface Web está em funcionamento na Internet no endereço http://txt2tags.sf.net/online.php, permitindo que o programa possa ser usado e testado antes de ser copiado.

Esta interface também pode ser colocada em uma rede local para uso local, evitando a instalação do txt2tags em todas as máquinas.


Interface de Linha de Comando

Para usuários de linha de comando acostumados, o parâmetro --help deve ser suficiente:

  Usage: txt2tags [OPTIONS] [infile.t2t ...]
  
    -t, --target        set target document type. currently supported:
                        html, xhtml, sgml, tex, man, mgp, moin, pm6, txt
    -i, --infile=FILE   set FILE as the input file name ('-' for STDIN)
    -o, --outfile=FILE  set FILE as the output file name ('-' for STDOUT)
    -n, --enum-title    enumerate all title lines as 1, 1.1, 1.1.1, etc
    -H, --no-headers    suppress header, title and footer information
        --headers       show header, title and footer information (default ON)
        --encoding      set target file encoding (utf-8, iso-8859-1, etc)
        --style=FILE    use FILE as the document style (like HTML CSS)
        --css-suggar    insert CSS-friendly tags for HTML and XHTML targets
        --mask-email    hide email from spam robots. x@y.z turns <x (a) y z>
        --toc           add TOC (Table of Contents) to target document
        --toc-only      print document TOC and exit
        --toc-level=N   set maximum TOC level (depth) to N
        --rc            read global user config file ~/.txt2tagsrc (default ON)
        --gui           invoke Graphical Tk Interface
    -v, --verbose       print informative messages during convertion
    -h, --help          print this help information and exit
    -V, --version       print program version and exit
        --dump-config   print all the config found and exit
  
  Turn OFF options:
       --no-outfile, --no-infile, --no-style, --no-encoding, --no-headers
       --no-toc, --no-toc-only, --no-mask-email, --no-enum-title, --no-rc
  
  Example:
        txt2tags -t html --toc myfile.t2t
  
  By default, converted output is saved to 'infile.<target>'.
  Use --outfile to force an output file name.
  If  input file is '-', reads from STDIN.
  If output file is '-', dumps output to STDOUT.

Exemplos

Supondo que exista um arquivo de marcação chamado file.t2t, vamos nos divertir um pouco.

Convertendo para HTML $ txt2tags -t html file.t2t
O mesmo, usando redireção $ txt2tags -t html -o - file.t2t > file.html
.
Incluindo uma Tabela de Conteúdo $ txt2tags -t html --toc file.t2t
Idem, numerando os títulos $ txt2tags -t html --toc --enum-title file.t2t
.
Visualização Rápida do Conteúdo $ txt2tags --toc-only file.t2t
Quem sabe com números? $ txt2tags --toc-only --enum-title file.t2t
.
Oneliners de STDIN $ echo -e "\n**bold**" | txt2tags -t html --no-headers -
Testando o Mascaramento de Email $ echo -e "\njohn.wayne@farwest.com" | txt2tags -t txt --mask-email --no-headers -
Edição pós-conversão $ txt2tags -t html -o- file.t2t | sed "s/<BODY .*/<BODY BGCOLOR=green>/" > file.html

Nota
A edição pré e pós conversão pode ser feita via a configuração nativa %!preproc e %!postproc.

Parte II - OK, eu quero um. E agora?

Basta baixar o programa e executar o mesmo no seu computador.

Download e Instalação do Python

Antes de mais nada, deve-se baixar e instalar o interpretador Python para o seu sistema. Se você já o tem, então pule eset passo.

O Python é uma das melhores linguagens de programação que existe, ela pode ser utilizada no Windows, Linux, UNIX, Macintosh, e outras plataformas, e pode ser baixada do web site do Python. As dicas de instalação podem ser encontradas no mesmo site. O t2t funciona com o Python 1.5 ou posterior.

Se você não tem certeza de ter o Python ou não, abra um console (tty, xterm, MSDOS) e escreva python. Se ele não estiver instalado, o sistema vai te informar.

Copiando o txt2tags

O local oficial de distribuição do t2t é na homepage do programa, em http://txt2tags.sf.net/src.

Todos os arquivos do programa estão em um tarball (arquivo .tgz), que pode ser expandido pela maioria dos utilitários de compressão (incluindo o Winzip).

Apenas pegue a última versão (data mais recente, número de versão maior). As versões anteriores estão lá apenas por razões históricas.

Instalação do t2t

Como é apenas um script Python, o t2t não precisa ser instalado.

O único arquivo necessário para usar o programa é o script txt2tags. Os outros arquivos do tarball compreendem a documentação, ferramentas e arquivos de exemplo.

O modo mais seguro de usar o txt2tags é chamar o Python com ele:

  prompt$ python txt2tags 

Se você quiser "instalar" o txt2tags, no sistema como um programa independente, basta copiar (ou criar um link) o script txt2tags para um diretório que esteja no PATH do sistema e certificar-se que o sistema saiba como executar o mesmo.

UNIX/Linux
Torne o script executável (chmod +x txt2tags) e copie o mesmo para um diretório no $PATH (cp txt2tags /usr/local/bin)

Windows
Renomeie o script, acrescentando a extensão .py (ren txt2tags txt2tags.py) e copie o mesmo para um diretório que esteja no PATH do sistema (copy txt2tags.py C:\WINNT)

Depois disto, pode-se criar um ícone no desktop para o programa, se se quiser usar a Interface Gráfica do programa.

Pacotes Especiais para Usuários Windows

Existem dois arquivos de distribuição .EXE para o txt2tags, que instalam o programa em máquinas Windows com apenas alguns cliques:

Visite o site Txt2tags-Win para baixar estes pacotes: http://txt2tags-win.sf.net/


Parte III - Escrevendo e Convertendo Seu Primeiro Documento

Desculpe, este capítulo ainda está em desenvolvimento.

As Áreas do documento .t2t

Os arquivos de marcação txt2tags são divididos em 3 áreas. Cada área tem suas próprias regras e finalidade. São elas:

Área de Cabeçalho
É o lugar para informações sobre o Título do Documento, Autor, Versão e Data. (opcional)
Área de Configuração
É o local para colocar as configurações Gerais do documento e modificadores do funcionamento do analisador. (opcional)
Corpo do Texto
É o local para o Conteúdo do Documento (requerida)

Como vemos acima, as duas primeiras áreas são opcionais, sendo que o Corpo do Texto é a única área indispensável. (Nota: A Área de Configuração foi introduzida no txt2tags na versão 1.3)

As áreas são delimitadas por regras especiais, que serão vistas em detalhe no próximo capítulo. Por enquanto, esta é uma representação gráfica das áreas de um documento:

               ____________
              |            |
              |  CABEÇALHO |       1. Primeiro, o cabeçalho
              |            |
              |   CONFIG   |       2. Então a configuração
              |            |
              |   CORPO    |       3. E, finalmente, o corpo do documento
              |            |
              |    ...     |          que segue até o final do arquivo.
              |    ...     |
              |____________|
  

Em resumo, é assim que as áreas são definidas:

Cabeçalhos As primeiras 3 linhas do arquivo, ou a primeira linha é deixada em branco se não são usados cabeçalhos
Configuração Começam logo depois do cabeçalho (4a. ou 2a. linha) e termina quando a Área de Conteúdo começa.
Corpo A primeira linha de texto válida (que não é comentário ou configuração) após a Área de Cabeçalho.

Exemplo Completo

  My nice doc Title
  Mr. John Doe
  Last Updated: %%date(%c)
  
  %! Style   : fancy.css
  %! Encoding: iso8859-1
  %! Cmdline : -t html --toc --enum--title
  
  Hi! This is my test document.
  Its content will end here.


Parte IV - Dominando o Txt2tags

A Área de Cabeçalho

Local:

A Área de Cabeçalho é a única que tem uma posição fixa, orientada a linhas. Ela está localizada nas três primeiras linhas do código fonte.

O conteúdo destas linhas é livre, sem necessidade de nenhuma informação estática de nenhum tipo. Mas recomenda-se o seguinte para a maioria dos documentos:

Tenha em mente que as 3 primeiras linhas do arquivo fonte serão as 3 primeiras linhas no documento gerado, separadas e com um grande contraste em relação ao corpo do texto (ou seja, letras grandes, negrito). Se a paginação for permitida, os cabeçalhos estarão separados e centralizados na primeira página.

Menos (ou Nenhuma) Linhas de Cabeçalho

Às vezes os usuários querem especificar menos de três linhas nos cabeçalhos, dando apenas o título do documento e/ou informação de data.

Basta deixar a 2a. e/ou a 3a. linhas em branco e estas linhas não serão incluídas no documento gerado. Mas tenha em mente que, mesmo em branco, estas linhas ainda são parte dos cabeçalho, e o corpo do documento deve começar após a 3a. linha.

O título é o único cabeçalho requerido (a primeira linha), mas se você deixar ela em branco, está dizendo que seu documento não tem cabeçalho. Desta forma, a Área de Texto irá começar em seguida, na 2a. linha.

Não usar cabeçalhos no documento é útil se você quiser especificar seus próprios cabeçalhos customizados após a conversão. A opção de linha de comando --no-headers é geralmente necessária para este tipo de coisa.

Direto ao ponto

Em resumo: "Cabeçalhos são apenas posições, não conteúdo "

Coloque um texto na primeira linha, ele irá aparecer na primeira linha do arquivo gerado. O mesmo para a 2a. e 3a. linhas de cabeçalho.


A Área de Configuração

Local:

A Área de Configuração é opcional. A maioria dos usuários pode escrever carradas de arquivos txt2tags mesmo sem saber que ela existe, mas os usuários experientes irão gostar do poder e controle que ela oferece.

O uso primário desta área é para definir configurações que afetam o comportamento do programa.

Então, como configurar algo? Qual a sintaxe?

As linhas de configuração são linhas de comentário especiais, marcadas com um identificador no início ("!") que torna estes comentários diferentes dos comentários normais. A sintaxe é tão simples quanto uma atribuição de valor a uma variável, composta por uma palavra-chave e um valor, separados um do outro pelo separador canônico dois-pontos (":").

%! keyword : value

Detalhes da Sintaxe: O ponto de exclamação deve ser colocado junto com o caracter de comentário, sem espaço entre eles ("%!"). Os espaços em torno de keyword e o separador são opcionais, e tanto keyword quanto value podem estar indiferentemente em maiúsculas ou minúsculas.

O que eu posso configurar? Quais são as keywords válidas?

As configurações que podem ser feitas são Style, Encoding, Cmdline, PreProc e Postproc.

A configuração Style só é suportada pelo tipo de documento destino HTML, para definir uma folha de estilo (Cascading Style Sheet - CSS).

A configuração Encoding é necessária para escritores não ingleses, qeu usem letras acentuadas e outros detalhes específicos de localização, de forma que o Conjunto de Caracteres do documento seja personalizado (se permitido).

A configuração Cmdline é útil para especificar opções de linha de comando padrão para o arquivo fonte. Estas opções podem ser sobrescritas pela linha de comando real. Usando esta opção, o arquivo pode ser convertido usando apenas o comando: txt2tags file.t2t

A configuração PreProc é um filtro. Ela define regras do tipo "busca e troca" que serão aplicadas ao arquivo original antes que qualquer análise por parte do txt2tags tenha lugar.

A configuração PostProc é um filtro. Ela devine regras do tipo "busca e troca" que serão aplicadas ao arquivo destino depois de todo o processamento por parte do txt2tags.

Exemplo:

  %! Style   : fancy.css
  %! Encoding: iso-8859-1
  %! Cmdline : -t html --toc --toc-level 3
  %! PreProc : "amj"       "Aurelio Marinho Jargas"
  %! PostProc: '<BODY.*?>' '<BODY bgcolor="yellow">'

Algumas regras sobre as Configurações


O Corpo do Texto

Localização:

Bem, o corpo do texto é tudo que estiver fora das Áreas de Cabeçalho e de Configuração.

O corpo do texto é onde está o conteúdo do documento e todas as estruturas e formatações que o txt2tags reconhece. Dentro do corpo podem ser também colocados comentários para TODOs e anotações particulares.

Pode-se utilizar a opção de linha de comando --no-headers para converter somente o corpo do documento, suprimindo os cabeçalhos. Esta opção é útil quanso os cabeçalhos estão em um arquivo separado, que será unido ao corpo depois da conversão.


Marcações (REGRAS)

Todas as marcações e sintaxe usadas pelo txt2tags estão detalhadas em um arquivo separado REGRAS.


A macro %%date

A macro %%date chamada sem nenhum parâmetro adicional, retorna a data atual no formato ISO yyyymmdd. Formatação opcional pode ser especificada usando a sintaxe %%date(format-string).

A format-string contém texto, e diretivas de formatação, que são compostas por um sinal de porcentagem % seguido por um caracter de identificação.

Segue uma lista de algumas diretivas comuns. A lista completa pode ser encontrada em http://www.python.org/doc/current/lib/module-time.html.

Diretiva Descrição
%a dia da semana local abreviado.
%A dia da semana completo.
%b nome do mês abreviado.
%B nome do mês.
%c dia e hora formatados apropriadamente.
%d dia do mês como um número decimal [01,31].
%H hora (24 horas) como um número decimal [00,23].
%I hora (12 horas) como um número decimal [01,12].
%m o mês como um número decimal [01,12].
%M o minuto como um número decimal [00,59].
%p o equivalente local a AM e PM.
%S os segundos como um número decimal [00,61]. (1)
%x representação local da data.
%X representação local da hora.
%y o ano sem o século como um número decimal [00,99].
%Y o ano com o século como um número decimal.
%% um caracter "%".

Exemplos

%%date(format) Resultado para: 2002, Jan31, 15:00
Last Update: %c Last Update: Thu Jan 31 15:00:00 2002
%Y-%m-%d 2002-01-31
%I:%M %p 03:00 PM
Today is %A, on %B. Today is Thursday, on January.


O comando %!include

A partir da versão 1.7, é possível usar o comando include para inserir o conteúdo de um arquivo externo dentro do corpo do documento original.

O %!include não é uma configuração, mas um comando, sendo somente válido dentro do corpo do texto.

O comando include é útil para dividir um documento grande em vários arquivos menores (como capítulos de um livro) ou para incluir todo o conteúdo de um arquivo qualquer no documento. Por exemplo:

  Meu Primeiro Livro
  Dr. Fulano da Silva
  1ª Edição
  
  %!include: introducao.t2t
  %!include: capitulo1.t2t
  %!include: capitulo2.t2t
  ...
  %!include: capitulo9.t2t
  %!include: conclusao.t2t

Como se pode ver, basta informar o nome do arquivo logo após o comando. Também é possível atrelar o comando a um destino específico, como em:

  %!include(html): arquivo.t2t

Note que o include vai inserir o CORPO do documento .t2t, ignorando seu cabeçalho e suas configurações. Assim é possível converter o arquivo incluído de maneira isolada ou como parte do documento mãe.

Além de incluir arquivos .t2t, há mais dois tipos de inclusão:

No primeiro tipo, o texto é incluído "como está", tendo seus espaços e quebras de linhna preservados. É como se esse texto estivesse entre as marcações '---'. Para incluir um arquivo dessa maneira, basta colocar seu nome entre crases:

`%!include:

Já no outro tipo, o texto é passado diretamente para o documento resultante, sem NENHUM tratamento pelo txt2tags. Assim é possível incluir tags adicionais, trechos já prontos ou estruturas mais complicadas que não são suportadas pelo programa. Outra aplicação é incluir um cabeçalho ou rodapé padrão em todos os documentos:

  %!include(html): 'rodape.html'

Note que o nome do arquivo está entre aspas simples (e não crases como o anterior). São estas aspas que indicam que o conteúdo deve ser passado diretamente. Como este conteúdo já contém tags, é primordial especificar o destino também, para evitar problemas.


Parte V - Dominando as Diretivas de Configuração

As Diretivas de Configuração são todas opcionais. A maioria dos usuários pode muito bem passar sem elas. Mas elas são viciantes, se você começa a usá-las, não consegue parar :)


%!Cmdline

Escrever longas linhas de comando toda vez que for necessário converter um documento é maçante e sujeito a erros. A configuração Cmdline permite que o usuário salve todas as opções de conversão juntas, no próprio documento.

Desta forma o usuário só precisa executar

  $ txt2tags file.t2t

E a conversão é feita, obtendo as definições de tipo de documentod e destino e outras configurações na linha %!cmdline. Desta forma também se garante que o documento sempre será convertido da mesma forma, com as mesmas opções.

Só é necessário escrevê-la sem erros de sintaxe, como se estivesse na linha de comando. Mas omita a chamada ao programa "txt2tags" no início e o nome do arquivo origem no fim da linha.

Por exemplo, se você usa esta linha de comando para converter seu documento:

  $ txt2tags -t html --toc --toc-level 2 --enum-title file.t2t

Pode-se economizar um bocado de digitação usando esta configuração de Cmdline dentro do documento origem:

  %!cmdline: -t html --toc --toc-level 2 --enum-title

A linha de comando real passa agora a ser apenas "txt2tags file.t2t", e a conversão pode ser executada dentro do seu editor de textos favorito, enquanto o conte está sendo editado. No Vi, o comando é:

  :!txt2tags %


%!Encoding

A configuração de Encoding é necessária para autores não ingleses, que usam letras acentuadas e outros detalhes específicos, de forma que o Conjunto de Caracteres do documento gerado possa ser personalizado (se possível).

Os valores válidos para a configuração de Encoding são os mesmos que são válidos para documentos, HTML, como iso-8859-1 e koi8-r. Se você não está certo de qual codificação quer usar, esta lista completa (e longa!) poderá ser de ajuda.

Quando for gerado documentos LaTeX, utiliza aliases para a codificação. Isto não deve ser problema para o usuário, já que o txt2tags faz a tradução internamente. Alguns exemplos:

txt2tags/HTML > LaTeX
windows-1250 >>> cp1250
windows-1252 >>> cp1252
ibm850 >>> cp850
ibm852 >>> cp852
iso-8859-1 >>> latin1
iso-8859-2 >>> latin2
koi8-r >>> koi8-r

Se o valor é desconhecido do txt2tags, ele será passado sem tradução, permitindo que o usuário especifique codificações personalizadas.


%!PreProc

O filtro de usuário PreProc é uma função "busca e troca" que é aplicada logo após a linha ter sido lida do arquivo original, antes de qualquer tratamento pelo txt2tags.

Ela é útil para definir algumas abreviações para texto que seja usado comumente, como:

  %!preproc amj          "Aurelio Marinho Jargas"
  %!preproc RELEASE_DATE "2003-05-01"
  %!preproc BULLET       "[images/tiny/bullet_blue.png]"

Desta forma, o usuário pode escrever uma linha como:

  Hi, I'm amj. Today is RELEASE_DATE.

E o txt2tags irá ver esta linha como:

  Hi, I'm Aurelio Marinho Jargas. Today is 2003-05-01.

Este filtro é um componente que trabalha entre o autor do documento e a conversão do txt2tags. É como uma primeira conversão antes da conversão "real". Este comportamento funciona exatamente como um filtro Sed/Perl externo, chamado assim:

  $ cat file.t2t | preproc-script.sh | txt2tags -

Assim, o tratamento executado pelo txt2tags irá começar após todas as substituições PreProc terem sido feitas.


%!PostProc

O filtro de usuário PostProc é uma função do tipo "busca e troca" que é aplicada no arquivo resultante, após todos as conversões do txt2tags terem sido feitas.

É útil para defintir alguns refinamentos no documento gerado, mudar algumas marcações e acrescentar algumas marcações extra ou texto extra. Alguns exemplos curtos:

  %!postproc(html): '<BODY.*?>' '<BODY BGCOLOR="green">'
  %!postproc(tex) : "\\newpage" ""

Estes filtros mudam a cor de fundo da página HTML e removem as quebras de página em arquivos LaTeX gerados.

As regras do PostProc são iguais a filtros externos Sed/Perl, chamados desta forma:

  $ txt2tags -t html -o- file.t2t | postproc-script.sh > file.html

Antes desta funcionalidade ter sido introduzida, era bastante comum ter pequenos scripts para "ajustar" os resultados gerados pelo txt2tags. Estes scripts eram, de fato, vários comandos sed (ou assemelhados), para fazer algo do tipo "substitua isto por aquilo". Agora estas trocas podem ser salvas junto com o texto do documento, e também aproveitar-se da poderosa máquina de Expressões Regulares do Python para encontrar os padrões.


%!Style


Detalhes dos Filtros PreProc e PostProc


Definindo uma Configuração para um Tipo-Destino Específico

Desde a versão 1.6 do txt2tags, todas as Diretivas de Configuração podem ser especificadas para um destino específico, usando a sintaxe %!key(target): value. Desta forma, o usuário pode definir diferentes configurações para diverentes tipos de arquivos gerados.

Este aspecto é especialmente útil nos filtros pre/postproc, mas pode ser utilizado em todas as diretrizes. Por exemplo, configurar diferentes valores de Codificação para HTML e LaTeX:

  %!encoding(html): iso-8859-1
  %!encoding(tex): latin1

Nota: O mapeamento de codificações para os nomes especiais LaTeX já é parte do txt2tags, o trecho acima é apenas um exemplo.

Para o %!cmdline, pode ser interessante:

  %!cmdline: -t sgml --toc
  %!cmdline(html): --style foo.css
  %!cmdline(txt): --toc-only --toc-level 2

Desta forma, o tipo de destino padrão é o SGML, com TOC. Se o usuário executar:

  $ txt2tags -t html file.t2t

O tipo de destino HTML será feito, e somente as opções de %!cmdline(html) serão usadas. Desta forma, a opçõa --style será usada e o arquivo HTML não terá TOC.

A Precedência é Diferente

Em geral, para as diretivas de configuração, a última encontrada é a usada, mas quando usar diretivas explícitas de tipo-destino, elas tem precedência sobre as genéricas, não importando qual vem antes. Assim

  %!encoding(html): iso-8859-1
  %!encoding: latin1

Irá expandir para 'iso-8859-1' quando chamado com "-t html" mesmo que 'latin1' seja definido logo após.

Filtros são Cumulativos

Os filtros pre/postproc não tem precedência e não se encaixam no esquema "último encontrado", eles são cumulativos. O usuário pode configurar múltiplos filtros, e eles serão aplicados na ordem em que são definidos.

Por exemplo:

  %!postproc     : ^ \t
  %!postproc(txt): ^ '> '

Com estes filtros, todos os tipos-destino serão indentados por uma TAB. Se o tipo-destino é TXT, ele também receberá quotações, como mensagens de email.

  Desta forma        My nice line.
  se tornará         \t> My nice line.

Em Resumo


Parte VI - Magia Negra

Este capítulo não é recomendado para novatos. Ele demonstra como fazer coisas estranhas com os filtros txt2tags, abusando de padrões complexos e Expressões Regulares.

CUIDADO! Os procedimentos detalhados a seguir NÃO são encorajados e podem acarretar danos. Mesmo algum texto dos documentos origem podem ser perdidos no processo de conversão, não aparecendo no arquivo gerado. Use estas táticas se você realmente precisa delas e sabe o que está fazendo.

Filtros são um recurso poderoso, mas podem ser perigosos!

Filtros mal-feitos geram resultados inesperados.

Tenha isto em mente, sempre.


Inserindo Múltiplas Linhas com %!PostProc (como regras CSS)

Nos filtros, o padrão de troca pode incluir múltiplas linhas usando o caracter de quebra de linha, \n.

Esta funcionalidade pode ser útil para incluir regras CSS curtas em um arquivo HTML gerado, sem a necessidade de se criar um arquivo separado. É o caso deste Guia do Usuário, que usa estes filtros:

  %!postproc: <HEAD>      '<HEAD>\n<STYLE TYPE="text/css">\n</STYLE>'
  %!postproc: (</STYLE>)  'body     { margin:3em               ;} \n\1'
  %!postproc: (</STYLE>)  'a        { text-decoration:none     ;} \n\1'
  %!postproc: (</STYLE>)  'pre,code { background-color:#ffffcc ;} \n\1'
  %!postproc: (</STYLE>)  'th       { background-color:yellow  ;} \n\1'

Todos os filtros estão presos ao primeiro, ao substituir uma string que ele inseriu. desta forma, um simples "<HEAD>" torna-se:

  <HEAD>
  <STYLE TYPE="text/css">
  body     { margin:3em               ;}
  a        { text-decoration:none     ;}
  pre,code { background-color:#ffffcc ;}
  th       { background-color:yellow  ;}
  </STYLE>


Criando Conteúdo "Específico ao Tipo Destino", com %!PreProc

Algumas vezes é necessário inserir algum texto só para um tipo destino específico, e não para outros. Este tipo de comportamento estranho pode ser feito usando alguns truques PreProc.

A idéia é inserir este texto extra no arquivo original como comentário, mas marcá-lo de forma que um filtro específico para aquele tipo destino irá "descomentar" aquelas linhas.

Por exemplo, se um parágrafo extra deve ser acrescentado somente no tipo destino HTML. Coloque o texto em um comentário especial, como este:

  %html% This HTML page is Powered by [txt2tags http://txt2tags.sf.net].
  %html% See the source TXT file [here source.t2t].

Como todas estas linhas começam com %, elas são linhas de comentário e serão ignoradas. Mas se acrescentarmos este filtro especial:

  %preproc(html): '^%html% ' ''

A string inicial é removida e aquelas linhas serão "ativadas", deixando de ser comentários. Como uma configuração específica a um tipo, este filtro será processado apenas quando for gerado um arquivo HTML.


Mudando Marcas txt2tags com %!PreProc

Se o usuário for um guru de Expressões Regulares, ele pode personalizar a sintaxe do documento, mudando as marcações txt2tags padrão para algo que ele achar mais confortável.

Por exemplo, uma TAB é a marca de quotação. Se o usuário não gostar disto, ou se seu texto tenha um estranho relacionamento com as TABs, ele pode definir uma nova marca para texto quotado. Digamos que colocar ">>> " seja sua escolha. Então ele irá precisar deste filtro simples:

  %!PreProc: '>>> ' \t

E no documento original, o texto quotado vai parecer algo tipo:

  >>> This is a quoted text.
  >>> The user defined this >>> mark.
  >>> But they will be converted to TABs by PreProc.

Antes que a análise do programa comece, os ">>> " esquisitos serão convertidos em TABs e o txt2tags irá reconhecer a marca de quotação.

CUIDADO! Regras PreProc extremas podem eventualmente mudar toda a sintaxe de marcação, e até mesmo gerar conflitos entre as marcações. Tenha muito cuidado quando trabalhar com estas regras.


Parte VII - História do txt2tags

Em julho de 2001, foi lançada a primeira versão ao público do txt2tags (v0.1). Mas suas origens vem de mais de um ano antes daquele dia...

Este capítulo ilustra em algumas palavras o desenvolvimento desta ferramenta desde a primeira linha ser escrita até a série atual.

Janeiro de 1999: Pré História

Do autor:

"Minha primeira tentativa de fazer uma ferramenta de conversão começou em 1999, como um script Bourne Shell que convertia texto com marcação em uma página HTML. Sim, Mais Outra ferrametna txt2html. Todo mundo já deve ter feito uma destas... Em resumo, ele reconhecia marcações simples como *bold*, /italic/, _under_, e escapava os caracteres especiais < & > do HTML. Não muito impressionante, mas hei, eu era novinho;)"

Junho 1999: Ainda Pré-História

O autor tem mais a dizer:

"Passaram-se alguns meses, e uma grande hype em torno da Sgml chegou à companhia que eu trabalhava (Conectiva). Então o txt2html tornou-se um script txt2sgml. Eu estava realmente tentando aprender sobre o SED* naquele tempo, de forma que o txt2tags na época era um script Bourne Shell com muito código SED."

* SED: UNIX Stream EDitor - uma ferramenta de edição automática de textos

Esta versão melhorada, com suporte a Sgml, oferecia suporte a mais estruturas como listas e texto preformatado. No seguinte arquivo exemplo, pode-se ver as origens das marcações txt2tags:

  		 * This was a bold line (BOLD line oriented? well...)
  
  		   --
  		 - bullet list was very similar to txt2tags list
  		 - but with these -- to begin and close a list
  		   --
  
  		 =----------------------
  		 Preformatted text was delimited by the =-- pattern.
  		 The other ------- was just cosmetic.
  		 =----------------------

Ainda não era impressionante, mas o grande passo está chegando...

Agosto de 2000: Não Mais Pré-História

TODO (txt2sgml.sed)

Julho de 2001: Debut das séries 0.x (Lançamento Mundial)

TODO

Setembro de 2002: Debut das séries 1.x

Announce
This release starts my 1.x series.

More than a year of almost-monthly updates, and the 0.x series provided me a nice set of features, as Command Line and Web interface, TOC handling, numbering titles and lists, STDIN/STDOUT facilities, vim/emacs syntax files and seven supported target formats.

For the incoming 1.x series, I'll try to spread myself out, providing a nice GUI, extensive documentation, mailing list, user base, Unix/Windows/Mac full compatibility and including more targets (as tex, rtf and xhtml).

On this 1.0 release I'm already at full speed ahead, with a new suit (Graphical Tk Interface) and compatibility with Unix/Windows/Mac, handling line breaks and other platform specific issues. Fortunely, now my master can reach Linux, Windows 2000, Cygwin and MacOS 8.6 systems for testing me.

2002, 2003... e as História não para

06 November 2002 - Released my new version 1.1

Atention! Please read carefuly before upgrade me!

This new v1.1 is a compatibility break release.

This means that after upgrading, you will have to check your current txt2tags files, and possibly fix them. Ignore this release is not an option :) because the next versions will assume you have fixed your files.

Please read the "Survivor's Guide for v1.1 Upgrade" for more detailed information of what has changed and how to fix your files.

But there are nice news also:
03 December 2002 - Released my new version 1.2 (LaTeX release)

Hi! Finally I've learned one of the geek's most used document formatting: LaTeX. Just run me with "-t tex" and see your current .t2t files turn into LaTeX, ready for compiling!

Ah! I'm getting smart, and now I can handle more than one file at the same time. Hint: "*.t2t"

And my last new feature is the ability of strip down an HTML file to an "almost finished" .t2t file. Sorry !vimmers, because this works on Vim only.

What are you waiting for? Download me right now and test my new features: txt2tags --toc -t tex *.t2t

20 December 2002 - Released my new version 1.3

Weeee, I'm tired! Lots of changes were made on me for this release and now I need a break!

The news include a brand new mark (rare to happen!) for raw text, this way you can easily include marks on the document target and I promisse I won't parse them!

A new Encoding command is available also for worldwide users specify their own Character Set for their documents.

And there are more improvements and bugfixes, but please read the ChangeLog file because now I'll go to sleep. zzZZzzzzZZZZzz...

18 February 2003 - Released my new version 1.4

I've enjoyed my X-mas/New Year vacation, then some lazy days on a hot Brazilian beach, what a great time! But now it is time to get back to work, so there's a new release of the most sexy text eater out there: me!

The burning sun has made lots of changes on me. I'm privately proud of my new ability to master table alignment. I can place the table centered or not, and I can place each table cell contents wherever I want! Left, Right, Centered... See AbuseMe! file for a demonstration.

The good news for HTML users is that now I've learned about that Cascading thing... SCC, CCS, CSS, I don't remember... Just use my new --style command line option or the %!Style: setting.

There's a new --toclevel option also, and I promisse I'll not make TOC deeper than the number you pass me.

Mmmmmm, there were some bug fixes also, but let's forget about them, you know I'm not buggy! ;)

09 May 2003 - Released my new version 1.5

Tsc, Tsc... Almost three months from the last version, what a shame! But the new features will worth the delay.

The most important improvement is my new %!cmdline setting. Using it you can define default options for each document, and when converting, you can call me with no options at all! Example: You place a "%!cmdline: -t html --toc" line on your source document, then you can convert it with the simple "txt2tags file.t2t" command.

There is also a new --outfile option (-o for short) to set the output filename. If you specify "-o -", you get the same behaviour of the old --stdout option (which is now deprecated).

Talking about options, there are the new short -H and -n for the existing --noheaders and --enumtitle options. A nice quick example:

  txt2tags-v1.4 -t html --enumtitle --stdout file.t2t > new.html
  txt2tags-v1.5 -t html -n -o new.html file.t2t

Ah! LaTeX target now supports images :)

23 Jul 2003 - Released my new version 1.6

Hi there! Here I am again with fresh news.

Today my v1.6 was released. The main improvement is the new %!preproc: and %!postproc: user defined filters. They are used to do some strange things on documents (see User Guide). There's also a new mark + for explicit numbered titles, +like this+, so now you can mix normal titles with numbered ones, like a book with Appendix.

Now all the config settings can be linked with a especific target, using the new %!key(target): value syntax. The target specification is optional, so the parentesis and its contents can be omitted. A nice sample: %!encoding(html): iso-8859-1

Lots of user reported bugs was fixed, titles on LaTeX are unnumbered by default (as other targets) and the Gui was improved, showing %!cmdline contents (if any) and refreshing checkboxes when a new file is loaded. Gui also can receive options from the command line, as in txt2tags --gui -n file.t2t

Fim. (veja o fonte)

1