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