TXT2TAGS

Dezembro, 2004

NOME

txt2tags - ferramenta para formatar e converter textos

SINOPSE

txt2tags [OPÇÃO]... [ARQUIVO]...

DESCRIÇÃO

O txt2tags é uma ferramenta GPL de conversão de formatos escrita em Python que gera documentos em HTML, XHTML, SGML, LaTeX, Lout, Man Page, MoinMoin, MagicPoint e Pagemaker a partir de um único arquivo de texto com algumas marcações.

O usuário só precisa conhecer algumas marcas usadas pelo txt2tags, e escrever textos normais. O programa faz todo o trabalho sujo, adicionando as tags complicadas e lidando com as pegadinhas dos documentos de destino.

O mesmo arquivo texto pode ser convertido para todos os formatos disponíveis, sem a necessidade de qualquer alteração. Esta é a finalidade do txt2tags: UM arquivo fonte, VÁRIOS destinos.

NOTA: A versão 2.0 do txt2tags foi completamente reescrita a partir do zero. Logo, se você for um usuário de versões anteriores do txt2tags, é possível que necessite reescrever partes de seus documentos antigos.

Visite a página do programa em http://txt2tags.sourceforge.net.

OPÇÕES

--css-sugar: insere tags compatíveis com CSS em destinos HTML e XHTML
--css-inside: insere o conteúdo do arquivo CSS no documento HTML/XHTML
--dump-config: exibe todas as configurações encontradas e sai
--encoding: informa a codificação de destino (utf-8, iso-8859-1, etc)
--gui: carrega a interface gráfica escrita em TK
-h, --help: exibe o texto de ajuda e sai
-H, --no-headers: suprime os cabeçalhos, título e rodapé
--headers: exibe os cabeçalhos, título e rodapé (padrão LIGADO)
-i, --infile=ARQUIVO: define ARQUIVO como arquivo fonte ('-' para STDIN)
--mask-email: esconde os e-mails dos robôs de SPAM. x@y.z vira <x (a) y z>
-n, --enum-title: numera todos os títulos como 1, 1.1, 1.1.1, etc
--no-encoding: exclui a configuração de codificação
--no-enum-title: desativa a auto-numeração de títulos
--no-infile: exclui as definições anteriores do arquivo fonte
--no-mask-email: exibe os e-mails, desabilitando a opção --mask-email
--no-outfile: exclui as definições anteriores sobre o arquivo de destino
--no-rc: não lê o arquivo configuração do usuário em ~/.txt2tagsrc
--no-style: exclui as configurações de estilo
--no-toc: não inclui o Índice (Table of Contents) no documento de destino
--no-toc-only: desativa a opção --toc-only
-o, --outfile=ARQUIVO: define ARQUIVO como destino ('-' para STDOUT)
--rc: lê a configuração do usuário em ~/.txt2tagsrc (padrão LIGADO)
--style=ARQUIVO: utiliza ARQUIVO como estilo do documento (como o CSS do Html)
-t, --target: define o tipo do documento de destino. atualmente suportados: html, xhtml, sgml, tex, man, mgp, moin, pm6, txt
--toc: inclui o Índice (Table of Contents) no documento de destino
--toc-level=N: define o nível máximo (profundidade) do Índice para N
--toc-only: exibe o Índice do documento e sai
-v, --verbose: exibe mensagens informativas durante a conversão
-V, --version: exibe a versão do programa e sai

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.

ESTRUTURA

Um arquivo fonte txt2tags pode ter três áreas:

Cabeçalho: As primeiras três linhas. São usadas para identificação do documento. Se não for necessário, o cabeçalho pode ser suprimido pela configuração no-header.
Configuração: Inicia a partir da quarta linha. Todas as configurações têm o formato %!chave: valor. As configurações também podem ser realizadas por arquivos de configuração ou linha de comando.
Corpo: O verdadeiro documento! É a única área necessária para que se tenha um documento txt2tags válido.

CONFIGURAÇÕES

O Txt2tags pode ser personalizado por métodos internos e externos. Os meios externos podem ser de um arquivo chamado .txt2tagsrc ou importado de outro arquivo txt2tags. O jeito interno é feito por comandos incluídos na área de configuração do fonte. Ambas formas usam a mesma sintaxe:

%!target:: define o formato destino (target) principal
%!options(target):: define as opções de cada destino
%!include: arquivo.txt: incli um arquivo texto no documento
%!include: ''arquivo.html'': include um arquivo literal no documento, ipsis literis
%!style:: para indicar um arquivo CSS (Cascading Style Sheets) para os destinos XHTML e HTML ou carregar um módulo \usepackage no destino TEX
%!encoding:: para indicar um conjunto de caracteres (como iso-8859-1) para usuários de língua não-inglesa
%!includeconf:: usado para incluir configurações a partir de um arquivo externo
%!guicolors:: configurações de cores para a interface gráfica (tk/tcl)
%!preproc:: filtros personalizados (macros) que serão processados ANTES da avaliação do documento
%!postproc:: filtros personalizados (macros) que serão processados APÓS a avaliação do documento

REGRAS DAS CONFIGURAÇÕES

As configurações são válidas somente dentro da Área de Configuração, e serão consideradas comentários simples se forem encontradas no Corpo do documento.
Se a mesma palavra-chave aparece mais de uma vez na Área de Configuração, apenas a última será usada. Exceção: options, preproc e postproc, que são acumulativas.
Uma linha de configuração com uma palavra-chave inválida será considerada um comentário.
Estas configurações têm precedência sobre o arquivo txt2tagsrc, mas não sobre as opções de linha de comando.

SINTAXE

Uma sintaxe de marcas bem simples é utilizada no arquivo fonte (o arquivo de texto puro) para identificar as estruturas e a formatação. Aqui está a lista completa:

Básico

  Cabeçalhos        As 3 primeiras linhas do arquivo fonte
  Título            = palavras =
  Título numerado   + palavras +
  Parágrafo         palavras

Embelezadores

  Negrito           **palavras**
  Itálico           //palavras//
  Sublinhado        __palavras__
  Monoespaçado      ``palavras``

Text Blocks

  Citação             <TAB>palavras
  Lista               - palavras
  Lista numerada      + palavras
  Lista de definição  : palavras
  Linha formatada     ``` palavras
  Área formatada      ```<Quebra> linhas <Quebra>```
  Linha protegida     """ palavras
  Área protegida      """<Quebra> linhas <Quebra>"""
  Tabela              | cel1 | cel2 | cel3...

Outros

  Linha de separação  -----------------------...
  Linha destacada     =======================...
  Links               [nome url]
  Imagem              [arquivo.XXX]
  Texto protegido     ""palavras""
  Data atual          %%date(formato)
  Comentário          % comentários

EXEMPLOS

Supondo que você criou um arquivo marcado chamado arquivo.t2t, vamos nos divertir fazendo algumas conversões.

Converte para HTML, gravando em arquivo.html: $ txt2tags -t html arquivo.t2t
Similar ao anterior, usando redirecionamento: $ txt2tags -t html -o - arquivo.t2t > arquivo.html
Incluindo o Índice: $ txt2tags -t html --toc arquivo.t2t
Incluindo o Índice e títulos numerados: $ txt2tags -t html --toc --enum-title arquivo.t2t
Exibição rápida do conteúdo: $ txt2tags --toc-only arquivo.t2t
Utilizando a interface gráfica: $ txt2tags --gui arquivo.t2t
Edição pós-conversão utilizando filtro externo: $ txt2tags -t html -o- arquivo.t2t | sed -f meufiltro.sed > arquivo.html
Teste rápido de uma linha vindo de STDIN: $ echo -e "\n**negrito**" | txt2tags -t html -H -

UTILIDADES

Há alguns truques que tornam o txt2tags uma excelente ferramenta de documentação:

Ancoramento

Os Títulos podem ser ligados por âncoras (se o formato de destino permitir). Isso permite ir diretamente a alguma parte do documento.

  Título            = palavras =[âncora]
  Título Numerado   + palavras +[âncora]

Múltiplos arquivos

O Txt2tags pode manipular mais de um arquivo, como: txt2tags *.t2t

A macro %%date

Permite incluir a data corrente no formato ISO aaaammdd. Uma formatação opcional pode ser especificada com a sintaxe %%date(formato).

AUTOR

O txt2tags foi criado e é mantido por Aurélio Marinho Jargas <<verde (a) aurelio net>>

Esta Página de Manual foi escrita por José Inácio Coelho <<jic (a) technologist com>> como um arquivo texto, e convertida para o formato de manual no txt2tags!

A tradução deste manual para o português foi feita por Mauricio Teixeira <<mteixeira (a) webset net>>

LICENÇA

Este programa é livre. Veja nos arquivos fonte as condições de cópia. NÃO HÁ garantia, nem de COMERCIALIZAÇÃO nem de ADEQUAÇÃO A QUALQUER PROPÓSITO.