userguide-pt.html | searchcode

/doc/Portuguese/userguide-pt.html

Large files files are truncated, but you can click here to view the full file
   1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
   2<HTML>
   3<HEAD>
   4<STYLE TYPE="text/css">
   5body {background-color:#ddeeff; color:black;   
   6      margin:2em; text-align:justify;}         
   7a {text-decoration:none;}
   8a:hover {color:red;}
   9a:visited {color:purple;}
  10dl {margin:1em;}    
  11h1 {text-align:center; background-color:blue;  
  12    color:white; padding:8px;}                 
  13h2 {padding-top:20px;}
  14hr {border-style:none;}
  15code {background-color:lightblue;}             
  16table {border-style:solid; border-color:black;}
  17th {background-color:lightblue; padding:1em;}  
  18td {border-style:none; background-color:white;}
  19pre {border-style:solid; border-width:1px 1px; 
  20     background-color:lightblue; padding:8px;  
  21     border-color:black;}                      
  22</STYLE>
  23<META NAME="generator" CONTENT="http://txt2tags.org">
  24<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=UTF-8">
  25<TITLE>Guia do Usuário Txt2tags</TITLE>
  26</HEAD><BODY BGCOLOR="white" TEXT="black">
  27<CENTER>
  28<H1>Guia do Usuário Txt2tags</H1>
  29<FONT SIZE="4"><I>Aurelio, Wed Jan 11 20:53:37 2012</I></FONT><BR>
  30<FONT SIZE="4">Tradução para o português: César A. K. Grossman</FONT>
  31</CENTER>
  32
  33<P></P>
  34<HR NOSHADE SIZE=1>
  35<P></P>
  36
  37  <UL>
  38  <LI><A HREF="#toc1">Sobre este documento</A>
  39  <LI><A HREF="#toc2">Parte I - Introdução ao Txt2tags</A>
  40    <UL>
  41    <LI><A HREF="#toc3">Suas Primeiras Questões</A>
  42    <LI><A HREF="#toc4">Estruturas de Formatação Suportadas</A>
  43    <LI><A HREF="#toc5">Formatos Suportados</A>
  44    <LI><A HREF="#estruturas">Situação dos Formatos-Destino para as Estruturas Suportadas</A>
  45    <LI><A HREF="#toc7">As Três Interfaces ao Usuário: GUI, Web e Linha de Comando</A>
  46    </UL>
  47  <LI><A HREF="#instalacao">Parte II - OK, eu quero um. E agora?</A>
  48    <UL>
  49    <LI><A HREF="#toc9">Download e Instalação do Python</A>
  50    <LI><A HREF="#toc10">Copiando o txt2tags</A>
  51    <LI><A HREF="#toc11">Instalação do txt2tags</A>
  52    <LI><A HREF="#sintaxe">Instalar os Arquivos de Sintaxe dos Editores de Texto</A> <b>[NOVO!]</b>
  53    </UL>
  54  <LI><A HREF="#toc13">Parte III - Escrevendo e Convertendo Seu Primeiro Documento</A>
  55    <UL>
  56    <LI><A HREF="#toc14">As Áreas do documento .t2t</A>
  57    </UL>
  58  <LI><A HREF="#toc15">Parte IV - Dominando o Txt2tags</A>
  59    <UL>
  60    <LI><A HREF="#toc16">A Área de Cabeçalho</A>
  61    <LI><A HREF="#toc17">A Área de Configuração</A>
  62    <LI><A HREF="#toc18">O Corpo do Texto</A>
  63    <LI><A HREF="#regras">Marcações (REGRAS)</A>
  64    <LI><A HREF="#data">A macro %%date</A>
  65    <LI><A HREF="#include">O comando %!include</A>
  66    </UL>
  67  <LI><A HREF="#settings">Parte V - Dominando as Diretivas de Configuração</A>
  68    <UL>
  69    <LI><A HREF="#toc23">%!Target</A> <b>[NOVO!]</b>
  70    <LI><A HREF="#toc24">%!Options</A> <b>[NOVO!]</b>
  71    <LI><A HREF="#toc25">%!Encoding</A>
  72    <LI><A HREF="#toc26">%!PreProc</A>
  73    <LI><A HREF="#toc27">%!PostProc</A>
  74    <LI><A HREF="#toc28">%!Style</A>
  75    <LI><A HREF="#toc29">Detalhes dos Filtros PreProc e PostProc</A>
  76    <LI><A HREF="#toc30">Definindo uma Configuração para um Tipo-Destino Específico</A>
  77    <LI><A HREF="#toc31">RC, CONF e a precedência de linha de comando</A> <b>[NOVO!]</b>
  78    </UL>
  79  <LI><A HREF="#toc32">Parte VI - Magia Negra</A>
  80    <UL>
  81    <LI><A HREF="#toc33">Inserindo Múltiplas Linhas com %!PostProc (como regras CSS)</A>
  82    <LI><A HREF="#toc34">Criando Conteúdo "Específico ao Tipo Destino", com %!PreProc</A>
  83    <LI><A HREF="#toc35">Mudando Marcas txt2tags com %!PreProc</A>
  84    </UL>
  85  <LI><A HREF="#historia">Parte VII - História do txt2tags</A>
  86    <UL>
  87    <LI><A HREF="#toc37">Janeiro de 1999: Pré História</A>
  88    <LI><A HREF="#toc38">Junho 1999: Ainda Pré-História</A>
  89    <LI><A HREF="#toc39">Agosto de 2000: Não Mais Pré-História</A>
  90    <LI><A HREF="#toc40">Julho de 2001: Debute das séries 0.x (Lançamento Mundial)</A>
  91    <LI><A HREF="#toc41">Setembro de 2002: Debute das séries 1.x</A>
  92    <LI><A HREF="#toc42">2002, 2003... e as História não pára</A>
  93    </UL>
  94  </UL>
  95
  96<P></P>
  97<HR NOSHADE SIZE=1>
  98<P></P>
  99
 100<H1 ID="toc1">Sobre este documento</H1>
 101
 102	<BLOCKQUOTE>
 103	Olá, eu sou o guia do usuário do txt2tags!
 104	</BLOCKQUOTE>
 105	<BLOCKQUOTE>
 106	Aqui você encontra toda a informação disponível sobre a
 107	ferramenta de conversão de textos txt2tags.
 108	</BLOCKQUOTE>
 109	<BLOCKQUOTE>
 110	Minha versão atualizada pode ser encontrada em
 111	<A HREF="http://txt2tags.org/userguide/">http://txt2tags.org/userguide/</A>
 112	</BLOCKQUOTE>
 113	<BLOCKQUOTE>
 114	Para mais informações e versões recentes, visite
 115	<A HREF="http://txt2tags.org/">o website do txt2tags</A>.
 116	</BLOCKQUOTE>
 117	<BLOCKQUOTE>
 118	Bom proveito!
 119	</BLOCKQUOTE>
 120
 121<HR NOSHADE SIZE=5>
 122
 123<H1 ID="toc2">Parte I - Introdução ao Txt2tags</H1>
 124
 125<H2 ID="toc3">Suas Primeiras Questões</H2>
 126
 127<P>
 128Este capítulo apresenta o txt2tags, introduzindo as funcionalidades e
 129objetivo do programa.
 130</P>
 131
 132<HR NOSHADE SIZE=1>
 133
 134<H3>O Que É?</H3>
 135
 136<P>
 137O txt2tags é uma ferramenta de formatação e conversão de texto.
 138</P>
 139<P>
 140O txt2tags converte um arquivo texto com algumas marcas para qualquer um
 141dos tipos de arquivos suportados:
 142</P>
 143
 144<UL>
 145<LI>Documento HTML
 146<LI>Documento XHTML
 147<LI>Documento SGML
 148<LI>Documento LaTeX
 149<LI>Página man UNIX
 150<LI>Apresentação Magic Point
 151<LI>Página MoinMoin
 152<LI>Documento PageMaker 6.0
 153<LI>Texto Plano (sem marcações)
 154</UL>
 155
 156<HR NOSHADE SIZE=1>
 157
 158<H3>Por Quê Eu Devo Usá-lo?</H3>
 159
 160<P>
 161Você achará o txt2tags bastante útil se você:
 162</P>
 163
 164<UL>
 165<LI>precisa publicar documentos em diferentes formatos
 166<LI>precisa manter documentos atualizados em diferentes formatos
 167<LI>escreve manuais ou documentos técnicos
 168<LI>não sabe como escrever um documento em um formato específico
 169<LI>não tem um editor específico para um certo formato.
 170<LI>quer usar um editor de texto simples para atualizar seus documentos
 171</UL>
 172
 173<P>
 174E a motivação principal é:
 175</P>
 176
 177<UL>
 178<LI>economizar tempo, escrevendo <B>conteúdo</B>, sem se preocupar com
 179  <B>formatação</B>
 180</UL>
 181
 182<HR NOSHADE SIZE=1>
 183
 184<H3>Quais vantagens oferece em relação a outras ferramentas?</H3>
 185
 186<P>
 187O txt2tags possui uma forma bem direta de crescimento, seguindo alguns
 188conceitos básicos. Os conceitos a seguir se destacam:
 189</P>
 190
 191<TABLE CELLPADDING="4">
 192<TR>
 193<TD><I>Arquivo fonte legível</I></TD>
 194<TD>As marcações do txt2tags são bastante simples, quase naturais.</TD>
 195</TR>
 196<TR>
 197<TD><I>Documento destino legível</I></TD>
 198<TD>Da mesma forma que o arquivo fonte, o código do documento gerado também é legível, alinhado e possui linhas curtas.</TD>
 199</TR>
 200<TR>
 201<TD><I>Consistência na Marcação</I></TD>
 202<TD>As marcações txt2tags são únicas, atendendo todos os tipos de documentos e não sendo confundidas com o conteúdo.</TD>
 203</TR>
 204<TR>
 205<TD><I>Regras Consistentes</I></TD>
 206<TD>Da mesma forma que as marcas, as regras aplicadas a elas são uniformes, não há "exceções" ou "casos especiais".</TD>
 207</TR>
 208<TR>
 209<TD><I>Estruturas Simples</I></TD>
 210<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>
 211</TR>
 212<TR>
 213<TD><I>Fácil de aprender</I></TD>
 214<TD>Com marcações simples e o código fonte legível, a curva de aprendizado é bem amigável.</TD>
 215</TR>
 216<TR>
 217<TD><I>Bons Exemplos</I></TD>
 218<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>
 219</TR>
 220<TR>
 221<TD><I>Ferramentas Valiosas</I></TD>
 222<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>
 223</TR>
 224<TR>
 225<TD><I>Três interfaces ao usuários</I></TD>
 226<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>
 227</TR>
 228<TR>
 229<TD><I>Suporte a Scripts</I></TD>
 230<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>
 231</TR>
 232<TR>
 233<TD><I>Baixe e Execute / Multiplataforma</I></TD>
 234<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>
 235</TR>
 236<TR>
 237<TD><I>Atualizações Freqüentes</I></TD>
 238<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>
 239</TR>
 240</TABLE>
 241
 242<HR NOSHADE SIZE=1>
 243
 244<H3>Tenho que pagar por ele?</H3>
 245
 246<TABLE ALIGN="center" BORDER="1" CELLPADDING="4">
 247<TR>
 248<TH>Absolutamente NÃO!</TH>
 249</TR>
 250</TABLE>
 251
 252<P>
 253O txt2tags é um programa gratuito, GPL, open source, domínio público,
 254etc...
 255</P>
 256<P>
 257Você pode copiar, usar, modificar, vender, liberar como seu. As
 258políticas de software e copyright não são uma das maiores preocupações
 259do autor.
 260</P>
 261
 262<HR NOSHADE SIZE=1>
 263
 264<H2 ID="toc4">Estruturas de Formatação Suportadas</H2>
 265
 266<P>
 267Segue uma lista de todas as estruturas suportadas pelo txt2tags.
 268</P>
 269
 270<UL>
 271<LI>cabeçalho (título, nome do autor, data)
 272<LI>títulos de seções (numeradas ou não)
 273<LI>parágrafos
 274<LI>modificadores de fontes
 275  <UL>
 276  <LI>negrito
 277  <LI>itálico
 278  <LI>sublinhado
 279  </UL>
 280<LI>fonte monoespaço (verbatim)
 281  <UL>
 282  <LI>monoespaço no meio de um parágrafo
 283  <LI>linha monoespaçada
 284  <LI>trecho em monoespaçado
 285  </UL>
 286<LI>citações
 287<LI>links
 288  <UL>
 289  <LI>Links de Internet (URL)
 290  <LI>links de email
 291  <LI>links locais
 292  <LI>links nomeados
 293  </UL>
 294<LI>listas
 295  <UL>
 296  <LI>listas com marcadores
 297  <LI>listas numeradas
 298  <LI>listas de definição
 299  </UL>
 300<LI>linha horizontal de separação
 301<LI>imagems (com alinhamento inteligente)
 302<LI>tabela (com ou sem borda, com alinhamento inteligente)
 303<LI>marcação especial para texto que não deve ser formatado
 304<LI>macro especial para a data atual (com formatação flexível)
 305<LI>comentários (para notas, A FAZER, CORREÇÕES, etc.)
 306</UL>
 307
 308<HR NOSHADE SIZE=1>
 309
 310<H2 ID="toc5">Formatos Suportados</H2>
 311
 312<DL>
 313<DT><B>HTML</B>                                                                </DT><DD>
 314Todo mundo sabe o que o HTML é (dica: Internet).
 315<P></P>
 316O txt2tags gera documentos HTML limpos, que tem boa apresentação e cujo
 317código fonte é legível. Ele NÃO USA javascript, frames ou outras
 318técnicas de formatação fúteis, que não são necessárias para documentos
 319técnicos simples. Mas um arquivo CSS separado pode ser utilizado, se for
 320desejado. O Txt2tags gera código "<I>HTML 4.0 Transitional</I>".
 321<P></P>
 322Desde a versão 2.0, o código HTML gerado pelo txt2tags é 100% aprovado
 323pelo <A HREF="vhttp://validator.w3.org/">validador w3c</A>.
 324</DL>
 325
 326<DL>
 327<DT><B>XHTML</B></DT><DD>
 328Esta é a nova generação do HTML, com regras mais restritas, como fechar
 329todas as marcas que forem abertas. Isto torna o código mas fácil de ser
 330avaliado e entendido. Para propósitos gerais, considere como HTML. O
 331txt2tags gera código "<I>HTML 4.0 Transitional</I>".
 332<P></P>
 333Desde a versão 2.0, o código XHTML gerado pelo txt2tags é 100% aprovado
 334pelo <A HREF="vhttp://validator.w3.org/">validador w3c</A>.
 335<P></P>
 336<DT><B>SGML</B></DT><DD>
 337O SGML é um formato de documento comum que possui aplicações de
 338conversão, como <A HREF="http://www.sgmltools.org/">sgmltools</A>. De um arquivo
 339sgml pode-se gerar documentos html, pdf, ps, info, latex, lyx, rtf e
 340xml. As ferramentas sgml2* também criam índices (TOC) e quebra de seções
 341em subpáginas (sgml2html).
 342<P></P>
 343O txt2tags gera arquivos SGML válidos para a DTD linuxdoc, prontos para
 344serem convertidos com uma ferramenta sgml2* sem qualquer arquivo de
 345catálogo extra ou outras exigências incômodas do SGML.
 346<P></P>
 347<DT><B>LATEX</B></DT><DD>
 348O formato de documentação preferido nos meios acadêmicos, é mais potente
 349do que normalmente se considera. Livros completos, fórmulas complicadas
 350e qualquer texto complexo pode ser escrito em LaTeX. Mas se prepare para
 351perder os cabelos se tentar escever as marcações à mão...
 352<P></P>
 353O txt2tags gera arquivos LaTeX prontos para usar, realizando todos os
 354complexos truques de escape e exceções. O escritor deve se preocupar
 355exclusivamente com o texto.
 356<P></P>
 357<DT><B>MAN</B></DT><DD>
 358As páginas man do UNIX resistiram pelos anos. Formatos de documento vem
 359e vão, e elas estão aí, imbatíveis.
 360<P></P>
 361Existem outras ferramentas para gerar documentos man, mas o txt2tags tem
 362uma vantagem: uma fonte, múltiplos formatos destino. Assim, o conteúdo
 363da mesma página man pode ser convertido para uma página HTML, uma
 364apresentação Magic Point, etc.
 365<P></P>
 366<DT><B>MGP</B></DT><DD>
 367O <A HREF="http://www.mew.org/mgp/">Magic Point</A> é uma ferramenta de apresentação
 368bastante útil (dica: Microsoft PowerPoint), que usa uma linguagem de
 369marcação para definir todas as telas. Desta forma, você pode criar
 370apresentações complexas no vi/emacs/notepad.
 371<P></P>
 372O txt2tags gera um arquivo .mgp pronto para ser usado, definindo todos
 373os cabeçalhos necessários para as definições de fontes e aparência, bem
 374como o suporte aos caracteres acentuados da página de código ISO-8859.
 375<P></P>
 376<B>Observação 1:</B> os arquivos .mgp criados pelo txt2tags usam as fontes
 377Type1 do XFree86! Desta forma, não é necessário incluir fontes TrueType
 378com sua apresentação.
 379<P></P>
 380<B>Observação 2:</B> as definições de cor para as fontes são limpas, de
 381forma que mesmo com uma paleta de cores de sistema pobre (como em
 382<CODE>startx -- -bpp 8</CODE>) a apresentação vai ter boa aparência.
 383<P></P>
 384A chave é: converta e use. Não há necessidade de remendos ou de outros
 385requisitos.
 386<P></P>
 387<DT><B>MOIN</B></DT><DD>
 388Você não sabe o que é o <A HREF="http://moin.sourceforge.net">MoinMoin</A>? Ele é
 389um <A HREF="http://www.c2.com/cgi/wiki">WikiWiki</A>!
 390<P></P>
 391A sintaxe do Moin é um pouco chata, quando você tem que ficar
 392<CODE>{{{'''''acrescentando chaves e plicas'''''}}}</CODE>, mas o txt2tags vem
 393com as marcações simplificadas e uma solução unificada: uma fonte,
 394múltiplos formatos destino.
 395<P></P>
 396<DT><B>PM6</B></DT><DD>
 397Aposto que você não sabia, mas o Adobe PageMaker 6.0 tem sua própria
 398linguagem de marcação! Estilos, tabelas de cores, embelezadores, e a
 399maior parte das funcionalidades acessíveis via cliques de mouse também
 400estão disponíveis em sua linguagem de marcação. Você só precisa acessar
 401o item de menu "Import tagged text". Apenas para registro, é um formato
 402de marcação semelhante ao HTML.
 403<P></P>
 404O txt2tags gera todas as tags e já define um cabeçalho extenso e
 405funcional, configurando os estilos de parágrafo e formatações. Esta é a
 406parte difícil. <B>EPA:</B> Sem quebras de linha! Um parágrafo deve ser uma
 407única linha.
 408<P></P>
 409Nota do Autor:
 410<I>Todo meu livro em português sobre <A HREF="http://guia-er.sf.net/">expressões regulares</A></I>
 411<I>foi escrito no vi, convertido para o formato do PageMaker com o</I>
 412<I>txt2tags e então mandado para o prelo.</I>
 413<P></P>
 414<DT><B>TXT</B></DT><DD>
 415TXT é texto. O único tipo de formatação verdadeiro.
 416<P></P>
 417Apesar das marcações do txt2tags serem bem intuitivas e discretas,
 418pode-se removê-las ao converter o arquivo para TXT puro.
 419<P></P>
 420Os títulos são sublinhados, e o texto é basicamente deixado como está no
 421código fonte.
 422</DL>
 423
 424<HR NOSHADE SIZE=1>
 425
 426<H2 ID="estruturas">Situação dos Formatos-Destino para as Estruturas Suportadas</H2>
 427
 428<TABLE ALIGN="center" BORDER="1" CELLPADDING="4">
 429<TR>
 430<TH>Estrutura</TH>
 431<TH>html</TH>
 432<TH>xhtml</TH>
 433<TH>sgml</TH>
 434<TH>tex</TH>
 435<TH>man</TH>
 436<TH>mgp</TH>
 437<TH>moin</TH>
 438<TH>pm6</TH>
 439<TH>txt</TH>
 440</TR>
 441<TR>
 442<TD>cabeçalhos</TD>
 443<TD ALIGN="center">S</TD>
 444<TD ALIGN="center">S</TD>
 445<TD ALIGN="center">S</TD>
 446<TD ALIGN="center">S</TD>
 447<TD ALIGN="center">S</TD>
 448<TD ALIGN="center">S</TD>
 449<TD ALIGN="center">N</TD>
 450<TD ALIGN="center">N</TD>
 451<TD ALIGN="center">S</TD>
 452</TR>
 453<TR>
 454<TD>título de seções</TD>
 455<TD ALIGN="center">S</TD>
 456<TD ALIGN="center">S</TD>
 457<TD ALIGN="center">S</TD>
 458<TD ALIGN="center">S</TD>
 459<TD ALIGN="center">S</TD>
 460<TD ALIGN="center">S</TD>
 461<TD ALIGN="center">S</TD>
 462<TD ALIGN="center">S</TD>
 463<TD ALIGN="center">S</TD>
 464</TR>
 465<TR>
 466<TD>parágrafos</TD>
 467<TD ALIGN="center">S</TD>
 468<TD ALIGN="center">S</TD>
 469<TD ALIGN="center">S</TD>
 470<TD ALIGN="center">S</TD>
 471<TD ALIGN="center">S</TD>
 472<TD ALIGN="center">S</TD>
 473<TD ALIGN="center">S</TD>
 474<TD ALIGN="center">S</TD>
 475<TD ALIGN="center">S</TD>
 476</TR>
 477<TR>
 478<TD>negrito</TD>
 479<TD ALIGN="center">S</TD>
 480<TD ALIGN="center">S</TD>
 481<TD ALIGN="center">S</TD>
 482<TD ALIGN="center">S</TD>
 483<TD ALIGN="center">S</TD>
 484<TD ALIGN="center">S</TD>
 485<TD ALIGN="center">S</TD>
 486<TD ALIGN="center">S</TD>
 487<TD ALIGN="center">-</TD>
 488</TR>
 489<TR>
 490<TD>itálico</TD>
 491<TD ALIGN="center">S</TD>
 492<TD ALIGN="center">S</TD>
 493<TD ALIGN="center">S</TD>
 494<TD ALIGN="center">S</TD>
 495<TD ALIGN="center">S</TD>
 496<TD ALIGN="center">S</TD>
 497<TD ALIGN="center">S</TD>
 498<TD ALIGN="center">S</TD>
 499<TD ALIGN="center">-</TD>
 500</TR>
 501<TR>
 502<TD>sublinhado</TD>
 503<TD ALIGN="center">S</TD>
 504<TD ALIGN="center">S</TD>
 505<TD ALIGN="center">-</TD>
 506<TD ALIGN="center">S</TD>
 507<TD ALIGN="center">-</TD>
 508<TD ALIGN="center">S</TD>
 509<TD ALIGN="center">S</TD>
 510<TD ALIGN="center">S</TD>
 511<TD ALIGN="center">-</TD>
 512</TR>
 513<TR>
 514<TD>pré-formatado</TD>
 515<TD ALIGN="center">S</TD>
 516<TD ALIGN="center">S</TD>
 517<TD ALIGN="center">S</TD>
 518<TD ALIGN="center">S</TD>
 519<TD ALIGN="center">-</TD>
 520<TD ALIGN="center">S</TD>
 521<TD ALIGN="center">S</TD>
 522<TD ALIGN="center">S</TD>
 523<TD ALIGN="center">-</TD>
 524</TR>
 525<TR>
 526<TD>linha pré-formatada</TD>
 527<TD ALIGN="center">S</TD>
 528<TD ALIGN="center">S</TD>
 529<TD ALIGN="center">S</TD>
 530<TD ALIGN="center">S</TD>
 531<TD ALIGN="center">S</TD>
 532<TD ALIGN="center">S</TD>
 533<TD ALIGN="center">S</TD>
 534<TD ALIGN="center">S</TD>
 535<TD ALIGN="center">-</TD>
 536</TR>
 537<TR>
 538<TD>área pré-formatada</TD>
 539<TD ALIGN="center">S</TD>
 540<TD ALIGN="center">S</TD>
 541<TD ALIGN="center">S</TD>
 542<TD ALIGN="center">S</TD>
 543<TD ALIGN="center">S</TD>
 544<TD ALIGN="center">S</TD>
 545<TD ALIGN="center">S</TD>
 546<TD ALIGN="center">S</TD>
 547<TD ALIGN="center">-</TD>
 548</TR>
 549<TR>
 550<TD>área cotada</TD>
 551<TD ALIGN="center">S</TD>
 552<TD ALIGN="center">S</TD>
 553<TD ALIGN="center">S</TD>
 554<TD ALIGN="center">S</TD>
 555<TD ALIGN="center">S</TD>
 556<TD ALIGN="center">S</TD>
 557<TD ALIGN="center">S</TD>
 558<TD ALIGN="center">S</TD>
 559<TD ALIGN="center">S</TD>
 560</TR>
 561<TR>
 562<TD>links internet</TD>
 563<TD ALIGN="center">S</TD>
 564<TD ALIGN="center">S</TD>
 565<TD ALIGN="center">S</TD>
 566<TD ALIGN="center">-</TD>
 567<TD ALIGN="center">-</TD>
 568<TD ALIGN="center">-</TD>
 569<TD ALIGN="center">S</TD>
 570<TD ALIGN="center">-</TD>
 571<TD ALIGN="center">-</TD>
 572</TR>
 573<TR>
 574<TD>links e-mail</TD>
 575<TD ALIGN="center">S</TD>
 576<TD ALIGN="center">S</TD>
 577<TD ALIGN="center">S</TD>
 578<TD ALIGN="center">-</TD>
 579<TD ALIGN="center">-</TD>
 580<TD ALIGN="center">-</TD>
 581<TD ALIGN="center">S</TD>
 582<TD ALIGN="center">-</TD>
 583<TD ALIGN="center">-</TD>
 584</TR>
 585<TR>
 586<TD>links locais</TD>
 587<TD ALIGN="center">S</TD>
 588<TD ALIGN="center">S</TD>
 589<TD ALIGN="center">S</TD>
 590<TD ALIGN="center">N</TD>
 591<TD ALIGN="center">-</TD>
 592<TD ALIGN="center">-</TD>
 593<TD ALIGN="center">S</TD>
 594<TD ALIGN="center">-</TD>
 595<TD ALIGN="center">-</TD>
 596</TR>
 597<TR>
 598<TD>links nomeados</TD>
 599<TD ALIGN="center">S</TD>
 600<TD ALIGN="center">S</TD>
 601<TD ALIGN="center">S</TD>
 602<TD ALIGN="center">-</TD>
 603<TD ALIGN="center">-</TD>
 604<TD ALIGN="center">-</TD>
 605<TD ALIGN="center">S</TD>
 606<TD ALIGN="center">-</TD>
 607<TD ALIGN="center">-</TD>
 608</TR>
 609<TR>
 610<TD>lista não-numerada</TD>
 611<TD ALIGN="center">S</TD>
 612<TD ALIGN="center">S</TD>
 613<TD ALIGN="center">S</TD>
 614<TD ALIGN="center">S</TD>
 615<TD ALIGN="center">S</TD>
 616<TD ALIGN="center">S</TD>
 617<TD ALIGN="center">S</TD>
 618<TD ALIGN="center">S</TD>
 619<TD ALIGN="center">S</TD>
 620</TR>
 621<TR>
 622<TD>lista numerada</TD>
 623<TD ALIGN="center">S</TD>
 624<TD ALIGN="center">S</TD>
 625<TD ALIGN="center">S</TD>
 626<TD ALIGN="center">S</TD>
 627<TD ALIGN="center">S</TD>
 628<TD ALIGN="center">S</TD>
 629<TD ALIGN="center">S</TD>
 630<TD ALIGN="center">S</TD>
 631<TD ALIGN="center">S</TD>
 632</TR>
 633<TR>
 634<TD>lista de definições</TD>
 635<TD ALIGN="center">S</TD>
 636<TD ALIGN="center">S</TD>
 637<TD ALIGN="center">S</TD>
 638<TD ALIGN="center">S</TD>
 639<TD ALIGN="center">S</TD>
 640<TD ALIGN="center">N</TD>
 641<TD ALIGN="center">N</TD>
 642<TD ALIGN="center">N</TD>
 643<TD ALIGN="center">S</TD>
 644</TR>
 645<TR>
 646<TD>linha horizontal</TD>
 647<TD ALIGN="center">S</TD>
 648<TD ALIGN="center">S</TD>
 649<TD ALIGN="center">-</TD>
 650<TD ALIGN="center">S</TD>
 651<TD ALIGN="center">-</TD>
 652<TD ALIGN="center">S</TD>
 653<TD ALIGN="center">S</TD>
 654<TD ALIGN="center">N</TD>
 655<TD ALIGN="center">S</TD>
 656</TR>
 657<TR>
 658<TD>imagem</TD>
 659<TD ALIGN="center">S</TD>
 660<TD ALIGN="center">S</TD>
 661<TD ALIGN="center">S</TD>
 662<TD ALIGN="center">S</TD>
 663<TD ALIGN="center">-</TD>
 664<TD ALIGN="center">S</TD>
 665<TD ALIGN="center">S</TD>
 666<TD ALIGN="center">N</TD>
 667<TD ALIGN="center">-</TD>
 668</TR>
 669<TR>
 670<TD>tabela</TD>
 671<TD ALIGN="center">S</TD>
 672<TD ALIGN="center">S</TD>
 673<TD ALIGN="center">S</TD>
 674<TD ALIGN="center">S</TD>
 675<TD ALIGN="center">S</TD>
 676<TD ALIGN="center">N</TD>
 677<TD ALIGN="center">S</TD>
 678<TD ALIGN="center">N</TD>
 679<TD ALIGN="center">N</TD>
 680</TR>
 681<TR>
 682<TH>Extras</TH>
 683<TH>html</TH>
 684<TH>xhtml</TH>
 685<TH>sgml</TH>
 686<TH>tex</TH>
 687<TH>man</TH>
 688<TH>mgp</TH>
 689<TH>moin</TH>
 690<TH>pm6</TH>
 691<TH>txt</TH>
 692</TR>
 693<TR>
 694<TD>image align</TD>
 695<TD ALIGN="center">S</TD>
 696<TD ALIGN="center">S</TD>
 697<TD ALIGN="center">N</TD>
 698<TD ALIGN="center">N</TD>
 699<TD ALIGN="center">-</TD>
 700<TD ALIGN="center">S</TD>
 701<TD ALIGN="center">N</TD>
 702<TD ALIGN="center">N</TD>
 703<TD ALIGN="center">-</TD>
 704</TR>
 705<TR>
 706<TD>table cell align</TD>
 707<TD ALIGN="center">S</TD>
 708<TD ALIGN="center">S</TD>
 709<TD ALIGN="center">S</TD>
 710<TD ALIGN="center">S</TD>
 711<TD ALIGN="center">S</TD>
 712<TD ALIGN="center">N</TD>
 713<TD ALIGN="center">S</TD>
 714<TD ALIGN="center">N</TD>
 715<TD ALIGN="center">N</TD>
 716</TR>
 717</TABLE>
 718
 719<TABLE ALIGN="center" CELLPADDING="4">
 720<TR>
 721<TH></TH>
 722<TH>Legenda</TH>
 723</TR>
 724<TR>
 725<TD><B>S</B></TD>
 726<TD><I>suportada</I></TD>
 727</TR>
 728<TR>
 729<TD><B>N</B></TD>
 730<TD><I>não suportada (talvez em uma versão futura)</I></TD>
 731</TR>
 732<TR>
 733<TD><B>-</B></TD>
 734<TD><I>não suportada (não pode ser feita neste formato)</I></TD>
 735</TR>
 736</TABLE>
 737
 738<HR NOSHADE SIZE=1>
 739
 740<H2 ID="toc7">As Três Interfaces ao Usuário: GUI, Web e Linha de Comando</H2>
 741
 742<P>
 743Assim como diferentes usuários possuem diferentes necessidades e
 744ambientes, o txt2tags é bastante flexivel na forma de ser usado.
 745</P>
 746<P>
 747Existem três Interfaces de Usuário para o programa, cada uma atendendo a
 748um objetivo definido e com funcionalidades próprias.
 749</P>
 750
 751<UL>
 752<LI><B>GUI</B>: Escrita em Tk, traz as janelas e os cliques para o txt2tags.
 753<LI><B>Web</B>: Escrita em PHP, permite que o usuário execute o txt2tags no
 754           navegador, não exigindo instalação do lado do cliente.
 755<LI><B>Linha de Comando</B>: Escrita em Python, é o núcleo do programa.
 756           Todas as funcionalidades estão disponíveis como opções de
 757           linha de comando.
 758</UL>
 759
 760<HR NOSHADE SIZE=1>
 761
 762<H3 ID="gui">Interface Gráfica Tk</H3>
 763
 764<P>
 765Desde a versão 1.0, há uma bela Interface Gráfica, que funciona do
 766Linux, Windows, Mac e outros.
 767</P>
 768<P>
 769O programa automaticamente detecta se seu sistema pode apresentar a
 770interface e a lança quando é chamado sem argumentos. Pode-se forçar a
 771apresentação da Interfaca Gráfica com a opção <CODE>--gui</CODE>. Se estiver
 772faltando algum recurso o programa irá alertar.
 773</P>
 774	<BLOCKQUOTE>
 775	<B>Nota:</B> O módulo Tkinter é necessário. Como ele vem com a
 776	distribição padrão do Python você já deve tê-lo.
 777	</BLOCKQUOTE>
 778<P>
 779Ela é bastante simples e fácil de usar:
 780</P>
 781          <center><IMG ALIGN="middle" SRC="../userguide/gui.png" BORDER="0" ALT=""></center>          
 782
 783<OL>
 784<LI>Você localiza o arquivo fonte .t2t no disco e suas opções são
 785  carregadas.
 786<P></P>
 787<LI>Se o destino ainda estiver vazio, você deve escolher um.
 788<P></P>
 789<LI>Há algumas opões que podem ser escolhidas, mas nenhuma delas é
 790  essencial.
 791<P></P>
 792<LI>Finalmente, pressione o botão "Converter!".
 793</OL>
 794
 795<P>
 796Uma boa opção a selecionar é "<I>Dump to screen</I>", assim se pode
 797verificar o código resultante em uma janela separada, sem que o arquivo
 798seja salvo. Quando o código estiver correto, basta desmarcá-la e o
 799arquivo será gravado.
 800</P>
 801<P>
 802As cores padrão podem ser mudadas no arquivo <CODE>~/.txt2tagsrc</CODE>,
 803configurando em <CODE>%!guicolors</CODE>. Por exemplo:
 804</P>
 805
 806<PRE>
 807   % minhas cores para a interface (fundo1, texto1, fundo2, texto2)
 808   %!guicolors: blue white brown yellow
 809</PRE>
 810
 811<HR NOSHADE SIZE=1>
 812
 813<H3 ID="web">Interface Web</H3>
 814
 815<P>
 816A Interface Web está em funcionamento na Internet no endereço
 817<A HREF="http://txt2tags.org/online.php">http://txt2tags.org/online.php</A>, permitindo que o programa possa ser
 818usado e testado antes de ser copiado.
 819</P>
 820          <center><IMG ALIGN="middle" SRC="../userguide/web.png" BORDER="0" ALT=""></center>          
 821<P>
 822Esta interface também pode ser colocada na intrant para uso local,
 823evitando a instalação do txt2tags em todas as máquinas.
 824</P>
 825
 826<HR NOSHADE SIZE=1>
 827
 828<H3 ID="linhadecomando">Interface de Linha de Comando</H3>
 829
 830<P>
 831Para usuários de linha de comando acostumados, o parâmetro --help deve
 832ser suficiente:
 833</P>
 834
 835<PRE>
 836  Uso: txt2tags [OPÇÕES] [arquivo.t2t ...]
 837  
 838    -t, --target        define o formato do destino. tipos suportados:
 839                        html, xhtml, sgml, tex, man, mgp, moin, pm6, txt
 840    -i, --infile=ARQ    define ARQ como o arquivo fonte ('-' para STDIN)
 841    -0, --outfile=ARQ   define ARQ como o arquivo destino ('-' para STDOUT)
 842    -n, --enum-title    numera todos os títulos como 1, 1.1, 1.1.1, etc
 843    -H, --no-headers    suprime os cabeçalhos, título e rodapé
 844        --headers       exibe os cabeçalhos, título e rodapé (padrão LIGADO)
 845        --encoding      informa a codificação de destino (utf-8, iso-8859-1, etc)
 846        --style=ARQ     utiliza ARQ como estilo do documento (CSS no Html)
 847        --css-sugar     insere tags compatíveis com CSS em destinos HTML e XHTML
 848        --mask-email    esconde e-mails dos robôs de SPAM. x@y.z vira &lt;x (a) y z&gt;
 849        --toc           inclui o Índice (Table of Contents) no documento destino
 850        --toc-only      exibe o Índice do documento e sai
 851        --toc-level=N   define o nível máximo do Índice para N
 852        --rc            lê a config do usuário em ~/.txt2tagsrc (padrão LIGADO)
 853        --gui           carrega a interface gráfica escrita em TK
 854    -v, --verbose       exibe mensagens informativas durante a conversão
 855    -h, --help          exibe este texto de ajuda e sai
 856    -V, --version       exibe a versão do programa e sai
 857        --dump-config   exibe todas as configurações encontradas e sai
 858  
 859  Opções para DESLIGAR funcionalidades:
 860       --no-outfile, --no-infile, --no-style, --no-encoding, --no-headers
 861       --no-toc, --no-toc-only, --no-mask-email, --no-enum-title, --no-rc
 862       --no-css-sugar
 863  
 864  Exemplo:
 865       txt2tags -t html --toc meuarquivo.t2t
 866  
 867  Normalmente a saída convertida é gravada em 'arquivo.&lt;tipo&gt;'.
 868  Utilize --outfile para forçar um nome para o arquivo de saída.
 869  Se o arquivo de entrada é '-', lê de STDIN.
 870  Se o arquivo de saída é '-', envia a saída para STDOUT.
 871</PRE>
 872
 873<H4>Exemplos</H4>
 874
 875<P>
 876Supondo que exista um arquivo de marcação chamado <CODE>file.t2t</CODE>, vamos nos
 877divertir um pouco.
 878</P>
 879
 880<TABLE CELLPADDING="4">
 881<TR>
 882<TD><B>Convertendo para HTML</B></TD>
 883<TD><CODE>$ txt2tags -t html file.t2t</CODE></TD>
 884</TR>
 885<TR>
 886<TD><B>O mesmo, usando redirecionamento</B></TD>
 887<TD><CODE>$ txt2tags -t html -o - file.t2t &gt; file.html</CODE></TD>
 888</TR>
 889<TR>
 890<TD></TD>
 891<TD>.</TD>
 892</TR>
 893<TR>
 894<TD><B>Incluindo uma Tabela de Conteúdo</B></TD>
 895<TD><CODE>$ txt2tags -t html --toc file.t2t</CODE></TD>
 896</TR>
 897<TR>
 898<TD><B>Idem, numerando os títulos</B></TD>
 899<TD><CODE>$ txt2tags -t html --toc --enum-title file.t2t</CODE></TD>
 900</TR>
 901<TR>
 902<TD></TD>
 903<TD>.</TD>
 904</TR>
 905<TR>
 906<TD><B>Visualização Rápida do Conteúdo</B></TD>
 907<TD><CODE>$ txt2tags --toc-only file.t2t</CODE></TD>
 908</TR>
 909<TR>
 910<TD><B>Quem sabe com números?</B></TD>
 911<TD><CODE>$ txt2tags --toc-only --enum-title file.t2t</CODE></TD>
 912</TR>
 913<TR>
 914<TD></TD>
 915<TD>.</TD>
 916</TR>
 917<TR>
 918<TD><B>Linha simples de STDIN</B></TD>
 919<TD><CODE>$ echo -e "\n**bold**" | txt2tags -t html --no-headers -</CODE></TD>
 920</TR>
 921<TR>
 922<TD><B>Testando o Mascaramento de Email</B></TD>
 923<TD><CODE>$ echo -e "\njohn.wayne@farwest.com" | txt2tags -t txt --mask-email --no-headers -</CODE></TD>
 924</TR>
 925<TR>
 926<TD><B>Edição pós-conversão</B></TD>
 927<TD><CODE>$ txt2tags -t html -o- file.t2t | sed "s/&lt;BODY .*/&lt;BODY BGCOLOR=green&gt;/" &gt; file.html</CODE></TD>
 928</TR>
 929</TABLE>
 930
 931<DL>
 932<DT><I>Nota</I></DT><DD>
 933Desde a versão 1.6 você pode fazer pre e pós processamento usando as
 934macros de configuração <CODE>%!preproc</CODE> e <CODE>%!postproc</CODE>.
 935</DL>
 936
 937<HR NOSHADE SIZE=5>
 938
 939<H1 ID="instalacao">Parte II - OK, eu quero um. E agora?</H1>
 940
 941<P>
 942Basta baixar o programa e executar o mesmo no seu computador.
 943</P>
 944
 945<H2 ID="toc9">Download e Instalação do Python</H2>
 946
 947<P>
 948Antes de mais nada, deve-se baixar e instalar o interpretador Python
 949para o seu sistema. Se você já o tem, então pule eset passo.
 950</P>
 951<P>
 952O Python é uma das melhores linguagens de programação que existem, ela
 953pode ser utilizada no Windows, Linux, UNIX, Macintosh, e outras
 954plataformas, e pode ser baixada do
 955<A HREF="http://www.python.org">web site do Python</A>. As dicas de instalação podem
 956ser encontradas no mesmo site. O txt2tags funciona com o Python 1.5 ou
 957posterior.
 958</P>
 959<P>
 960Se você não tem certeza de ter o Python ou não, abra um console (tty,
 961xterm, MSDOS) e escreva <CODE>python</CODE>. Se ele não estiver instalado, o
 962sistema vai lhe informar.
 963</P>
 964
 965<H2 ID="toc10">Copiando o txt2tags</H2>
 966
 967<P>
 968O local oficial de distribuição do txt2tags é na homepage do programa,
 969em <A HREF="http://txt2tags.org/src">http://txt2tags.org/src</A>.
 970</P>
 971<P>
 972Todos os arquivos do programa estão em um tarball (arquivo .tgz), que
 973pode ser expandido pela maioria dos utilitários de compressão (incluindo
 974o Winzip).
 975</P>
 976<P>
 977Simplesmente pegue a <B>última</B> versão (data mais recente, número de
 978versão maior). As versões anteriores estão lá apenas por razões
 979históricas.
 980</P>
 981
 982<H2 ID="toc11">Instalação do txt2tags</H2>
 983
 984<P>
 985Como é apenas um script Python, o txt2tags não precisa ser instalado.
 986</P>
 987<P>
 988O único arquivo necessário para usar o programa é o script txt2tags. Os
 989outros arquivos do tarball compreendem a documentação, ferramentas e
 990arquivos de exemplo.
 991</P>
 992<P>
 993O modo mais seguro de usar o txt2tags é chamar o Python com ele:
 994</P>
 995
 996<PRE>
 997  prompt$ python txt2tags 
 998</PRE>
 999
1000<P>
1001Se você quiser "instalar" o txt2tags no sistema como um programa
1002independente, basta copiar (ou criar um link) o script txt2tags para um
1003diretório que esteja no PATH do sistema e certificar-se que o sistema
1004saiba como executar o mesmo.
1005</P>
1006
1007<DL>
1008<DT><B>UNIX/Linux</B></DT><DD>
1009  Torne o script executável (<CODE>chmod +x txt2tags</CODE>) e copie o mesmo para
1010  um diretório no $PATH (<CODE>cp txt2tags /usr/local/bin</CODE>)
1011<P></P>
1012<DT><B>Windows</B></DT><DD>
1013  Renomeie o script, acrescentando a extensão .py
1014  (<CODE>ren txt2tags txt2tags.py</CODE>) e o copie para um diretório que esteja
1015  no PATH do sistema (<CODE>copy txt2tags.py C:\WINNT</CODE>)
1016</DL>
1017
1018<P>
1019Depois disto, pode-se criar um ícone no desktop para o programa, se
1020quiser usar a Interface Gráfica do programa.
1021</P>
1022
1023<H3>Pacotes Especiais para Usuários Windows</H3>
1024
1025<P>
1026Existem dois arquivos de distribuição .EXE para o txt2tags, que instalam
1027o programa em máquinas Windows com apenas alguns cliques:
1028</P>
1029
1030<UL>
1031<LI>O script txt2tags para aqueles que tem o interpretador Python
1032  instalado
1033<LI>A versão stand-alone, que não requer a instalação do interpretador
1034  Pyton para ser executada (já tem uma versão pequena incluída).
1035</UL>
1036
1037<P>
1038Visite o site <I>Txt2tags-Win</I> para baixar estes pacotes:
1039<A HREF="http://txt2tags-win.sf.net/">http://txt2tags-win.sf.net/</A>
1040</P>
1041
1042<H2 ID="sintaxe">Instalar os Arquivos de Sintaxe dos Editores de Texto</H2>
1043
1044<P>
1045O txt2tags possui arquivos de sintaxe práticos que podem ser usados com
1046os seguintes editores de texto:
1047</P>
1048
1049<UL>
1050<LI>Vim (<A HREF="http://www.vim.org">www.vim.org</A>)
1051<LI>Emacs (<A HREF="http://www.emacs.org">www.emacs.org</A>)
1052<LI>Nano (<A HREF="http://www.nano-editor.org">www.nano-editor.org</A>)
1053<LI>Kate (<A HREF="http://kate.kde.org">http://kate.kde.org</A>)
1054</UL>
1055
1056<P>
1057Os arquivos de sintaxe têm registro de todas as regras e marcações do
1058txt2tags, ajudando ao usuário a escrever documentos sem erros. As marcas
1059são mostradas coloridas, assim se pode ver se tudo foi escrito
1060corretamente.
1061</P>
1062
1063<TABLE ALIGN="center" BORDER="1" CELLPADDING="4">
1064<TR>
1065<TD ALIGN="center"><center><IMG ALIGN="middle" SRC="../userguide/vim.png" BORDER="0" ALT=""></center></TD>
1066</TR>
1067<TR>
1068<TD ALIGN="center">O arquivo de exemplo aberto no Editor Vim</TD>
1069</TR>
1070</TABLE>
1071
1072<P>
1073Cada editor tem um procedimento diferente para usar seu arquivo de
1074sintaxe. Por favor verifique no cabeçalho de cada arquivo e na
1075documentação do editor.
1076</P>
1077
1078<HR NOSHADE SIZE=5>
1079
1080<H1 ID="toc13">Parte III - Escrevendo e Convertendo Seu Primeiro Documento</H1>
1081
1082<P>
1083Desculpe, este capítulo ainda está em desenvolvimento.
1084</P>
1085
1086<H2 ID="toc14">As Áreas do documento .t2t</H2>
1087
1088<P>
1089Os arquivos de marcação txt2tags são divididos em 3 áreas. Cada área tem
1090suas próprias regras e finalidade. São elas:
1091</P>
1092
1093<DL>
1094<DT><I>Área de Cabeçalho</I></DT><DD>
1095É o lugar para informações sobre o Título do Documento, Autor, Versão e
1096Data. (opcional)
1097<P></P>
1098<DT><I>Área de Configuração</I></DT><DD>
1099É o local para colocar as configurações Gerais do documento e
1100modificadores do funcionamento do analisador. (opcional)
1101<P></P>
1102<DT><I>Corpo do Texto</I></DT><DD>
1103É o local para o Conteúdo do Documento (requerida)
1104</DL>
1105
1106<P>
1107Como vemos acima, as duas primeiras áreas são opcionais, sendo que o
1108<I>Corpo do Texto</I> é a única área indispensável.
1109(<I>Nota: A <B>Área de Configuração</B> foi introduzida no txt2tags na versão 1.3</I>)
1110</P>
1111<P>
1112As áreas são delimitadas por regras especiais, que serão vistas em
1113detalhe no próximo capítulo. Por enquanto, esta é uma representação
1114gráfica das áreas de um documento:
1115</P>
1116
1117<PRE>
1118               ____________
1119              |            |
1120              |  CABEÇALHO |       1. Primeiro, o cabeçalho
1121              |            |
1122              |   CONFIG   |       2. Então a configuração
1123              |            |
1124              |   CORPO    |       3. E, finalmente, o corpo do documento
1125              |            |
1126              |    ...     |          que segue até o final do arquivo.
1127              |    ...     |
1128              |____________|
1129  
1130</PRE>
1131
1132<P>
1133Em resumo, é assim que as áreas são definidas:
1134</P>
1135
1136<TABLE ALIGN="center" CELLPADDING="4">
1137<TR>
1138<TD><B>Cabeçalhos</B></TD>
1139<TD>As primeiras 3 linhas do arquivo, ou a primeira linha é deixada em branco se não são usados cabeçalhos</TD>
1140</TR>
1141<TR>
1142<TD><B>Configuração</B></TD>
1143<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>
1144</TR>
1145<TR>
1146<TD><B>Corpo</B></TD>
1147<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>
1148</TR>
1149</TABLE>
1150
1151<H3>Exemplo Completo</H3>
1152
1153<PRE>
1154  Título do meu belo documento
1155  Sr. Fulano da Silva
1156  Última atualização: %%date(%c)
1157  
1158  %! Target  : html
1159  %! Style   : fancy.css
1160  %! Encoding: UTF-8
1161  %! Options : --toc --enum--title
1162  
1163  Oi! Este é o meu documento de teste.
1164  E o seu conteúdo termina aqui.
1165</PRE>
1166
1167<HR NOSHADE SIZE=5>
1168
1169<H1 ID="toc15">Parte IV - Dominando o Txt2tags</H1>
1170
1171<H2 ID="toc16">A Área de Cabeçalho</H2>
1172
1173<P>
1174Localização:
1175</P>
1176
1177<UL>
1178<LI>Posição fixa: <B>Primeiras 3 linhas</B> do arquivo. Ponto.
1179<LI>Posição fixa: <B>A Primeira Linha</B> do arquivo está em branco. Isto
1180  significa que o cabeçalho está vazio.
1181</UL>
1182
1183<P>
1184A Área de Cabeçalho é a única que tem uma posição fixa, orientada a
1185linhas. Ela está localizada nas três primeiras linhas do código fonte.
1186</P>
1187<P>
1188O conteúdo destas linhas é livre, sem necessidade de nenhuma informação
1189estática de nenhum tipo. Mas recomenda-se o seguinte para a maioria dos
1190documentos:
1191</P>
1192
1193   <UL>
1194   <LI><I>linha 1</I>: título do documento
1195   <LI><I>linha 2</I>: nome e/ou email do autor
1196   <LI><I>linha 3</I>: data e/ou versão do documento
1197                 (um bom lugar para colocar <CODE>%%date</CODE>)
1198   </UL>
1199
1200<P>
1201Tenha em mente que as 3 primeiras linhas do arquivo fonte serão as 3
1202primeiras linhas no documento gerado, separadas e com um grande
1203contraste em relação ao corpo do texto (ou seja, letras grandes,
1204negrito). Se a paginação for permitida, os cabeçalhos estarão separados
1205e centralizados na primeira página.
1206</P>
1207
1208<H4>Menos (ou Nenhuma) Linhas de Cabeçalho</H4>
1209
1210<P>
1211Às vezes os usuários querem especificar menos de três linhas nos
1212cabeçalhos, dando apenas o título do documento e/ou informação de data.
1213</P>
1214<P>
1215Basta deixar a 2a. e/ou a 3a. linhas em branco e estas linhas não serão
1216incluídas no documento gerado. Mas tenha em mente que, mesmo em branco,
1217estas linhas ainda são parte dos cabeçalho, e o corpo do documento deve
1218começar <B>após</B> a 3a. linha.
1219</P>
1220<P>
1221O título é o único cabeçalho requerido (a primeira linha), mas se você
1222deixar ela em branco, está dizendo que seu documento
1223<B>não tem cabeçalho</B>. Desta forma, a <I>Área de Texto</I> irá começar em
1224seguida, na 2a. linha.
1225</P>
1226<P>
1227Não usar cabeçalhos no documento é útil se você quiser especificar seus
1228próprios cabeçalhos customizados após a conversão. A opção de linha de
1229comando <CODE>--no-headers</CODE> é geralmente necessária para este tipo de coisa.
1230</P>
1231
1232<H4>Direto ao ponto</H4>
1233
1234<TABLE ALIGN="center" BORDER="1" CELLPADDING="4">
1235<TR>
1236<TH>Em resumo: "Cabeçalhos são apenas <U>posições</U>, não conteúdo "</TH>
1237</TR>
1238</TABLE>
1239
1240<P>
1241Coloque um texto na primeira linha, ele irá aparecer na primeira linha
1242do arquivo gerado. O mesmo para a 2a. e 3a. linhas de cabeçalho.
1243</P>
1244
1245<HR NOSHADE SIZE=1>
1246
1247<H2 ID="toc17">A Área de Configuração</H2>
1248
1249<P>
1250Localização:
1251</P>
1252
1253<UL>
1254<LI>Começa logo após a Área de Cabeçalhos
1255  <UL>
1256  <LI>Começa na <B>4a. linha</B> do arquivo se forem especificados <B>Cabeçalhos</B>
1257  <LI>Começa na <B>2a. linha</B> se <B>não</B> forem especificados <B>Cabeçalhos</B>
1258  </UL>
1259<LI>Termina quando a Área de Conteúdo começa
1260  <UL>
1261  <LI>Termina com uma linha que não seja de Configuração, ou de
1262    Comentário, ou que seja uma linha em Branco.
1263  </UL>
1264</UL>
1265
1266<P>
1267A Área de Configuração é opcional. A maioria dos usuários pode escrever
1268carradas de arquivos txt2tags mesmo sem saber que ela existe, mas os
1269usuários experientes irão gostar do poder e controle que ela oferece.
1270</P>
1271<P>
1272O uso primário desta área é para definir configurações que afetam o
1273comportamento do programa.
1274</P>
1275
1276<H4>Então, como configurar algo? Qual a sintaxe?</H4>
1277
1278<P>
1279As linhas de configuração são <I>linhas de comentário especiais</I>,
1280marcadas com um identificador no início ("<CODE>!</CODE>") que torna estes
1281comentários diferentes dos comentários normais. A sintaxe é tão simples
1282quanto uma atribuição de valor a uma variável, composta por uma
1283palavra-chave e um valor, separados um do outro pelo separador canônico
1284dois-pontos ("<CODE>:</CODE>").
1285</P>
1286
1287<TABLE ALIGN="center" BORDER="1" CELLPADDING="4">
1288<TR>
1289<TH>%! palavra-chave : valor</TH>
1290</TR>
1291</TABLE>
1292
1293<P>
1294<B><CODE>Detalhes da Sintaxe:</CODE></B> O ponto de exclamação deve ser colocado
1295junto com o caractere de comentário, sem espaço entre eles ("<CODE>%!</CODE>").
1296Os espaços em torno da <I>palavra-chave</I> e o separador são opcionais, e
1297tanto a <I>palavra-chave</I> quanto o <I>valor</I> podem estar
1298indiferentemente em maiúsculas ou minúsculas.
1299</P>
1300
1301<H4>O que eu posso configurar? Quais são as palavra-chave válidas?</H4>
1302
1303<P>
1304As configurações que podem ser feitas são <I>Target</I>, <I>Options</I>, <I>Style</I>,
1305<I>Encoding</I>, <I>PreProc</I> e <I>PostProc</I>.
1306</P>
1307<P>
1308A configuração <B><I>Target</I></B> define o destino padrão na qual o
1309documento deve ser convertido.
1310</P>
1311<P>
1312A configuração <B><I>Options</I></B> é útil para especificar as opções de
1313linha de comando padrão para o arquivo fonte. Estas opções podem ser
1314sobrescritas pela linha de comando real. Usar esta opção juntamente com
1315<CODE>%!target</CODE> permite converter o documento simplesmente comandando:
1316<CODE>txt2tags file.t2t</CODE>
1317</P>
1318<P>
1319A configuração <B><I>Style</I></B> só é suportada pelo tipo de documento
1320destino HTML, para definir uma folha de estilo
1321(<I>Cascading Style Sheets - CSS</I>).
1322</P>
1323<P>
1324A configuração <B><I>Encoding</I></B> é necessária para escritores não
1325ingleses, que usem letras acentuadas e outros detalhes específicos de
1326localização, de forma que o <I>Conjunto de Caracteres</I> do documento seja
1327personalizado (se permitido).
1328</P>
1329<P>
1330A configuração <B><I>PreProc</I></B> é um filtro. Ela define regras do tipo
1331"busca e troca" que serão aplicadas ao arquivo original <U>antes</U> que
1332qualquer análise por parte do txt2tags ocorra.
1333</P>
1334<P>
1335A configuração <B><I>PostProc</I></B> é um filtro. Ela define regras do tipo
1336"busca e troca" que serão aplicadas ao arquivo destino <U>depois</U> de
1337todo o processamento por parte do txt2tags.
1338</P>
1339<P>
1340Exemplo:
1341</P>
1342
1343<PRE>
1344  %! Target  : html
1345  %! Options : --toc --toc-level 3
1346  %! Style   : fancy.css
1347  %! Encoding: UTF-8
1348  %! PreProc : "amj"       "Aurelio Marinho Jargas"
1349  %! PostProc: '&lt;BODY.*?&gt;' '&lt;BODY bgcolor="yellow"&gt;'
1350</PRE>
1351
1352<H4>Algumas regras sobre as Configurações</H4>
1353
1354 <UL>
1355 <LI>As configurações são válidas somente dentro da Área de Configuração,
1356   e serão consideradas comentários simples se forem encontradas no
1357   Corpo do documento.
1358 <P></P>
1359 <LI>Se a mesma palavra-chave aparece mais de uma vez na Área de
1360   Configuração, apenas a última será usada. Exceção: options, preproc e
1361   postproc, que são acumulativas.
1362 <P></P>
1363 <LI>Uma linha de configuração com uma palavra-chave inválida será
1364   considerada um comentário.
1365 <P></P>
1366 <LI>Estas configurações têm precedência sobre o arquivo <CODE>txt2tagsrc</CODE>,
1367   as não sobre as opções de linha de comando.
1368 </UL>
1369
1370<HR NOSHADE SIZE=1>
1371
1372<H2 ID="toc18">O Corpo do Texto</H2>
1373
1374<P>
1375Localização:
1376</P>
1377
1378<UL>
1379<LI>Começa na primeira linha válida de texto do arquivo
1380  <UL>
1381  <LI>Cabeçalhos, Configurações e Comentários <B>não</B> são linhas de texto
1382    válidas
1383  </UL>
1384<LI>Termina no fim do arquivo (EOF)
1385</UL>
1386
1387<P>
1388Bem, o corpo do texto é tudo que estiver fora das Áreas de Cabeçalho e
1389de Configuração.
1390</P>
1391<P>
1392O corpo do texto é onde está o conteúdo do documento e todas as
1393estruturas e formatações que o txt2tags reconhece. Dentro do corpo podem
1394ser também colocados comentários para <I>A FAZER</I> e anotações
1395particulares.
1396</P>
1397<P>
1398Pode-se utilizar a opção de linha de comando <CODE>--no-headers</CODE> para
1399converter somente o corpo do documento, suprimindo os cabeçalhos. Esta
1400opção é útil quando os cabeçalhos estão em um arquivo separado, que será
1401unido ao corpo depois da conversão.
1402</P>
1403
1404<HR NOSHADE SIZE=1>
1405
1406<H2 ID="regras">Marcações (REGRAS)</H2>
1407
1408<P>
1409Todas as marcações e sintaxe usadas pelo txt2tags estão detalhadas em
1410um <A HREF="REGRAS">arquivo REGRAS a parte</A>.
1411</P>
1412
1413<HR NOSHADE SIZE=1>
1414
1415<H2 ID="data">A macro %%date</H2>
1416
1417<P>
1418A macro <CODE>%%date</CODE> chamada sem nenhum parâmetro adicional retorna a data
1419atual no formato ISO <I>yyyymmdd</I>. Uma formatação opcional pode ser
1420especificada usando a sintaxe <CODE>%%date(formato)</CODE>.
1421</P>
1422<P>
1423O <I>formato</I> contém texto de diretivas de formatação, que são compostas
1424por um sinal de porcentagem (<CODE>%</CODE>) seguido por um caractere de
1425identificação.
1426</P>
1427<P>
1428Segue uma lista de algumas diretivas comuns. A lista completa pode ser
1429encontrada em <A HREF="http://www.python.org/doc/current/lib/module-time.html">http://www.python.org/doc/current/lib/module-time.html</A>.
1430</P>
1431
1432<TABLE ALIGN="center" BORDER="1" CELLPADDING="4">
1433<TR>
1434<TH>Diretiva</TH>
1435<TH>Descrição</TH>
1436</TR>
1437<TR>
1438<TD ALIGN="center">%a</TD>
1439<TD>Dia da semana local abreviado.</TD>
1440</TR>
1441<TR>
1442<TD ALIGN="center">%A</TD>
1443<TD>Dia da semana completo.</TD>
1444</TR>
1445<TR>
1446<TD ALIGN="center">%b</TD>
1447<TD>Nome do mês abreviado.</TD>
1448</TR>
1449<TR>
1450<TD ALIGN="center">%B</TD>
1451<TD>Nome do mês.</TD>
1452</TR>
1453<TR>
1454<TD ALIGN="center">%c</TD>
1455<TD>Dia e hora formatados apropriadamente.</TD>
1456</TR>
1457<TR>
1458<TD ALIGN="center">%d</TD>
1459<TD>Dia do mês como um número decimal [01,31].</TD>
1460</TR>
1461<TR>
1462<TD ALIGN="center">%H</TD>
1463<TD>Hora (24 horas) como um número decimal [00,23].</TD>
1464</TR>
1465<TR>
1466<TD ALIGN="center">%I</TD>
1467<TD>Hora (12 horas) como um número decimal [01,12].</TD>
1468</TR>
1469<TR>
1470<TD ALIGN="center">%m</TD>
1471<TD>O mês como um número decimal [01,12].</TD>
1472</TR>
1473<TR>
1474<TD ALIGN="center">%M</TD>
1475<TD>O minuto como um número decimal [00,59].</TD>
1476</TR>
1477<TR>
1478<TD ALIGN="center">%p</TD>
1479<TD>O equivalente local a AM e PM.</TD>
1480</TR>
1481<TR>
1482<TD ALIGN="center">%S</TD>
1483<TD>Os segundos como um número decimal [00,61].  (1)</TD>
1484</TR>
1485<TR>
1486<TD ALIGN="center">%x</TD>
1487<TD>Representação local da data.</TD>
1488</TR>
1489<TR>
1490<TD ALIGN="center">%X</TD>
1491<TD>Representação local da hora.</TD>
1492</TR>
1493<TR>
1494<TD ALIGN="center">%y</TD>
1495<TD>O ano sem o século como um número decimal [00,99].</TD>
1496</TR>
1497<TR>
1498<TD ALIGN="center">%Y</TD>
1499<TD>O ano com o século como um número decimal.</TD>
1500</TR>
1501<TR>
1502<TD ALIGN="center">%%</TD>
1503<TD>Um caractere "%".</TD>
1504</TR>
1505</TABLE>
1506
1507<H4>Exemplos</H4>
1508
1509<TABLE ALIGN="center" BORDER="1" CELLPADDING="4">
1510<TR>
1511<TH><CODE>%%date(format)</CODE></TH>
1512<TH>Resultado para: 2004, Jul13, 18:49</TH>
1513</TR>
1514<TR>
1515<TD>Last Update: %c</TD>
1516<TD>Last Update: Tue Jan 13 18:49:32 2004</TD>
1517</TR>
1518<TR>
1519<TD>%Y-%m-%d</TD>
1520<TD>2004-07-13</TD>
1521</TR>
1522<TR>
1523<TD>%I:%M %p</TD>
1524<TD>18:49 PM</TD>
1525</TR>
1526<TR>
1527<TD>Hoje e %A, em %B.</TD>
1528<TD>Hoje e Tuesday, em July.</TD>
1529</TR>
1530</TABLE>
1531
1532<HR NOSHADE SIZE=1>
1533
1534<H2 ID="include">O comando %!include</H2>
1535
1536<P>
1537A partir da versão 1.7, é possível usar o comando <CODE>include</CODE> para
1538inserir o conteúdo de um arquivo externo dentro do corpo do documento
1539original.
1540</P>
1541<P>
1542O <CODE>%!include</CODE> não é uma configuração, mas um comando, sendo somente
1543válido na área de CORPO do texto.
1544</P>
1545<P>
1546O comando <CODE>include</CODE> é útil para dividir um documento grande em vários
1547arquivos menores (como capítulos de um livro) ou para incluir todo o
1548conteúdo de um arquivo qualquer no documento. Por exemplo:
1549</P>
1550
1551<PRE>
1552  Meu Primeiro Livro
1553  Dr. Fulano da Silva
1554  1ª Edição
1555  
1556  %!include: introducao.t2t
1557  %!include: capitulo1.t2t
1558  %!include: capitulo2.t2t
1559  ...
1560  %!include: capitulo9.t2t
1561  %!include: conclusao.t2t
1562</PRE>
1563
1564<P>
1565Como se pode ver, basta informar o nome do arquivo logo após o comando
1566<CODE>%!include</CODE>. Também é possível atrelar o comando a um destino
1567específico, como em:
1568</P>
1569
1570<PRE>
1571  %!include(html): arquivo.t2t
1572</PRE>
1573
1574<P>
1575Note que o <CODE>include</CODE> vai inserir o CORPO do documento .t2t, ignorando
1576seu CABEÇALHO e suas CONFIGURAÇÕES. Assim é possível converter o arquivo
1577incluído de maneira isolada ou como parte do documento mãe.
1578</P>
1579<P>
1580Além de incluir arquivos .t2t, há mais três tipos de inclusão:
1581</P>
1582
1583<UL>
1584<LI>Inclusão de texto pré-formatado (Verbatim)
1585<LI>Inclusão de texto protegido (Raw)
1586<LI>Inclusão de texto já convertido (Tagged)
1587</UL>
1588
1589<P>
1590No tipo <B>Verbatim</B> o texto é incluído preservado seus espaços e
1591formatação originais. É como se esse texto estivesse entre as marcações
1592(```) da área VERB do txt2tags. Para incluir um arquivo dessa maneira,
1593basta colocar seu nome entre crases:
1594</P>
1595
1596<PRE>
1597  %!include: ``/etc/fstab``
1598</PRE>
1599
1600<P>
1601No tipo <B>Raw</B> o texto é incluído "como está", sem tentar encontrar e
1602avaliar as marcas do txt2tags dele. É como se esse texto estivesse entre
1603as marcações (""") da área protegida. Para incluir um arquivo dessa
1604maneira, basta colocar seu nome entre aspas
1605</P>
1606
1607<PRE>
1608  %!include: ""bom_texto.txt""
1609</PRE>
1610
1611<P>
1612Já no tipo <B>Tagged</B>, o texto é passado diretamente para o documento
1613resultante, sem NENHUM tratamento pelo txt2tags. Assim é possível
1614incluir tags adicionais, trechos já prontos ou estruturas mais
1615complicadas que não são suportadas pelo programa. Outra aplicação é
1616incluir um cabeçalho ou rodapé padrão em todos os documentos:
1617</P>
1618
1619<PRE>
1620  %!include(html): ''rodape.html''
1621</PRE>
1622
1623<P>
1624Note que o nome do arquivo está entre aspas simples (e não crases como o
1625anterior). São estas aspas que indicam que o conteúdo deve ser passado
1626diretamente. Como este conteúdo já contém tags, é primordial especificar
1627o destino também, para evitar problemas.
1628</P>
1629
1630<HR NOSHADE SIZE=5>
1631
1632<H1 ID="settings">Parte V - Dominando as Diretivas de Configuração</H1>
1633
1634<P>
1635As Diretivas de Configuração são todas opcionais. A maioria dos usuários
1636pode muito bem passar sem elas. Mas elas são viciantes, se você começa a
1637usá-las, não consegue parar :)
1638</P>
1639
1640<HR NOSHADE SIZE=1>
1641
1642<H2 ID="toc23">%!Target</H2>
1643
1644<P>
1645Usando a configuração Target define o destino padrão definido no
1646documento:
1647</P>
1648
1649<PRE>
1650  %!target: html
1651</PRE>
1652
1653<P>
1654Assim o usuário pode simplesmente comandar
1655</P>
1656
1657<PRE>
1658  $ txt2tags file.t2t
1659</PRE>
1660
1661<P>
1662E a conversão será efetuada para o destino especificado.
1663</P>
1664<P>
1665A configuração Target não permite a especificação opcional de destino.
1666Afinal, não faz sentido algo como <CODE>%!target(tex): html</CODE>.
1667</P>
1668
1669<HR NOSHADE SIZE=1>
1670
1671<H2 ID="toc24">%!Options</H2>
1672
1673<P>
1674Escrever longas lin…
Large files files are truncated, but you can click here to view the full file