PageRenderTime 26ms CodeModel.GetById 9ms app.highlight 5ms RepoModel.GetById 1ms app.codeStats 1ms

/doc/Portuguese/userguide-pt.t2t

http://txt2tags.googlecode.com/
Unknown | 1736 lines | 1235 code | 501 blank | 0 comment | 0 complexity | ff6cc7b6181103b19ee14898de320836 MD5 | raw file

Large files files are truncated, but you can click here to view the full file

   1Guia do Usuário Txt2tags
   2Aurelio, %%date(%c)
   3Tradução para o português: César A. K. Grossman
   4
   5%!target: html
   6%!encoding: UTF-8
   7%!options: --toc --toc-level 2
   8
   9%!preproc: IMGPATH ../userguide
  10
  11%!postproc(html): '(<LI>.*include </A>)$'          '\1 <b>[NOVO!]</b>'
  12%!postproc(html): '(<LI>.*%!Target</A>)$'          '\1 <b>[NOVO!]</b>'
  13%!postproc(html): '(<LI>.*%!Options</A>)$'         '\1 <b>[NOVO!]</b>'
  14%!postproc(html): '(<LI>.*linha de comando</A>)$'  '\1 <b>[NOVO!]</b>'
  15%!postproc(html): '(<LI>.*Editores de Texto</A>)$' '\1 <b>[NOVO!]</b>'
  16
  17%%% Embedded CSS code
  18%
  19%!postproc(html): ^<HEAD>$ '<HEAD>\n<STYLE TYPE="text/css">\n@#@'
  20%!postproc(html): (@#@)$ 'body {background-color:#ddeeff; color:black;   \n\1'
  21%!postproc(html): (@#@)$ '      margin:2em; text-align:justify;}         \n\1'
  22%!postproc(html): (@#@)$ 'a {text-decoration:none;}\na:hover {color:red;}\n\1'
  23%!postproc(html): (@#@)$ 'a:visited {color:purple;}\ndl {margin:1em;}    \n\1'
  24%!postproc(html): (@#@)$ 'h1 {text-align:center; background-color:blue;  \n\1'
  25%!postproc(html): (@#@)$ '    color:white; padding:8px;}                 \n\1'
  26%!postproc(html): (@#@)$ 'h2 {padding-top:20px;}\nhr {border-style:none;}\n\1'
  27%!postproc(html): (@#@)$ 'code {background-color:lightblue;}             \n\1'
  28%!postproc(html): (@#@)$ 'table {border-style:solid; border-color:black;}\n\1'
  29%!postproc(html): (@#@)$ 'th {background-color:lightblue; padding:1em;}  \n\1'
  30%!postproc(html): (@#@)$ 'td {border-style:none; background-color:white;}\n\1'
  31%!postproc(html): (@#@)$ 'pre {border-style:solid; border-width:1px 1px; \n\1'
  32%!postproc(html): (@#@)$ '     background-color:lightblue; padding:8px;  \n\1'
  33%!postproc(html): (@#@)$ '     border-color:black;}                      \n\1'
  34%!postproc(html):  @#@$  </STYLE>
  35
  36% 23/08/2003 grossman: traduzido para o português
  37% 13/07/2004 jic     : revisado e atualizado por jic conforme V2.0 beta 4
  38% 22/07/2004 aurelio : revisado para a v2.0
  39
  40
  41= Sobre este documento =
  42
  43	Olá, eu sou o guia do usuário do txt2tags!
  44	
  45	Aqui você encontra toda a informação disponível sobre a
  46	ferramenta de conversão de textos txt2tags.
  47	
  48	Minha versão atualizada pode ser encontrada em
  49	http://txt2tags.org/userguide/
  50	
  51	Para mais informações e versões recentes, visite
  52	[o website do txt2tags http://txt2tags.org/].
  53	
  54	Bom proveito!
  55
  56========================================================================
  57
  58
  59
  60= Parte I - Introdução ao Txt2tags =
  61
  62== Suas Primeiras Questões ==
  63
  64Este capítulo apresenta o txt2tags, introduzindo as funcionalidades e
  65objetivo do programa.
  66
  67------------------------------------------------------------------------
  68
  69
  70=== O Que É? ===
  71
  72O txt2tags é uma ferramenta de formatação e conversão de texto.
  73
  74O txt2tags converte um arquivo texto com algumas marcas para qualquer um
  75dos tipos de arquivos suportados:
  76
  77- Documento HTML
  78- Documento XHTML
  79- Documento SGML
  80- Documento LaTeX
  81- Página man UNIX
  82- Apresentação Magic Point
  83- Página MoinMoin
  84- Documento PageMaker 6.0
  85- Texto Plano (sem marcações)
  86
  87
  88------------------------------------------------------------------------
  89
  90
  91=== Por Quê Eu Devo Usá-lo? ===
  92
  93Você achará o txt2tags bastante útil se você:
  94- precisa publicar documentos em diferentes formatos
  95- precisa manter documentos atualizados em diferentes formatos
  96- escreve manuais ou documentos técnicos
  97- não sabe como escrever um documento em um formato específico
  98- não tem um editor específico para um certo formato.
  99- quer usar um editor de texto simples para atualizar seus documentos
 100
 101
 102E a motivação principal é:
 103- economizar tempo, escrevendo **conteúdo**, sem se preocupar com
 104  **formatação**
 105
 106
 107------------------------------------------------------------------------
 108
 109
 110=== Quais vantagens oferece em relação a outras ferramentas? ===
 111
 112O txt2tags possui uma forma bem direta de crescimento, seguindo alguns
 113conceitos básicos. Os conceitos a seguir se destacam:
 114
 115| //Arquivo fonte legível//       | As marcações do txt2tags são bastante simples, quase naturais.
 116| //Documento destino legível//   | Da mesma forma que o arquivo fonte, o código do documento gerado também é legível, alinhado e possui linhas curtas.
 117| //Consistência na Marcação// 	  | As marcações txt2tags são únicas, atendendo todos os tipos de documentos e não sendo confundidas com o conteúdo.
 118| //Regras Consistentes//         | Da mesma forma que as marcas, as regras aplicadas a elas são uniformes, não há "exceções" ou "casos especiais".
 119| //Estruturas Simples//          | Toda a formatação suportada é **simples**, sem opções extras ou modificadores complexos de comportamento. Uma marcação é só uma marcação, sem opções adicionais.
 120| //Fácil de aprender//           | Com marcações simples e o código fonte legível, a curva de aprendizado é bem amigável.
 121| //Bons Exemplos//               | Os **arquivos de exemplo** incluídos com o pacote dão mostras reais de documentos simples e super-estruturados, escritos no formato txt2tags.
 122| //Ferramentas Valiosas//        | Os **arquivos de sintaxe** incluídos com o pacote (para os editores vim, emacs, nano e kate) ajudam a escrever documentos sem erros sintáticos.
 123| //Três interfaces ao usuários// | Há uma **interface Gráfica Tk** que é bastante amigável, uma **inteface Web** para usar remotamente ou na intranet, e uma **interface de Linha de Comando**, para usuários avançados e scripts.
 124| //Suporte a Scripts//           | Com o modo completo de linha de comando, um usuário experiente pode **automatizar** tarefas e efetuar **pós-edições** nos arquivos convertidos.
 125| //Baixe e Execute / Multiplataforma// | O txt2tags é apenas um **script Python**. 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.
 126| //Atualizações Freqüentes//     | 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.
 127
 128
 129------------------------------------------------------------------------
 130
 131
 132=== Tenho que pagar por ele? ===
 133
 134  ||  Absolutamente NÃO!  |
 135
 136O txt2tags é um programa gratuito, GPL, open source, domínio público,
 137etc...
 138
 139Você pode copiar, usar, modificar, vender, liberar como seu. As
 140políticas de software e copyright não são uma das maiores preocupações
 141do autor.
 142
 143
 144------------------------------------------------------------------------
 145
 146
 147== Estruturas de Formatação Suportadas ==
 148
 149Segue uma lista de todas as estruturas suportadas pelo txt2tags.
 150
 151- cabeçalho (título, nome do autor, data)
 152- títulos de seções (numeradas ou não)
 153- parágrafos
 154- modificadores de fontes
 155  - negrito
 156  - itálico
 157  - sublinhado
 158- fonte monoespaço (verbatim)
 159  - monoespaço no meio de um parágrafo
 160  - linha monoespaçada
 161  - trecho em monoespaçado
 162- citações
 163- links
 164  - Links de Internet (URL)
 165  - links de email
 166  - links locais
 167  - links nomeados
 168- listas
 169  - listas com marcadores
 170  - listas numeradas
 171  - listas de definição
 172- linha horizontal de separação
 173- imagems (com alinhamento inteligente)
 174- tabela (com ou sem borda, com alinhamento inteligente)
 175- marcação especial para texto que não deve ser formatado
 176- macro especial para a data atual (com formatação flexível)
 177- comentários (para notas, A FAZER, CORREÇÕES, etc.)
 178
 179
 180------------------------------------------------------------------------
 181
 182
 183== Formatos Suportados ==
 184
 185: **HTML**                                                                
 186Todo mundo sabe o que o HTML é (dica: Internet).
 187
 188O txt2tags gera documentos HTML limpos, que tem boa apresentação e cujo
 189código fonte é legível. Ele NÃO USA javascript, frames ou outras
 190técnicas de formatação fúteis, que não são necessárias para documentos
 191técnicos simples. Mas um arquivo CSS separado pode ser utilizado, se for
 192desejado. O Txt2tags gera código "//HTML 4.0 Transitional//".
 193
 194Desde a versão 2.0, o código HTML gerado pelo txt2tags é 100% aprovado
 195pelo [validador w3c vhttp://validator.w3.org/].
 196
 197
 198: **XHTML**
 199Esta é a nova generação do HTML, com regras mais restritas, como fechar
 200todas as marcas que forem abertas. Isto torna o código mas fácil de ser
 201avaliado e entendido. Para propósitos gerais, considere como HTML. O
 202txt2tags gera código "//HTML 4.0 Transitional//".
 203
 204Desde a versão 2.0, o código XHTML gerado pelo txt2tags é 100% aprovado
 205pelo [validador w3c vhttp://validator.w3.org/].
 206
 207: **SGML**
 208O SGML é um formato de documento comum que possui aplicações de
 209conversão, como [sgmltools http://www.sgmltools.org/]. De um arquivo
 210sgml pode-se gerar documentos html, pdf, ps, info, latex, lyx, rtf e
 211xml. As ferramentas sgml2* também criam índices (TOC) e quebra de seções
 212em subpáginas (sgml2html).
 213
 214O txt2tags gera arquivos SGML válidos para a DTD linuxdoc, prontos para
 215serem convertidos com uma ferramenta sgml2* sem qualquer arquivo de
 216catálogo extra ou outras exigências incômodas do SGML.
 217
 218: **LATEX**
 219O formato de documentação preferido nos meios acadêmicos, é mais potente
 220do que normalmente se considera. Livros completos, fórmulas complicadas
 221e qualquer texto complexo pode ser escrito em LaTeX. Mas se prepare para
 222perder os cabelos se tentar escever as marcações à mão...
 223
 224O txt2tags gera arquivos LaTeX prontos para usar, realizando todos os
 225complexos truques de escape e exceções. O escritor deve se preocupar
 226exclusivamente com o texto.
 227
 228: **MAN**
 229As páginas man do UNIX resistiram pelos anos. Formatos de documento vem
 230e vão, e elas estão aí, imbatíveis.
 231
 232Existem outras ferramentas para gerar documentos man, mas o txt2tags tem
 233uma vantagem: uma fonte, múltiplos formatos destino. Assim, o conteúdo
 234da mesma página man pode ser convertido para uma página HTML, uma
 235apresentação Magic Point, etc.
 236
 237: **MGP**
 238O [Magic Point http://www.mew.org/mgp/] é uma ferramenta de apresentação
 239bastante útil (dica: Microsoft PowerPoint), que usa uma linguagem de
 240marcação para definir todas as telas. Desta forma, você pode criar
 241apresentações complexas no vi/emacs/notepad.
 242
 243O txt2tags gera um arquivo .mgp pronto para ser usado, definindo todos
 244os cabeçalhos necessários para as definições de fontes e aparência, bem
 245como o suporte aos caracteres acentuados da página de código ISO-8859.
 246
 247**Observação 1:** os arquivos .mgp criados pelo txt2tags usam as fontes
 248Type1 do XFree86! Desta forma, não é necessário incluir fontes TrueType
 249com sua apresentação.
 250
 251**Observação 2:** as definições de cor para as fontes são limpas, de
 252forma que mesmo com uma paleta de cores de sistema pobre (como em
 253``startx -- -bpp 8``) a apresentação vai ter boa aparência.
 254
 255A chave é: converta e use. Não há necessidade de remendos ou de outros
 256requisitos.
 257
 258: **MOIN**
 259Você não sabe o que é o [MoinMoin http://moin.sourceforge.net]? Ele é
 260um [WikiWiki http://www.c2.com/cgi/wiki]!
 261
 262A sintaxe do Moin é um pouco chata, quando você tem que ficar
 263``{{{'''''acrescentando chaves e plicas'''''}}}``, mas o txt2tags vem
 264com as marcações simplificadas e uma solução unificada: uma fonte,
 265múltiplos formatos destino.
 266
 267: **PM6**
 268Aposto que você não sabia, mas o Adobe PageMaker 6.0 tem sua própria
 269linguagem de marcação! Estilos, tabelas de cores, embelezadores, e a
 270maior parte das funcionalidades acessíveis via cliques de mouse também
 271estão disponíveis em sua linguagem de marcação. Você só precisa acessar
 272o item de menu "Import tagged text". Apenas para registro, é um formato
 273de marcação semelhante ao HTML.
 274
 275O txt2tags gera todas as tags e já define um cabeçalho extenso e
 276funcional, configurando os estilos de parágrafo e formatações. Esta é a
 277parte difícil. **EPA:** Sem quebras de linha! Um parágrafo deve ser uma
 278única linha.
 279
 280Nota do Autor:
 281//Todo meu livro em português sobre [expressões regulares http://guia-er.sf.net/]//
 282//foi escrito no vi, convertido para o formato do PageMaker com o//
 283//txt2tags e então mandado para o prelo.//
 284
 285: **TXT**
 286TXT é texto. O único tipo de formatação verdadeiro.
 287
 288Apesar das marcações do txt2tags serem bem intuitivas e discretas,
 289pode-se removê-las ao converter o arquivo para TXT puro.
 290
 291Os títulos são sublinhados, e o texto é basicamente deixado como está no
 292código fonte.
 293
 294
 295------------------------------------------------------------------------
 296
 297
 298== Situação dos Formatos-Destino para as Estruturas Suportadas ==[estruturas]
 299
 300  || Estrutura          | html | xhtml | sgml | tex | man | mgp | moin | pm6 | txt |
 301  | cabeçalhos          |  S   |   S   |  S   |  S  |  S  |  S  |  N   |  N  |  S  |
 302  | título de seções    |  S   |   S   |  S   |  S  |  S  |  S  |  S   |  S  |  S  |
 303  | parágrafos          |  S   |   S   |  S   |  S  |  S  |  S  |  S   |  S  |  S  |
 304  | negrito             |  S   |   S   |  S   |  S  |  S  |  S  |  S   |  S  |  -  |
 305  | itálico             |  S   |   S   |  S   |  S  |  S  |  S  |  S   |  S  |  -  |
 306  | sublinhado          |  S   |   S   |  -   |  S  |  -  |  S  |  S   |  S  |  -  |
 307  | pré-formatado       |  S   |   S   |  S   |  S  |  -  |  S  |  S   |  S  |  -  |
 308  | linha pré-formatada |  S   |   S   |  S   |  S  |  S  |  S  |  S   |  S  |  -  |
 309  | área pré-formatada  |  S   |   S   |  S   |  S  |  S  |  S  |  S   |  S  |  -  |
 310  | área cotada         |  S   |   S   |  S   |  S  |  S  |  S  |  S   |  S  |  S  |
 311  | links internet      |  S   |   S   |  S   |  -  |  -  |  -  |  S   |  -  |  -  |
 312  | links e-mail        |  S   |   S   |  S   |  -  |  -  |  -  |  S   |  -  |  -  |
 313  | links locais        |  S   |   S   |  S   |  N  |  -  |  -  |  S   |  -  |  -  |
 314  | links nomeados      |  S   |   S   |  S   |  -  |  -  |  -  |  S   |  -  |  -  |
 315  | lista não-numerada  |  S   |   S   |  S   |  S  |  S  |  S  |  S   |  S  |  S  |
 316  | lista numerada      |  S   |   S   |  S   |  S  |  S  |  S  |  S   |  S  |  S  |
 317  | lista de definições |  S   |   S   |  S   |  S  |  S  |  N  |  N   |  N  |  S  |
 318  | linha horizontal    |  S   |   S   |  -   |  S  |  -  |  S  |  S   |  N  |  S  |
 319  | imagem              |  S   |   S   |  S   |  S  |  -  |  S  |  S   |  N  |  -  |
 320  | tabela              |  S   |   S   |  S   |  S  |  S  |  N  |  S   |  N  |  N  |
 321  || Extras             | html | xhtml | sgml | tex | man | mgp | moin | pm6 | txt |
 322  | image align         |  S   |   S   |  N   |  N  |  -  |  S  |  N   |  N  |  -  |
 323  | table cell align    |  S   |   S   |  S   |  S  |  S  |  N  |  S   |  N  |  N  |
 324
 325  ||      | Legenda
 326  | **S** | //suportada//
 327  | **N** | //não suportada (talvez em uma versão futura)//
 328  | **-** | //não suportada (não pode ser feita neste formato)//
 329% | **?** | //não suportada (não estou bem certo se pode ou não ser feito)//
 330
 331
 332------------------------------------------------------------------------
 333
 334
 335== As Três Interfaces ao Usuário: GUI, Web e Linha de Comando ==
 336
 337Assim como diferentes usuários possuem diferentes necessidades e
 338ambientes, o txt2tags é bastante flexivel na forma de ser usado.
 339
 340Existem três Interfaces de Usuário para o programa, cada uma atendendo a
 341um objetivo definido e com funcionalidades próprias.
 342
 343- **GUI**: Escrita em Tk, traz as janelas e os cliques para o txt2tags.
 344- **Web**: Escrita em PHP, permite que o usuário execute o txt2tags no
 345           navegador, não exigindo instalação do lado do cliente.
 346- **Linha de Comando**: Escrita em Python, é o núcleo do programa.
 347           Todas as funcionalidades estão disponíveis como opções de
 348           linha de comando.
 349
 350
 351------------------------------------------------------------------------
 352
 353
 354=== Interface Gráfica Tk ===[gui]
 355
 356Desde a versão 1.0, há uma bela Interface Gráfica, que funciona do
 357Linux, Windows, Mac e outros.
 358
 359O programa automaticamente detecta se seu sistema pode apresentar a
 360interface e a lança quando é chamado sem argumentos. Pode-se forçar a
 361apresentação da Interfaca Gráfica com a opção ``--gui``. Se estiver
 362faltando algum recurso o programa irá alertar.
 363
 364	**Nota:** O módulo Tkinter é necessário. Como ele vem com a
 365	distribição padrão do Python você já deve tê-lo.
 366
 367Ela é bastante simples e fácil de usar:
 368
 369          [IMGPATH/gui.png]          
 370
 371+ Você localiza o arquivo fonte .t2t no disco e suas opções são
 372  carregadas.
 373
 374+ Se o destino ainda estiver vazio, você deve escolher um.
 375
 376+ Há algumas opões que podem ser escolhidas, mas nenhuma delas é
 377  essencial.
 378
 379+ Finalmente, pressione o botão "Converter!".
 380
 381
 382Uma boa opção a selecionar é "//Dump to screen//", assim se pode
 383verificar o código resultante em uma janela separada, sem que o arquivo
 384seja salvo. Quando o código estiver correto, basta desmarcá-la e o
 385arquivo será gravado.
 386
 387As cores padrão podem ser mudadas no arquivo ``~/.txt2tagsrc``,
 388configurando em ``%!guicolors``. Por exemplo:
 389
 390
 391``` 
 392 % minhas cores para a interface (fundo1, texto1, fundo2, texto2)
 393 %!guicolors: blue white brown yellow
 394```
 395
 396------------------------------------------------------------------------
 397
 398=== Interface Web ===[web]
 399
 400A Interface Web está em funcionamento na Internet no endereço
 401http://txt2tags.org/online.php, permitindo que o programa possa ser
 402usado e testado antes de ser copiado.
 403
 404          [IMGPATH/web.png]          
 405
 406Esta interface também pode ser colocada na intrant para uso local,
 407evitando a instalação do txt2tags em todas as máquinas.
 408
 409------------------------------------------------------------------------
 410
 411=== Interface de Linha de Comando ===[linhadecomando]
 412
 413Para usuários de linha de comando acostumados, o parâmetro --help deve
 414ser suficiente:
 415
 416```
 417Uso: txt2tags [OPÇÕES] [arquivo.t2t ...]
 418
 419  -t, --target        define o formato do destino. tipos suportados:
 420                      html, xhtml, sgml, tex, man, mgp, moin, pm6, txt
 421  -i, --infile=ARQ    define ARQ como o arquivo fonte ('-' para STDIN)
 422  -0, --outfile=ARQ   define ARQ como o arquivo destino ('-' para STDOUT)
 423  -n, --enum-title    numera todos os títulos como 1, 1.1, 1.1.1, etc
 424  -H, --no-headers    suprime os cabeçalhos, título e rodapé
 425      --headers       exibe os cabeçalhos, título e rodapé (padrão LIGADO)
 426      --encoding      informa a codificação de destino (utf-8, iso-8859-1, etc)
 427      --style=ARQ     utiliza ARQ como estilo do documento (CSS no Html)
 428      --css-sugar     insere tags compatíveis com CSS em destinos HTML e XHTML
 429      --mask-email    esconde e-mails dos robôs de SPAM. x@y.z vira <x (a) y z>
 430      --toc           inclui o Índice (Table of Contents) no documento destino
 431      --toc-only      exibe o Índice do documento e sai
 432      --toc-level=N   define o nível máximo do Índice para N
 433      --rc            lê a config do usuário em ~/.txt2tagsrc (padrão LIGADO)
 434      --gui           carrega a interface gráfica escrita em TK
 435  -v, --verbose       exibe mensagens informativas durante a conversão
 436  -h, --help          exibe este texto de ajuda e sai
 437  -V, --version       exibe a versão do programa e sai
 438      --dump-config   exibe todas as configurações encontradas e sai
 439
 440Opções para DESLIGAR funcionalidades:
 441     --no-outfile, --no-infile, --no-style, --no-encoding, --no-headers
 442     --no-toc, --no-toc-only, --no-mask-email, --no-enum-title, --no-rc
 443     --no-css-sugar
 444
 445Exemplo:
 446     txt2tags -t html --toc meuarquivo.t2t
 447
 448Normalmente a saída convertida é gravada em 'arquivo.<tipo>'.
 449Utilize --outfile para forçar um nome para o arquivo de saída.
 450Se o arquivo de entrada é '-', lê de STDIN.
 451Se o arquivo de saída é '-', envia a saída para STDOUT.
 452```
 453
 454==== Exemplos ====
 455
 456Supondo que exista um arquivo de marcação chamado ``file.t2t``, vamos nos
 457divertir um pouco.
 458
 459| **Convertendo para HTML**            | ``$ txt2tags -t html file.t2t``
 460| **O mesmo, usando redirecionamento** | ``$ txt2tags -t html -o - file.t2t > file.html``
 461|  | .
 462| **Incluindo uma Tabela de Conteúdo** | ``$ txt2tags -t html --toc file.t2t``
 463| **Idem, numerando os títulos**       | ``$ txt2tags -t html --toc --enum-title file.t2t``
 464|  | .
 465| **Visualização Rápida do Conteúdo**  | ``$ txt2tags --toc-only file.t2t``
 466| **Quem sabe com números?**           | ``$ txt2tags --toc-only --enum-title file.t2t``
 467|  | .
 468| **Linha simples de STDIN**           | ``$ echo -e "\n**bold**" | txt2tags -t html --no-headers -``
 469| **Testando o Mascaramento de Email** | ``$ echo -e "\njohn.wayne@farwest.com" | txt2tags -t txt --mask-email --no-headers -``
 470| **Edição pós-conversão**             | ``$ txt2tags -t html -o- file.t2t | sed "s/<BODY .*/<BODY BGCOLOR=green>/" > file.html``
 471
 472: //Nota//
 473Desde a versão 1.6 você pode fazer pre e pós processamento usando as
 474macros de configuração ``%!preproc`` e ``%!postproc``.
 475
 476
 477========================================================================
 478
 479
 480
 481= Parte II - OK, eu quero um. E agora? =[instalacao]
 482
 483Basta baixar o programa e executar o mesmo no seu computador.
 484
 485== Download e Instalação do Python ==
 486
 487Antes de mais nada, deve-se baixar e instalar o interpretador Python
 488para o seu sistema. Se você já o tem, então pule eset passo.
 489
 490O Python é uma das melhores linguagens de programação que existem, ela
 491pode ser utilizada no Windows, Linux, UNIX, Macintosh, e outras
 492plataformas, e pode ser baixada do
 493[web site do Python http://www.python.org]. As dicas de instalação podem
 494ser encontradas no mesmo site. O txt2tags funciona com o Python 1.5 ou
 495posterior.
 496
 497Se você não tem certeza de ter o Python ou não, abra um console (tty,
 498xterm, MSDOS) e escreva ``python``. Se ele não estiver instalado, o
 499sistema vai lhe informar.
 500
 501== Copiando o txt2tags ==
 502
 503O local oficial de distribuição do txt2tags é na homepage do programa,
 504em http://txt2tags.org/src.
 505
 506Todos os arquivos do programa estão em um tarball (arquivo .tgz), que
 507pode ser expandido pela maioria dos utilitários de compressão (incluindo
 508o Winzip).
 509
 510Simplesmente pegue a **última** versão (data mais recente, número de
 511versão maior). As versões anteriores estão lá apenas por razões
 512históricas.
 513
 514== Instalação do txt2tags ==
 515
 516Como é apenas um script Python, o txt2tags não precisa ser instalado.
 517
 518O único arquivo necessário para usar o programa é o script txt2tags. Os
 519outros arquivos do tarball compreendem a documentação, ferramentas e
 520arquivos de exemplo.
 521
 522O modo mais seguro de usar o txt2tags é chamar o Python com ele:
 523
 524``` prompt$ python txt2tags 
 525
 526Se você quiser "instalar" o txt2tags no sistema como um programa
 527independente, basta copiar (ou criar um link) o script txt2tags para um
 528diretório que esteja no PATH do sistema e certificar-se que o sistema
 529saiba como executar o mesmo.
 530
 531: **UNIX/Linux**
 532  Torne o script executável (``chmod +x txt2tags``) e copie o mesmo para
 533  um diretório no $PATH (``cp txt2tags /usr/local/bin``)
 534
 535: **Windows**
 536  Renomeie o script, acrescentando a extensão .py
 537  (``ren txt2tags txt2tags.py``) e o copie para um diretório que esteja
 538  no PATH do sistema (``copy txt2tags.py C:\WINNT``)
 539
 540
 541Depois disto, pode-se criar um ícone no desktop para o programa, se
 542quiser usar a Interface Gráfica do programa.
 543
 544=== Pacotes Especiais para Usuários Windows ===
 545
 546Existem dois arquivos de distribuição .EXE para o txt2tags, que instalam
 547o programa em máquinas Windows com apenas alguns cliques:
 548
 549- O script txt2tags para aqueles que tem o interpretador Python
 550  instalado
 551- A versão stand-alone, que não requer a instalação do interpretador
 552  Pyton para ser executada (já tem uma versão pequena incluída).
 553
 554
 555Visite o site //Txt2tags-Win// para baixar estes pacotes:
 556http://txt2tags-win.sf.net/
 557
 558== Instalar os Arquivos de Sintaxe dos Editores de Texto ==[sintaxe]
 559
 560O txt2tags possui arquivos de sintaxe práticos que podem ser usados com
 561os seguintes editores de texto:
 562
 563- Vim (www.vim.org)
 564- Emacs (www.emacs.org)
 565- Nano (www.nano-editor.org)
 566- Kate (http://kate.kde.org)
 567
 568
 569Os arquivos de sintaxe têm registro de todas as regras e marcações do
 570txt2tags, ajudando ao usuário a escrever documentos sem erros. As marcas
 571são mostradas coloridas, assim se pode ver se tudo foi escrito
 572corretamente.
 573
 574           |  [IMGPATH/vim.png]  |
 575           |  O arquivo de exemplo aberto no Editor Vim 
 576
 577Cada editor tem um procedimento diferente para usar seu arquivo de
 578sintaxe. Por favor verifique no cabeçalho de cada arquivo e na
 579documentação do editor.
 580
 581========================================================================
 582
 583
 584
 585= Parte III - Escrevendo e Convertendo Seu Primeiro Documento =
 586
 587Desculpe, este capítulo ainda está em desenvolvimento.
 588
 589== As Áreas do documento .t2t ==
 590
 591Os arquivos de marcação txt2tags são divididos em 3 áreas. Cada área tem
 592suas próprias regras e finalidade. São elas:
 593
 594: //Área de Cabeçalho//
 595É o lugar para informações sobre o Título do Documento, Autor, Versão e
 596Data. (opcional)
 597
 598: //Área de Configuração//
 599É o local para colocar as configurações Gerais do documento e
 600modificadores do funcionamento do analisador. (opcional)
 601
 602: //Corpo do Texto//
 603É o local para o Conteúdo do Documento (requerida)
 604
 605
 606Como vemos acima, as duas primeiras áreas são opcionais, sendo que o
 607//Corpo do Texto// é a única área indispensável.
 608(//Nota: A **Área de Configuração** foi introduzida no txt2tags na versão 1.3//)
 609
 610As áreas são delimitadas por regras especiais, que serão vistas em
 611detalhe no próximo capítulo. Por enquanto, esta é uma representação
 612gráfica das áreas de um documento:
 613
 614```
 615             ____________
 616            |            |
 617            |  CABEÇALHO |       1. Primeiro, o cabeçalho
 618            |            |
 619            |   CONFIG   |       2. Então a configuração
 620            |            |
 621            |   CORPO    |       3. E, finalmente, o corpo do documento
 622            |            |
 623            |    ...     |          que segue até o final do arquivo.
 624            |    ...     |
 625            |____________|
 626
 627```
 628
 629Em resumo, é assim que as áreas são definidas:
 630
 631  | **Cabeçalhos**   | As primeiras 3 linhas do arquivo, ou a primeira linha é deixada em branco se não são usados cabeçalhos
 632  | **Configuração** | Começam logo depois do cabeçalho (4a. ou 2a. linha)  e termina quando a //Área de Conteúdo// começa.
 633  | **Corpo**        | A primeira linha de texto válida (que não é comentário ou configuração) após a //Área de Cabeçalho//.
 634
 635=== Exemplo Completo ===
 636
 637```
 638Título do meu belo documento
 639Sr. Fulano da Silva
 640Última atualização: %%date(%c)
 641
 642%! Target  : html
 643%! Style   : fancy.css
 644%! Encoding: UTF-8
 645%! Options : --toc --enum--title
 646
 647Oi! Este é o meu documento de teste.
 648E o seu conteúdo termina aqui.
 649```
 650
 651=======================================================================
 652
 653
 654
 655= Parte IV - Dominando o Txt2tags =
 656
 657
 658== A Área de Cabeçalho ==
 659
 660Localização:
 661- Posição fixa: **Primeiras 3 linhas** do arquivo. Ponto.
 662- Posição fixa: **A Primeira Linha** do arquivo está em branco. Isto
 663  significa que o cabeçalho está vazio.
 664
 665
 666A Área de Cabeçalho é a única que tem uma posição fixa, orientada a
 667linhas. Ela está localizada nas três primeiras linhas do código fonte.
 668
 669O conteúdo destas linhas é livre, sem necessidade de nenhuma informação
 670estática de nenhum tipo. Mas recomenda-se o seguinte para a maioria dos
 671documentos:
 672
 673   - //linha 1//: título do documento
 674   - //linha 2//: nome e/ou email do autor
 675   - //linha 3//: data e/ou versão do documento
 676                 (um bom lugar para colocar ``%%date``)
 677
 678
 679Tenha em mente que as 3 primeiras linhas do arquivo fonte serão as 3
 680primeiras linhas no documento gerado, separadas e com um grande
 681contraste em relação ao corpo do texto (ou seja, letras grandes,
 682negrito). Se a paginação for permitida, os cabeçalhos estarão separados
 683e centralizados na primeira página.
 684
 685==== Menos (ou Nenhuma) Linhas de Cabeçalho ====
 686
 687Às vezes os usuários querem especificar menos de três linhas nos
 688cabeçalhos, dando apenas o título do documento e/ou informação de data.
 689
 690Basta deixar a 2a. e/ou a 3a. linhas em branco e estas linhas não serão
 691incluídas no documento gerado. Mas tenha em mente que, mesmo em branco,
 692estas linhas ainda são parte dos cabeçalho, e o corpo do documento deve
 693começar **após** a 3a. linha.
 694
 695O título é o único cabeçalho requerido (a primeira linha), mas se você
 696deixar ela em branco, está dizendo que seu documento
 697**não tem cabeçalho**. Desta forma, a //Área de Texto// irá começar em
 698seguida, na 2a. linha.
 699
 700Não usar cabeçalhos no documento é útil se você quiser especificar seus
 701próprios cabeçalhos customizados após a conversão. A opção de linha de
 702comando ``--no-headers`` é geralmente necessária para este tipo de coisa.
 703
 704==== Direto ao ponto ====
 705
 706 || Em resumo: "Cabeçalhos são apenas __posições__, não conteúdo " |
 707
 708Coloque um texto na primeira linha, ele irá aparecer na primeira linha
 709do arquivo gerado. O mesmo para a 2a. e 3a. linhas de cabeçalho.
 710
 711------------------------------------------------------------------------
 712
 713== A Área de Configuração ==
 714
 715Localização:
 716- Começa logo após a Área de Cabeçalhos
 717  - Começa na **4a. linha** do arquivo se forem especificados **Cabeçalhos**
 718  - Começa na **2a. linha** se **não** forem especificados **Cabeçalhos**
 719- Termina quando a Área de Conteúdo começa
 720  - Termina com uma linha que não seja de Configuração, ou de
 721    Comentário, ou que seja uma linha em Branco.
 722
 723
 724A Área de Configuração é opcional. A maioria dos usuários pode escrever
 725carradas de arquivos txt2tags mesmo sem saber que ela existe, mas os
 726usuários experientes irão gostar do poder e controle que ela oferece.
 727
 728O uso primário desta área é para definir configurações que afetam o
 729comportamento do programa.
 730
 731==== Então, como configurar algo? Qual a sintaxe? ====
 732
 733As linhas de configuração são //linhas de comentário especiais//,
 734marcadas com um identificador no início ("``!``") que torna estes
 735comentários diferentes dos comentários normais. A sintaxe é tão simples
 736quanto uma atribuição de valor a uma variável, composta por uma
 737palavra-chave e um valor, separados um do outro pelo separador canônico
 738dois-pontos ("``:``").
 739
 740 || %! palavra-chave : valor |
 741
 742**``Detalhes da Sintaxe:``** O ponto de exclamação deve ser colocado
 743junto com o caractere de comentário, sem espaço entre eles ("``%!``").
 744Os espaços em torno da //palavra-chave// e o separador são opcionais, e
 745tanto a //palavra-chave// quanto o //valor// podem estar
 746indiferentemente em maiúsculas ou minúsculas.
 747
 748==== O que eu posso configurar? Quais são as palavra-chave válidas? ====
 749
 750As configurações que podem ser feitas são //Target//, //Options//, //Style//,
 751//Encoding//, //PreProc// e //PostProc//.
 752
 753A configuração **//Target//** define o destino padrão na qual o
 754documento deve ser convertido.
 755
 756A configuração **//Options//** é útil para especificar as opções de
 757linha de comando padrão para o arquivo fonte. Estas opções podem ser
 758sobrescritas pela linha de comando real. Usar esta opção juntamente com
 759``%!target`` permite converter o documento simplesmente comandando:
 760``txt2tags file.t2t``
 761
 762A configuração **//Style//** só é suportada pelo tipo de documento
 763destino HTML, para definir uma folha de estilo
 764(//Cascading Style Sheets - CSS//).
 765
 766A configuração **//Encoding//** é necessária para escritores não
 767ingleses, que usem letras acentuadas e outros detalhes específicos de
 768localização, de forma que o //Conjunto de Caracteres// do documento seja
 769personalizado (se permitido).
 770
 771A configuração **//PreProc//** é um filtro. Ela define regras do tipo
 772"busca e troca" que serão aplicadas ao arquivo original __antes__ que
 773qualquer análise por parte do txt2tags ocorra.
 774
 775A configuração **//PostProc//** é um filtro. Ela define regras do tipo
 776"busca e troca" que serão aplicadas ao arquivo destino __depois__ de
 777todo o processamento por parte do txt2tags.
 778
 779Exemplo:
 780
 781```
 782%! Target  : html
 783%! Options : --toc --toc-level 3
 784%! Style   : fancy.css
 785%! Encoding: UTF-8
 786%! PreProc : "amj"       "Aurelio Marinho Jargas"
 787%! PostProc: '<BODY.*?>' '<BODY bgcolor="yellow">'
 788```
 789
 790
 791==== Algumas regras sobre as Configurações ====
 792
 793 - As configurações são válidas somente dentro da Área de Configuração,
 794   e serão consideradas comentários simples se forem encontradas no
 795   Corpo do documento.
 796
 797 - Se a mesma palavra-chave aparece mais de uma vez na Área de
 798   Configuração, apenas a última será usada. Exceção: options, preproc e
 799   postproc, que são acumulativas.
 800
 801 - Uma linha de configuração com uma palavra-chave inválida será
 802   considerada um comentário.
 803
 804 - Estas configurações têm precedência sobre o arquivo ``txt2tagsrc``,
 805   as não sobre as opções de linha de comando.
 806
 807
 808----------------------------------------------------------------
 809
 810== O Corpo do Texto == 
 811
 812Localização:
 813- Começa na primeira linha válida de texto do arquivo
 814  - Cabeçalhos, Configurações e Comentários **não** são linhas de texto
 815    válidas
 816- Termina no fim do arquivo (EOF)
 817
 818
 819Bem, o corpo do texto é tudo que estiver fora das Áreas de Cabeçalho e
 820de Configuração.
 821
 822O corpo do texto é onde está o conteúdo do documento e todas as
 823estruturas e formatações que o txt2tags reconhece. Dentro do corpo podem
 824ser também colocados comentários para //A FAZER// e anotações
 825particulares.
 826
 827Pode-se utilizar a opção de linha de comando ``--no-headers`` para
 828converter somente o corpo do documento, suprimindo os cabeçalhos. Esta
 829opção é útil quando os cabeçalhos estão em um arquivo separado, que será
 830unido ao corpo depois da conversão.
 831
 832-----------------------------------------------------------------------
 833
 834== Marcações (REGRAS) ==[regras]
 835
 836Todas as marcações e sintaxe usadas pelo txt2tags estão detalhadas em
 837um [arquivo REGRAS a parte REGRAS].
 838
 839-----------------------------------------------------------------------
 840
 841== A macro %%date ==[data]
 842
 843A macro ``%%date`` chamada sem nenhum parâmetro adicional retorna a data
 844atual no formato ISO //yyyymmdd//. Uma formatação opcional pode ser
 845especificada usando a sintaxe ``%%date(formato)``.
 846
 847O //formato// contém texto de diretivas de formatação, que são compostas
 848por um sinal de porcentagem (``%``) seguido por um caractere de
 849identificação.
 850
 851Segue uma lista de algumas diretivas comuns. A lista completa pode ser
 852encontrada em http://www.python.org/doc/current/lib/module-time.html.
 853
 854 || Diretiva | Descrição |
 855  |  %a  | Dia da semana local abreviado.
 856  |  %A  | Dia da semana completo.
 857  |  %b  | Nome do mês abreviado.
 858  |  %B  | Nome do mês.
 859  |  %c  | Dia e hora formatados apropriadamente.
 860  |  %d  | Dia do mês como um número decimal [01,31].
 861  |  %H  | Hora (24 horas) como um número decimal [00,23].
 862  |  %I  | Hora (12 horas) como um número decimal [01,12].
 863  |  %m  | O mês como um número decimal [01,12].
 864  |  %M  | O minuto como um número decimal [00,59].
 865  |  %p  | O equivalente local a AM e PM.
 866  |  %S  | Os segundos como um número decimal [00,61].  (1)
 867  |  %x  | Representação local da data.
 868  |  %X  | Representação local da hora.
 869  |  %y  | O ano sem o século como um número decimal [00,99].
 870  |  %Y  | O ano com o século como um número decimal.
 871  |  %%  | Um caractere "%".
 872
 873
 874==== Exemplos ====
 875
 876 || ``%%date(format)``  | Resultado para: 2004, Jul13, 18:49 |
 877  | Last Update: %c     | Last Update: Tue Jan 13 18:49:32 2004
 878  | %Y-%m-%d            | 2004-07-13
 879  | %I:%M %p            | 18:49 PM
 880  | Hoje e %A, em %B.   | Hoje e Tuesday, em July.
 881
 882-----------------------------------------------------------------------
 883
 884== O comando %!include ==[include]
 885
 886A partir da versão 1.7, é possível usar o comando ``include`` para
 887inserir o conteúdo de um arquivo externo dentro do corpo do documento
 888original.
 889
 890O ``%!include`` não é uma configuração, mas um comando, sendo somente
 891válido na área de CORPO do texto.
 892
 893O comando ``include`` é útil para dividir um documento grande em vários
 894arquivos menores (como capítulos de um livro) ou para incluir todo o
 895conteúdo de um arquivo qualquer no documento. Por exemplo:
 896
 897```
 898Meu Primeiro Livro
 899Dr. Fulano da Silva
 9001ª Edição
 901
 902%!include: introducao.t2t
 903%!include: capitulo1.t2t
 904%!include: capitulo2.t2t
 905...
 906%!include: capitulo9.t2t
 907%!include: conclusao.t2t
 908```
 909
 910Como se pode ver, basta informar o nome do arquivo logo após o comando
 911``%!include``. Também é possível atrelar o comando a um destino
 912específico, como em:
 913
 914``` %!include(html): arquivo.t2t
 915
 916Note que o ``include`` vai inserir o CORPO do documento .t2t, ignorando
 917seu CABEÇALHO e suas CONFIGURAÇÕES. Assim é possível converter o arquivo
 918incluído de maneira isolada ou como parte do documento mãe.
 919
 920Além de incluir arquivos .t2t, há mais três tipos de inclusão:
 921
 922- Inclusão de texto pré-formatado (Verbatim)
 923- Inclusão de texto protegido (Raw)
 924- Inclusão de texto já convertido (Tagged)
 925
 926
 927No tipo **Verbatim** o texto é incluído preservado seus espaços e
 928formatação originais. É como se esse texto estivesse entre as marcações
 929(```) da área VERB do txt2tags. Para incluir um arquivo dessa maneira,
 930basta colocar seu nome entre crases:
 931
 932``` %!include: ``/etc/fstab``
 933
 934No tipo **Raw** o texto é incluído "como está", sem tentar encontrar e
 935avaliar as marcas do txt2tags dele. É como se esse texto estivesse entre
 936as marcações (""") da área protegida. Para incluir um arquivo dessa
 937maneira, basta colocar seu nome entre aspas
 938
 939``` %!include: ""bom_texto.txt""
 940
 941Já no tipo **Tagged**, o texto é passado diretamente para o documento
 942resultante, sem NENHUM tratamento pelo txt2tags. Assim é possível
 943incluir tags adicionais, trechos já prontos ou estruturas mais
 944complicadas que não são suportadas pelo programa. Outra aplicação é
 945incluir um cabeçalho ou rodapé padrão em todos os documentos:
 946
 947``` %!include(html): ''rodape.html''
 948
 949Note que o nome do arquivo está entre aspas simples (e não crases como o
 950anterior). São estas aspas que indicam que o conteúdo deve ser passado
 951diretamente. Como este conteúdo já contém tags, é primordial especificar
 952o destino também, para evitar problemas.
 953
 954=======================================================================
 955
 956
 957
 958= Parte V - Dominando as Diretivas de Configuração =[settings]
 959
 960As Diretivas de Configuração são todas opcionais. A maioria dos usuários
 961pode muito bem passar sem elas. Mas elas são viciantes, se você começa a
 962usá-las, não consegue parar :)
 963
 964-----------------------------------------------------------------------
 965
 966== %!Target ==
 967
 968Usando a configuração Target define o destino padrão definido no
 969documento:
 970
 971``` %!target: html
 972
 973Assim o usuário pode simplesmente comandar
 974
 975``` $ txt2tags file.t2t
 976
 977E a conversão será efetuada para o destino especificado.
 978
 979A configuração Target não permite a especificação opcional de destino.
 980Afinal, não faz sentido algo como ``%!target(tex): html``.
 981
 982
 983-----------------------------------------------------------------------
 984
 985== %!Options ==
 986
 987Escrever longas linhas de comando toda vez que for necessário converter
 988um documento é maçante e sujeito a erros. A configuração Options permite
 989que o usuário salve todas as opções de conversão juntas, no próprio
 990documento. Desta forma também se garante que o documento sempre será
 991convertido da mesma forma, com as mesmas opções.
 992
 993Só é necessário escrevê-la sem erros de sintaxe, como se estivesse na
 994linha de comando. Mas omita a chamada ao programa "txt2tags" no início e
 995o nome do arquivo origem no fim da linha.
 996
 997Por exemplo, se você usa esta linha de comando para converter seu
 998documento:
 999
1000``` $ txt2tags -t html --toc --toc-level 2 --enum-title file.t2t
1001
1002Pode-se economizar um bocado de digitação usando esta configuração de
1003Options dentro do documento origem:
1004
1005```
1006%!target: html
1007%!options(html): --toc --toc-level 2 --enum-title
1008```
1009
1010A linha de comando real passa agora a ser apenas "``txt2tags file.t2t``",
1011e a conversão pode ser executada dentro do seu editor de textos
1012favorito, enquanto o conteúdo está sendo editado. No Vi, o comando é:
1013
1014``` :!txt2tags %
1015
1016-----------------------------------------------------------------------
1017
1018== %!Encoding ==
1019
1020A configuração de Encoding é necessária para autores não ingleses, que
1021usam letras acentuadas e outros detalhes específicos, de forma que o
1022//Conjunto de Caracteres// do documento gerado possa ser personalizado
1023(se possível).
1024
1025Os valores válidos para a configuração de Encoding são os mesmos que são
1026válidos para documentos, HTML, como //UTF-8// e //koi8-r//. Se você
1027não está certo de qual codificação quer usar,
1028[esta lista completa (e longa!) http://www.iana.org/assignments/character-sets]
1029poderá ser de ajuda.
1030
1031Quando for gerado documentos LaTeX, utiliza aliases para a codificação.
1032Isto não deve ser problema para o usuário, já que o txt2tags faz a
1033tradução internamente. Alguns exemplos:
1034
1035      || txt2tags/HTML   |  >  | LaTeX  |
1036       | windows-1250    | >>> | cp1250 |
1037       | windows-1252    | >>> | cp1252 |
1038       | ibm850          | >>> | cp850  |
1039       | ibm852          | >>> | cp852  |
1040       | iso-8859-1      | >>> | latin1 |
1041       | iso-8859-2      | >>> | latin2 |
1042       | koi8-r          | >>> | koi8-r |
1043
1044Se o valor é desconhecido do txt2tags, ele será passado sem tradução,
1045permitindo que o usuário especifique codificações personalizadas.
1046
1047-----------------------------------------------------------------------
1048
1049== %!PreProc ==
1050
1051O filtro de usuário PreProc é uma função "busca e troca" que é aplicada
1052logo após a linha ter sido lida do arquivo original, antes de qualquer
1053tratamento pelo txt2tags.
1054
1055Ela é útil para definir algumas abreviações para texto que seja usado
1056comumente, como:
1057
1058```
1059%!preproc amj          "Aurelio Marinho Jargas"
1060%!preproc RELEASE_DATE "2004-07-13"
1061%!preproc BOLOTA       "[images/tiny/bullet_blue.png]"
1062```
1063
1064Desta forma, o usuário pode escrever uma linha como:
1065
1066``` Oi, eu sou amj. Hoje é RELEASE_DATE.
1067
1068E o txt2tags irá ver esta linha como:
1069
1070``` Oi, eu sou Aurelio Marinho Jargas. Hoje é 2004-07-13.
1071
1072Este filtro é um componente que trabalha entre o autor do documento e a
1073conversão do txt2tags. É como uma primeira conversão antes da conversão
1074"real". Este comportamento funciona exatamente como um filtro Sed/Perl
1075externo, chamado assim:
1076
1077``` $ cat arquivo.t2t | preproc-script.sh | txt2tags -
1078
1079Assim, o tratamento executado pelo txt2tags irá começar após todas as
1080substituições PreProc terem sido feitas.
1081
1082-----------------------------------------------------------------------
1083
1084== %!PostProc ==
1085
1086O filtro de usuário PostProc é uma função do tipo "busca e troca" que é
1087aplicada no arquivo resultante, após todos as conversões do txt2tags
1088terem sido feitas.
1089
1090É útil para defintir alguns refinamentos no documento gerado, mudar
1091algumas marcações e acrescentar algumas marcações ou texto extra.
1092Alguns exemplos breves:
1093
1094```
1095%!postproc(html): '<BODY.*?>' '<BODY BGCOLOR="green">'
1096%!postproc(tex) : "\\clearpage" ""
1097```
1098
1099Estes filtros mudam a cor de fundo da página HTML e removem as quebras
1100de página em arquivos LaTeX gerados.
1101
1102As regras do PostProc são iguais a filtros externos Sed/Perl, chamados
1103desta forma:
1104
1105``` $ txt2tags -t html -o- arquivo.t2t | postproc-script.sh > arquivo.html
1106
1107Antes desta funcionalidade ter sido introduzida, era bastante comum ter
1108pequenos scripts para "ajustar" os resultados gerados pelo txt2tags.
1109Estes scripts eram, de fato, vários comandos sed (ou assemelhados), para
1110fazer algo do tipo "substitua isto por aquilo". Agora estas trocas podem
1111ser salvas junto com o texto do documento, e também aproveitar-se da
1112poderosa máquina de Expressões Regulares do Python para encontrar os
1113padrões.
1114
1115-----------------------------------------------------------------------
1116
1117== %!Style ==
1118
1119- Esta opção é útil na geração de arquivos HTML e XHTML, definindo o
1120  nome do arquivo CSS que será usado no documento gerado.
1121
1122- No formato LaTeX, essa opção é usada para carregar módulos com o
1123  ``\usepackage``.
1124
1125- O mesmo efeito pode ser obtido com a opção de linha de comando
1126  ``--style``.
1127
1128- A opção de linha de comando --style tem precedência sobre a
1129  configuração de %!style
1130
1131
1132-----------------------------------------------------------------------
1133
1134== Detalhes dos Filtros PreProc e PostProc ==
1135
1136- Estes filtros foram acrescentados ao txt2tags na versão 1.6.
1137
1138- Filtros são uma função do tipo "buscar e trocar" (pense no sed)
1139
1140- O PREproc é aplicado logo após a linha ser lida, e o POSTproc é
1141  aplicado após todo o tratamento ter sido feito. Funcionam exatamente
1142  como em (UUOC à frente):
1143
1144``` $ cat file.t2t | preproc.sh | txt2tags | postproc.sh
1145
1146- Escapes especiais como ``\n`` e ``\t`` são interpretados
1147
1148- Os filtros são cumulativos e são aplicados na mesma ordem em que são
1149  definidos
1150
1151- Os filtros devem receber exatamente DOIS argumentos
1152
1153- Para apagar uma string, troque ela por uma string vazia
1154``` %!postproc: "undesired string" ""
1155
1156- Para evitar problemas, sempre use informar explicitamente para que
1157  destino se aplica o filtro quando estiver usando o PostProc para mudar
1158  marcações: ``%!PostProc(destino): <isto> <aquilo>``
1159
1160- As Expressões Regulares do Python podem ser utilizadas! Elas são
1161  similares às Regex do Perl. Por exemplo: troque todas as marcações "B"
1162  para "STRONG" no HTML:
1163
1164``` %!postproc(html):   '(</?)B>'   '\1STRONG>'
1165
1166- Os argumentos dos filtros podem ser passados de 3 formas:
1167   + Uma palavra simples, sem aspas ou plicas, como FOO (sem espaços)
1168   + Uma string com aspas duplas, como em "FOO"
1169   + Uma string com plicas ou apóstrofos, como em 'FOO'
1170
1171- Se seu padrão tem aspas, proteja as mesmas com plicas, e vice-versa.
1172  Alguns exemplos válidos:
1173```
1174%!postproc:   PADRÃO    TROCA
1175%!postproc:  "PADRÃO"  "TROCA"
1176%!postproc:  'PADRÃO'  'TROCA'
1177%!postproc:   PADRÃO   "TROCA"
1178%!postproc:  "PADRÃO"  'TROCA'
1179```
1180
1181
1182-----------------------------------------------------------------------
1183
1184== Definindo uma Configuração para um Tipo-Destino Específico ==
1185
1186Desde a versão 1.6 do txt2tags, todas as Diretivas de Configuração podem
1187ser especificadas para um destino específico, usando a sintaxe
1188``%!key(target): value``. Desta forma, o usuário pode definir diferentes
1189configurações para diverentes tipos de arquivos gerados.
1190
1191Este aspecto é especialmente útil nos filtros pre/postproc, mas pode ser
1192utilizado em todas as diretrizes. Por exemplo, configurar diferentes
1193valores de Encoding para HTML e LaTeX:
1194
1195```
1196%!encoding(html): UTF-8
1197%!encoding(tex): latin1
1198```
1199
1200	**Nota:** O mapeamento de codificações para os nomes especiais
1201	LaTeX já é parte do txt2tags, o trecho acima é apenas um
1202	exemplo.
1203
1204Para o ``%!options``, pode ser interessante:
1205
1206```
1207%!target: sgml
1208%!options(sgml): --toc
1209%!options(html): --style foo.css
1210%!options(txt ): --toc-only --toc-level 2
1211```
1212
1213Desta forma, o tipo de destino padrão é o SGML, com TOC. Se o usuário
1214executar:
1215
1216``` $ txt2tags -t html file.t2t
1217
1218O tipo de destino HTML será feito, e **somente** as opções de
1219``%!options(html)`` serão usadas. Desta forma, a opçõa --style será
1220usada e o arquivo HTML não terá TOC.
1221
1222=== A Precedência é Diferente ===
1223
1224Em geral, para as diretivas de configuração, a última encontrada é a
1225usada, mas quando usar diretivas explícitas de tipo-destino, elas tem
1226precedência sobre as genéricas, não importando qual vem antes. Assim:
1227
1228```
1229%!encoding(html): UTF-8
1230%!encoding: latin1
1231```
1232
1233Irá expandir para 'UTF-8' quando chamado com ``-t html`` mesmo que
1234'latin1' seja definido logo após.
1235
1236=== Filtros são Cumulativos ===
1237
1238Os filtros pre/postproc não tem precedência e não se encaixam no esquema
1239"último encontrado", eles são cumulativos. O usuário pode configurar
1240múltiplos filtros, e eles serão aplicados na ordem em que são definidos.
1241
1242Por exemplo:
1243
1244```
1245%!postproc     : ^ \t
1246%!postproc(txt): ^ '> '
1247```
1248
1249Com estes filtros, todos os tipos-destino serão indentados por uma TAB.
1250Se o tipo-destino é TXT, ele também receberá citações, como mensagens
1251de email.
1252
1253```
1254Desta forma        Minha bela linha.
1255se tornará         \t> Minha bela linha.
1256```
1257
1258=== Em Resumo ===
1259
1260- Para filtros, a ordem faz diferença e as regras genéricas __e__
1261  específicas ao tipo-destino serão usadas
1262
1263- Para outras configurações, __somente__ o tipo-destino especificado é
1264  usado (se definido, é claro), não importando a ordem
1265
1266
1267== RC, CONF e a precedência de linha de comando ==
1268
1269Há três maneiras de dizer ao txt2tags quais opções e configurações usar:
1270
1271+ O arquivo de usuário RC  (``.txt2tagsrc``)
1272+ A Área de Configurações CONF do documento
1273+ As opções de linha de comando
1274
1275
1276E esta é a ordem exata de como as configurações são lidas e aplicadas.
1277Logo, as configuraçõe dp arquivo RC são lidas primeiro, daí as
1278configurações do fonte do documento vêm a seguir, sobreescrevendo as do
1279RC e finalmente as opções da linha de comando, mais fortes do que as
1280outras duas.
1281
1282Então se o "encoding" do documento foi definido nas três opções, a da
1283linha de comando será a utilizada.
1284
1285
1286=======================================================================
1287
1288
1289
1290= Parte VI - Magia Negra =
1291
1292Este capítulo não é recomendado para novatos. Ele demonstra como fazer
1293coisas estranhas com os filtros txt2tags, abusando de padrões complexos
1294e Expressões Regulares.
1295
1296	**CUIDADO!** Os procedimentos detalhados a seguir NÃO são
1297	encorajados e podem acarretar danos. Até mesmo algum texto do
1298	arquivo fonte pode ser perdido no processo de conversão, não
1299	aparecendo no arquivo gerado. Use estas táticas se você
1300	realmente precisa delas e sabe o que está fazendo.
1301
1302 || Filtros são um recurso poderoso, mas podem ser perigosos! |
1303
1304 ||…

Large files files are truncated, but you can click here to view the full file