Parsewiki é um programa que permite transformar um ficheiro de texto, com alguma sintaxe simples do estilo Wiki, em vários outros formatos que incluem HTML, XHTML, Docbook e LaTeX. Este manual serve também como exemplo do tipo de sintaxe que pode ser usada no ficheiro de texto.
Copyright, 2002 Jaime E. Villate. Autoriza-se a copia, distribuição e/ou modificação deste documento sob as condições da Licencia GNU para Documentação Livre, versão 1.1 ou posterior, publicada pela Free Software Foundation, sem secções invariantes. Uma cópia da licença encontra-se no ficheiro GFDL.
O método que propomos neste manual para produzir documentos, tem como objectivo facilitar ao utilizador a escrita do documento e separar ao máximo o conteúdo da apresentação. Basta saber umas poucas regras de sintaxe para começar a escrever documentos que depois podem gerar vários formatos diferentes quando processados com parsewiki.
A vantagem dos sistemas wiki é permitir que possa ser escrita rapidamente uma versão final, com marcas de formatação mínimas, de forma quase tão simples como escrever texto numa mensagem de correio. O texto fonte pode ser lido facilmente e até enviado em mensagens de correio, sem assustar a ninguém com marcas estranhas. Uma outra grande vantagem deste sistema é que independentemente do que for escrito no ficheiro fonte, sempre teremos um ficheiro de saída. Nunca aparecerão erros que impeçam a criação do ficheiro final; pode acontecer que o resultado não seja o esperado, mas nunca existirão erros de sintaxe. Esta forma de escrever documentos tem resultado ser muito útil na criação de sites na web onde qualquer pessoa pode contribuir, como por exemplo a enciclopédia Wikipedia.
Para aprender a usar este sistema, recomenda-se usar o documento fonte
deste manual (manual-pt.txt) processando-lo com parsewiki para
produzir uma versão HTML:
parsewiki manual-pt.txt > manual-pt.html
Depois convém ler em simultâneo as duas versões, comparando-as para entender o funcionamento das regras de formatação. Quem souber processar um ficheiro Docbook/XML ou LaTeX para obter uma versão para impressão, poderá também usar os seguintes comandos para obter um ficheiro Docbook/XML ou LaTeX
parsewiki -f docbook manual-pt.txt > manual-pt.xml parsewiki -f latex manual-pt.txt > manual-pt.tex
A primeira regra a ter em conta para escrever um documento
é que o texto em cada linha deve começar na primeira coluna. Se deixarmos
espaço no começo da linha, esta será interpretada como parte de uma listagem
de programa e será apresentada textualmente no ficheiro de saída. As linhas de
este parágrafo não têm qualquer espaço inicial, o que faz com que sejam unidas
preenchendo as margens do bloco que ocupa o parágrafo; o mesmo comportamento
não será apropriado no caso de apresentarmos um fragmento de código de um
programa, sendo preciso inserir espaços no inicio de cada linha. Por exemplo,
uma subrutina no programa parsewiki é:
sub WikiHeading
{
my ($depth, $text) = @_;
$depth = length($depth);
$depth = 5 if ($depth > 5);
return $OpenItem{'h'.$depth} . $text . $CloseItem{'h'.$depth} . "\n";
}
Para terminar um parágrafo e começar outro, deixamos pelo menos uma linha em branco. O título de uma secção escreve-se entre dois símbolos =, sem deixar espaço no começo da linha, mas deixando espaço entre os símbolos = e o texto do título; por exemplo:
= Secção 1 =
Para subsecções de vários níveis, usa-se mais do que um símbolo =; por exemplo:
=== Secção de nível 3 ===
Existem três tipos de listas: listas sem enumerar, listas enumeradas e listas descritivas (glossários). Cada item numa lista deve ocupar apenas uma linha e não devem ser deixadas linhas em branco a menos que quisermos fechar a lista. Quando o conteúdo de um item for muito comprido, poderemos cortar uma linha, colocando um \ no fim para indicar que a linha continua na seguinte.
Cada item numa lista sem enumerar deve começar por um asterisco (sempre na primeira coluna); por exemplo:
Esta parte do texto já não faz parte da lista, e vai fazer com que comece um novo parágrafo, a pesar de não termos deixado linha em branco no ficheiro fonte (a linha em branco neste caso é optativa).
São listas de termos seguidos pelas suas descrições, como um dicionário ou un glossário. Cada item começa com ponto e coma (;) na primeira coluna, seguido pelo termo, seguido por dois pontos (:) e finalmente a sua definição, tudo na mesma linha. Por exemplo:
Para incluir uma lista dentro de outra, deve-se aumentar o nível da lista (ou as listas) que estejam dentro das outras; por exemplo:
Sempre que se escrever uma URL como por exemplo http://www.usemod.com/cgi-bin/wiki.pl, será reconhecida por parsewiki e aparecerá com um enlace à respectiva URL. Para associar um texto ao enlace, escreve-se a URL seguida pelo texto, dentro dos caracteres [ e ] sem deixar espaço depois de [. Exemplo: orgulho-me de ser membro do Projecto GNU.
Enlaces "internos", com uma URL que não começa por http:// terão
de ser escritos entre [[ e ]]. Por exemplo, se o documento fonte de este
manual estiver no mesmo directório onde foi gerada a versão HTML,
a página HTML terá um enlace ao ficheiro fonte aqui: manual-pt.txt.
Ou se quiser usar algum texto: Ficheiro fonte de este manual.
Se uma URL terminar com um nome de ficheiro que tem uma extensão reconhecida
como um formato gráfico visível pelos navegadores web, a URL será
substituída pela imagem (quando o formato de saída for HTML ou XHTML).
Por exemplo
Se quisermos que a figura apareça aparte do texto, deverá ser posta num parágrafo separado:
(Esta figura só aparecerá nas versões HTML e XHTML pois nos outros formatos não é possível apresentar figuras algures na web). Se associarmos algum texto à URL da figura, em vez de aparecer a figura dentro do documento, obteremos um enlace para a figura:
Se a figura se encontrar dentro dum directório local, o caminho e nome
completo deverão ser escritos dentro de [[ e ]]. É necessário que o nome da
figura termine em alguma das extensões reconhecidas por parsewiki
jpg jpeg png bmp gif
(que podem vir também em maiúsculas). Se assim não for, será necessário criar
uma versão em algum desses formatos. No caso de LaTeX produzido com
parsewiki, a pesar de se usar um destes formatos, espera-se que exista o
mesmo ficheiro mas com extensão .ps ou .eps, quando se usar
dvips; se for usado pdflatex em vez, este esperará encontrar ficheiros
terminados em .jpg, .jpeg, .png ou .pdf.
Junto com este manual distribui-se uma figura vectorial barra.ps que
também vem em formato PNG (barra.png). Poderemos vé-la em todos os
formatos de saída assim:
A versão PostScript obtida com latex e dvips usará o ficheiro
barra.ps. A versão PDF produzida por pdflatex usará o ficheiro
barra.png, já que não existe neste caso um ficheiro barra.pdf.
Pode-se obter letra itálica usando dois apóstrofos seguidos, ou usando uma
marca <em> como em HTML: assim ou também
<em>assim</em>. Para letra bold
usam-se três apóstrofos ou a marca <strong>: 3 apóstrofos ou
<strong>strong</strong>. Para obter letra com espaçamento constante, como
numa máquina de escrever, usam-se duas comas ou a marca <tt>; por
exemplo "ls --color".
Nos 3 casos o texto em letra diferente deve estar dentro de uma única
linha; observando o código fonte de este manual ver-se-á que tenho usado
essa característica para evitar confusões quando escrevi a marca <em>
sem uma </em> companheira (e mais uma vez o mesmo truque :-). Se o texto
for muito comprido, pode-se usar o caracter de continuação de linha.
Alguma informação optativa sobre o documento pode ser incluída no começo, usando a sintaxe: {nome: conteúdo}. Se nome for algum na lista a seguir:
title author date organization address version abstract copyright
o correspondente conteúdo será usado na parte inicial do documento. Pode-se usar qualquer outro nome que no não esteja na lista, mas o seu conteúdo será ignorado, a menos que modifiquemos o modelo usado normalmente. A meta informação sobre um documento deverá vir toda ao começo do documento, antes de qualquer outro texto, e cada conjunto {nome: conteúdo} deverá ocupar uma única linha. De outra forma seria processado como texto normal.
O ficheiro de saída, em qualquer um dos quatro formatos que podem ser
produzidos por parsewiki cria-se
a partir de uns modelos definidos pelo
próprio programa. O subdirectório templates no arquivo distribuído
com este programa traz cópias dos 4 modelos usados intrinsecamente.
Podem ser usados como base para produzir outros modelos diferentes que se
ajustem ao formato desejado. Se, por exemplo, temos modificado
o modelo para LaTeX ficando no ficheiro
~/modelo.tex, poderemos usá-lo por meio da opção -t de parsewiki:
parsewiki -f latex -t ~/modelo.tex ficheiro.txt > ficheiro.tex
O sistema simples que temos documentado neste manual permite criar documentos em forma fácil e rápida. Devido à sua simplicidade, não é possível esperar que possa ser usado o mesmo sistema para documentos mais complexos; no entanto, este método pode servir como base para criar uma versão inicial que depois seja tornada mais complexa a partir do ficheiro LaTeX ou DocBook criado com este método.
Esta é uma versão beta e por isso provavelmente cheia de erros. Os planos futuros incluem a implementação de tabelas, bibliografias y figuras com legendas.
