Manual de parsewiki

Jaime E. Villate
Universidade do Porto
villate@gnu.org

versão 0.4

11 de Abril de 2002

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.

Introdução

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

Regras elementares

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

Listas

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.

Listas sem enumerar

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

Listas enumeradas

  1. Funcionam em forma semelhante às anteriores.
  2. A diferença está em que em vez de *, usa-se #.
  3. Já veremos mais para a frente como incluir uma lista dentro de outra.

Listas descritivas

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:

HTML
Usado para publicar conteúdo na Web ou para consultar localmente com um navegador web.
XHTML
A linguagem proposta para substituir ao HTML, com todas as vantagens do XML.
DocBook
Um tipo de documentos XML muito na moda no mundo editorial.
LaTeX
Sem dúvida o melhor formato para produzir textos científicos de boa qualidade.

Listas dentro de outras listas

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:

  1. Esta é uma lista de nível 1
  2. Dentro de este segundo item vem uma lista de nível 2:
  3. Aqui continuamos com a nossa lista inicial. Se quiséssemos que este item começa-se uma nova lista independente da primeira, teríamos deixado uma linha em branco.
  1. Por exemplo aqui começámos uma nova lista.
  2. Que incluirá uma lista descritiva:
    opção -t
    Um ficheiro com um modelo que será usado em vez do modelo padrão.
    opção -f
    Formato de saída. Pode ser:
    • html
    • xhtml
    • docbook
    • latex
  3. Aqui termina a lista.

Enlaces (hyperlinks)

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.

Figuras

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 http://savannah.gnu.org/icons/back.png

Se quisermos que a figura apareça aparte do texto, deverá ser posta num parágrafo separado:

http://savannah.gnu.org/images/floating.jpg

(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:

Logotipo de GNU

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:

barra.png

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.

Outros tipos de letras

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.

Meta informação

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.

Modelos

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

Conclusões

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.