Olá, eu sou o guia do usuário 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.org/userguide/
Para mais informações e versões recentes, visite o website do txt2tags.
Bom proveito!
Este capítulo apresenta o txt2tags, introduzindo as funcionalidades e objetivo do programa.
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:
Você achará o txt2tags bastante útil se você:
E a motivação principal é:
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 código do documento gerado também é legível, alinhado e possui linhas curtas. |
| Consistência na Marcação | As marcações txt2tags são únicas, atendendo todos os tipos de documentos e não sendo confundidas com o conteúdo. |
| Regras Consistentes | Da mesma forma que as marcas, as regras aplicadas a elas são uniformes, não há "exceções" ou "casos especiais". |
| Estruturas Simples | Toda a formatação suportada é simples, sem opções extras 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 mostras reais de documentos simples e super-estruturados, escritos no formato txt2tags. |
| Ferramentas Valiosas | Os arquivos de sintaxe incluídos com o pacote (para os editores vim, emacs, nano e kate) 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 usar 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. |
| Baixe e Execute / Multiplataforma | O txt2tags é apenas um script Python. Não há necessidade de compilá-lo 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 melhorias. O próprio autor é um usuário intenso em casa e no trabalho, por isto o desenvolvimento não irá parar tão cedo. |
| Absolutamente NÃO! |
|---|
O txt2tags é um programa gratuito, GPL, open source, domínio público, etc...
Você pode copiar, usar, modificar, vender, liberar como seu. As políticas de software e copyright não são uma das maiores preocupações do autor.
Segue uma lista de todas as estruturas suportadas pelo txt2tags.
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.
{{{'''''acrescentando chaves e plicas'''''}}}, mas o txt2tags vem
com as marcações simplificadas e uma solução unificada: uma fonte,
múltiplos formatos destino.
| Estrutura | html | xhtml | sgml | tex | man | mgp | moin | pm6 | txt |
|---|---|---|---|---|---|---|---|---|---|
| cabeçalhos | S | S | S | S | S | S | N | N | S |
| título de seções | S | S | S | S | S | S | S | S | S |
| parágrafos | S | S | S | S | S | S | S | S | S |
| negrito | S | S | S | S | S | S | S | S | - |
| itálico | S | S | S | S | S | S | S | S | - |
| sublinhado | S | S | - | S | - | S | S | S | - |
| pré-formatado | S | S | S | S | - | S | S | S | - |
| linha pré-formatada | S | S | S | S | S | S | S | S | - |
| área pré-formatada | S | S | S | S | S | S | S | S | - |
| área cotada | S | S | S | S | S | S | S | S | S |
| links internet | S | S | S | - | - | - | S | - | - |
| links e-mail | S | S | S | - | - | - | S | - | - |
| links locais | S | S | S | N | - | - | S | - | - |
| links nomeados | S | S | S | - | - | - | S | - | - |
| lista não-numerada | S | S | S | S | S | S | S | S | S |
| lista numerada | S | S | S | S | S | S | S | S | S |
| lista de definições | S | S | S | S | S | N | N | N | S |
| linha horizontal | S | S | - | S | - | S | S | N | S |
| imagem | S | S | S | S | - | S | S | N | - |
| tabela | S | S | S | S | S | N | S | N | N |
| Extras | html | xhtml | sgml | tex | man | mgp | moin | pm6 | txt |
| image align | S | S | N | N | - | S | N | N | - |
| table cell align | S | S | S | S | S | N | S | N | N |
| Legenda | |
|---|---|
| S | suportada |
| N | não suportada (talvez em uma versão futura) |
| - | não suportada (não pode ser feita neste formato) |
Assim como diferentes usuários possuem diferentes necessidades e ambientes, o txt2tags é 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.
Desde a versão 1.0, há uma bela Interface Gráfica, que funciona do Linux, Windows, Mac e outros.
O programa automaticamente detecta se seu sistema pode apresentar a
interface e a lança quando é chamado sem argumentos. Pode-se forçar a
apresentação da Interfaca Gráfica com a opção --gui. Se estiver
faltando algum recurso o programa irá alertar.
Nota: O módulo Tkinter é necessário. Como ele vem com a distribição padrão do Python você já deve tê-lo.
Ela é bastante simples e fácil de usar:
Uma boa opção a selecionar é "Dump to screen", assim se pode verificar o código resultante em uma janela separada, sem que o arquivo seja salvo. Quando o código estiver correto, basta desmarcá-la e o arquivo será gravado.
As cores padrão podem ser mudadas no arquivo ~/.txt2tagsrc,
configurando em %!guicolors. Por exemplo:
% minhas cores para a interface (fundo1, texto1, fundo2, texto2) %!guicolors: blue white brown yellow
A Interface Web está em funcionamento na Internet no endereço http://txt2tags.org/online.php, permitindo que o programa possa ser usado e testado antes de ser copiado.
Esta interface também pode ser colocada na intrant para uso local, evitando a instalação do txt2tags em todas as máquinas.
Para usuários de linha de comando acostumados, o parâmetro --help deve ser suficiente:
Uso: txt2tags [OPÇÕES] [arquivo.t2t ...]
-t, --target define o formato do destino. tipos suportados:
html, xhtml, sgml, tex, man, mgp, moin, pm6, txt
-i, --infile=ARQ define ARQ como o arquivo fonte ('-' para STDIN)
-0, --outfile=ARQ define ARQ como o arquivo destino ('-' para STDOUT)
-n, --enum-title numera todos os títulos como 1, 1.1, 1.1.1, etc
-H, --no-headers suprime os cabeçalhos, título e rodapé
--headers exibe os cabeçalhos, título e rodapé (padrão LIGADO)
--encoding informa a codificação de destino (utf-8, iso-8859-1, etc)
--style=ARQ utiliza ARQ como estilo do documento (CSS no Html)
--css-sugar insere tags compatíveis com CSS em destinos HTML e XHTML
--mask-email esconde e-mails dos robôs de SPAM. x@y.z vira <x (a) y z>
--toc inclui o Índice (Table of Contents) no documento destino
--toc-only exibe o Índice do documento e sai
--toc-level=N define o nível máximo do Índice para N
--rc lê a config do usuário em ~/.txt2tagsrc (padrão LIGADO)
--gui carrega a interface gráfica escrita em TK
-v, --verbose exibe mensagens informativas durante a conversão
-h, --help exibe este texto de ajuda e sai
-V, --version exibe a versão do programa e sai
--dump-config exibe todas as configurações encontradas e sai
Opções para DESLIGAR funcionalidades:
--no-outfile, --no-infile, --no-style, --no-encoding, --no-headers
--no-toc, --no-toc-only, --no-mask-email, --no-enum-title, --no-rc
--no-css-sugar
Exemplo:
txt2tags -t html --toc meuarquivo.t2t
Normalmente a saída convertida é gravada em 'arquivo.<tipo>'.
Utilize --outfile para forçar um nome para o arquivo de saída.
Se o arquivo de entrada é '-', lê de STDIN.
Se o arquivo de saída é '-', envia a saída para STDOUT.
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 redirecionamento | $ 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 |
| . | |
| Linha simples 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 |
%!preproc e %!postproc.
Basta baixar o programa e executar o mesmo no seu computador.
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 existem, 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 txt2tags 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 lhe informar.
O local oficial de distribuição do txt2tags é na homepage do programa, em http://txt2tags.org/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).
Simplesmente 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.
Como é apenas um script Python, o txt2tags 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.
chmod +x txt2tags) e copie o mesmo para
um diretório no $PATH (cp txt2tags /usr/local/bin)
ren txt2tags txt2tags.py) e o copie 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 quiser usar a Interface Gráfica do programa.
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/
O txt2tags possui arquivos de sintaxe práticos que podem ser usados com os seguintes editores de texto:
Os arquivos de sintaxe têm registro de todas as regras e marcações do txt2tags, ajudando ao usuário a escrever documentos sem erros. As marcas são mostradas coloridas, assim se pode ver se tudo foi escrito corretamente.
 |
| O arquivo de exemplo aberto no Editor Vim |
Cada editor tem um procedimento diferente para usar seu arquivo de sintaxe. Por favor verifique no cabeçalho de cada arquivo e na documentação do editor.
Desculpe, este capítulo ainda está em desenvolvimento.
Os arquivos de marcação txt2tags são divididos em 3 áreas. Cada área tem suas próprias regras e finalidade. São elas:
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. |
Título do meu belo documento Sr. Fulano da Silva Última atualização: %%date(%c) %! Target : html %! Style : fancy.css %! Encoding: UTF-8 %! Options : --toc --enum--title Oi! Este é o meu documento de teste. E o seu conteúdo termina aqui.
Localização:
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:
%%date)
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.
À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.
| 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.
Localização:
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.
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 (":").
| %! palavra-chave : valor |
|---|
Detalhes da Sintaxe: O ponto de exclamação deve ser colocado
junto com o caractere de comentário, sem espaço entre eles ("%!").
Os espaços em torno da palavra-chave e o separador são opcionais, e
tanto a palavra-chave quanto o valor podem estar
indiferentemente em maiúsculas ou minúsculas.
As configurações que podem ser feitas são Target, Options, Style, Encoding, PreProc e PostProc.
A configuração Target define o destino padrão na qual o documento deve ser convertido.
A configuração Options é útil para especificar as opções de
linha de comando padrão para o arquivo fonte. Estas opções podem ser
sobrescritas pela linha de comando real. Usar esta opção juntamente com
%!target permite converter o documento simplesmente comandando:
txt2tags file.t2t
A configuração Style só é suportada pelo tipo de documento destino HTML, para definir uma folha de estilo (Cascading Style Sheets - CSS).
A configuração Encoding é necessária para escritores não ingleses, que 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 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 ocorra.
A configuração PostProc é um filtro. Ela define regras do tipo "busca e troca" que serão aplicadas ao arquivo destino depois de todo o processamento por parte do txt2tags.
Exemplo:
%! Target : html %! Options : --toc --toc-level 3 %! Style : fancy.css %! Encoding: UTF-8 %! PreProc : "amj" "Aurelio Marinho Jargas" %! PostProc: '<BODY.*?>' '<BODY bgcolor="yellow">'
txt2tagsrc,
as não sobre as opções de linha de comando.
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 A FAZER 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 quando os cabeçalhos estão em um arquivo separado, que será
unido ao corpo depois da conversão.
Todas as marcações e sintaxe usadas pelo txt2tags estão detalhadas em um arquivo REGRAS a parte.
A macro %%date chamada sem nenhum parâmetro adicional retorna a data
atual no formato ISO yyyymmdd. Uma formatação opcional pode ser
especificada usando a sintaxe %%date(formato).
O formato contém texto de diretivas de formatação, que são compostas
por um sinal de porcentagem (%) seguido por um caractere 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 caractere "%". |
%%date(format) |
Resultado para: 2004, Jul13, 18:49 |
|---|---|
| Last Update: %c | Last Update: Tue Jan 13 18:49:32 2004 |
| %Y-%m-%d | 2004-07-13 |
| %I:%M %p | 18:49 PM |
| Hoje e %A, em %B. | Hoje e Tuesday, em July. |
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 na área de 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
%!include. 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 três tipos de inclusão:
No tipo Verbatim o texto é incluído preservado seus espaços e formatação originais. É como se esse texto estivesse entre as marcações (```) da área VERB do txt2tags. Para incluir um arquivo dessa maneira, basta colocar seu nome entre crases:
%!include: ``/etc/fstab``
No tipo Raw o texto é incluído "como está", sem tentar encontrar e avaliar as marcas do txt2tags dele. É como se esse texto estivesse entre as marcações (""") da área protegida. Para incluir um arquivo dessa maneira, basta colocar seu nome entre aspas
%!include: ""bom_texto.txt""
Já no tipo Tagged, 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.
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 :)
Usando a configuração Target define o destino padrão definido no documento:
%!target: html
Assim o usuário pode simplesmente comandar
$ txt2tags file.t2t
E a conversão será efetuada para o destino especificado.
A configuração Target não permite a especificação opcional de destino.
Afinal, não faz sentido algo como %!target(tex): html.
Escrever longas linhas de comando toda vez que for necessário converter um documento é maçante e sujeito a erros. A configuração Options permite que o usuário salve todas as opções de conversão juntas, no próprio documento. 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 Options dentro do documento origem:
%!target: html %!options(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údo está sendo editado. No Vi, o comando é:
:!txt2tags %
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 UTF-8 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.
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 "2004-07-13" %!preproc BOLOTA "[images/tiny/bullet_blue.png]"
Desta forma, o usuário pode escrever uma linha como:
Oi, eu sou amj. Hoje é RELEASE_DATE.
E o txt2tags irá ver esta linha como:
Oi, eu sou Aurelio Marinho Jargas. Hoje é 2004-07-13.
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 arquivo.t2t | preproc-script.sh | txt2tags -
Assim, o tratamento executado pelo txt2tags irá começar após todas as substituições PreProc terem sido feitas.
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 ou texto extra. Alguns exemplos breves:
%!postproc(html): '<BODY.*?>' '<BODY BGCOLOR="green">' %!postproc(tex) : "\\clearpage" ""
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- arquivo.t2t | postproc-script.sh > arquivo.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.
\usepackage.
--style.
$ cat file.t2t | preproc.sh | txt2tags | postproc.sh
\n e \t são interpretados
%!postproc: "undesired string" ""
%!PostProc(destino): <isto> <aquilo>
%!postproc(html): '(</?)B>' '\1STRONG>'
%!postproc: PADRÃO TROCA %!postproc: "PADRÃO" "TROCA" %!postproc: 'PADRÃO' 'TROCA' %!postproc: PADRÃO "TROCA" %!postproc: "PADRÃO" 'TROCA'
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 Encoding para HTML e LaTeX:
%!encoding(html): UTF-8 %!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 %!options, pode ser interessante:
%!target: sgml %!options(sgml): --toc %!options(html): --style foo.css %!options(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
%!options(html) serão usadas. Desta forma, a opçõa --style será
usada e o arquivo HTML não terá TOC.
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): UTF-8 %!encoding: latin1
Irá expandir para 'UTF-8' quando chamado com -t html mesmo que
'latin1' seja definido logo após.
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á citações, como mensagens de email.
Desta forma Minha bela linha. se tornará \t> Minha bela linha.
Há três maneiras de dizer ao txt2tags quais opções e configurações usar:
.txt2tagsrc)
E esta é a ordem exata de como as configurações são lidas e aplicadas. Logo, as configuraçõe dp arquivo RC são lidas primeiro, daí as configurações do fonte do documento vêm a seguir, sobreescrevendo as do RC e finalmente as opções da linha de comando, mais fortes do que as outras duas.
Então se o "encoding" do documento foi definido nas três opções, a da linha de comando será a utilizada.
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. Até mesmo algum texto do arquivo fonte pode ser perdido 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.
Nos filtros, o padrão de troca pode incluir múltiplas linhas usando o
caractere 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>
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 de 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% Esta página HTML foi produzida pelo [txt2tags http://txt2tags.org]. %html% Veja o arquivo fonte TXT [aqui fonte.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.
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 citaçã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 citado. Digamos que colocar ">>>" seja sua escolha. Então ele irá precisar deste filtro simples:
%!PreProc: '>>> ' \t
E no documento original, o texto citado vai parecer algo tipo:
>>> Este é um texto de citação. >>> O usuário definiu esta marca esquisita. >>> Mas elas serão convertidas para TABs pelo PreProc.
Antes que a análise do programa comece, os ">>> " esquisitos serão convertidos em TABs e o txt2tags irá reconhecer a marca de citaçã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.
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.
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 ferramenta 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 ei, eu era novinho ;)"
O autor tem mais a dizer:
"Passaram-se alguns meses, e um grande hype em torno de 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:
* Esta é uma linha em negrito (NEGRITO orientado a linha? bem...) -- - lista não numerada muito semelhante à lista do txt2tags - mas com estes -- para iniciar e terminar a lista -- =---------------------- Texto preformatado era delimitado pelo =-- padrão. Os outros ------- eram apenas cosméticos. =----------------------
Ainda não era impressionante, mas o grande passo está chegando...
TODO (txt2sgml.sed)
TODO
[[img.gif] www.abc.com]
-t tex" e veja seus arquivos
.t2t tornarem-se LaTeX, prontos para compilar!
Ah! Estou ficando esperto e agora posso cuidar de mais de um arquivo
ao mesmo tempo. Dica: "*.t2t"
E meu último novo recurso é a habilidade de tornar um arquivo HTML em
um arquivo .t2t "quase pronto". Desculpem-me os não-usuários do vim
porque isso só funciona neste editor.
O que você está esperando? Baixe-me agora e teste meus novos recursos:
txt2tags --toc -t tex *.t2t
--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! ;)
%!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.t2tAh! LaTeX target now supports images :)
%!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
%!include. Com ele você pode incluir texto, tags e até
mesmo outro arquivo .t2t no documento original. Veja como fazer isso
no Guia do Usuário.
Fora isso mais checagens foram adicionadas e bugs foram corrigidos.
Os usuários do Emacs ficarão felizes com o arquivo novo de sintaxe.
Os usuários do Vim continuarão felizes com o arquivo de sintaxe
atualizado.
MUITO IMPORTANTE: Essa versão fecha a minha série 1.x, então não
haverão versões 1.8 e 1.9. A próxima será a tão esperada 2.0, com
código reescrito, conversões mais ricas e enxutas e suporte ao
destino XHTML. Eu serei mais massa!
Fim. (veja o fonte)