userguide-pt.html | searchcode

/doc/Portuguese/userguide-pt.html

http://txt2tags.googlecode.com/
HTML | 2503 lines | 2348 code | 155 blank | 0 comment | 0 complexity | 10c3d69f49fe24423985d57058a5a0ea MD5 | raw file
Possible License(s): GPL-2.0, GPL-3.0, WTFPL

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
<STYLE TYPE="text/css">
body {background-color:#ddeeff; color:black;   
      margin:2em; text-align:justify;}         
a {text-decoration:none;}
a:hover {color:red;}
a:visited {color:purple;}
dl {margin:1em;}    
h1 {text-align:center; background-color:blue;  
    color:white; padding:8px;}                 
h2 {padding-top:20px;}
hr {border-style:none;}
code {background-color:lightblue;}             
table {border-style:solid; border-color:black;}
th {background-color:lightblue; padding:1em;}  
td {border-style:none; background-color:white;}
pre {border-style:solid; border-width:1px 1px; 
     background-color:lightblue; padding:8px;  
     border-color:black;}                      
</STYLE>
<META NAME="generator" CONTENT="http://txt2tags.org">
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=UTF-8">
<TITLE>Guia do Usuário Txt2tags</TITLE>
</HEAD><BODY BGCOLOR="white" TEXT="black">
<CENTER>
<H1>Guia do Usuário Txt2tags</H1>
<FONT SIZE="4"><I>Aurelio, Wed Jan 11 20:53:37 2012</I></FONT><BR>
<FONT SIZE="4">Tradução para o português: César A. K. Grossman</FONT>
</CENTER>

<P></P>
<HR NOSHADE SIZE=1>
<P></P>

  <UL>
  <LI><A HREF="#toc1">Sobre este documento</A>
  <LI><A HREF="#toc2">Parte I - Introdução ao Txt2tags</A>
    <UL>
    <LI><A HREF="#toc3">Suas Primeiras Questões</A>
    <LI><A HREF="#toc4">Estruturas de Formatação Suportadas</A>
    <LI><A HREF="#toc5">Formatos Suportados</A>
    <LI><A HREF="#estruturas">Situação dos Formatos-Destino para as Estruturas Suportadas</A>
    <LI><A HREF="#toc7">As Três Interfaces ao Usuário: GUI, Web e Linha de Comando</A>
    </UL>
  <LI><A HREF="#instalacao">Parte II - OK, eu quero um. E agora?</A>
    <UL>
    <LI><A HREF="#toc9">Download e Instalação do Python</A>
    <LI><A HREF="#toc10">Copiando o txt2tags</A>
    <LI><A HREF="#toc11">Instalação do txt2tags</A>
    <LI><A HREF="#sintaxe">Instalar os Arquivos de Sintaxe dos Editores de Texto</A> <b>[NOVO!]</b>
    </UL>
  <LI><A HREF="#toc13">Parte III - Escrevendo e Convertendo Seu Primeiro Documento</A>
    <UL>
    <LI><A HREF="#toc14">As Áreas do documento .t2t</A>
    </UL>
  <LI><A HREF="#toc15">Parte IV - Dominando o Txt2tags</A>
    <UL>
    <LI><A HREF="#toc16">A Área de Cabeçalho</A>
    <LI><A HREF="#toc17">A Área de Configuração</A>
    <LI><A HREF="#toc18">O Corpo do Texto</A>
    <LI><A HREF="#regras">Marcações (REGRAS)</A>
    <LI><A HREF="#data">A macro %%date</A>
    <LI><A HREF="#include">O comando %!include</A>
    </UL>
  <LI><A HREF="#settings">Parte V - Dominando as Diretivas de Configuração</A>
    <UL>
    <LI><A HREF="#toc23">%!Target</A> <b>[NOVO!]</b>
    <LI><A HREF="#toc24">%!Options</A> <b>[NOVO!]</b>
    <LI><A HREF="#toc25">%!Encoding</A>
    <LI><A HREF="#toc26">%!PreProc</A>
    <LI><A HREF="#toc27">%!PostProc</A>
    <LI><A HREF="#toc28">%!Style</A>
    <LI><A HREF="#toc29">Detalhes dos Filtros PreProc e PostProc</A>
    <LI><A HREF="#toc30">Definindo uma Configuração para um Tipo-Destino Específico</A>
    <LI><A HREF="#toc31">RC, CONF e a precedência de linha de comando</A> <b>[NOVO!]</b>
    </UL>
  <LI><A HREF="#toc32">Parte VI - Magia Negra</A>
    <UL>
    <LI><A HREF="#toc33">Inserindo Múltiplas Linhas com %!PostProc (como regras CSS)</A>
    <LI><A HREF="#toc34">Criando Conteúdo "Específico ao Tipo Destino", com %!PreProc</A>
    <LI><A HREF="#toc35">Mudando Marcas txt2tags com %!PreProc</A>
    </UL>
  <LI><A HREF="#historia">Parte VII - História do txt2tags</A>
    <UL>
    <LI><A HREF="#toc37">Janeiro de 1999: Pré História</A>
    <LI><A HREF="#toc38">Junho 1999: Ainda Pré-História</A>
    <LI><A HREF="#toc39">Agosto de 2000: Não Mais Pré-História</A>
    <LI><A HREF="#toc40">Julho de 2001: Debute das séries 0.x (Lançamento Mundial)</A>
    <LI><A HREF="#toc41">Setembro de 2002: Debute das séries 1.x</A>
    <LI><A HREF="#toc42">2002, 2003... e as História não pára</A>
    </UL>
  </UL>

<P></P>
<HR NOSHADE SIZE=1>
<P></P>

<H1 ID="toc1">Sobre este documento</H1>

	<BLOCKQUOTE>
	Olá, eu sou o guia do usuário do txt2tags!
	</BLOCKQUOTE>
	<BLOCKQUOTE>
	Aqui você encontra toda a informação disponível sobre a
	ferramenta de conversão de textos txt2tags.
	</BLOCKQUOTE>
	<BLOCKQUOTE>
	Minha versão atualizada pode ser encontrada em
	<A HREF="http://txt2tags.org/userguide/">http://txt2tags.org/userguide/</A>
	</BLOCKQUOTE>
	<BLOCKQUOTE>
	Para mais informações e versões recentes, visite
	<A HREF="http://txt2tags.org/">o website do txt2tags</A>.
	</BLOCKQUOTE>
	<BLOCKQUOTE>
	Bom proveito!
	</BLOCKQUOTE>

<HR NOSHADE SIZE=5>

<H1 ID="toc2">Parte I - Introdução ao Txt2tags</H1>

<H2 ID="toc3">Suas Primeiras Questões</H2>

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

<HR NOSHADE SIZE=1>

<H3>O Que É?</H3>

<P>
O txt2tags é uma ferramenta de formatação e conversão de texto.
</P>
<P>
O txt2tags converte um arquivo texto com algumas marcas para qualquer um
dos tipos de arquivos suportados:
</P>

<UL>
<LI>Documento HTML
<LI>Documento XHTML
<LI>Documento SGML
<LI>Documento LaTeX
<LI>Página man UNIX
<LI>Apresentação Magic Point
<LI>Página MoinMoin
<LI>Documento PageMaker 6.0
<LI>Texto Plano (sem marcações)
</UL>

<HR NOSHADE SIZE=1>

<H3>Por Quê Eu Devo Usá-lo?</H3>

<P>
Você achará o txt2tags bastante útil se você:
</P>

<UL>
<LI>precisa publicar documentos em diferentes formatos
<LI>precisa manter documentos atualizados em diferentes formatos
<LI>escreve manuais ou documentos técnicos
<LI>não sabe como escrever um documento em um formato específico
<LI>não tem um editor específico para um certo formato.
<LI>quer usar um editor de texto simples para atualizar seus documentos
</UL>

<P>
E a motivação principal é:
</P>

<UL>
<LI>economizar tempo, escrevendo <B>conteúdo</B>, sem se preocupar com
  <B>formatação</B>
</UL>

<HR NOSHADE SIZE=1>

<H3>Quais vantagens oferece em relação a outras ferramentas?</H3>

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

<TABLE CELLPADDING="4">
<TR>
<TD><I>Arquivo fonte legível</I></TD>
<TD>As marcações do txt2tags são bastante simples, quase naturais.</TD>
</TR>
<TR>
<TD><I>Documento destino legível</I></TD>
<TD>Da mesma forma que o arquivo fonte, o código do documento gerado também é legível, alinhado e possui linhas curtas.</TD>
</TR>
<TR>
<TD><I>Consistência na Marcação</I></TD>
<TD>As marcações txt2tags são únicas, atendendo todos os tipos de documentos e não sendo confundidas com o conteúdo.</TD>
</TR>
<TR>
<TD><I>Regras Consistentes</I></TD>
<TD>Da mesma forma que as marcas, as regras aplicadas a elas são uniformes, não há "exceções" ou "casos especiais".</TD>
</TR>
<TR>
<TD><I>Estruturas Simples</I></TD>
<TD>Toda a formatação suportada é <B>simples</B>, sem opções extras ou modificadores complexos de comportamento. Uma marcação é só uma marcação, sem opções adicionais.</TD>
</TR>
<TR>
<TD><I>Fácil de aprender</I></TD>
<TD>Com marcações simples e o código fonte legível, a curva de aprendizado é bem amigável.</TD>
</TR>
<TR>
<TD><I>Bons Exemplos</I></TD>
<TD>Os <B>arquivos de exemplo</B> incluídos com o pacote dão mostras reais de documentos simples e super-estruturados, escritos no formato txt2tags.</TD>
</TR>
<TR>
<TD><I>Ferramentas Valiosas</I></TD>
<TD>Os <B>arquivos de sintaxe</B> incluídos com o pacote (para os editores vim, emacs, nano e kate) ajudam a escrever documentos sem erros sintáticos.</TD>
</TR>
<TR>
<TD><I>Três interfaces ao usuários</I></TD>
<TD>Há uma <B>interface Gráfica Tk</B> que é bastante amigável, uma <B>inteface Web</B> para usar remotamente ou na intranet, e uma <B>interface de Linha de Comando</B>, para usuários avançados e scripts.</TD>
</TR>
<TR>
<TD><I>Suporte a Scripts</I></TD>
<TD>Com o modo completo de linha de comando, um usuário experiente pode <B>automatizar</B> tarefas e efetuar <B>pós-edições</B> nos arquivos convertidos.</TD>
</TR>
<TR>
<TD><I>Baixe e Execute / Multiplataforma</I></TD>
<TD>O txt2tags é apenas um <B>script Python</B>. 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.</TD>
</TR>
<TR>
<TD><I>Atualizações Freqüentes</I></TD>
<TD>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.</TD>
</TR>
</TABLE>

<HR NOSHADE SIZE=1>

<H3>Tenho que pagar por ele?</H3>

<TABLE ALIGN="center" BORDER="1" CELLPADDING="4">
<TR>
<TH>Absolutamente NÃO!</TH>
</TR>
</TABLE>

<P>
O txt2tags é um programa gratuito, GPL, open source, domínio público,
etc...
</P>
<P>
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.
</P>

<HR NOSHADE SIZE=1>

<H2 ID="toc4">Estruturas de Formatação Suportadas</H2>

<P>
Segue uma lista de todas as estruturas suportadas pelo txt2tags.
</P>

<UL>
<LI>cabeçalho (título, nome do autor, data)
<LI>títulos de seções (numeradas ou não)
<LI>parágrafos
<LI>modificadores de fontes
  <UL>
  <LI>negrito
  <LI>itálico
  <LI>sublinhado
  </UL>
<LI>fonte monoespaço (verbatim)
  <UL>
  <LI>monoespaço no meio de um parágrafo
  <LI>linha monoespaçada
  <LI>trecho em monoespaçado
  </UL>
<LI>citações
<LI>links
  <UL>
  <LI>Links de Internet (URL)
  <LI>links de email
  <LI>links locais
  <LI>links nomeados
  </UL>
<LI>listas
  <UL>
  <LI>listas com marcadores
  <LI>listas numeradas
  <LI>listas de definição
  </UL>
<LI>linha horizontal de separação
<LI>imagems (com alinhamento inteligente)
<LI>tabela (com ou sem borda, com alinhamento inteligente)
<LI>marcação especial para texto que não deve ser formatado
<LI>macro especial para a data atual (com formatação flexível)
<LI>comentários (para notas, A FAZER, CORREÇÕES, etc.)
</UL>

<HR NOSHADE SIZE=1>

<H2 ID="toc5">Formatos Suportados</H2>

<DL>
<DT><B>HTML</B>                                                                </DT><DD>
Todo mundo sabe o que o HTML é (dica: Internet).
<P></P>
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. O Txt2tags gera código "<I>HTML 4.0 Transitional</I>".
<P></P>
Desde a versão 2.0, o código HTML gerado pelo txt2tags é 100% aprovado
pelo <A HREF="vhttp://validator.w3.org/">validador w3c</A>.
</DL>

<DL>
<DT><B>XHTML</B></DT><DD>
Esta é a nova generação do HTML, com regras mais restritas, como fechar
todas as marcas que forem abertas. Isto torna o código mas fácil de ser
avaliado e entendido. Para propósitos gerais, considere como HTML. O
txt2tags gera código "<I>HTML 4.0 Transitional</I>".
<P></P>
Desde a versão 2.0, o código XHTML gerado pelo txt2tags é 100% aprovado
pelo <A HREF="vhttp://validator.w3.org/">validador w3c</A>.
<P></P>
<DT><B>SGML</B></DT><DD>
O SGML é um formato de documento comum que possui aplicações de
conversão, como <A HREF="http://www.sgmltools.org/">sgmltools</A>. De um arquivo
sgml pode-se gerar documentos html, pdf, ps, info, latex, lyx, rtf e
xml. As ferramentas sgml2* também criam índices (TOC) e quebra de seções
em subpáginas (sgml2html).
<P></P>
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.
<P></P>
<DT><B>LATEX</B></DT><DD>
O formato de documentação preferido nos meios acadêmicos, é mais potente
do que normalmente se considera. Livros completos, fórmulas complicadas
e qualquer texto complexo pode ser escrito em LaTeX. Mas se prepare para
perder os cabelos se tentar escever as marcações à mão...
<P></P>
O txt2tags gera arquivos LaTeX prontos para usar, realizando todos os
complexos truques de escape e exceções. O escritor deve se preocupar
exclusivamente com o texto.
<P></P>
<DT><B>MAN</B></DT><DD>
As páginas man do UNIX resistiram pelos anos. Formatos de documento vem
e vão, e elas estão aí, imbatíveis.
<P></P>
Existem outras ferramentas para gerar documentos man, mas o txt2tags 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.
<P></P>
<DT><B>MGP</B></DT><DD>
O <A HREF="http://www.mew.org/mgp/">Magic Point</A> é 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.
<P></P>
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.
<P></P>
<B>Observação 1:</B> os arquivos .mgp criados pelo txt2tags usam as fontes
Type1 do XFree86! Desta forma, não é necessário incluir fontes TrueType
com sua apresentação.
<P></P>
<B>Observação 2:</B> 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
<CODE>startx -- -bpp 8</CODE>) a apresentação vai ter boa aparência.
<P></P>
A chave é: converta e use. Não há necessidade de remendos ou de outros
requisitos.
<P></P>
<DT><B>MOIN</B></DT><DD>
Você não sabe o que é o <A HREF="http://moin.sourceforge.net">MoinMoin</A>? Ele é
um <A HREF="http://www.c2.com/cgi/wiki">WikiWiki</A>!
<P></P>
A sintaxe do Moin é um pouco chata, quando você tem que ficar
<CODE>{{{'''''acrescentando chaves e plicas'''''}}}</CODE>, mas o txt2tags vem
com as marcações simplificadas e uma solução unificada: uma fonte,
múltiplos formatos destino.
<P></P>
<DT><B>PM6</B></DT><DD>
Aposto que você não sabia, mas o Adobe PageMaker 6.0 tem sua própria
linguagem de marcação! Estilos, tabelas de cores, embelezadores, 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.
<P></P>
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. <B>EPA:</B> Sem quebras de linha! Um parágrafo deve ser uma
única linha.
<P></P>
Nota do Autor:
<I>Todo meu livro em português sobre <A HREF="http://guia-er.sf.net/">expressões regulares</A></I>
<I>foi escrito no vi, convertido para o formato do PageMaker com o</I>
<I>txt2tags e então mandado para o prelo.</I>
<P></P>
<DT><B>TXT</B></DT><DD>
TXT é texto. O único tipo de formatação verdadeiro.
<P></P>
Apesar das marcações do txt2tags serem bem intuitivas e discretas,
pode-se removê-las ao converter o arquivo para TXT puro.
<P></P>
Os títulos são sublinhados, e o texto é basicamente deixado como está no
código fonte.
</DL>

<HR NOSHADE SIZE=1>

<H2 ID="estruturas">Situação dos Formatos-Destino para as Estruturas Suportadas</H2>

<TABLE ALIGN="center" BORDER="1" CELLPADDING="4">
<TR>
<TH>Estrutura</TH>
<TH>html</TH>
<TH>xhtml</TH>
<TH>sgml</TH>
<TH>tex</TH>
<TH>man</TH>
<TH>mgp</TH>
<TH>moin</TH>
<TH>pm6</TH>
<TH>txt</TH>
</TR>
<TR>
<TD>cabeçalhos</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">N</TD>
<TD ALIGN="center">N</TD>
<TD ALIGN="center">S</TD>
</TR>
<TR>
<TD>título de seções</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
</TR>
<TR>
<TD>parágrafos</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
</TR>
<TR>
<TD>negrito</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">-</TD>
</TR>
<TR>
<TD>itálico</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">-</TD>
</TR>
<TR>
<TD>sublinhado</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">-</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">-</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">-</TD>
</TR>
<TR>
<TD>pré-formatado</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">-</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">-</TD>
</TR>
<TR>
<TD>linha pré-formatada</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">-</TD>
</TR>
<TR>
<TD>área pré-formatada</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">-</TD>
</TR>
<TR>
<TD>área cotada</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
</TR>
<TR>
<TD>links internet</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">-</TD>
<TD ALIGN="center">-</TD>
<TD ALIGN="center">-</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">-</TD>
<TD ALIGN="center">-</TD>
</TR>
<TR>
<TD>links e-mail</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">-</TD>
<TD ALIGN="center">-</TD>
<TD ALIGN="center">-</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">-</TD>
<TD ALIGN="center">-</TD>
</TR>
<TR>
<TD>links locais</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">N</TD>
<TD ALIGN="center">-</TD>
<TD ALIGN="center">-</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">-</TD>
<TD ALIGN="center">-</TD>
</TR>
<TR>
<TD>links nomeados</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">-</TD>
<TD ALIGN="center">-</TD>
<TD ALIGN="center">-</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">-</TD>
<TD ALIGN="center">-</TD>
</TR>
<TR>
<TD>lista não-numerada</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
</TR>
<TR>
<TD>lista numerada</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
</TR>
<TR>
<TD>lista de definições</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">N</TD>
<TD ALIGN="center">N</TD>
<TD ALIGN="center">N</TD>
<TD ALIGN="center">S</TD>
</TR>
<TR>
<TD>linha horizontal</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">-</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">-</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">N</TD>
<TD ALIGN="center">S</TD>
</TR>
<TR>
<TD>imagem</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">-</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">N</TD>
<TD ALIGN="center">-</TD>
</TR>
<TR>
<TD>tabela</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">N</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">N</TD>
<TD ALIGN="center">N</TD>
</TR>
<TR>
<TH>Extras</TH>
<TH>html</TH>
<TH>xhtml</TH>
<TH>sgml</TH>
<TH>tex</TH>
<TH>man</TH>
<TH>mgp</TH>
<TH>moin</TH>
<TH>pm6</TH>
<TH>txt</TH>
</TR>
<TR>
<TD>image align</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">N</TD>
<TD ALIGN="center">N</TD>
<TD ALIGN="center">-</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">N</TD>
<TD ALIGN="center">N</TD>
<TD ALIGN="center">-</TD>
</TR>
<TR>
<TD>table cell align</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">N</TD>
<TD ALIGN="center">S</TD>
<TD ALIGN="center">N</TD>
<TD ALIGN="center">N</TD>
</TR>
</TABLE>

<TABLE ALIGN="center" CELLPADDING="4">
<TR>
<TH></TH>
<TH>Legenda</TH>
</TR>
<TR>
<TD><B>S</B></TD>
<TD><I>suportada</I></TD>
</TR>
<TR>
<TD><B>N</B></TD>
<TD><I>não suportada (talvez em uma versão futura)</I></TD>
</TR>
<TR>
<TD><B>-</B></TD>
<TD><I>não suportada (não pode ser feita neste formato)</I></TD>
</TR>
</TABLE>

<HR NOSHADE SIZE=1>

<H2 ID="toc7">As Três Interfaces ao Usuário: GUI, Web e Linha de Comando</H2>

<P>
Assim como diferentes usuários possuem diferentes necessidades e
ambientes, o txt2tags é bastante flexivel na forma de ser usado.
</P>
<P>
Existem três Interfaces de Usuário para o programa, cada uma atendendo a
um objetivo definido e com funcionalidades próprias.
</P>

<UL>
<LI><B>GUI</B>: Escrita em Tk, traz as janelas e os cliques para o txt2tags.
<LI><B>Web</B>: Escrita em PHP, permite que o usuário execute o txt2tags no
           navegador, não exigindo instalação do lado do cliente.
<LI><B>Linha de Comando</B>: Escrita em Python, é o núcleo do programa.
           Todas as funcionalidades estão disponíveis como opções de
           linha de comando.
</UL>

<HR NOSHADE SIZE=1>

<H3 ID="gui">Interface Gráfica Tk</H3>

<P>
Desde a versão 1.0, há uma bela Interface Gráfica, que funciona do
Linux, Windows, Mac e outros.
</P>
<P>
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 <CODE>--gui</CODE>. Se estiver
faltando algum recurso o programa irá alertar.
</P>
	<BLOCKQUOTE>
	<B>Nota:</B> O módulo Tkinter é necessário. Como ele vem com a
	distribição padrão do Python você já deve tê-lo.
	</BLOCKQUOTE>
<P>
Ela é bastante simples e fácil de usar:
</P>
          <center><IMG ALIGN="middle" SRC="../userguide/gui.png" BORDER="0" ALT=""></center>          

<OL>
<LI>Você localiza o arquivo fonte .t2t no disco e suas opções são
  carregadas.
<P></P>
<LI>Se o destino ainda estiver vazio, você deve escolher um.
<P></P>
<LI>Há algumas opões que podem ser escolhidas, mas nenhuma delas é
  essencial.
<P></P>
<LI>Finalmente, pressione o botão "Converter!".
</OL>

<P>
Uma boa opção a selecionar é "<I>Dump to screen</I>", 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.
</P>
<P>
As cores padrão podem ser mudadas no arquivo <CODE>~/.txt2tagsrc</CODE>,
configurando em <CODE>%!guicolors</CODE>. Por exemplo:
</P>

<PRE>
   % minhas cores para a interface (fundo1, texto1, fundo2, texto2)
   %!guicolors: blue white brown yellow
</PRE>

<HR NOSHADE SIZE=1>

<H3 ID="web">Interface Web</H3>

<P>
A Interface Web está em funcionamento na Internet no endereço
<A HREF="http://txt2tags.org/online.php">http://txt2tags.org/online.php</A>, permitindo que o programa possa ser
usado e testado antes de ser copiado.
</P>
          <center><IMG ALIGN="middle" SRC="../userguide/web.png" BORDER="0" ALT=""></center>          
<P>
Esta interface também pode ser colocada na intrant para uso local,
evitando a instalação do txt2tags em todas as máquinas.
</P>

<HR NOSHADE SIZE=1>

<H3 ID="linhadecomando">Interface de Linha de Comando</H3>

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

<PRE>
  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 &lt;x (a) y z&gt;
        --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.&lt;tipo&gt;'.
  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.
</PRE>

<H4>Exemplos</H4>

<P>
Supondo que exista um arquivo de marcação chamado <CODE>file.t2t</CODE>, vamos nos
divertir um pouco.
</P>

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

<DL>
<DT><I>Nota</I></DT><DD>
Desde a versão 1.6 você pode fazer pre e pós processamento usando as
macros de configuração <CODE>%!preproc</CODE> e <CODE>%!postproc</CODE>.
</DL>

<HR NOSHADE SIZE=5>

<H1 ID="instalacao">Parte II - OK, eu quero um. E agora?</H1>

<P>
Basta baixar o programa e executar o mesmo no seu computador.
</P>

<H2 ID="toc9">Download e Instalação do Python</H2>

<P>
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.
</P>
<P>
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
<A HREF="http://www.python.org">web site do Python</A>. As dicas de instalação podem
ser encontradas no mesmo site. O txt2tags funciona com o Python 1.5 ou
posterior.
</P>
<P>
Se você não tem certeza de ter o Python ou não, abra um console (tty,
xterm, MSDOS) e escreva <CODE>python</CODE>. Se ele não estiver instalado, o
sistema vai lhe informar.
</P>

<H2 ID="toc10">Copiando o txt2tags</H2>

<P>
O local oficial de distribuição do txt2tags é na homepage do programa,
em <A HREF="http://txt2tags.org/src">http://txt2tags.org/src</A>.
</P>
<P>
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).
</P>
<P>
Simplesmente pegue a <B>última</B> versão (data mais recente, número de
versão maior). As versões anteriores estão lá apenas por razões
históricas.
</P>

<H2 ID="toc11">Instalação do txt2tags</H2>

<P>
Como é apenas um script Python, o txt2tags não precisa ser instalado.
</P>
<P>
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.
</P>
<P>
O modo mais seguro de usar o txt2tags é chamar o Python com ele:
</P>

<PRE>
  prompt$ python txt2tags 
</PRE>

<P>
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.
</P>

<DL>
<DT><B>UNIX/Linux</B></DT><DD>
  Torne o script executável (<CODE>chmod +x txt2tags</CODE>) e copie o mesmo para
  um diretório no $PATH (<CODE>cp txt2tags /usr/local/bin</CODE>)
<P></P>
<DT><B>Windows</B></DT><DD>
  Renomeie o script, acrescentando a extensão .py
  (<CODE>ren txt2tags txt2tags.py</CODE>) e o copie para um diretório que esteja
  no PATH do sistema (<CODE>copy txt2tags.py C:\WINNT</CODE>)
</DL>

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

<H3>Pacotes Especiais para Usuários Windows</H3>

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

<UL>
<LI>O script txt2tags para aqueles que tem o interpretador Python
  instalado
<LI>A versão stand-alone, que não requer a instalação do interpretador
  Pyton para ser executada (já tem uma versão pequena incluída).
</UL>

<P>
Visite o site <I>Txt2tags-Win</I> para baixar estes pacotes:
<A HREF="http://txt2tags-win.sf.net/">http://txt2tags-win.sf.net/</A>
</P>

<H2 ID="sintaxe">Instalar os Arquivos de Sintaxe dos Editores de Texto</H2>

<P>
O txt2tags possui arquivos de sintaxe práticos que podem ser usados com
os seguintes editores de texto:
</P>

<UL>
<LI>Vim (<A HREF="http://www.vim.org">www.vim.org</A>)
<LI>Emacs (<A HREF="http://www.emacs.org">www.emacs.org</A>)
<LI>Nano (<A HREF="http://www.nano-editor.org">www.nano-editor.org</A>)
<LI>Kate (<A HREF="http://kate.kde.org">http://kate.kde.org</A>)
</UL>

<P>
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.
</P>

<TABLE ALIGN="center" BORDER="1" CELLPADDING="4">
<TR>
<TD ALIGN="center"><center><IMG ALIGN="middle" SRC="../userguide/vim.png" BORDER="0" ALT=""></center></TD>
</TR>
<TR>
<TD ALIGN="center">O arquivo de exemplo aberto no Editor Vim</TD>
</TR>
</TABLE>

<P>
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.
</P>

<HR NOSHADE SIZE=5>

<H1 ID="toc13">Parte III - Escrevendo e Convertendo Seu Primeiro Documento</H1>

<P>
Desculpe, este capítulo ainda está em desenvolvimento.
</P>

<H2 ID="toc14">As Áreas do documento .t2t</H2>

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

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

<P>
Como vemos acima, as duas primeiras áreas são opcionais, sendo que o
<I>Corpo do Texto</I> é a única área indispensável.
(<I>Nota: A <B>Área de Configuração</B> foi introduzida no txt2tags na versão 1.3</I>)
</P>
<P>
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:
</P>

<PRE>
               ____________
              |            |
              |  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.
              |    ...     |
              |____________|
  
</PRE>

<P>
Em resumo, é assim que as áreas são definidas:
</P>

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

<H3>Exemplo Completo</H3>

<PRE>
  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.
</PRE>

<HR NOSHADE SIZE=5>

<H1 ID="toc15">Parte IV - Dominando o Txt2tags</H1>

<H2 ID="toc16">A Área de Cabeçalho</H2>

<P>
Localização:
</P>

<UL>
<LI>Posição fixa: <B>Primeiras 3 linhas</B> do arquivo. Ponto.
<LI>Posição fixa: <B>A Primeira Linha</B> do arquivo está em branco. Isto
  significa que o cabeçalho está vazio.
</UL>

<P>
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.
</P>
<P>
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:
</P>

   <UL>
   <LI><I>linha 1</I>: título do documento
   <LI><I>linha 2</I>: nome e/ou email do autor
   <LI><I>linha 3</I>: data e/ou versão do documento
                 (um bom lugar para colocar <CODE>%%date</CODE>)
   </UL>

<P>
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.
</P>

<H4>Menos (ou Nenhuma) Linhas de Cabeçalho</H4>

<P>
À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.
</P>
<P>
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 <B>após</B> a 3a. linha.
</P>
<P>
O título é o único cabeçalho requerido (a primeira linha), mas se você
deixar ela em branco, está dizendo que seu documento
<B>não tem cabeçalho</B>. Desta forma, a <I>Área de Texto</I> irá começar em
seguida, na 2a. linha.
</P>
<P>
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 <CODE>--no-headers</CODE> é geralmente necessária para este tipo de coisa.
</P>

<H4>Direto ao ponto</H4>

<TABLE ALIGN="center" BORDER="1" CELLPADDING="4">
<TR>
<TH>Em resumo: "Cabeçalhos são apenas <U>posições</U>, não conteúdo "</TH>
</TR>
</TABLE>

<P>
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.
</P>

<HR NOSHADE SIZE=1>

<H2 ID="toc17">A Área de Configuração</H2>

<P>
Localização:
</P>

<UL>
<LI>Começa logo após a Área de Cabeçalhos
  <UL>
  <LI>Começa na <B>4a. linha</B> do arquivo se forem especificados <B>Cabeçalhos</B>
  <LI>Começa na <B>2a. linha</B> se <B>não</B> forem especificados <B>Cabeçalhos</B>
  </UL>
<LI>Termina quando a Área de Conteúdo começa
  <UL>
  <LI>Termina com uma linha que não seja de Configuração, ou de
    Comentário, ou que seja uma linha em Branco.
  </UL>
</UL>

<P>
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.
</P>
<P>
O uso primário desta área é para definir configurações que afetam o
comportamento do programa.
</P>

<H4>Então, como configurar algo? Qual a sintaxe?</H4>

<P>
As linhas de configuração são <I>linhas de comentário especiais</I>,
marcadas com um identificador no início ("<CODE>!</CODE>") 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 ("<CODE>:</CODE>").
</P>

<TABLE ALIGN="center" BORDER="1" CELLPADDING="4">
<TR>
<TH>%! palavra-chave : valor</TH>
</TR>
</TABLE>

<P>
<B><CODE>Detalhes da Sintaxe:</CODE></B> O ponto de exclamação deve ser colocado
junto com o caractere de comentário, sem espaço entre eles ("<CODE>%!</CODE>").
Os espaços em torno da <I>palavra-chave</I> e o separador são opcionais, e
tanto a <I>palavra-chave</I> quanto o <I>valor</I> podem estar
indiferentemente em maiúsculas ou minúsculas.
</P>

<H4>O que eu posso configurar? Quais são as palavra-chave válidas?</H4>

<P>
As configurações que podem ser feitas são <I>Target</I>, <I>Options</I>, <I>Style</I>,
<I>Encoding</I>, <I>PreProc</I> e <I>PostProc</I>.
</P>
<P>
A configuração <B><I>Target</I></B> define o destino padrão na qual o
documento deve ser convertido.
</P>
<P>
A configuração <B><I>Options</I></B> é ú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
<CODE>%!target</CODE> permite converter o documento simplesmente comandando:
<CODE>txt2tags file.t2t</CODE>
</P>
<P>
A configuração <B><I>Style</I></B> só é suportada pelo tipo de documento
destino HTML, para definir uma folha de estilo
(<I>Cascading Style Sheets - CSS</I>).
</P>
<P>
A configuração <B><I>Encoding</I></B> é necessária para escritores não
ingleses, que usem letras acentuadas e outros detalhes específicos de
localização, de forma que o <I>Conjunto de Caracteres</I> do documento seja
personalizado (se permitido).
</P>
<P>
A configuração <B><I>PreProc</I></B> é um filtro. Ela define regras do tipo
"busca e troca" que serão aplicadas ao arquivo original <U>antes</U> que
qualquer análise por parte do txt2tags ocorra.
</P>
<P>
A configuração <B><I>PostProc</I></B> é um filtro. Ela define regras do tipo
"busca e troca" que serão aplicadas ao arquivo destino <U>depois</U> de
todo o processamento por parte do txt2tags.
</P>
<P>
Exemplo:
</P>

<PRE>
  %! Target  : html
  %! Options : --toc --toc-level 3
  %! Style   : fancy.css
  %! Encoding: UTF-8
  %! PreProc : "amj"       "Aurelio Marinho Jargas"
  %! PostProc: '&lt;BODY.*?&gt;' '&lt;BODY bgcolor="yellow"&gt;'
</PRE>

<H4>Algumas regras sobre as Configurações</H4>

 <UL>
 <LI>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.
 <P></P>
 <LI>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.
 <P></P>
 <LI>Uma linha de configuração com uma palavra-chave inválida será
   considerada um comentário.
 <P></P>
 <LI>Estas configurações têm precedência sobre o arquivo <CODE>txt2tagsrc</CODE>,
   as não sobre as opções de linha de comando.
 </UL>

<HR NOSHADE SIZE=1>

<H2 ID="toc18">O Corpo do Texto</H2>

<P>
Localização:
</P>

<UL>
<LI>Começa na primeira linha válida de texto do arquivo
  <UL>
  <LI>Cabeçalhos, Configurações e Comentários <B>não</B> são linhas de texto
    válidas
  </UL>
<LI>Termina no fim do arquivo (EOF)
</UL>

<P>
Bem, o corpo do texto é tudo que estiver fora das Áreas de Cabeçalho e
de Configuração.
</P>
<P>
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 <I>A FAZER</I> e anotações
particulares.
</P>
<P>
Pode-se utilizar a opção de linha de comando <CODE>--no-headers</CODE> 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.
</P>

<HR NOSHADE SIZE=1>

<H2 ID="regras">Marcações (REGRAS)</H2>

<P>
Todas as marcações e sintaxe usadas pelo txt2tags estão detalhadas em
um <A HREF="REGRAS">arquivo REGRAS a parte</A>.
</P>

<HR NOSHADE SIZE=1>

<H2 ID="data">A macro %%date</H2>

<P>
A macro <CODE>%%date</CODE> chamada sem nenhum parâmetro adicional retorna a data
atual no formato ISO <I>yyyymmdd</I>. Uma formatação opcional pode ser
especificada usando a sintaxe <CODE>%%date(formato)</CODE>.
</P>
<P>
O <I>formato</I> contém texto de diretivas de formatação, que são compostas
por um sinal de porcentagem (<CODE>%</CODE>) seguido por um caractere de
identificação.
</P>
<P>
Segue uma lista de algumas diretivas comuns. A lista completa pode ser
encontrada em <A HREF="http://www.python.org/doc/current/lib/module-time.html">http://www.python.org/doc/current/lib/module-time.html</A>.
</P>

<TABLE ALIGN="center" BORDER="1" CELLPADDING="4">
<TR>
<TH>Diretiva</TH>
<TH>Descrição</TH>
</TR>
<TR>
<TD ALIGN="center">%a</TD>
<TD>Dia da semana local abreviado.</TD>
</TR>
<TR>
<TD ALIGN="center">%A</TD>
<TD>Dia da semana completo.</TD>
</TR>
<TR>
<TD ALIGN="center">%b</TD>
<TD>Nome do mês abreviado.</TD>
</TR>
<TR>
<TD ALIGN="center">%B</TD>
<TD>Nome do mês.</TD>
</TR>
<TR>
<TD ALIGN="center">%c</TD>
<TD>Dia e hora formatados apropriadamente.</TD>
</TR>
<TR>
<TD ALIGN="center">%d</TD>
<TD>Dia do mês como um número decimal [01,31].</TD>
</TR>
<TR>
<TD ALIGN="center">%H</TD>
<TD>Hora (24 horas) como um número decimal [00,23].</TD>
</TR>
<TR>
<TD ALIGN="center">%I</TD>
<TD>Hora (12 horas) como um número decimal [01,12].</TD>
</TR>
<TR>
<TD ALIGN="center">%m</TD>
<TD>O mês como um número decimal [01,12].</TD>
</TR>
<TR>
<TD ALIGN="center">%M</TD>
<TD>O minuto como um número decimal [00,59].</TD>
</TR>
<TR>
<TD ALIGN="center">%p</TD>
<TD>O equivalente local a AM e PM.</TD>
</TR>
<TR>
<TD ALIGN="center">%S</TD>
<TD>Os segundos como um número decimal [00,61].  (1)</TD>
</TR>
<TR>
<TD ALIGN="center">%x</TD>
<TD>Representação local da data.</TD>
</TR>
<TR>
<TD ALIGN="center">%X</TD>
<TD>Representação local da hora.</TD>
</TR>
<TR>
<TD ALIGN="center">%y</TD>
<TD>O ano sem o século como um número decimal [00,99].</TD>
</TR>
<TR>
<TD ALIGN="center">%Y</TD>
<TD>O ano com o século como um número decimal.</TD>
</TR>
<TR>
<TD ALIGN="center">%%</TD>
<TD>Um caractere "%".</TD>
</TR>
</TABLE>

<H4>Exemplos</H4>

<TABLE ALIGN="center" BORDER="1" CELLPADDING="4">
<TR>
<TH><CODE>%%date(format)</CODE></TH>
<TH>Resultado para: 2004, Jul13, 18:49</TH>
</TR>
<TR>
<TD>Last Update: %c</TD>
<TD>Last Update: Tue Jan 13 18:49:32 2004</TD>
</TR>
<TR>
<TD>%Y-%m-%d</TD>
<TD>2004-07-13</TD>
</TR>
<TR>
<TD>%I:%M %p</TD>
<TD>18:49 PM</TD>
</TR>
<TR>
<TD>Hoje e %A, em %B.</TD>
<TD>Hoje e Tuesday, em July.</TD>
</TR>
</TABLE>

<HR NOSHADE SIZE=1>

<H2 ID="include">O comando %!include</H2>

<P>
A partir da versão 1.7, é possível usar o comando <CODE>include</CODE> para
inserir o conteúdo de um arquivo externo dentro do corpo do documento
original.
</P>
<P>
O <CODE>%!include</CODE> não é uma configuração, mas um comando, sendo somente
válido na área de CORPO do texto.
</P>
<P>
O comando <CODE>include</CODE> é ú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:
</P>

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

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

<PRE>
  %!include(html): arquivo.t2t
</PRE>

<P>
Note que o <CODE>include</CODE> 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.
</P>
<P>
Além de incluir arquivos .t2t, há mais três tipos de inclusão:
</P>

<UL>
<LI>Inclusão de texto pré-formatado (Verbatim)
<LI>Inclusão de texto protegido (Raw)
<LI>Inclusão de texto já convertido (Tagged)
</UL>

<P>
No tipo <B>Verbatim</B> 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:
</P>

<PRE>
  %!include: ``/etc/fstab``
</PRE>

<P>
No tipo <B>Raw</B> 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
</P>

<PRE>
  %!include: ""bom_texto.txt""
</PRE>

<P>
Já no tipo <B>Tagged</B>, 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:
</P>

<PRE>
  %!include(html): ''rodape.html''
</PRE>

<P>
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.
</P>

<HR NOSHADE SIZE=5>

<H1 ID="settings">Parte V - Dominando as Diretivas de Configuração</H1>

<P>
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 :)
</P>

<HR NOSHADE SIZE=1>

<H2 ID="toc23">%!Target</H2>

<P>
Usando a configuração Target define o destino padrão definido no
documento:
</P>

<PRE>
  %!target: html
</PRE>

<P>
Assim o usuário pode simplesmente comandar
</P>

<PRE>
  $ txt2tags file.t2t
</PRE>

<P>
E a conversão será efetuada para o destino especificado.
</P>
<P>
A configuração Target não permite a especificação opcional de destino.
Afinal, não faz sentido algo como <CODE>%!target(tex): html</CODE>.
</P>

<HR NOSHADE SIZE=1>

<H2 ID="toc24">%!Options</H2>

<P>
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.
</P>
<P>
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.
</P>
<P>
Por exemplo, se você usa esta linha de comando para converter seu
documento:
</P>

<PRE>
  $ txt2tags -t html --toc --toc-level 2 --enum-title file.t2t
</PRE>

<P>
Pode-se economizar um bocado de digitação usando esta configuração de
Options dentro do documento origem:
</P>

<PRE>
  %!target: html
  %!options(html): --toc --toc-level 2 --enum-title
</PRE>

<P>
A linha de comando real passa agora a ser apenas "<CODE>txt2tags file.t2t</CODE>",
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 é:
</P>

<PRE>
  :!txt2tags %
</PRE>

<HR NOSHADE SIZE=1>

<H2 ID="toc25">%!Encoding</H2>

<P>
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
<I>Conjunto de Caracteres</I> do documento gerado possa ser personalizado
(se possível).
</P>
<P>
Os valores válidos para a configuração de Encoding são os mesmos que são
válidos para documentos, HTML, como <I>UTF-8</I> e <I>koi8-r</I>. Se você
não está certo de qual codificação quer usar,
<A HREF="http://www.iana.org/assignments/character-sets">esta lista completa (e longa!)</A>
poderá ser de ajuda.
</P>
<P>
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:
</P>

<TABLE ALIGN="center" BORDER="1" CELLPADDING="4">
<TR>
<TH>txt2tags/HTML</TH>
<TH>&gt;</TH>
<TH>LaTeX</TH>
</TR>
<TR>
<TD>windows-1250</TD>
<TD>&gt;&gt;&gt;</TD>
<TD>cp1250</TD>
</TR>
<TR>
<TD>windows-1252</TD>
<TD>&gt;&gt;&gt;</TD>
<TD>cp1252</TD>
</TR>
<TR>
<TD>ibm850</TD>
<TD>&gt;&gt;&gt;</TD>
<TD>cp850</TD>
</TR>
<TR>
<TD>ibm852</TD>
<TD>&gt;&gt;&gt;</TD>
<TD>cp852</TD>
</TR>
<TR>
<TD>iso-8859-1</TD>
<TD>&gt;&gt;&gt;</TD>
<TD>latin1</TD>
</TR>
<TR>
<TD>iso-8859-2</TD>
<TD>&gt;&gt;&gt;</TD>
<TD>latin2</TD>
</TR>
<TR>
<TD>koi8-r</TD>
<TD>&gt;&gt;&gt;</TD>
<TD>koi8-r</TD>
</TR>
</TABLE>

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

<HR NOSHADE SIZE=1>

<H2 ID="toc26">%!PreProc</H2>

<P>
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.
</P>
<P>
Ela é útil para definir algumas abreviações para texto que seja usado
comumente, como:
</P>

<PRE>
  %!preproc amj          "Aurelio Marinho Jargas"
  %!preproc RELEASE_DATE "2004-07-13"
  %!preproc BOLOTA       "[images/tiny/bullet_blue.png]"
</PRE>

<P>
Desta forma, o usuário pode escrever uma linha como:
</P>

<PRE>
  Oi, eu sou amj. Hoje é RELEASE_DATE.
</PRE>

<P>
E o txt2tags irá ver esta linha como:
</P>

<PRE>
  Oi, eu sou Aurelio Marinho Jargas. Hoje é 2004-07-13.
</PRE>

<P>
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:
</P>

<PRE>
  $ cat arquivo.t2t | preproc-script.sh | txt2tags -
</PRE>

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

<HR NOSHADE SIZE=1>

<H2 ID="toc27">%!PostProc</H2>

<P>
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.
</P>
<P>
É útil para defintir alguns refinamentos no documento gerado, mudar
algumas marcações e acrescentar algumas marcações ou texto extra.
Alguns exemplos breves:
</P>

<PRE>
  %!postproc(html): '&lt;BODY.*?&gt;' '&lt;BODY BGCOLOR="green"&gt;'
  %!postproc(tex) : "\\clearpage" ""
</PRE>

<P>
Estes filtros mudam a cor de fundo da página HTML e removem as quebras
de página em arquivos LaTeX gerados.
</P>
<P>
As regras do PostProc são iguais a filtros externos Sed/Perl, chamados
desta forma:
</P>

<PRE>
  $ txt2tags -t html -o- arquivo.t2t | postproc-script.sh &gt; arquivo.html
</PRE>

<P>
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.
</P>

<HR NOSHADE SIZE=1>

<H2 ID="toc28">%!Style</H2>

<UL>
<LI>Esta opção é útil na geração de arquivos HTML e XHTML, definindo o
  nome do arquivo CSS que será usado no documento gerado.
<P></P>
<LI>No formato LaTeX, essa opção é usada para carregar módulos com o
  <CODE>\usepackage</CODE>.
<P></P>
<LI>O mesmo efeito pode ser obtido com a opção de linha de comando
  <CODE>--style</CODE>.
<P></P>
<LI>A opção de linha de comando --style tem precedência sobre a
  configuração de %!style
</UL>

<HR NOSHADE SIZE=1>

<H2 ID="toc29">Detalhes dos Filtros PreProc e PostProc</H2>

<UL>
<LI>Estes filtros foram acrescentados ao txt2tags na versão 1.6.
<P></P>
<LI>Filtros são uma função do tipo "buscar e trocar" (pense no sed)
<P></P>
<LI>O PREproc é aplicado logo após a linha ser lida, e o POSTproc é
  aplicado após todo o tratamento ter sido feito. Funcionam exatamente
  como em (UUOC à frente):
<P></P>
<PRE>
  $ cat file.t2t | preproc.sh | txt2tags | postproc.sh
</PRE>

<P></P>
<LI>Escapes especiais como <CODE>\n</CODE> e <CODE>\t</CODE> são interpretados
<P></P>
<LI>Os filtros são cumulativos e são aplicados na mesma ordem em que são
  definidos
<P></P>
<LI>Os filtros devem receber exatamente DOIS argumentos
<P></P>
<LI>Para apagar uma string, troque ela por uma string vazia
<PRE>
  %!postproc: "undesired string" ""
</PRE>

<P></P>
<LI>Para evitar problemas, sempre use informar explicitamente para que
  destino se aplica o filtro quando estiver usando o PostProc para mudar
  marcações: <CODE>%!PostProc(destino): &lt;isto&gt; &lt;aquilo&gt;</CODE>
<P></P>
<LI>As Expressões Regulares do Python podem ser utilizadas! Elas são
  similares às Regex do Perl. Por exemplo: troque todas as marcações "B"
  para "STRONG" no HTML:
<P></P>
<PRE>
  %!postproc(html):   '(&lt;/?)B&gt;'   '\1STRONG&gt;'
</PRE>

<P></P>
<LI>Os argumentos dos filtros podem ser passados de 3 formas:
   <OL>
   <LI>Uma palavra simples, sem aspas ou plicas, como FOO (sem espaços)
   <LI>Uma string com aspas duplas, como em "FOO"
   <LI>Uma string com plicas ou apóstrofos, como em 'FOO'
   <P></P>
   </OL>
<LI>Se seu padrão tem aspas, proteja as mesmas com plicas, e vice-versa.
  Alguns exemplos válidos:
<PRE>
  %!postproc:   PADRÃO    TROCA
  %!postproc:  "PADRÃO"  "TROCA"
  %!postproc:  'PADRÃO'  'TROCA'
  %!postproc:   PADRÃO   "TROCA"
  %!postproc:  "PADRÃO"  'TROCA'
</PRE>

</UL>

<HR NOSHADE SIZE=1>

<H2 ID="toc30">Definindo uma Configuração para um Tipo-Destino Específico</H2>

<P>
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
<CODE>%!key(target): value</CODE>. Desta forma, o usuário pode definir diferentes
configurações para diverentes tipos de arquivos gerados.
</P>
<P>
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:
</P>

<PRE>
  %!encoding(html): UTF-8
  %!encoding(tex): latin1
</PRE>

	<BLOCKQUOTE>
	<B>Nota:</B> O mapeamento de codificações para os nomes especiais
	LaTeX já é parte do txt2tags, o trecho acima é apenas um
	exemplo.
	</BLOCKQUOTE>
<P>
Para o <CODE>%!options</CODE>, pode ser interessante:
</P>

<PRE>
  %!target: sgml
  %!options(sgml): --toc
  %!options(html): --style foo.css
  %!options(txt ): --toc-only --toc-level 2
</PRE>

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

<PRE>
  $ txt2tags -t html file.t2t
</PRE>

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

<H3>A Precedência é Diferente</H3>

<P>
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:
</P>

<PRE>
  %!encoding(html): UTF-8
  %!encoding: latin1
</PRE>

<P>
Irá expandir para 'UTF-8' quando chamado com <CODE>-t html</CODE> mesmo que
'latin1' seja definido logo após.
</P>

<H3>Filtros são Cumulativos</H3>

<P>
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.
</P>
<P>
Por exemplo:
</P>

<PRE>
  %!postproc     : ^ \t
  %!postproc(txt): ^ '&gt; '
</PRE>

<P>
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.
</P>

<PRE>
  Desta forma        Minha bela linha.
  se tornará         \t&gt; Minha bela linha.
</PRE>

<H3>Em Resumo</H3>

<UL>
<LI>Para filtros, a ordem faz diferença e as regras genéricas <U>e</U>
  específicas ao tipo-destino serão usadas
<P></P>
<LI>Para outras configurações, <U>somente</U> o tipo-destino especificado é
  usado (se definido, é claro), não importando a ordem
</UL>

<H2 ID="toc31">RC, CONF e a precedência de linha de comando</H2>

<P>
Há três maneiras de dizer ao txt2tags quais opções e configurações usar:
</P>

<OL>
<LI>O arquivo de usuário RC  (<CODE>.txt2tagsrc</CODE>)
<LI>A Área de Configurações CONF do documento
<LI>As opções de linha de comando
</OL>

<P>
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.
</P>
<P>
Então se o "encoding" do documento foi definido nas três opções, a da
linha de comando será a utilizada.
</P>

<HR NOSHADE SIZE=5>

<H1 ID="toc32">Parte VI - Magia Negra</H1>

<P>
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.
</P>
	<BLOCKQUOTE>
	<B>CUIDADO!</B> 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.
	</BLOCKQUOTE>

<TABLE ALIGN="center" BORDER="1" CELLPADDING="4">
<TR>
<TH>Filtros são um recurso poderoso, mas podem ser perigosos!</TH>
</TR>
</TABLE>

<TABLE ALIGN="center" BORDER="1" CELLPADDING="4">
<TR>
<TH>Filtros mal-feitos geram resultados inesperados.</TH>
</TR>
</TABLE>

<P>
Tenha isto em mente, sempre.
</P>

<HR NOSHADE SIZE=1>

<H2 ID="toc33">Inserindo Múltiplas Linhas com %!PostProc (como regras CSS)</H2>

<P>
Nos filtros, o padrão de troca pode incluir múltiplas linhas usando o
caractere de quebra de linha, <CODE>\n</CODE>.
</P>
<P>
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:
</P>

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

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

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

<HR NOSHADE SIZE=1>

<H2 ID="toc34">Criando Conteúdo "Específico ao Tipo Destino", com %!PreProc</H2>

<P>
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.
</P>
<P>
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.
</P>
<P>
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:
</P>

<PRE>
  %html% Esta página HTML foi produzida pelo [txt2tags http://txt2tags.org].
  %html% Veja o arquivo fonte TXT [aqui fonte.t2t].
</PRE>

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

<PRE>
  %preproc(html): '^%html% ' ''
</PRE>

<P>
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.
</P>

<HR NOSHADE SIZE=1>

<H2 ID="toc35">Mudando Marcas txt2tags com %!PreProc</H2>

<P>
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.
</P>
<P>
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 "&gt;&gt;&gt;"
seja sua escolha. Então ele irá precisar deste filtro simples:
</P>

<PRE>
  %!PreProc: '&gt;&gt;&gt; ' \t
</PRE>

<P>
E no documento original, o texto citado vai parecer algo tipo:
</P>

<PRE>
  &gt;&gt;&gt; Este é um texto de citação.
  &gt;&gt;&gt; O usuário definiu esta marca esquisita.
  &gt;&gt;&gt; Mas elas serão convertidas para TABs pelo PreProc.
</PRE>

<P>
Antes que a análise do programa comece, os "&gt;&gt;&gt; " esquisitos serão
convertidos em TABs e o txt2tags irá reconhecer a marca de citação.
</P>
	<BLOCKQUOTE>
	<B>CUIDADO!</B> 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.
	</BLOCKQUOTE>

<HR NOSHADE SIZE=5>

<H1 ID="historia">Parte VII - História do txt2tags</H1>

<P>
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...
</P>
<P>
Este capítulo ilustra em algumas palavras o desenvolvimento desta
ferramenta desde a primeira linha ser escrita até a série atual.
</P>

<H2 ID="toc37">Janeiro de 1999: Pré História</H2>

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

<H2 ID="toc38">Junho 1999: Ainda Pré-História</H2>

<P>
O autor tem mais a dizer:
</P>
	<BLOCKQUOTE>
	<I>"Passaram-se alguns meses, e um grande hype em torno de</I>
	<I>Sgml chegou à companhia que eu trabalhava (Conectiva). Então o</I>
	<I>txt2html tornou-se um script txt2sgml. Eu estava realmente</I>
	<I>tentando aprender sobre o SED* naquele tempo, de forma que o</I>
	<I>txt2tags na época era um script Bourne Shell com muito</I>
	<I>código SED."</I>
	</BLOCKQUOTE>
	<BLOCKQUOTE>
	* <B>SED:</B> UNIX Stream EDitor - uma ferramenta de edição
	automática de textos
	</BLOCKQUOTE>
<P>
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:
</P>

<PRE>
  		 * 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.
  		 =----------------------
</PRE>

<P>
Ainda não era impressionante, mas o grande passo está chegando...
</P>

<H2 ID="toc39">Agosto de 2000: Não Mais Pré-História</H2>

<P>
TODO (txt2sgml.sed)
</P>

<H2 ID="toc40">Julho de 2001: Debute das séries 0.x (Lançamento Mundial)</H2>

<P>
TODO
</P>

<H2 ID="toc41">Setembro de 2002: Debute das séries 1.x</H2>

<DL>
<DT><B>Anúncio</B></DT><DD>
  Este release inicia a minha <I>série 1.x</I>.
<P></P>
  Mais de um ano de atualizaçõs quase mensais e a <I>série 0.x</I>
  proporcionou-me muitos bons recursos, como Linha de Comando e
  interface Web, criação de Sumário (TOC), títulos e listas numerados,
  facilidades STDIN e STDOUT, arquivos de sintaxe vim/emacs e sete
  formatos de destino suportados.
<P></P>
  Para a iniciar a <I>série 1.x</I> vou tentar me espalhar por aí, com uma
  boa interface GUI, muita documentação, lista de discussão, base de
  usuários, compatibilidade Unix/Windows/Mac e incluir mais destinos
  (como tex, rtf e xhtml).
<P></P>
  Nesta versão 1.0 já estou com a corda toda, com uma roupa nova
  (Interface Gráfica Tk) e compatibilidade com Unix/Windows/Mac,
  manipulação de quebras de linhas e outros detalhes específicos de cada
  plataforma. Felizmente agora meu mestre pode usar os sistemas Linux,
  Windows 2000, Cygwin e MacOS 8.6 para me testar.
</DL>

<H2 ID="toc42">2002, 2003... e as História não pára</H2>

<DL>
<DT><I>06 Novembro 2002</I> - <B>Liberada minha nova versão 1.1</B></DT><DD>
<P></P>
  Atenção! Por favor leia <I>cuidadosamnte</I> antes de me atualizar!
<P></P>
  Esta nova v1.1 é uma <U><B>quebra de compatibilidade</B></U> .
<P></P>
  Isto significa que antes de atualizar você deve verificar seus
  arquivos txt2tags atuais, e, possivelmente ajustá-los. Ignorar esta
  versão não é uma opção :) porque as próximas versões consideram que
  você arrumou os seus arquivos.
<P></P>
  Por favor leia o "Guia de Sobrevivência de Atualização para a v1.1"
  para mais informações mais detalhadas sobre <I>o que</I> foi mudado e
  <I>como</I> ajustar os seus arquivos.
<P></P>
  Mas há algumas boas novas, como:
    <UL>
    <LI>imagens agora podem apontar links, como <CODE>[[img.gif] www.abc.com]</CODE>
    <LI>novas regras de foldmethod=syntax no arquivo de sintaxe do Vim
    <LI>melhorias no detector de URL
    <P></P>
    </UL>
<DT><I>03 Dezembro 2002</I> - <B>Lançamento da nova versão 1.2 (versão LaTeX)</B></DT><DD>
<P></P>
  Oi! Finalmente aprendi um dos formatos de documento mais usado pelos
  geeks: <B><I>LaTeX</I></B>. Me execute com "<CODE>-t tex</CODE>" e veja seus arquivos
  .t2t tornarem-se LaTeX, prontos para compilar!
<P></P>
  Ah! Estou ficando esperto e agora posso cuidar de mais de um arquivo
  ao mesmo tempo. Dica: "<CODE>*.t2t</CODE>"
<P></P>
  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.
<P></P>
  O que você está esperando? Baixe-me agora e teste meus novos recursos:
  <CODE>txt2tags --toc -t tex *.t2t</CODE>
<P></P>
<DT><I>20 Dezembro 2002</I> - <B>Lançamento da nova versão 1.3</B></DT><DD>
<P></P>
  Ufa, estou cansado! Muitas modificações foram feitas para esta versão
  e agora preciso de um tempo!
<P></P>
  A novidade inclui uma nova marca (coisa rara de acontecer!) para texto
  protegido. Desta forma você pode facilmente incluir marcas no
  documento destino e eu prometo que não as vou considerar!
<P></P>
  Um novo comando <I>Encoding</I> está disponível para permitir que
  usuários de todo o mundo especifiquem suas próprias codificações em
  seus documentos.
<P></P>
  E há mais melhorias e ajustes, mas, por favor leia o arquivo ChangeLog
  por que agora vou dormir. zzZZzzzzZZZZzz...
<P></P>
<DT><I>18 Fevereiro 2003</I> - <B>Lançamento da nova versão 1.4</B></DT><DD>
<P></P>
  I've enjoyed my <I>X-mas/New Year</I> 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: <B>me!</B>
<P></P>
  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 <I>each table cell</I> contents wherever
  I want! Left, Right, Centered... See AbuseMe! file for a
  demonstration.
<P></P>
  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 <CODE>--style</CODE> command line option or the <CODE>%!Style:</CODE> setting.
<P></P>
  There's a new <CODE>--toclevel</CODE> option also, and I promisse I'll not make
  TOC deeper than the number you pass me.
<P></P>
  Mmmmmm, there were some bug fixes also, but let's forget about them,
  you know I'm not buggy! ;)
<P></P>
<DT><I>09 Maio 2003</I> - <B>Lançamento da nova versão 1.5</B></DT><DD>
<P></P>
  Tsc, Tsc... Almost three months from the last version, what a shame!
  But the new features will worth the delay.
<P></P>
  The most important improvement is my new <CODE>%!cmdline</CODE> 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 "<I>%!cmdline: -t html --toc</I>" line on your source document, then you
  can convert it with the simple "<I>txt2tags file.t2t</I>" command.
<P></P>
  There is also a new <CODE>--outfile</CODE> option (<CODE>-o</CODE> for short) to set the
  output filename. If you specify "<I>-o -</I>", you get the same behaviour
  of the old <CODE>--stdout</CODE> option (which is now deprecated).
<P></P>
  Talking about options, there are the new short <CODE>-H</CODE> and <CODE>-n</CODE> for the
  existing <CODE>--noheaders</CODE> and <CODE>--enumtitle</CODE> options. A nice quick
  example:
<P></P>
<PRE>
  txt2tags-v1.4 -t html --enumtitle --stdout file.t2t &gt; new.html
  txt2tags-v1.5 -t html -n -o new.html file.t2t
</PRE>

<P></P>
  Ah! LaTeX target now supports images :)
<P></P>
<DT><I>23 Jul 2003</I> - <B>Lançamento da nova versão 1.6</B></DT><DD>
<P></P>
  Hi there! Here I am again with fresh news.
<P></P>
  Today my v1.6 was released. The main improvement is the new
  <CODE>%!preproc:</CODE> and <CODE>%!postproc:</CODE> 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, <I>+like this+</I>, so now you
  can mix normal titles with numbered ones, like a book with Appendix.
<P></P>
  Now all the config settings can be linked with a especific target,
  using the new <CODE>%!key(target): value</CODE> syntax. The target specification
  is optional, so the parentesis and its contents can be omitted. A nice
  sample: <I>%!encoding(html): iso-8859-1</I>
<P></P>
  Lots of user reported bugs was fixed, titles on LaTeX are unnumbered
  by default (as other targets) and the Gui was improved, showing
  <CODE>%!cmdline</CODE> contents (if any) and refreshing checkboxes when a new
  file is loaded. Gui also can receive options from the command line, as
  in <CODE>txt2tags --gui -n file.t2t</CODE>
<P></P>
<DT><I>30 Novembro 2003</I> - <B>Lançamento da nova versão 1.7</B></DT><DD>
<P></P>
   Saiu a minha versão 1.7! Agora tenho o comando que os usuários mais
   pediram: <CODE>%!include</CODE>. Com ele você pode incluir texto, tags e até
   mesmo outro arquivo .t2t no documento original. Veja como fazer isso
   no <A HREF="#include">Guia do Usuário</A>.
<P></P>
   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.
<P></P>
   <B>MUITO IMPORTANTE:</B> 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!
<P></P>
</DL>

<HR NOSHADE SIZE=5>

<P>
Fim. (<A HREF="userguide-pt.t2t">veja o fonte</A>)
</P>

<!-- html code generated by txt2tags 2.6.641 (http://txt2tags.org) -->
<!-- cmdline: txt2tags userguide-pt.t2t -->
</BODY></HTML>