/doc/Portuguese/userguide-pt.t2t
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