{CVS: $Id: manual-pt.txt,v 1.6 2002/04/11 19:51:57 villate Exp $ }

{Título: Manual de parsewiki}
{Autor: Jaime E. Villate}
{Organização: Universidade do Porto}
{Endereço: [mailto:villate@gnu.org villate@gnu.org] }
{Versão: 0.4}
{Data: 11 de Abril de 2002}
{Língua: pt}

{Resumo: 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: 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 [http://www.wikipedia.com 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:
* Pode-se deixar ou não espaço a seguir a cada asterisco.
* A lista termina quando aparecer uma linha com algo diferente de * na primeira coluna.
* Podemos distribuir \
o conteúdo de cada item em várias \
linhas, se usarmos o caracter de continuação de linha (\).
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 ==

# Funcionam em forma semelhante às anteriores.
# A diferença está em que em vez de *, usa-se #.
# 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:

# Esta é uma lista de nível 1
# Dentro de este segundo item vem uma lista de nível 2:
** O nível aumenta-se aumentando o número de caracteres iniciais.
** Neste caso temos usado 2 asteriscos em vez de um.
# 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.

# Por exemplo aqui começámos uma nova lista.
# 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
# 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
[http://www.gnu.org 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: [[manual-pt.txt 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:

[http://www.gnu.org/graphics/gnu-head-sm.jpg 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.
