/doc/Portuguese/userguide-pt.html
HTML | 2503 lines | 2348 code | 155 blank | 0 comment | 0 complexity | 10c3d69f49fe24423985d57058a5a0ea MD5 | raw file
Possible License(s): GPL-2.0, GPL-3.0, WTFPL
- <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
- <HTML>
- <HEAD>
- <STYLE TYPE="text/css">
- body {background-color:#ddeeff; color:black;
- margin:2em; text-align:justify;}
- a {text-decoration:none;}
- a:hover {color:red;}
- a:visited {color:purple;}
- dl {margin:1em;}
- h1 {text-align:center; background-color:blue;
- color:white; padding:8px;}
- h2 {padding-top:20px;}
- hr {border-style:none;}
- code {background-color:lightblue;}
- table {border-style:solid; border-color:black;}
- th {background-color:lightblue; padding:1em;}
- td {border-style:none; background-color:white;}
- pre {border-style:solid; border-width:1px 1px;
- background-color:lightblue; padding:8px;
- border-color:black;}
- </STYLE>
- <META NAME="generator" CONTENT="http://txt2tags.org">
- <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=UTF-8">
- <TITLE>Guia do Usuário Txt2tags</TITLE>
- </HEAD><BODY BGCOLOR="white" TEXT="black">
- <CENTER>
- <H1>Guia do Usuário Txt2tags</H1>
- <FONT SIZE="4"><I>Aurelio, Wed Jan 11 20:53:37 2012</I></FONT><BR>
- <FONT SIZE="4">Tradução para o português: César A. K. Grossman</FONT>
- </CENTER>
- <P></P>
- <HR NOSHADE SIZE=1>
- <P></P>
- <UL>
- <LI><A HREF="#toc1">Sobre este documento</A>
- <LI><A HREF="#toc2">Parte I - Introdução ao Txt2tags</A>
- <UL>
- <LI><A HREF="#toc3">Suas Primeiras Questões</A>
- <LI><A HREF="#toc4">Estruturas de Formatação Suportadas</A>
- <LI><A HREF="#toc5">Formatos Suportados</A>
- <LI><A HREF="#estruturas">Situação dos Formatos-Destino para as Estruturas Suportadas</A>
- <LI><A HREF="#toc7">As Três Interfaces ao Usuário: GUI, Web e Linha de Comando</A>
- </UL>
- <LI><A HREF="#instalacao">Parte II - OK, eu quero um. E agora?</A>
- <UL>
- <LI><A HREF="#toc9">Download e Instalação do Python</A>
- <LI><A HREF="#toc10">Copiando o txt2tags</A>
- <LI><A HREF="#toc11">Instalação do txt2tags</A>
- <LI><A HREF="#sintaxe">Instalar os Arquivos de Sintaxe dos Editores de Texto</A> <b>[NOVO!]</b>
- </UL>
- <LI><A HREF="#toc13">Parte III - Escrevendo e Convertendo Seu Primeiro Documento</A>
- <UL>
- <LI><A HREF="#toc14">As Áreas do documento .t2t</A>
- </UL>
- <LI><A HREF="#toc15">Parte IV - Dominando o Txt2tags</A>
- <UL>
- <LI><A HREF="#toc16">A Área de Cabeçalho</A>
- <LI><A HREF="#toc17">A Área de Configuração</A>
- <LI><A HREF="#toc18">O Corpo do Texto</A>
- <LI><A HREF="#regras">Marcações (REGRAS)</A>
- <LI><A HREF="#data">A macro %%date</A>
- <LI><A HREF="#include">O comando %!include</A>
- </UL>
- <LI><A HREF="#settings">Parte V - Dominando as Diretivas de Configuração</A>
- <UL>
- <LI><A HREF="#toc23">%!Target</A> <b>[NOVO!]</b>
- <LI><A HREF="#toc24">%!Options</A> <b>[NOVO!]</b>
- <LI><A HREF="#toc25">%!Encoding</A>
- <LI><A HREF="#toc26">%!PreProc</A>
- <LI><A HREF="#toc27">%!PostProc</A>
- <LI><A HREF="#toc28">%!Style</A>
- <LI><A HREF="#toc29">Detalhes dos Filtros PreProc e PostProc</A>
- <LI><A HREF="#toc30">Definindo uma Configuração para um Tipo-Destino Específico</A>
- <LI><A HREF="#toc31">RC, CONF e a precedência de linha de comando</A> <b>[NOVO!]</b>
- </UL>
- <LI><A HREF="#toc32">Parte VI - Magia Negra</A>
- <UL>
- <LI><A HREF="#toc33">Inserindo Múltiplas Linhas com %!PostProc (como regras CSS)</A>
- <LI><A HREF="#toc34">Criando Conteúdo "Específico ao Tipo Destino", com %!PreProc</A>
- <LI><A HREF="#toc35">Mudando Marcas txt2tags com %!PreProc</A>
- </UL>
- <LI><A HREF="#historia">Parte VII - História do txt2tags</A>
- <UL>
- <LI><A HREF="#toc37">Janeiro de 1999: Pré História</A>
- <LI><A HREF="#toc38">Junho 1999: Ainda Pré-História</A>
- <LI><A HREF="#toc39">Agosto de 2000: Não Mais Pré-História</A>
- <LI><A HREF="#toc40">Julho de 2001: Debute das séries 0.x (Lançamento Mundial)</A>
- <LI><A HREF="#toc41">Setembro de 2002: Debute das séries 1.x</A>
- <LI><A HREF="#toc42">2002, 2003... e as História não pára</A>
- </UL>
- </UL>
- <P></P>
- <HR NOSHADE SIZE=1>
- <P></P>
- <H1 ID="toc1">Sobre este documento</H1>
- <BLOCKQUOTE>
- Olá, eu sou o guia do usuário do txt2tags!
- </BLOCKQUOTE>
- <BLOCKQUOTE>
- Aqui você encontra toda a informação disponível sobre a
- ferramenta de conversão de textos txt2tags.
- </BLOCKQUOTE>
- <BLOCKQUOTE>
- Minha versão atualizada pode ser encontrada em
- <A HREF="http://txt2tags.org/userguide/">http://txt2tags.org/userguide/</A>
- </BLOCKQUOTE>
- <BLOCKQUOTE>
- Para mais informações e versões recentes, visite
- <A HREF="http://txt2tags.org/">o website do txt2tags</A>.
- </BLOCKQUOTE>
- <BLOCKQUOTE>
- Bom proveito!
- </BLOCKQUOTE>
- <HR NOSHADE SIZE=5>
- <H1 ID="toc2">Parte I - Introdução ao Txt2tags</H1>
- <H2 ID="toc3">Suas Primeiras Questões</H2>
- <P>
- Este capítulo apresenta o txt2tags, introduzindo as funcionalidades e
- objetivo do programa.
- </P>
- <HR NOSHADE SIZE=1>
- <H3>O Que É?</H3>
- <P>
- O txt2tags é uma ferramenta de formatação e conversão de texto.
- </P>
- <P>
- O txt2tags converte um arquivo texto com algumas marcas para qualquer um
- dos tipos de arquivos suportados:
- </P>
- <UL>
- <LI>Documento HTML
- <LI>Documento XHTML
- <LI>Documento SGML
- <LI>Documento LaTeX
- <LI>Página man UNIX
- <LI>Apresentação Magic Point
- <LI>Página MoinMoin
- <LI>Documento PageMaker 6.0
- <LI>Texto Plano (sem marcações)
- </UL>
- <HR NOSHADE SIZE=1>
- <H3>Por Quê Eu Devo Usá-lo?</H3>
- <P>
- Você achará o txt2tags bastante útil se você:
- </P>
- <UL>
- <LI>precisa publicar documentos em diferentes formatos
- <LI>precisa manter documentos atualizados em diferentes formatos
- <LI>escreve manuais ou documentos técnicos
- <LI>não sabe como escrever um documento em um formato específico
- <LI>não tem um editor específico para um certo formato.
- <LI>quer usar um editor de texto simples para atualizar seus documentos
- </UL>
- <P>
- E a motivação principal é:
- </P>
- <UL>
- <LI>economizar tempo, escrevendo <B>conteúdo</B>, sem se preocupar com
- <B>formatação</B>
- </UL>
- <HR NOSHADE SIZE=1>
- <H3>Quais vantagens oferece em relação a outras ferramentas?</H3>
- <P>
- O txt2tags possui uma forma bem direta de crescimento, seguindo alguns
- conceitos básicos. Os conceitos a seguir se destacam:
- </P>
- <TABLE CELLPADDING="4">
- <TR>
- <TD><I>Arquivo fonte legível</I></TD>
- <TD>As marcações do txt2tags são bastante simples, quase naturais.</TD>
- </TR>
- <TR>
- <TD><I>Documento destino legível</I></TD>
- <TD>Da mesma forma que o arquivo fonte, o código do documento gerado também é legível, alinhado e possui linhas curtas.</TD>
- </TR>
- <TR>
- <TD><I>Consistência na Marcação</I></TD>
- <TD>As marcações txt2tags são únicas, atendendo todos os tipos de documentos e não sendo confundidas com o conteúdo.</TD>
- </TR>
- <TR>
- <TD><I>Regras Consistentes</I></TD>
- <TD>Da mesma forma que as marcas, as regras aplicadas a elas são uniformes, não há "exceções" ou "casos especiais".</TD>
- </TR>
- <TR>
- <TD><I>Estruturas Simples</I></TD>
- <TD>Toda a formatação suportada é <B>simples</B>, sem opções extras ou modificadores complexos de comportamento. Uma marcação é só uma marcação, sem opções adicionais.</TD>
- </TR>
- <TR>
- <TD><I>Fácil de aprender</I></TD>
- <TD>Com marcações simples e o código fonte legível, a curva de aprendizado é bem amigável.</TD>
- </TR>
- <TR>
- <TD><I>Bons Exemplos</I></TD>
- <TD>Os <B>arquivos de exemplo</B> incluídos com o pacote dão mostras reais de documentos simples e super-estruturados, escritos no formato txt2tags.</TD>
- </TR>
- <TR>
- <TD><I>Ferramentas Valiosas</I></TD>
- <TD>Os <B>arquivos de sintaxe</B> incluídos com o pacote (para os editores vim, emacs, nano e kate) ajudam a escrever documentos sem erros sintáticos.</TD>
- </TR>
- <TR>
- <TD><I>Três interfaces ao usuários</I></TD>
- <TD>Há uma <B>interface Gráfica Tk</B> que é bastante amigável, uma <B>inteface Web</B> para usar remotamente ou na intranet, e uma <B>interface de Linha de Comando</B>, para usuários avançados e scripts.</TD>
- </TR>
- <TR>
- <TD><I>Suporte a Scripts</I></TD>
- <TD>Com o modo completo de linha de comando, um usuário experiente pode <B>automatizar</B> tarefas e efetuar <B>pós-edições</B> nos arquivos convertidos.</TD>
- </TR>
- <TR>
- <TD><I>Baixe e Execute / Multiplataforma</I></TD>
- <TD>O txt2tags é apenas um <B>script Python</B>. Não há necessidade de compilá-lo ou carregar módulos extras. Assim, ele pode ser executado sem problemas em máquinas *NIX, Linux, Windows e Macintosh.</TD>
- </TR>
- <TR>
- <TD><I>Atualizações Freqüentes</I></TD>
- <TD>O programa possui uma lista de discussões com usuários ativos que sugerem correções e melhorias. O próprio autor é um usuário intenso em casa e no trabalho, por isto o desenvolvimento não irá parar tão cedo.</TD>
- </TR>
- </TABLE>
- <HR NOSHADE SIZE=1>
- <H3>Tenho que pagar por ele?</H3>
- <TABLE ALIGN="center" BORDER="1" CELLPADDING="4">
- <TR>
- <TH>Absolutamente NÃO!</TH>
- </TR>
- </TABLE>
- <P>
- O txt2tags é um programa gratuito, GPL, open source, domínio público,
- etc...
- </P>
- <P>
- Você pode copiar, usar, modificar, vender, liberar como seu. As
- políticas de software e copyright não são uma das maiores preocupações
- do autor.
- </P>
- <HR NOSHADE SIZE=1>
- <H2 ID="toc4">Estruturas de Formatação Suportadas</H2>
- <P>
- Segue uma lista de todas as estruturas suportadas pelo txt2tags.
- </P>
- <UL>
- <LI>cabeçalho (título, nome do autor, data)
- <LI>títulos de seções (numeradas ou não)
- <LI>parágrafos
- <LI>modificadores de fontes
- <UL>
- <LI>negrito
- <LI>itálico
- <LI>sublinhado
- </UL>
- <LI>fonte monoespaço (verbatim)
- <UL>
- <LI>monoespaço no meio de um parágrafo
- <LI>linha monoespaçada
- <LI>trecho em monoespaçado
- </UL>
- <LI>citações
- <LI>links
- <UL>
- <LI>Links de Internet (URL)
- <LI>links de email
- <LI>links locais
- <LI>links nomeados
- </UL>
- <LI>listas
- <UL>
- <LI>listas com marcadores
- <LI>listas numeradas
- <LI>listas de definição
- </UL>
- <LI>linha horizontal de separação
- <LI>imagems (com alinhamento inteligente)
- <LI>tabela (com ou sem borda, com alinhamento inteligente)
- <LI>marcação especial para texto que não deve ser formatado
- <LI>macro especial para a data atual (com formatação flexível)
- <LI>comentários (para notas, A FAZER, CORREÇÕES, etc.)
- </UL>
- <HR NOSHADE SIZE=1>
- <H2 ID="toc5">Formatos Suportados</H2>
- <DL>
- <DT><B>HTML</B> </DT><DD>
- Todo mundo sabe o que o HTML é (dica: Internet).
- <P></P>
- O txt2tags gera documentos HTML limpos, que tem boa apresentação e cujo
- código fonte é legível. Ele NÃO USA javascript, frames ou outras
- técnicas de formatação fúteis, que não são necessárias para documentos
- técnicos simples. Mas um arquivo CSS separado pode ser utilizado, se for
- desejado. O Txt2tags gera código "<I>HTML 4.0 Transitional</I>".
- <P></P>
- Desde a versão 2.0, o código HTML gerado pelo txt2tags é 100% aprovado
- pelo <A HREF="vhttp://validator.w3.org/">validador w3c</A>.
- </DL>
- <DL>
- <DT><B>XHTML</B></DT><DD>
- Esta é a nova generação do HTML, com regras mais restritas, como fechar
- todas as marcas que forem abertas. Isto torna o código mas fácil de ser
- avaliado e entendido. Para propósitos gerais, considere como HTML. O
- txt2tags gera código "<I>HTML 4.0 Transitional</I>".
- <P></P>
- Desde a versão 2.0, o código XHTML gerado pelo txt2tags é 100% aprovado
- pelo <A HREF="vhttp://validator.w3.org/">validador w3c</A>.
- <P></P>
- <DT><B>SGML</B></DT><DD>
- O SGML é um formato de documento comum que possui aplicações de
- conversão, como <A HREF="http://www.sgmltools.org/">sgmltools</A>. De um arquivo
- sgml pode-se gerar documentos html, pdf, ps, info, latex, lyx, rtf e
- xml. As ferramentas sgml2* também criam índices (TOC) e quebra de seções
- em subpáginas (sgml2html).
- <P></P>
- O txt2tags gera arquivos SGML válidos para a DTD linuxdoc, prontos para
- serem convertidos com uma ferramenta sgml2* sem qualquer arquivo de
- catálogo extra ou outras exigências incômodas do SGML.
- <P></P>
- <DT><B>LATEX</B></DT><DD>
- O formato de documentação preferido nos meios acadêmicos, é mais potente
- do que normalmente se considera. Livros completos, fórmulas complicadas
- e qualquer texto complexo pode ser escrito em LaTeX. Mas se prepare para
- perder os cabelos se tentar escever as marcações à mão...
- <P></P>
- O txt2tags gera arquivos LaTeX prontos para usar, realizando todos os
- complexos truques de escape e exceções. O escritor deve se preocupar
- exclusivamente com o texto.
- <P></P>
- <DT><B>MAN</B></DT><DD>
- As páginas man do UNIX resistiram pelos anos. Formatos de documento vem
- e vão, e elas estão aí, imbatíveis.
- <P></P>
- Existem outras ferramentas para gerar documentos man, mas o txt2tags tem
- uma vantagem: uma fonte, múltiplos formatos destino. Assim, o conteúdo
- da mesma página man pode ser convertido para uma página HTML, uma
- apresentação Magic Point, etc.
- <P></P>
- <DT><B>MGP</B></DT><DD>
- O <A HREF="http://www.mew.org/mgp/">Magic Point</A> é uma ferramenta de apresentação
- bastante útil (dica: Microsoft PowerPoint), que usa uma linguagem de
- marcação para definir todas as telas. Desta forma, você pode criar
- apresentações complexas no vi/emacs/notepad.
- <P></P>
- O txt2tags gera um arquivo .mgp pronto para ser usado, definindo todos
- os cabeçalhos necessários para as definições de fontes e aparência, bem
- como o suporte aos caracteres acentuados da página de código ISO-8859.
- <P></P>
- <B>Observação 1:</B> os arquivos .mgp criados pelo txt2tags usam as fontes
- Type1 do XFree86! Desta forma, não é necessário incluir fontes TrueType
- com sua apresentação.
- <P></P>
- <B>Observação 2:</B> as definições de cor para as fontes são limpas, de
- forma que mesmo com uma paleta de cores de sistema pobre (como em
- <CODE>startx -- -bpp 8</CODE>) a apresentação vai ter boa aparência.
- <P></P>
- A chave é: converta e use. Não há necessidade de remendos ou de outros
- requisitos.
- <P></P>
- <DT><B>MOIN</B></DT><DD>
- Você não sabe o que é o <A HREF="http://moin.sourceforge.net">MoinMoin</A>? Ele é
- um <A HREF="http://www.c2.com/cgi/wiki">WikiWiki</A>!
- <P></P>
- A sintaxe do Moin é um pouco chata, quando você tem que ficar
- <CODE>{{{'''''acrescentando chaves e plicas'''''}}}</CODE>, mas o txt2tags vem
- com as marcações simplificadas e uma solução unificada: uma fonte,
- múltiplos formatos destino.
- <P></P>
- <DT><B>PM6</B></DT><DD>
- Aposto que você não sabia, mas o Adobe PageMaker 6.0 tem sua própria
- linguagem de marcação! Estilos, tabelas de cores, embelezadores, e a
- maior parte das funcionalidades acessíveis via cliques de mouse também
- estão disponíveis em sua linguagem de marcação. Você só precisa acessar
- o item de menu "Import tagged text". Apenas para registro, é um formato
- de marcação semelhante ao HTML.
- <P></P>
- O txt2tags gera todas as tags e já define um cabeçalho extenso e
- funcional, configurando os estilos de parágrafo e formatações. Esta é a
- parte difícil. <B>EPA:</B> Sem quebras de linha! Um parágrafo deve ser uma
- única linha.
- <P></P>
- Nota do Autor:
- <I>Todo meu livro em português sobre <A HREF="http://guia-er.sf.net/">expressões regulares</A></I>
- <I>foi escrito no vi, convertido para o formato do PageMaker com o</I>
- <I>txt2tags e então mandado para o prelo.</I>
- <P></P>
- <DT><B>TXT</B></DT><DD>
- TXT é texto. O único tipo de formatação verdadeiro.
- <P></P>
- Apesar das marcações do txt2tags serem bem intuitivas e discretas,
- pode-se removê-las ao converter o arquivo para TXT puro.
- <P></P>
- Os títulos são sublinhados, e o texto é basicamente deixado como está no
- código fonte.
- </DL>
- <HR NOSHADE SIZE=1>
- <H2 ID="estruturas">Situação dos Formatos-Destino para as Estruturas Suportadas</H2>
- <TABLE ALIGN="center" BORDER="1" CELLPADDING="4">
- <TR>
- <TH>Estrutura</TH>
- <TH>html</TH>
- <TH>xhtml</TH>
- <TH>sgml</TH>
- <TH>tex</TH>
- <TH>man</TH>
- <TH>mgp</TH>
- <TH>moin</TH>
- <TH>pm6</TH>
- <TH>txt</TH>
- </TR>
- <TR>
- <TD>cabeçalhos</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">S</TD>
- </TR>
- <TR>
- <TD>título de seções</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- </TR>
- <TR>
- <TD>parágrafos</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- </TR>
- <TR>
- <TD>negrito</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">-</TD>
- </TR>
- <TR>
- <TD>itálico</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">-</TD>
- </TR>
- <TR>
- <TD>sublinhado</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">-</TD>
- </TR>
- <TR>
- <TD>pré-formatado</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">-</TD>
- </TR>
- <TR>
- <TD>linha pré-formatada</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">-</TD>
- </TR>
- <TR>
- <TD>área pré-formatada</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">-</TD>
- </TR>
- <TR>
- <TD>área cotada</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- </TR>
- <TR>
- <TD>links internet</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">-</TD>
- </TR>
- <TR>
- <TD>links e-mail</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">-</TD>
- </TR>
- <TR>
- <TD>links locais</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">-</TD>
- </TR>
- <TR>
- <TD>links nomeados</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">-</TD>
- </TR>
- <TR>
- <TD>lista não-numerada</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- </TR>
- <TR>
- <TD>lista numerada</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- </TR>
- <TR>
- <TD>lista de definições</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">S</TD>
- </TR>
- <TR>
- <TD>linha horizontal</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">S</TD>
- </TR>
- <TR>
- <TD>imagem</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">-</TD>
- </TR>
- <TR>
- <TD>tabela</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">N</TD>
- </TR>
- <TR>
- <TH>Extras</TH>
- <TH>html</TH>
- <TH>xhtml</TH>
- <TH>sgml</TH>
- <TH>tex</TH>
- <TH>man</TH>
- <TH>mgp</TH>
- <TH>moin</TH>
- <TH>pm6</TH>
- <TH>txt</TH>
- </TR>
- <TR>
- <TD>image align</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">-</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">-</TD>
- </TR>
- <TR>
- <TD>table cell align</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">S</TD>
- <TD ALIGN="center">N</TD>
- <TD ALIGN="center">N</TD>
- </TR>
- </TABLE>
- <TABLE ALIGN="center" CELLPADDING="4">
- <TR>
- <TH></TH>
- <TH>Legenda</TH>
- </TR>
- <TR>
- <TD><B>S</B></TD>
- <TD><I>suportada</I></TD>
- </TR>
- <TR>
- <TD><B>N</B></TD>
- <TD><I>não suportada (talvez em uma versão futura)</I></TD>
- </TR>
- <TR>
- <TD><B>-</B></TD>
- <TD><I>não suportada (não pode ser feita neste formato)</I></TD>
- </TR>
- </TABLE>
- <HR NOSHADE SIZE=1>
- <H2 ID="toc7">As Três Interfaces ao Usuário: GUI, Web e Linha de Comando</H2>
- <P>
- Assim como diferentes usuários possuem diferentes necessidades e
- ambientes, o txt2tags é bastante flexivel na forma de ser usado.
- </P>
- <P>
- Existem três Interfaces de Usuário para o programa, cada uma atendendo a
- um objetivo definido e com funcionalidades próprias.
- </P>
- <UL>
- <LI><B>GUI</B>: Escrita em Tk, traz as janelas e os cliques para o txt2tags.
- <LI><B>Web</B>: Escrita em PHP, permite que o usuário execute o txt2tags no
- navegador, não exigindo instalação do lado do cliente.
- <LI><B>Linha de Comando</B>: Escrita em Python, é o núcleo do programa.
- Todas as funcionalidades estão disponíveis como opções de
- linha de comando.
- </UL>
- <HR NOSHADE SIZE=1>
- <H3 ID="gui">Interface Gráfica Tk</H3>
- <P>
- Desde a versão 1.0, há uma bela Interface Gráfica, que funciona do
- Linux, Windows, Mac e outros.
- </P>
- <P>
- O programa automaticamente detecta se seu sistema pode apresentar a
- interface e a lança quando é chamado sem argumentos. Pode-se forçar a
- apresentação da Interfaca Gráfica com a opção <CODE>--gui</CODE>. Se estiver
- faltando algum recurso o programa irá alertar.
- </P>
- <BLOCKQUOTE>
- <B>Nota:</B> O módulo Tkinter é necessário. Como ele vem com a
- distribição padrão do Python você já deve tê-lo.
- </BLOCKQUOTE>
- <P>
- Ela é bastante simples e fácil de usar:
- </P>
- <center><IMG ALIGN="middle" SRC="../userguide/gui.png" BORDER="0" ALT=""></center>
- <OL>
- <LI>Você localiza o arquivo fonte .t2t no disco e suas opções são
- carregadas.
- <P></P>
- <LI>Se o destino ainda estiver vazio, você deve escolher um.
- <P></P>
- <LI>Há algumas opões que podem ser escolhidas, mas nenhuma delas é
- essencial.
- <P></P>
- <LI>Finalmente, pressione o botão "Converter!".
- </OL>
- <P>
- Uma boa opção a selecionar é "<I>Dump to screen</I>", assim se pode
- verificar o código resultante em uma janela separada, sem que o arquivo
- seja salvo. Quando o código estiver correto, basta desmarcá-la e o
- arquivo será gravado.
- </P>
- <P>
- As cores padrão podem ser mudadas no arquivo <CODE>~/.txt2tagsrc</CODE>,
- configurando em <CODE>%!guicolors</CODE>. Por exemplo:
- </P>
- <PRE>
- % minhas cores para a interface (fundo1, texto1, fundo2, texto2)
- %!guicolors: blue white brown yellow
- </PRE>
- <HR NOSHADE SIZE=1>
- <H3 ID="web">Interface Web</H3>
- <P>
- A Interface Web está em funcionamento na Internet no endereço
- <A HREF="http://txt2tags.org/online.php">http://txt2tags.org/online.php</A>, permitindo que o programa possa ser
- usado e testado antes de ser copiado.
- </P>
- <center><IMG ALIGN="middle" SRC="../userguide/web.png" BORDER="0" ALT=""></center>
- <P>
- Esta interface também pode ser colocada na intrant para uso local,
- evitando a instalação do txt2tags em todas as máquinas.
- </P>
- <HR NOSHADE SIZE=1>
- <H3 ID="linhadecomando">Interface de Linha de Comando</H3>
- <P>
- Para usuários de linha de comando acostumados, o parâmetro --help deve
- ser suficiente:
- </P>
- <PRE>
- Uso: txt2tags [OPÇÕES] [arquivo.t2t ...]
-
- -t, --target define o formato do destino. tipos suportados:
- html, xhtml, sgml, tex, man, mgp, moin, pm6, txt
- -i, --infile=ARQ define ARQ como o arquivo fonte ('-' para STDIN)
- -0, --outfile=ARQ define ARQ como o arquivo destino ('-' para STDOUT)
- -n, --enum-title numera todos os títulos como 1, 1.1, 1.1.1, etc
- -H, --no-headers suprime os cabeçalhos, título e rodapé
- --headers exibe os cabeçalhos, título e rodapé (padrão LIGADO)
- --encoding informa a codificação de destino (utf-8, iso-8859-1, etc)
- --style=ARQ utiliza ARQ como estilo do documento (CSS no Html)
- --css-sugar insere tags compatíveis com CSS em destinos HTML e XHTML
- --mask-email esconde e-mails dos robôs de SPAM. x@y.z vira <x (a) y z>
- --toc inclui o Índice (Table of Contents) no documento destino
- --toc-only exibe o Índice do documento e sai
- --toc-level=N define o nível máximo do Índice para N
- --rc lê a config do usuário em ~/.txt2tagsrc (padrão LIGADO)
- --gui carrega a interface gráfica escrita em TK
- -v, --verbose exibe mensagens informativas durante a conversão
- -h, --help exibe este texto de ajuda e sai
- -V, --version exibe a versão do programa e sai
- --dump-config exibe todas as configurações encontradas e sai
-
- Opções para DESLIGAR funcionalidades:
- --no-outfile, --no-infile, --no-style, --no-encoding, --no-headers
- --no-toc, --no-toc-only, --no-mask-email, --no-enum-title, --no-rc
- --no-css-sugar
-
- Exemplo:
- txt2tags -t html --toc meuarquivo.t2t
-
- Normalmente a saída convertida é gravada em 'arquivo.<tipo>'.
- Utilize --outfile para forçar um nome para o arquivo de saída.
- Se o arquivo de entrada é '-', lê de STDIN.
- Se o arquivo de saída é '-', envia a saída para STDOUT.
- </PRE>
- <H4>Exemplos</H4>
- <P>
- Supondo que exista um arquivo de marcação chamado <CODE>file.t2t</CODE>, vamos nos
- divertir um pouco.
- </P>
- <TABLE CELLPADDING="4">
- <TR>
- <TD><B>Convertendo para HTML</B></TD>
- <TD><CODE>$ txt2tags -t html file.t2t</CODE></TD>
- </TR>
- <TR>
- <TD><B>O mesmo, usando redirecionamento</B></TD>
- <TD><CODE>$ txt2tags -t html -o - file.t2t > file.html</CODE></TD>
- </TR>
- <TR>
- <TD></TD>
- <TD>.</TD>
- </TR>
- <TR>
- <TD><B>Incluindo uma Tabela de Conteúdo</B></TD>
- <TD><CODE>$ txt2tags -t html --toc file.t2t</CODE></TD>
- </TR>
- <TR>
- <TD><B>Idem, numerando os títulos</B></TD>
- <TD><CODE>$ txt2tags -t html --toc --enum-title file.t2t</CODE></TD>
- </TR>
- <TR>
- <TD></TD>
- <TD>.</TD>
- </TR>
- <TR>
- <TD><B>Visualização Rápida do Conteúdo</B></TD>
- <TD><CODE>$ txt2tags --toc-only file.t2t</CODE></TD>
- </TR>
- <TR>
- <TD><B>Quem sabe com números?</B></TD>
- <TD><CODE>$ txt2tags --toc-only --enum-title file.t2t</CODE></TD>
- </TR>
- <TR>
- <TD></TD>
- <TD>.</TD>
- </TR>
- <TR>
- <TD><B>Linha simples de STDIN</B></TD>
- <TD><CODE>$ echo -e "\n**bold**" | txt2tags -t html --no-headers -</CODE></TD>
- </TR>
- <TR>
- <TD><B>Testando o Mascaramento de Email</B></TD>
- <TD><CODE>$ echo -e "\njohn.wayne@farwest.com" | txt2tags -t txt --mask-email --no-headers -</CODE></TD>
- </TR>
- <TR>
- <TD><B>Edição pós-conversão</B></TD>
- <TD><CODE>$ txt2tags -t html -o- file.t2t | sed "s/<BODY .*/<BODY BGCOLOR=green>/" > file.html</CODE></TD>
- </TR>
- </TABLE>
- <DL>
- <DT><I>Nota</I></DT><DD>
- Desde a versão 1.6 você pode fazer pre e pós processamento usando as
- macros de configuração <CODE>%!preproc</CODE> e <CODE>%!postproc</CODE>.
- </DL>
- <HR NOSHADE SIZE=5>
- <H1 ID="instalacao">Parte II - OK, eu quero um. E agora?</H1>
- <P>
- Basta baixar o programa e executar o mesmo no seu computador.
- </P>
- <H2 ID="toc9">Download e Instalação do Python</H2>
- <P>
- Antes de mais nada, deve-se baixar e instalar o interpretador Python
- para o seu sistema. Se você já o tem, então pule eset passo.
- </P>
- <P>
- O Python é uma das melhores linguagens de programação que existem, ela
- pode ser utilizada no Windows, Linux, UNIX, Macintosh, e outras
- plataformas, e pode ser baixada do
- <A HREF="http://www.python.org">web site do Python</A>. As dicas de instalação podem
- ser encontradas no mesmo site. O txt2tags funciona com o Python 1.5 ou
- posterior.
- </P>
- <P>
- Se você não tem certeza de ter o Python ou não, abra um console (tty,
- xterm, MSDOS) e escreva <CODE>python</CODE>. Se ele não estiver instalado, o
- sistema vai lhe informar.
- </P>
- <H2 ID="toc10">Copiando o txt2tags</H2>
- <P>
- O local oficial de distribuição do txt2tags é na homepage do programa,
- em <A HREF="http://txt2tags.org/src">http://txt2tags.org/src</A>.
- </P>
- <P>
- Todos os arquivos do programa estão em um tarball (arquivo .tgz), que
- pode ser expandido pela maioria dos utilitários de compressão (incluindo
- o Winzip).
- </P>
- <P>
- Simplesmente pegue a <B>última</B> versão (data mais recente, número de
- versão maior). As versões anteriores estão lá apenas por razões
- históricas.
- </P>
- <H2 ID="toc11">Instalação do txt2tags</H2>
- <P>
- Como é apenas um script Python, o txt2tags não precisa ser instalado.
- </P>
- <P>
- O único arquivo necessário para usar o programa é o script txt2tags. Os
- outros arquivos do tarball compreendem a documentação, ferramentas e
- arquivos de exemplo.
- </P>
- <P>
- O modo mais seguro de usar o txt2tags é chamar o Python com ele:
- </P>
- <PRE>
- prompt$ python txt2tags
- </PRE>
- <P>
- Se você quiser "instalar" o txt2tags no sistema como um programa
- independente, basta copiar (ou criar um link) o script txt2tags para um
- diretório que esteja no PATH do sistema e certificar-se que o sistema
- saiba como executar o mesmo.
- </P>
- <DL>
- <DT><B>UNIX/Linux</B></DT><DD>
- Torne o script executável (<CODE>chmod +x txt2tags</CODE>) e copie o mesmo para
- um diretório no $PATH (<CODE>cp txt2tags /usr/local/bin</CODE>)
- <P></P>
- <DT><B>Windows</B></DT><DD>
- Renomeie o script, acrescentando a extensão .py
- (<CODE>ren txt2tags txt2tags.py</CODE>) e o copie para um diretório que esteja
- no PATH do sistema (<CODE>copy txt2tags.py C:\WINNT</CODE>)
- </DL>
- <P>
- Depois disto, pode-se criar um ícone no desktop para o programa, se
- quiser usar a Interface Gráfica do programa.
- </P>
- <H3>Pacotes Especiais para Usuários Windows</H3>
- <P>
- Existem dois arquivos de distribuição .EXE para o txt2tags, que instalam
- o programa em máquinas Windows com apenas alguns cliques:
- </P>
- <UL>
- <LI>O script txt2tags para aqueles que tem o interpretador Python
- instalado
- <LI>A versão stand-alone, que não requer a instalação do interpretador
- Pyton para ser executada (já tem uma versão pequena incluída).
- </UL>
- <P>
- Visite o site <I>Txt2tags-Win</I> para baixar estes pacotes:
- <A HREF="http://txt2tags-win.sf.net/">http://txt2tags-win.sf.net/</A>
- </P>
- <H2 ID="sintaxe">Instalar os Arquivos de Sintaxe dos Editores de Texto</H2>
- <P>
- O txt2tags possui arquivos de sintaxe práticos que podem ser usados com
- os seguintes editores de texto:
- </P>
- <UL>
- <LI>Vim (<A HREF="http://www.vim.org">www.vim.org</A>)
- <LI>Emacs (<A HREF="http://www.emacs.org">www.emacs.org</A>)
- <LI>Nano (<A HREF="http://www.nano-editor.org">www.nano-editor.org</A>)
- <LI>Kate (<A HREF="http://kate.kde.org">http://kate.kde.org</A>)
- </UL>
- <P>
- Os arquivos de sintaxe têm registro de todas as regras e marcações do
- txt2tags, ajudando ao usuário a escrever documentos sem erros. As marcas
- são mostradas coloridas, assim se pode ver se tudo foi escrito
- corretamente.
- </P>
- <TABLE ALIGN="center" BORDER="1" CELLPADDING="4">
- <TR>
- <TD ALIGN="center"><center><IMG ALIGN="middle" SRC="../userguide/vim.png" BORDER="0" ALT=""></center></TD>
- </TR>
- <TR>
- <TD ALIGN="center">O arquivo de exemplo aberto no Editor Vim</TD>
- </TR>
- </TABLE>
- <P>
- Cada editor tem um procedimento diferente para usar seu arquivo de
- sintaxe. Por favor verifique no cabeçalho de cada arquivo e na
- documentação do editor.
- </P>
- <HR NOSHADE SIZE=5>
- <H1 ID="toc13">Parte III - Escrevendo e Convertendo Seu Primeiro Documento</H1>
- <P>
- Desculpe, este capítulo ainda está em desenvolvimento.
- </P>
- <H2 ID="toc14">As Áreas do documento .t2t</H2>
- <P>
- Os arquivos de marcação txt2tags são divididos em 3 áreas. Cada área tem
- suas próprias regras e finalidade. São elas:
- </P>
- <DL>
- <DT><I>Área de Cabeçalho</I></DT><DD>
- É o lugar para informações sobre o Título do Documento, Autor, Versão e
- Data. (opcional)
- <P></P>
- <DT><I>Área de Configuração</I></DT><DD>
- É o local para colocar as configurações Gerais do documento e
- modificadores do funcionamento do analisador. (opcional)
- <P></P>
- <DT><I>Corpo do Texto</I></DT><DD>
- É o local para o Conteúdo do Documento (requerida)
- </DL>
- <P>
- Como vemos acima, as duas primeiras áreas são opcionais, sendo que o
- <I>Corpo do Texto</I> é a única área indispensável.
- (<I>Nota: A <B>Área de Configuração</B> foi introduzida no txt2tags na versão 1.3</I>)
- </P>
- <P>
- As áreas são delimitadas por regras especiais, que serão vistas em
- detalhe no próximo capítulo. Por enquanto, esta é uma representação
- gráfica das áreas de um documento:
- </P>
- <PRE>
- ____________
- | |
- | CABEÇALHO | 1. Primeiro, o cabeçalho
- | |
- | CONFIG | 2. Então a configuração
- | |
- | CORPO | 3. E, finalmente, o corpo do documento
- | |
- | ... | que segue até o final do arquivo.
- | ... |
- |____________|
-
- </PRE>
- <P>
- Em resumo, é assim que as áreas são definidas:
- </P>
- <TABLE ALIGN="center" CELLPADDING="4">
- <TR>
- <TD><B>Cabeçalhos</B></TD>
- <TD>As primeiras 3 linhas do arquivo, ou a primeira linha é deixada em branco se não são usados cabeçalhos</TD>
- </TR>
- <TR>
- <TD><B>Configuração</B></TD>
- <TD>Começam logo depois do cabeçalho (4a. ou 2a. linha) e termina quando a <I>Área de Conteúdo</I> começa.</TD>
- </TR>
- <TR>
- <TD><B>Corpo</B></TD>
- <TD>A primeira linha de texto válida (que não é comentário ou configuração) após a <I>Área de Cabeçalho</I>.</TD>
- </TR>
- </TABLE>
- <H3>Exemplo Completo</H3>
- <PRE>
- Título do meu belo documento
- Sr. Fulano da Silva
- Última atualização: %%date(%c)
-
- %! Target : html
- %! Style : fancy.css
- %! Encoding: UTF-8
- %! Options : --toc --enum--title
-
- Oi! Este é o meu documento de teste.
- E o seu conteúdo termina aqui.
- </PRE>
- <HR NOSHADE SIZE=5>
- <H1 ID="toc15">Parte IV - Dominando o Txt2tags</H1>
- <H2 ID="toc16">A Área de Cabeçalho</H2>
- <P>
- Localização:
- </P>
- <UL>
- <LI>Posição fixa: <B>Primeiras 3 linhas</B> do arquivo. Ponto.
- <LI>Posição fixa: <B>A Primeira Linha</B> do arquivo está em branco. Isto
- significa que o cabeçalho está vazio.
- </UL>
- <P>
- A Área de Cabeçalho é a única que tem uma posição fixa, orientada a
- linhas. Ela está localizada nas três primeiras linhas do código fonte.
- </P>
- <P>
- O conteúdo destas linhas é livre, sem necessidade de nenhuma informação
- estática de nenhum tipo. Mas recomenda-se o seguinte para a maioria dos
- documentos:
- </P>
- <UL>
- <LI><I>linha 1</I>: título do documento
- <LI><I>linha 2</I>: nome e/ou email do autor
- <LI><I>linha 3</I>: data e/ou versão do documento
- (um bom lugar para colocar <CODE>%%date</CODE>)
- </UL>
- <P>
- Tenha em mente que as 3 primeiras linhas do arquivo fonte serão as 3
- primeiras linhas no documento gerado, separadas e com um grande
- contraste em relação ao corpo do texto (ou seja, letras grandes,
- negrito). Se a paginação for permitida, os cabeçalhos estarão separados
- e centralizados na primeira página.
- </P>
- <H4>Menos (ou Nenhuma) Linhas de Cabeçalho</H4>
- <P>
- Às vezes os usuários querem especificar menos de três linhas nos
- cabeçalhos, dando apenas o título do documento e/ou informação de data.
- </P>
- <P>
- Basta deixar a 2a. e/ou a 3a. linhas em branco e estas linhas não serão
- incluídas no documento gerado. Mas tenha em mente que, mesmo em branco,
- estas linhas ainda são parte dos cabeçalho, e o corpo do documento deve
- começar <B>após</B> a 3a. linha.
- </P>
- <P>
- O título é o único cabeçalho requerido (a primeira linha), mas se você
- deixar ela em branco, está dizendo que seu documento
- <B>não tem cabeçalho</B>. Desta forma, a <I>Área de Texto</I> irá começar em
- seguida, na 2a. linha.
- </P>
- <P>
- Não usar cabeçalhos no documento é útil se você quiser especificar seus
- próprios cabeçalhos customizados após a conversão. A opção de linha de
- comando <CODE>--no-headers</CODE> é geralmente necessária para este tipo de coisa.
- </P>
- <H4>Direto ao ponto</H4>
- <TABLE ALIGN="center" BORDER="1" CELLPADDING="4">
- <TR>
- <TH>Em resumo: "Cabeçalhos são apenas <U>posições</U>, não conteúdo "</TH>
- </TR>
- </TABLE>
- <P>
- Coloque um texto na primeira linha, ele irá aparecer na primeira linha
- do arquivo gerado. O mesmo para a 2a. e 3a. linhas de cabeçalho.
- </P>
- <HR NOSHADE SIZE=1>
- <H2 ID="toc17">A Área de Configuração</H2>
- <P>
- Localização:
- </P>
- <UL>
- <LI>Começa logo após a Área de Cabeçalhos
- <UL>
- <LI>Começa na <B>4a. linha</B> do arquivo se forem especificados <B>Cabeçalhos</B>
- <LI>Começa na <B>2a. linha</B> se <B>não</B> forem especificados <B>Cabeçalhos</B>
- </UL>
- <LI>Termina quando a Área de Conteúdo começa
- <UL>
- <LI>Termina com uma linha que não seja de Configuração, ou de
- Comentário, ou que seja uma linha em Branco.
- </UL>
- </UL>
- <P>
- A Área de Configuração é opcional. A maioria dos usuários pode escrever
- carradas de arquivos txt2tags mesmo sem saber que ela existe, mas os
- usuários experientes irão gostar do poder e controle que ela oferece.
- </P>
- <P>
- O uso primário desta área é para definir configurações que afetam o
- comportamento do programa.
- </P>
- <H4>Então, como configurar algo? Qual a sintaxe?</H4>
- <P>
- As linhas de configuração são <I>linhas de comentário especiais</I>,
- marcadas com um identificador no início ("<CODE>!</CODE>") que torna estes
- comentários diferentes dos comentários normais. A sintaxe é tão simples
- quanto uma atribuição de valor a uma variável, composta por uma
- palavra-chave e um valor, separados um do outro pelo separador canônico
- dois-pontos ("<CODE>:</CODE>").
- </P>
- <TABLE ALIGN="center" BORDER="1" CELLPADDING="4">
- <TR>
- <TH>%! palavra-chave : valor</TH>
- </TR>
- </TABLE>
- <P>
- <B><CODE>Detalhes da Sintaxe:</CODE></B> O ponto de exclamação deve ser colocado
- junto com o caractere de comentário, sem espaço entre eles ("<CODE>%!</CODE>").
- Os espaços em torno da <I>palavra-chave</I> e o separador são opcionais, e
- tanto a <I>palavra-chave</I> quanto o <I>valor</I> podem estar
- indiferentemente em maiúsculas ou minúsculas.
- </P>
- <H4>O que eu posso configurar? Quais são as palavra-chave válidas?</H4>
- <P>
- As configurações que podem ser feitas são <I>Target</I>, <I>Options</I>, <I>Style</I>,
- <I>Encoding</I>, <I>PreProc</I> e <I>PostProc</I>.
- </P>
- <P>
- A configuração <B><I>Target</I></B> define o destino padrão na qual o
- documento deve ser convertido.
- </P>
- <P>
- A configuração <B><I>Options</I></B> é útil para especificar as opções de
- linha de comando padrão para o arquivo fonte. Estas opções podem ser
- sobrescritas pela linha de comando real. Usar esta opção juntamente com
- <CODE>%!target</CODE> permite converter o documento simplesmente comandando:
- <CODE>txt2tags file.t2t</CODE>
- </P>
- <P>
- A configuração <B><I>Style</I></B> só é suportada pelo tipo de documento
- destino HTML, para definir uma folha de estilo
- (<I>Cascading Style Sheets - CSS</I>).
- </P>
- <P>
- A configuração <B><I>Encoding</I></B> é necessária para escritores não
- ingleses, que usem letras acentuadas e outros detalhes específicos de
- localização, de forma que o <I>Conjunto de Caracteres</I> do documento seja
- personalizado (se permitido).
- </P>
- <P>
- A configuração <B><I>PreProc</I></B> é um filtro. Ela define regras do tipo
- "busca e troca" que serão aplicadas ao arquivo original <U>antes</U> que
- qualquer análise por parte do txt2tags ocorra.
- </P>
- <P>
- A configuração <B><I>PostProc</I></B> é um filtro. Ela define regras do tipo
- "busca e troca" que serão aplicadas ao arquivo destino <U>depois</U> de
- todo o processamento por parte do txt2tags.
- </P>
- <P>
- Exemplo:
- </P>
- <PRE>
- %! Target : html
- %! Options : --toc --toc-level 3
- %! Style : fancy.css
- %! Encoding: UTF-8
- %! PreProc : "amj" "Aurelio Marinho Jargas"
- %! PostProc: '<BODY.*?>' '<BODY bgcolor="yellow">'
- </PRE>
- <H4>Algumas regras sobre as Configurações</H4>
- <UL>
- <LI>As configurações são válidas somente dentro da Área de Configuração,
- e serão consideradas comentários simples se forem encontradas no
- Corpo do documento.
- <P></P>
- <LI>Se a mesma palavra-chave aparece mais de uma vez na Área de
- Configuração, apenas a última será usada. Exceção: options, preproc e
- postproc, que são acumulativas.
- <P></P>
- <LI>Uma linha de configuração com uma palavra-chave inválida será
- considerada um comentário.
- <P></P>
- <LI>Estas configurações têm precedência sobre o arquivo <CODE>txt2tagsrc</CODE>,
- as não sobre as opções de linha de comando.
- </UL>
- <HR NOSHADE SIZE=1>
- <H2 ID="toc18">O Corpo do Texto</H2>
- <P>
- Localização:
- </P>
- <UL>
- <LI>Começa na primeira linha válida de texto do arquivo
- <UL>
- <LI>Cabeçalhos, Configurações e Comentários <B>não</B> são linhas de texto
- válidas
- </UL>
- <LI>Termina no fim do arquivo (EOF)
- </UL>
- <P>
- Bem, o corpo do texto é tudo que estiver fora das Áreas de Cabeçalho e
- de Configuração.
- </P>
- <P>
- O corpo do texto é onde está o conteúdo do documento e todas as
- estruturas e formatações que o txt2tags reconhece. Dentro do corpo podem
- ser também colocados comentários para <I>A FAZER</I> e anotações
- particulares.
- </P>
- <P>
- Pode-se utilizar a opção de linha de comando <CODE>--no-headers</CODE> para
- converter somente o corpo do documento, suprimindo os cabeçalhos. Esta
- opção é útil quando os cabeçalhos estão em um arquivo separado, que será
- unido ao corpo depois da conversão.
- </P>
- <HR NOSHADE SIZE=1>
- <H2 ID="regras">Marcações (REGRAS)</H2>
- <P>
- Todas as marcações e sintaxe usadas pelo txt2tags estão detalhadas em
- um <A HREF="REGRAS">arquivo REGRAS a parte</A>.
- </P>
- <HR NOSHADE SIZE=1>
- <H2 ID="data">A macro %%date</H2>
- <P>
- A macro <CODE>%%date</CODE> chamada sem nenhum parâmetro adicional retorna a data
- atual no formato ISO <I>yyyymmdd</I>. Uma formatação opcional pode ser
- especificada usando a sintaxe <CODE>%%date(formato)</CODE>.
- </P>
- <P>
- O <I>formato</I> contém texto de diretivas de formatação, que são compostas
- por um sinal de porcentagem (<CODE>%</CODE>) seguido por um caractere de
- identificação.
- </P>
- <P>
- Segue uma lista de algumas diretivas comuns. A lista completa pode ser
- encontrada em <A HREF="http://www.python.org/doc/current/lib/module-time.html">http://www.python.org/doc/current/lib/module-time.html</A>.
- </P>
- <TABLE ALIGN="center" BORDER="1" CELLPADDING="4">
- <TR>
- <TH>Diretiva</TH>
- <TH>Descrição</TH>
- </TR>
- <TR>
- <TD ALIGN="center">%a</TD>
- <TD>Dia da semana local abreviado.</TD>
- </TR>
- <TR>
- <TD ALIGN="center">%A</TD>
- <TD>Dia da semana completo.</TD>
- </TR>
- <TR>
- <TD ALIGN="center">%b</TD>
- <TD>Nome do mês abreviado.</TD>
- </TR>
- <TR>
- <TD ALIGN="center">%B</TD>
- <TD>Nome do mês.</TD>
- </TR>
- <TR>
- <TD ALIGN="center">%c</TD>
- <TD>Dia e hora formatados apropriadamente.</TD>
- </TR>
- <TR>
- <TD ALIGN="center">%d</TD>
- <TD>Dia do mês como um número decimal [01,31].</TD>
- </TR>
- <TR>
- <TD ALIGN="center">%H</TD>
- <TD>Hora (24 horas) como um número decimal [00,23].</TD>
- </TR>
- <TR>
- <TD ALIGN="center">%I</TD>
- <TD>Hora (12 horas) como um número decimal [01,12].</TD>
- </TR>
- <TR>
- <TD ALIGN="center">%m</TD>
- <TD>O mês como um número decimal [01,12].</TD>
- </TR>
- <TR>
- <TD ALIGN="center">%M</TD>
- <TD>O minuto como um número decimal [00,59].</TD>
- </TR>
- <TR>
- <TD ALIGN="center">%p</TD>
- <TD>O equivalente local a AM e PM.</TD>
- </TR>
- <TR>
- <TD ALIGN="center">%S</TD>
- <TD>Os segundos como um número decimal [00,61]. (1)</TD>
- </TR>
- <TR>
- <TD ALIGN="center">%x</TD>
- <TD>Representação local da data.</TD>
- </TR>
- <TR>
- <TD ALIGN="center">%X</TD>
- <TD>Representação local da hora.</TD>
- </TR>
- <TR>
- <TD ALIGN="center">%y</TD>
- <TD>O ano sem o século como um número decimal [00,99].</TD>
- </TR>
- <TR>
- <TD ALIGN="center">%Y</TD>
- <TD>O ano com o século como um número decimal.</TD>
- </TR>
- <TR>
- <TD ALIGN="center">%%</TD>
- <TD>Um caractere "%".</TD>
- </TR>
- </TABLE>
- <H4>Exemplos</H4>
- <TABLE ALIGN="center" BORDER="1" CELLPADDING="4">
- <TR>
- <TH><CODE>%%date(format)</CODE></TH>
- <TH>Resultado para: 2004, Jul13, 18:49</TH>
- </TR>
- <TR>
- <TD>Last Update: %c</TD>
- <TD>Last Update: Tue Jan 13 18:49:32 2004</TD>
- </TR>
- <TR>
- <TD>%Y-%m-%d</TD>
- <TD>2004-07-13</TD>
- </TR>
- <TR>
- <TD>%I:%M %p</TD>
- <TD>18:49 PM</TD>
- </TR>
- <TR>
- <TD>Hoje e %A, em %B.</TD>
- <TD>Hoje e Tuesday, em July.</TD>
- </TR>
- </TABLE>
- <HR NOSHADE SIZE=1>
- <H2 ID="include">O comando %!include</H2>
- <P>
- A partir da versão 1.7, é possível usar o comando <CODE>include</CODE> para
- inserir o conteúdo de um arquivo externo dentro do corpo do documento
- original.
- </P>
- <P>
- O <CODE>%!include</CODE> não é uma configuração, mas um comando, sendo somente
- válido na área de CORPO do texto.
- </P>
- <P>
- O comando <CODE>include</CODE> é útil para dividir um documento grande em vários
- arquivos menores (como capítulos de um livro) ou para incluir todo o
- conteúdo de um arquivo qualquer no documento. Por exemplo:
- </P>
- <PRE>
- Meu Primeiro Livro
- Dr. Fulano da Silva
- 1ª Edição
-
- %!include: introducao.t2t
- %!include: capitulo1.t2t
- %!include: capitulo2.t2t
- ...
- %!include: capitulo9.t2t
- %!include: conclusao.t2t
- </PRE>
- <P>
- Como se pode ver, basta informar o nome do arquivo logo após o comando
- <CODE>%!include</CODE>. Também é possível atrelar o comando a um destino
- específico, como em:
- </P>
- <PRE>
- %!include(html): arquivo.t2t
- </PRE>
- <P>
- Note que o <CODE>include</CODE> vai inserir o CORPO do documento .t2t, ignorando
- seu CABEÇALHO e suas CONFIGURAÇÕES. Assim é possível converter o arquivo
- incluído de maneira isolada ou como parte do documento mãe.
- </P>
- <P>
- Além de incluir arquivos .t2t, há mais três tipos de inclusão:
- </P>
- <UL>
- <LI>Inclusão de texto pré-formatado (Verbatim)
- <LI>Inclusão de texto protegido (Raw)
- <LI>Inclusão de texto já convertido (Tagged)
- </UL>
- <P>
- No tipo <B>Verbatim</B> o texto é incluído preservado seus espaços e
- formatação originais. É como se esse texto estivesse entre as marcações
- (```) da área VERB do txt2tags. Para incluir um arquivo dessa maneira,
- basta colocar seu nome entre crases:
- </P>
- <PRE>
- %!include: ``/etc/fstab``
- </PRE>
- <P>
- No tipo <B>Raw</B> o texto é incluído "como está", sem tentar encontrar e
- avaliar as marcas do txt2tags dele. É como se esse texto estivesse entre
- as marcações (""") da área protegida. Para incluir um arquivo dessa
- maneira, basta colocar seu nome entre aspas
- </P>
- <PRE>
- %!include: ""bom_texto.txt""
- </PRE>
- <P>
- Já no tipo <B>Tagged</B>, o texto é passado diretamente para o documento
- resultante, sem NENHUM tratamento pelo txt2tags. Assim é possível
- incluir tags adicionais, trechos já prontos ou estruturas mais
- complicadas que não são suportadas pelo programa. Outra aplicação é
- incluir um cabeçalho ou rodapé padrão em todos os documentos:
- </P>
- <PRE>
- %!include(html): ''rodape.html''
- </PRE>
- <P>
- Note que o nome do arquivo está entre aspas simples (e não crases como o
- anterior). São estas aspas que indicam que o conteúdo deve ser passado
- diretamente. Como este conteúdo já contém tags, é primordial especificar
- o destino também, para evitar problemas.
- </P>
- <HR NOSHADE SIZE=5>
- <H1 ID="settings">Parte V - Dominando as Diretivas de Configuração</H1>
- <P>
- As Diretivas de Configuração são todas opcionais. A maioria dos usuários
- pode muito bem passar sem elas. Mas elas são viciantes, se você começa a
- usá-las, não consegue parar :)
- </P>
- <HR NOSHADE SIZE=1>
- <H2 ID="toc23">%!Target</H2>
- <P>
- Usando a configuração Target define o destino padrão definido no
- documento:
- </P>
- <PRE>
- %!target: html
- </PRE>
- <P>
- Assim o usuário pode simplesmente comandar
- </P>
- <PRE>
- $ txt2tags file.t2t
- </PRE>
- <P>
- E a conversão será efetuada para o destino especificado.
- </P>
- <P>
- A configuração Target não permite a especificação opcional de destino.
- Afinal, não faz sentido algo como <CODE>%!target(tex): html</CODE>.
- </P>
- <HR NOSHADE SIZE=1>
- <H2 ID="toc24">%!Options</H2>
- <P>
- Escrever longas linhas de comando toda vez que for necessário converter
- um documento é maçante e sujeito a erros. A configuração Options permite
- que o usuário salve todas as opções de conversão juntas, no próprio
- documento. Desta forma também se garante que o documento sempre será
- convertido da mesma forma, com as mesmas opções.
- </P>
- <P>
- Só é necessário escrevê-la sem erros de sintaxe, como se estivesse na
- linha de comando. Mas omita a chamada ao programa "txt2tags" no início e
- o nome do arquivo origem no fim da linha.
- </P>
- <P>
- Por exemplo, se você usa esta linha de comando para converter seu
- documento:
- </P>
- <PRE>
- $ txt2tags -t html --toc --toc-level 2 --enum-title file.t2t
- </PRE>
- <P>
- Pode-se economizar um bocado de digitação usando esta configuração de
- Options dentro do documento origem:
- </P>
- <PRE>
- %!target: html
- %!options(html): --toc --toc-level 2 --enum-title
- </PRE>
- <P>
- A linha de comando real passa agora a ser apenas "<CODE>txt2tags file.t2t</CODE>",
- e a conversão pode ser executada dentro do seu editor de textos
- favorito, enquanto o conteúdo está sendo editado. No Vi, o comando é:
- </P>
- <PRE>
- :!txt2tags %
- </PRE>
- <HR NOSHADE SIZE=1>
- <H2 ID="toc25">%!Encoding</H2>
- <P>
- A configuração de Encoding é necessária para autores não ingleses, que
- usam letras acentuadas e outros detalhes específicos, de forma que o
- <I>Conjunto de Caracteres</I> do documento gerado possa ser personalizado
- (se possível).
- </P>
- <P>
- Os valores válidos para a configuração de Encoding são os mesmos que são
- válidos para documentos, HTML, como <I>UTF-8</I> e <I>koi8-r</I>. Se você
- não está certo de qual codificação quer usar,
- <A HREF="http://www.iana.org/assignments/character-sets">esta lista completa (e longa!)</A>
- poderá ser de ajuda.
- </P>
- <P>
- Quando for gerado documentos LaTeX, utiliza aliases para a codificação.
- Isto não deve ser problema para o usuário, já que o txt2tags faz a
- tradução internamente. Alguns exemplos:
- </P>
- <TABLE ALIGN="center" BORDER="1" CELLPADDING="4">
- <TR>
- <TH>txt2tags/HTML</TH>
- <TH>></TH>
- <TH>LaTeX</TH>
- </TR>
- <TR>
- <TD>windows-1250</TD>
- <TD>>>></TD>
- <TD>cp1250</TD>
- </TR>
- <TR>
- <TD>windows-1252</TD>
- <TD>>>></TD>
- <TD>cp1252</TD>
- </TR>
- <TR>
- <TD>ibm850</TD>
- <TD>>>></TD>
- <TD>cp850</TD>
- </TR>
- <TR>
- <TD>ibm852</TD>
- <TD>>>></TD>
- <TD>cp852</TD>
- </TR>
- <TR>
- <TD>iso-8859-1</TD>
- <TD>>>></TD>
- <TD>latin1</TD>
- </TR>
- <TR>
- <TD>iso-8859-2</TD>
- <TD>>>></TD>
- <TD>latin2</TD>
- </TR>
- <TR>
- <TD>koi8-r</TD>
- <TD>>>></TD>
- <TD>koi8-r</TD>
- </TR>
- </TABLE>
- <P>
- Se o valor é desconhecido do txt2tags, ele será passado sem tradução,
- permitindo que o usuário especifique codificações personalizadas.
- </P>
- <HR NOSHADE SIZE=1>
- <H2 ID="toc26">%!PreProc</H2>
- <P>
- O filtro de usuário PreProc é uma função "busca e troca" que é aplicada
- logo após a linha ter sido lida do arquivo original, antes de qualquer
- tratamento pelo txt2tags.
- </P>
- <P>
- Ela é útil para definir algumas abreviações para texto que seja usado
- comumente, como:
- </P>
- <PRE>
- %!preproc amj "Aurelio Marinho Jargas"
- %!preproc RELEASE_DATE "2004-07-13"
- %!preproc BOLOTA "[images/tiny/bullet_blue.png]"
- </PRE>
- <P>
- Desta forma, o usuário pode escrever uma linha como:
- </P>
- <PRE>
- Oi, eu sou amj. Hoje é RELEASE_DATE.
- </PRE>
- <P>
- E o txt2tags irá ver esta linha como:
- </P>
- <PRE>
- Oi, eu sou Aurelio Marinho Jargas. Hoje é 2004-07-13.
- </PRE>
- <P>
- Este filtro é um componente que trabalha entre o autor do documento e a
- conversão do txt2tags. É como uma primeira conversão antes da conversão
- "real". Este comportamento funciona exatamente como um filtro Sed/Perl
- externo, chamado assim:
- </P>
- <PRE>
- $ cat arquivo.t2t | preproc-script.sh | txt2tags -
- </PRE>
- <P>
- Assim, o tratamento executado pelo txt2tags irá começar após todas as
- substituições PreProc terem sido feitas.
- </P>
- <HR NOSHADE SIZE=1>
- <H2 ID="toc27">%!PostProc</H2>
- <P>
- O filtro de usuário PostProc é uma função do tipo "busca e troca" que é
- aplicada no arquivo resultante, após todos as conversões do txt2tags
- terem sido feitas.
- </P>
- <P>
- É útil para defintir alguns refinamentos no documento gerado, mudar
- algumas marcações e acrescentar algumas marcações ou texto extra.
- Alguns exemplos breves:
- </P>
- <PRE>
- %!postproc(html): '<BODY.*?>' '<BODY BGCOLOR="green">'
- %!postproc(tex) : "\\clearpage" ""
- </PRE>
- <P>
- Estes filtros mudam a cor de fundo da página HTML e removem as quebras
- de página em arquivos LaTeX gerados.
- </P>
- <P>
- As regras do PostProc são iguais a filtros externos Sed/Perl, chamados
- desta forma:
- </P>
- <PRE>
- $ txt2tags -t html -o- arquivo.t2t | postproc-script.sh > arquivo.html
- </PRE>
- <P>
- Antes desta funcionalidade ter sido introduzida, era bastante comum ter
- pequenos scripts para "ajustar" os resultados gerados pelo txt2tags.
- Estes scripts eram, de fato, vários comandos sed (ou assemelhados), para
- fazer algo do tipo "substitua isto por aquilo". Agora estas trocas podem
- ser salvas junto com o texto do documento, e também aproveitar-se da
- poderosa máquina de Expressões Regulares do Python para encontrar os
- padrões.
- </P>
- <HR NOSHADE SIZE=1>
- <H2 ID="toc28">%!Style</H2>
- <UL>
- <LI>Esta opção é útil na geração de arquivos HTML e XHTML, definindo o
- nome do arquivo CSS que será usado no documento gerado.
- <P></P>
- <LI>No formato LaTeX, essa opção é usada para carregar módulos com o
- <CODE>\usepackage</CODE>.
- <P></P>
- <LI>O mesmo efeito pode ser obtido com a opção de linha de comando
- <CODE>--style</CODE>.
- <P></P>
- <LI>A opção de linha de comando --style tem precedência sobre a
- configuração de %!style
- </UL>
- <HR NOSHADE SIZE=1>
- <H2 ID="toc29">Detalhes dos Filtros PreProc e PostProc</H2>
- <UL>
- <LI>Estes filtros foram acrescentados ao txt2tags na versão 1.6.
- <P></P>
- <LI>Filtros são uma função do tipo "buscar e trocar" (pense no sed)
- <P></P>
- <LI>O PREproc é aplicado logo após a linha ser lida, e o POSTproc é
- aplicado após todo o tratamento ter sido feito. Funcionam exatamente
- como em (UUOC à frente):
- <P></P>
- <PRE>
- $ cat file.t2t | preproc.sh | txt2tags | postproc.sh
- </PRE>
- <P></P>
- <LI>Escapes especiais como <CODE>\n</CODE> e <CODE>\t</CODE> são interpretados
- <P></P>
- <LI>Os filtros são cumulativos e são aplicados na mesma ordem em que são
- definidos
- <P></P>
- <LI>Os filtros devem receber exatamente DOIS argumentos
- <P></P>
- <LI>Para apagar uma string, troque ela por uma string vazia
- <PRE>
- %!postproc: "undesired string" ""
- </PRE>
- <P></P>
- <LI>Para evitar problemas, sempre use informar explicitamente para que
- destino se aplica o filtro quando estiver usando o PostProc para mudar
- marcações: <CODE>%!PostProc(destino): <isto> <aquilo></CODE>
- <P></P>
- <LI>As Expressões Regulares do Python podem ser utilizadas! Elas são
- similares às Regex do Perl. Por exemplo: troque todas as marcações "B"
- para "STRONG" no HTML:
- <P></P>
- <PRE>
- %!postproc(html): '(</?)B>' '\1STRONG>'
- </PRE>
- <P></P>
- <LI>Os argumentos dos filtros podem ser passados de 3 formas:
- <OL>
- <LI>Uma palavra simples, sem aspas ou plicas, como FOO (sem espaços)
- <LI>Uma string com aspas duplas, como em "FOO"
- <LI>Uma string com plicas ou apóstrofos, como em 'FOO'
- <P></P>
- </OL>
- <LI>Se seu padrão tem aspas, proteja as mesmas com plicas, e vice-versa.
- Alguns exemplos válidos:
- <PRE>
- %!postproc: PADRÃO TROCA
- %!postproc: "PADRÃO" "TROCA"
- %!postproc: 'PADRÃO' 'TROCA'
- %!postproc: PADRÃO "TROCA"
- %!postproc: "PADRÃO" 'TROCA'
- </PRE>
- </UL>
- <HR NOSHADE SIZE=1>
- <H2 ID="toc30">Definindo uma Configuração para um Tipo-Destino Específico</H2>
- <P>
- Desde a versão 1.6 do txt2tags, todas as Diretivas de Configuração podem
- ser especificadas para um destino específico, usando a sintaxe
- <CODE>%!key(target): value</CODE>. Desta forma, o usuário pode definir diferentes
- configurações para diverentes tipos de arquivos gerados.
- </P>
- <P>
- Este aspecto é especialmente útil nos filtros pre/postproc, mas pode ser
- utilizado em todas as diretrizes. Por exemplo, configurar diferentes
- valores de Encoding para HTML e LaTeX:
- </P>
- <PRE>
- %!encoding(html): UTF-8
- %!encoding(tex): latin1
- </PRE>
- <BLOCKQUOTE>
- <B>Nota:</B> O mapeamento de codificações para os nomes especiais
- LaTeX já é parte do txt2tags, o trecho acima é apenas um
- exemplo.
- </BLOCKQUOTE>
- <P>
- Para o <CODE>%!options</CODE>, pode ser interessante:
- </P>
- <PRE>
- %!target: sgml
- %!options(sgml): --toc
- %!options(html): --style foo.css
- %!options(txt ): --toc-only --toc-level 2
- </PRE>
- <P>
- Desta forma, o tipo de destino padrão é o SGML, com TOC. Se o usuário
- executar:
- </P>
- <PRE>
- $ txt2tags -t html file.t2t
- </PRE>
- <P>
- O tipo de destino HTML será feito, e <B>somente</B> as opções de
- <CODE>%!options(html)</CODE> serão usadas. Desta forma, a opçõa --style será
- usada e o arquivo HTML não terá TOC.
- </P>
- <H3>A Precedência é Diferente</H3>
- <P>
- Em geral, para as diretivas de configuração, a última encontrada é a
- usada, mas quando usar diretivas explícitas de tipo-destino, elas tem
- precedência sobre as genéricas, não importando qual vem antes. Assim:
- </P>
- <PRE>
- %!encoding(html): UTF-8
- %!encoding: latin1
- </PRE>
- <P>
- Irá expandir para 'UTF-8' quando chamado com <CODE>-t html</CODE> mesmo que
- 'latin1' seja definido logo após.
- </P>
- <H3>Filtros são Cumulativos</H3>
- <P>
- Os filtros pre/postproc não tem precedência e não se encaixam no esquema
- "último encontrado", eles são cumulativos. O usuário pode configurar
- múltiplos filtros, e eles serão aplicados na ordem em que são definidos.
- </P>
- <P>
- Por exemplo:
- </P>
- <PRE>
- %!postproc : ^ \t
- %!postproc(txt): ^ '> '
- </PRE>
- <P>
- Com estes filtros, todos os tipos-destino serão indentados por uma TAB.
- Se o tipo-destino é TXT, ele também receberá citações, como mensagens
- de email.
- </P>
- <PRE>
- Desta forma Minha bela linha.
- se tornará \t> Minha bela linha.
- </PRE>
- <H3>Em Resumo</H3>
- <UL>
- <LI>Para filtros, a ordem faz diferença e as regras genéricas <U>e</U>
- específicas ao tipo-destino serão usadas
- <P></P>
- <LI>Para outras configurações, <U>somente</U> o tipo-destino especificado é
- usado (se definido, é claro), não importando a ordem
- </UL>
- <H2 ID="toc31">RC, CONF e a precedência de linha de comando</H2>
- <P>
- Há três maneiras de dizer ao txt2tags quais opções e configurações usar:
- </P>
- <OL>
- <LI>O arquivo de usuário RC (<CODE>.txt2tagsrc</CODE>)
- <LI>A Área de Configurações CONF do documento
- <LI>As opções de linha de comando
- </OL>
- <P>
- E esta é a ordem exata de como as configurações são lidas e aplicadas.
- Logo, as configuraçõe dp arquivo RC são lidas primeiro, daí as
- configurações do fonte do documento vêm a seguir, sobreescrevendo as do
- RC e finalmente as opções da linha de comando, mais fortes do que as
- outras duas.
- </P>
- <P>
- Então se o "encoding" do documento foi definido nas três opções, a da
- linha de comando será a utilizada.
- </P>
- <HR NOSHADE SIZE=5>
- <H1 ID="toc32">Parte VI - Magia Negra</H1>
- <P>
- Este capítulo não é recomendado para novatos. Ele demonstra como fazer
- coisas estranhas com os filtros txt2tags, abusando de padrões complexos
- e Expressões Regulares.
- </P>
- <BLOCKQUOTE>
- <B>CUIDADO!</B> Os procedimentos detalhados a seguir NÃO são
- encorajados e podem acarretar danos. Até mesmo algum texto do
- arquivo fonte pode ser perdido no processo de conversão, não
- aparecendo no arquivo gerado. Use estas táticas se você
- realmente precisa delas e sabe o que está fazendo.
- </BLOCKQUOTE>
- <TABLE ALIGN="center" BORDER="1" CELLPADDING="4">
- <TR>
- <TH>Filtros são um recurso poderoso, mas podem ser perigosos!</TH>
- </TR>
- </TABLE>
- <TABLE ALIGN="center" BORDER="1" CELLPADDING="4">
- <TR>
- <TH>Filtros mal-feitos geram resultados inesperados.</TH>
- </TR>
- </TABLE>
- <P>
- Tenha isto em mente, sempre.
- </P>
- <HR NOSHADE SIZE=1>
- <H2 ID="toc33">Inserindo Múltiplas Linhas com %!PostProc (como regras CSS)</H2>
- <P>
- Nos filtros, o padrão de troca pode incluir múltiplas linhas usando o
- caractere de quebra de linha, <CODE>\n</CODE>.
- </P>
- <P>
- Esta funcionalidade pode ser útil para incluir regras CSS curtas em um
- arquivo HTML gerado, sem a necessidade de se criar um arquivo separado.
- É o caso deste Guia do Usuário, que usa estes filtros:
- </P>
- <PRE>
- %!postproc: <HEAD> '<HEAD>\n<STYLE TYPE="text/css">\n</STYLE>'
- %!postproc: (</STYLE>) 'body { margin:3em ;} \n\1'
- %!postproc: (</STYLE>) 'a { text-decoration:none ;} \n\1'
- %!postproc: (</STYLE>) 'pre,code { background-color:#ffffcc ;} \n\1'
- %!postproc: (</STYLE>) 'th { background-color:yellow ;} \n\1'
- </PRE>
- <P>
- Todos os filtros estão presos ao primeiro, ao substituir uma string que
- ele inseriu. desta forma, um simples "<HEAD>" torna-se:
- </P>
- <PRE>
- <HEAD>
- <STYLE TYPE="text/css">
- body { margin:3em ;}
- a { text-decoration:none ;}
- pre,code { background-color:#ffffcc ;}
- th { background-color:yellow ;}
- </STYLE>
- </PRE>
- <HR NOSHADE SIZE=1>
- <H2 ID="toc34">Criando Conteúdo "Específico ao Tipo Destino", com %!PreProc</H2>
- <P>
- Algumas vezes é necessário inserir algum texto só para um tipo destino
- específico, e não para outros. Este tipo de comportamento estranho pode
- ser feito usando alguns truques de PreProc.
- </P>
- <P>
- A idéia é inserir este texto extra no arquivo original como comentário,
- mas marcá-lo de forma que um filtro específico para aquele tipo destino
- irá "descomentar" aquelas linhas.
- </P>
- <P>
- Por exemplo, se um parágrafo extra deve ser acrescentado somente no tipo
- destino HTML. Coloque o texto em um comentário especial, como este:
- </P>
- <PRE>
- %html% Esta página HTML foi produzida pelo [txt2tags http://txt2tags.org].
- %html% Veja o arquivo fonte TXT [aqui fonte.t2t].
- </PRE>
- <P>
- Como todas estas linhas começam com <CODE>%</CODE>, elas são linhas de comentário e
- serão ignoradas. Mas se acrescentarmos este filtro especial:
- </P>
- <PRE>
- %preproc(html): '^%html% ' ''
- </PRE>
- <P>
- A string inicial é removida e aquelas linhas serão "ativadas", deixando
- de ser comentários. Como uma configuração específica a um tipo, este
- filtro será processado apenas quando for gerado um arquivo HTML.
- </P>
- <HR NOSHADE SIZE=1>
- <H2 ID="toc35">Mudando Marcas txt2tags com %!PreProc</H2>
- <P>
- Se o usuário for um guru de Expressões Regulares, ele pode personalizar
- a sintaxe do documento, mudando as marcações txt2tags padrão para algo
- que ele achar mais confortável.
- </P>
- <P>
- Por exemplo, uma TAB é a marca de citação. Se o usuário não gostar
- disto, ou se seu texto tenha um estranho relacionamento com as TABs, ele
- pode definir uma nova marca para texto citado. Digamos que colocar ">>>"
- seja sua escolha. Então ele irá precisar deste filtro simples:
- </P>
- <PRE>
- %!PreProc: '>>> ' \t
- </PRE>
- <P>
- E no documento original, o texto citado vai parecer algo tipo:
- </P>
- <PRE>
- >>> Este é um texto de citação.
- >>> O usuário definiu esta marca esquisita.
- >>> Mas elas serão convertidas para TABs pelo PreProc.
- </PRE>
- <P>
- Antes que a análise do programa comece, os ">>> " esquisitos serão
- convertidos em TABs e o txt2tags irá reconhecer a marca de citação.
- </P>
- <BLOCKQUOTE>
- <B>CUIDADO!</B> Regras PreProc extremas podem eventualmente mudar
- toda a sintaxe de marcação, e até mesmo gerar conflitos entre as
- marcações. Tenha muito cuidado quando trabalhar com estas
- regras.
- </BLOCKQUOTE>
- <HR NOSHADE SIZE=5>
- <H1 ID="historia">Parte VII - História do txt2tags</H1>
- <P>
- Em julho de 2001, foi lançada a primeira versão ao público do txt2tags
- (v0.1). Mas suas origens vem de mais de um ano antes daquele dia...
- </P>
- <P>
- Este capítulo ilustra em algumas palavras o desenvolvimento desta
- ferramenta desde a primeira linha ser escrita até a série atual.
- </P>
- <H2 ID="toc37">Janeiro de 1999: Pré História</H2>
- <P>
- Do autor:
- </P>
- <BLOCKQUOTE>
- <I>"Minha primeira tentativa de fazer uma ferramenta de</I>
- <I>conversão começou em 1999, como um script Bourne Shell</I>
- <I>que convertia texto com marcação em uma página HTML. Sim,</I>
- <I>Mais Outra ferramenta txt2html. Todo mundo já deve ter feito</I>
- <I>uma destas... Em resumo, ele reconhecia marcações simples</I>
- <I>como <CODE>*bold*</CODE>, <CODE>/italic/</CODE>, <CODE>_under_</CODE>, e escapava os</I>
- <I>caracteres especiais <CODE>< & ></CODE> do HTML. Não muito</I>
- <I>impressionante, mas ei, eu era novinho ;)"</I>
- </BLOCKQUOTE>
- <H2 ID="toc38">Junho 1999: Ainda Pré-História</H2>
- <P>
- O autor tem mais a dizer:
- </P>
- <BLOCKQUOTE>
- <I>"Passaram-se alguns meses, e um grande hype em torno de</I>
- <I>Sgml chegou à companhia que eu trabalhava (Conectiva). Então o</I>
- <I>txt2html tornou-se um script txt2sgml. Eu estava realmente</I>
- <I>tentando aprender sobre o SED* naquele tempo, de forma que o</I>
- <I>txt2tags na época era um script Bourne Shell com muito</I>
- <I>código SED."</I>
- </BLOCKQUOTE>
- <BLOCKQUOTE>
- * <B>SED:</B> UNIX Stream EDitor - uma ferramenta de edição
- automática de textos
- </BLOCKQUOTE>
- <P>
- Esta versão melhorada, com suporte a Sgml, oferecia suporte a mais
- estruturas como listas e texto preformatado. No seguinte arquivo
- exemplo, pode-se ver as origens das marcações txt2tags:
- </P>
- <PRE>
- * Esta é uma linha em negrito (NEGRITO orientado a linha? bem...)
-
- --
- - lista não numerada muito semelhante à lista do txt2tags
- - mas com estes -- para iniciar e terminar a lista
- --
-
- =----------------------
- Texto preformatado era delimitado pelo =-- padrão.
- Os outros ------- eram apenas cosméticos.
- =----------------------
- </PRE>
- <P>
- Ainda não era impressionante, mas o grande passo está chegando...
- </P>
- <H2 ID="toc39">Agosto de 2000: Não Mais Pré-História</H2>
- <P>
- TODO (txt2sgml.sed)
- </P>
- <H2 ID="toc40">Julho de 2001: Debute das séries 0.x (Lançamento Mundial)</H2>
- <P>
- TODO
- </P>
- <H2 ID="toc41">Setembro de 2002: Debute das séries 1.x</H2>
- <DL>
- <DT><B>Anúncio</B></DT><DD>
- Este release inicia a minha <I>série 1.x</I>.
- <P></P>
- Mais de um ano de atualizaçõs quase mensais e a <I>série 0.x</I>
- proporcionou-me muitos bons recursos, como Linha de Comando e
- interface Web, criação de Sumário (TOC), títulos e listas numerados,
- facilidades STDIN e STDOUT, arquivos de sintaxe vim/emacs e sete
- formatos de destino suportados.
- <P></P>
- Para a iniciar a <I>série 1.x</I> vou tentar me espalhar por aí, com uma
- boa interface GUI, muita documentação, lista de discussão, base de
- usuários, compatibilidade Unix/Windows/Mac e incluir mais destinos
- (como tex, rtf e xhtml).
- <P></P>
- Nesta versão 1.0 já estou com a corda toda, com uma roupa nova
- (Interface Gráfica Tk) e compatibilidade com Unix/Windows/Mac,
- manipulação de quebras de linhas e outros detalhes específicos de cada
- plataforma. Felizmente agora meu mestre pode usar os sistemas Linux,
- Windows 2000, Cygwin e MacOS 8.6 para me testar.
- </DL>
- <H2 ID="toc42">2002, 2003... e as História não pára</H2>
- <DL>
- <DT><I>06 Novembro 2002</I> - <B>Liberada minha nova versão 1.1</B></DT><DD>
- <P></P>
- Atenção! Por favor leia <I>cuidadosamnte</I> antes de me atualizar!
- <P></P>
- Esta nova v1.1 é uma <U><B>quebra de compatibilidade</B></U> .
- <P></P>
- Isto significa que antes de atualizar você deve verificar seus
- arquivos txt2tags atuais, e, possivelmente ajustá-los. Ignorar esta
- versão não é uma opção :) porque as próximas versões consideram que
- você arrumou os seus arquivos.
- <P></P>
- Por favor leia o "Guia de Sobrevivência de Atualização para a v1.1"
- para mais informações mais detalhadas sobre <I>o que</I> foi mudado e
- <I>como</I> ajustar os seus arquivos.
- <P></P>
- Mas há algumas boas novas, como:
- <UL>
- <LI>imagens agora podem apontar links, como <CODE>[[img.gif] www.abc.com]</CODE>
- <LI>novas regras de foldmethod=syntax no arquivo de sintaxe do Vim
- <LI>melhorias no detector de URL
- <P></P>
- </UL>
- <DT><I>03 Dezembro 2002</I> - <B>Lançamento da nova versão 1.2 (versão LaTeX)</B></DT><DD>
- <P></P>
- Oi! Finalmente aprendi um dos formatos de documento mais usado pelos
- geeks: <B><I>LaTeX</I></B>. Me execute com "<CODE>-t tex</CODE>" e veja seus arquivos
- .t2t tornarem-se LaTeX, prontos para compilar!
- <P></P>
- Ah! Estou ficando esperto e agora posso cuidar de mais de um arquivo
- ao mesmo tempo. Dica: "<CODE>*.t2t</CODE>"
- <P></P>
- E meu último novo recurso é a habilidade de tornar um arquivo HTML em
- um arquivo .t2t "quase pronto". Desculpem-me os não-usuários do vim
- porque isso só funciona neste editor.
- <P></P>
- O que você está esperando? Baixe-me agora e teste meus novos recursos:
- <CODE>txt2tags --toc -t tex *.t2t</CODE>
- <P></P>
- <DT><I>20 Dezembro 2002</I> - <B>Lançamento da nova versão 1.3</B></DT><DD>
- <P></P>
- Ufa, estou cansado! Muitas modificações foram feitas para esta versão
- e agora preciso de um tempo!
- <P></P>
- A novidade inclui uma nova marca (coisa rara de acontecer!) para texto
- protegido. Desta forma você pode facilmente incluir marcas no
- documento destino e eu prometo que não as vou considerar!
- <P></P>
- Um novo comando <I>Encoding</I> está disponível para permitir que
- usuários de todo o mundo especifiquem suas próprias codificações em
- seus documentos.
- <P></P>
- E há mais melhorias e ajustes, mas, por favor leia o arquivo ChangeLog
- por que agora vou dormir. zzZZzzzzZZZZzz...
- <P></P>
- <DT><I>18 Fevereiro 2003</I> - <B>Lançamento da nova versão 1.4</B></DT><DD>
- <P></P>
- I've enjoyed my <I>X-mas/New Year</I> vacation, then some lazy days on
- a hot Brazilian beach, what a great time! But now it is time to get
- back to work, so there's a new release of the most sexy text eater
- out there: <B>me!</B>
- <P></P>
- The burning sun has made lots of changes on me. I'm privately proud
- of my new ability to master table alignment. I can place the table
- centered or not, and I can place <I>each table cell</I> contents wherever
- I want! Left, Right, Centered... See AbuseMe! file for a
- demonstration.
- <P></P>
- The good news for HTML users is that now I've learned about that
- Cascading thing... SCC, CCS, CSS, I don't remember... Just use my
- new <CODE>--style</CODE> command line option or the <CODE>%!Style:</CODE> setting.
- <P></P>
- There's a new <CODE>--toclevel</CODE> option also, and I promisse I'll not make
- TOC deeper than the number you pass me.
- <P></P>
- Mmmmmm, there were some bug fixes also, but let's forget about them,
- you know I'm not buggy! ;)
- <P></P>
- <DT><I>09 Maio 2003</I> - <B>Lançamento da nova versão 1.5</B></DT><DD>
- <P></P>
- Tsc, Tsc... Almost three months from the last version, what a shame!
- But the new features will worth the delay.
- <P></P>
- The most important improvement is my new <CODE>%!cmdline</CODE> setting. Using
- it you can define default options for each document, and when
- converting, you can call me with no options at all! Example: You place
- a "<I>%!cmdline: -t html --toc</I>" line on your source document, then you
- can convert it with the simple "<I>txt2tags file.t2t</I>" command.
- <P></P>
- There is also a new <CODE>--outfile</CODE> option (<CODE>-o</CODE> for short) to set the
- output filename. If you specify "<I>-o -</I>", you get the same behaviour
- of the old <CODE>--stdout</CODE> option (which is now deprecated).
- <P></P>
- Talking about options, there are the new short <CODE>-H</CODE> and <CODE>-n</CODE> for the
- existing <CODE>--noheaders</CODE> and <CODE>--enumtitle</CODE> options. A nice quick
- example:
- <P></P>
- <PRE>
- txt2tags-v1.4 -t html --enumtitle --stdout file.t2t > new.html
- txt2tags-v1.5 -t html -n -o new.html file.t2t
- </PRE>
- <P></P>
- Ah! LaTeX target now supports images :)
- <P></P>
- <DT><I>23 Jul 2003</I> - <B>Lançamento da nova versão 1.6</B></DT><DD>
- <P></P>
- Hi there! Here I am again with fresh news.
- <P></P>
- Today my v1.6 was released. The main improvement is the new
- <CODE>%!preproc:</CODE> and <CODE>%!postproc:</CODE> user defined filters. They are used to
- do some strange things on documents (see User Guide). There's also a
- new mark + for explicit numbered titles, <I>+like this+</I>, so now you
- can mix normal titles with numbered ones, like a book with Appendix.
- <P></P>
- Now all the config settings can be linked with a especific target,
- using the new <CODE>%!key(target): value</CODE> syntax. The target specification
- is optional, so the parentesis and its contents can be omitted. A nice
- sample: <I>%!encoding(html): iso-8859-1</I>
- <P></P>
- Lots of user reported bugs was fixed, titles on LaTeX are unnumbered
- by default (as other targets) and the Gui was improved, showing
- <CODE>%!cmdline</CODE> contents (if any) and refreshing checkboxes when a new
- file is loaded. Gui also can receive options from the command line, as
- in <CODE>txt2tags --gui -n file.t2t</CODE>
- <P></P>
- <DT><I>30 Novembro 2003</I> - <B>Lançamento da nova versão 1.7</B></DT><DD>
- <P></P>
- Saiu a minha versão 1.7! Agora tenho o comando que os usuários mais
- pediram: <CODE>%!include</CODE>. Com ele você pode incluir texto, tags e até
- mesmo outro arquivo .t2t no documento original. Veja como fazer isso
- no <A HREF="#include">Guia do Usuário</A>.
- <P></P>
- Fora isso mais checagens foram adicionadas e bugs foram corrigidos.
- Os usuários do Emacs ficarão felizes com o arquivo novo de sintaxe.
- Os usuários do Vim continuarão felizes com o arquivo de sintaxe
- atualizado.
- <P></P>
- <B>MUITO IMPORTANTE:</B> Essa versão fecha a minha série 1.x, então não
- haverão versões 1.8 e 1.9. A próxima será a tão esperada 2.0, com
- código reescrito, conversões mais ricas e enxutas e suporte ao
- destino XHTML. Eu serei mais massa!
- <P></P>
- </DL>
- <HR NOSHADE SIZE=5>
- <P>
- Fim. (<A HREF="userguide-pt.t2t">veja o fonte</A>)
- </P>
- <!-- html code generated by txt2tags 2.6.641 (http://txt2tags.org) -->
- <!-- cmdline: txt2tags userguide-pt.t2t -->
- </BODY></HTML>