Origem: Wikipédia, a enciclopédia livre.

Guia do Usuário Txt2tags Aurelio, 11/03/04 19:03:46

Esta página Wiki é o próprio manual do usuário que tem sua versão completa em http://txt2tags.sourceforge.net/pt/guia-usuario.html

[editar] Sobre este documento

 Olá, eu sou o guia do usuário do txt2tags!
 Aqui você encontra toda a informação disponível sobre a
 ferramenta de conversão de textos txt2tags.
 Minha versão atualizada pode ser encontrada em
 [1]
 Para mais informações e versões recentes, visite
 o website do txt2tags.
 Bom proveito!

[editar] Parte I - Introdução ao Txt2tags

[editar] Suas Primeiras Questões

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

[editar] O Que É?

O txt2tags é uma ferramenta de formatação e conversão de texto.

O txt2tags converte um arquivo texto com algumas marcas para qualquer um dos tipos de arquivos suportados:

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

[editar] Por Quê Eu Devo Usá-lo?

Você achará o txt2tags bastante útil se você:

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

E a motivação principal é:

economizar tempo, escrevendo conteúdo, sem se preocupar com formatação

[editar] Quais vantagens oferece em relação a outras ferramentas?

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

[editar] Tenho que pagar por ele?

Absolutamente NÃO!

O txt2tags é um programa gratuito, GPL, open source, domínio público, etc...

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.

Ele pode ser encontrado em http://txt2tags.sourceforge.net/pt que também conta com vasta documentação

[editar] Estruturas de Formatação Suportadas

Segue uma lista de todas as estruturas suportadas pelo txt2tags.

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

[editar] Formatos Suportados

HTML

Todo mundo sabe o que o HTML é (dica: Internet).

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 "HTML 4.0 Transitional".

Desde a versão 2.0, o código HTML gerado pelo txt2tags é 100% aprovado

pelo [vhttp://validator.w3.org/ validador w3c].

XHTML

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 "HTML 4.0 Transitional".

Desde a versão 2.0, o código XHTML gerado pelo txt2tags é 100% aprovado pelo [vhttp://validator.w3.org/ validador w3c].

SGML

O SGML é um formato de documento comum que possui aplicações de conversão, como sgmltools. 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).

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.

LATEX

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

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.

MAN

As páginas man do UNIX resistiram pelos anos. Formatos de documento vem e vão, e elas estão aí, imbatíveis.

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.

MGP

O Magic Point é 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.

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.

Observação 1: 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.

Observação 2: 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 {{{startx -- -bpp 8}}}) a apresentação vai ter boa aparência.

A chave é: converta e use. Não há necessidade de remendos ou de outros requisitos.

MOIN

Você não sabe o que é o MoinMoin? Ele é um WikiWiki!

A sintaxe do Moin é um pouco chata, quando você tem que ficar {{{{{{acrescentando chaves e plicas}}}}}}, mas o txt2tags vem com as marcações simplificadas e uma solução unificada: uma fonte, múltiplos formatos destino.

PM6

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.

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. EPA: Sem quebras de linha! Um parágrafo deve ser uma única linha.

Nota do Autor: Todo meu livro em português sobre expressões regulares foi escrito no vi, convertido para o formato do PageMaker com o txt2tags e então mandado para o prelo.

TXT

TXT é texto. O único tipo de formatação verdadeiro.

Apesar das marcações do txt2tags serem bem intuitivas e discretas, pode-se removê-las ao converter o arquivo para TXT puro.

Os títulos são sublinhados, e o texto é basicamente deixado como está no código fonte.

[editar] Situação dos Formatos-Destino para as Estruturas Suportadas

[editar] As Três Interfaces ao Usuário: GUI, Web e Linha de Comando

Assim como diferentes usuários possuem diferentes necessidades e ambientes, o txt2tags é bastante flexivel na forma de ser usado.

Existem três Interfaces de Usuário para o programa, cada uma atendendo a um objetivo definido e com funcionalidades próprias.

• GUI: Escrita em Tk, traz as janelas e os cliques para o txt2tags.
• Web: Escrita em PHP, permite que o usuário execute o txt2tags no navegador, não exigindo instalação do lado do cliente.
• Linha de Comando: Escrita em Python, é o núcleo do programa.

Todas as funcionalidades estão disponíveis como opções de linha de comando.

[editar] Interface Gráfica Tk

Desde a versão 1.0, há uma bela Interface Gráfica, que funciona do Linux, Windows, Mac e outros.

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 {{{--gui}}}. Se estiver faltando algum recurso o programa irá alertar.

Nota: O módulo Tkinter é necessário. Como ele vem com a distribição padrão do Python você já deve tê-lo.

Ela é bastante simples e fácil de usar:

         [../userguide/gui.png]          

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

Uma boa opção a selecionar é "Dump to screen", 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.

As cores padrão podem ser mudadas no arquivo {{{~/.txt2tagsrc}}}, configurando em {{{%!guicolors}}}. Por exemplo:

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

[editar] Interface Web

A Interface Web está em funcionamento na Internet no endereço [2], permitindo que o programa possa ser usado e testado antes de ser copiado.

         [../userguide/web.png]          

Esta interface também pode ser colocada na intrant para uso local, evitando a instalação do txt2tags em todas as máquinas.

[editar] Interface de Linha de Comando

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

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-suggar    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-suggar

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.