TXT2TAGS

Jul, 2008

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, Wikipedia, DokuWiki, Google Code Wiki, 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.

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

OPÇÕES

-C, --config-file
lê a configuração de um arquivo externo (igual ao %!includeconf)

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

--dump-source
exibe os fontes do documento, com os includes expandidos

--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-dump-config
desativa a opção de exibir as configurações

--no-dump-source
desativa a opção de exibir os fontes

--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, desativando a opção --mask-email

--no-outfile
exclui as definições anteriores sobre o arquivo de destino

--no-quiet
mostras as mensagens, desativando a opção --quiet

--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 sumário (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)

-q, --quiet
modo silencioso, não mostra nada na saída (exceto os erros)

--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=TIPO
define o tipo do documento de destino. atualmente suportados: html, xhtml, sgml, tex, lout, man, mgp, wiki, gwiki, doku, moin, pm6, txt

--toc
inclui o sumário (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: file.t2t
inclui um arquivo txt2tags no documento

%!include: ``arquivo.txt``
inclui um arquivo texto no documento

%!include: ''arquivo.html''
inclui 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

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__
  Riscado           --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""
  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

Teste rápido de uma linha vindo de STDIN
$ echo -e "\n**negrito**" | txt2tags -t html -H -

MACROS

%%date
Representa a data atual, usando o formato YYYYMMDD. Também é possível mudar o formato da data usando a seguinte sintaxe: %%date(formato).

%%infile
Representa o nome do arquivo fonte. O formato pode ser especificado usando a seguinte sintaxe: %%infile(formato).

Útil para colocar um link para os fontes, no final do documento, como em [Veja os fontes %%infile]. Assim, você pode mudar o nome do arquivo, e o link não ficará quebrado.

%%mtime
Representa a data de modificação do arquivo fonte. Os mesmos formatos usados na macro %%date também são aceitos.

%%outfile
Representa o nome do arquivo de saída. O formato pode ser especificado usando a seguinte sintaxe: %%outfile(formato).

Útil para mencionar o próprio arquivo, como em "Este é o arquivo manpage-pt.html". Assim, você pode mudar o nome do arquivo, mas ele sempre aparecerá corretamente no documento.

%%toc
A macro %%toc indica em que local do documento deve ser inserido o sumário (Table Of Contents). Você pode utilizá-la em qualquer parte do documento, inclusive mais de uma vez.

NOTA: A %%toc só será aplicada se a opção --toc for utilizada.

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

Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Aurélio Marinho Jargas

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.