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

{Ttulo: Manual de parsewiki}
{Autor: Jaime E. Villate}
{Organizao: Universidade do Porto}
{Endereo: [mailto:villate@gnu.org villate@gnu.org] }
{Verso: 0.4}
{Data: 11 de Abril de 2002}
{Lngua: pt}

{Resumo: Parsewiki  um programa que permite transformar um ficheiro \
de texto, com alguma sintaxe simples do estilo ''Wiki'', em \
vrios outros formatos que incluem HTML, XHTML, Docbook e LaTeX. Este manual \
serve tambm como exemplo do tipo de sintaxe que pode ser usada \
no ficheiro de texto.}

{Copyright: Copyright, 2002 Jaime E. Villate. \
Autoriza-se a copia, distribuio e/ou modificao deste documento \
sob as condies da Licencia GNU para Documentao Livre, \
verso 1.1 ou posterior, publicada pela ''Free Software Foundation'', \
sem seces invariantes. Uma cpia da licena encontra-se \
no ficheiro GFDL.}

= Introduo =

O mtodo que propomos neste manual para produzir documentos, tem como
objectivo facilitar ao utilizador a escrita do documento e separar ao mximo
o contedo da apresentao. Basta saber umas poucas regras de sintaxe
para comear a escrever documentos que depois podem gerar vrios formatos
diferentes quando processados com '''parsewiki'''.

A vantagem dos sistemas ''wiki''  permitir que possa ser escrita rapidamente
uma verso final, com marcas de formatao mnimas, de forma quase to 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 ningum com
marcas estranhas. Uma outra grande vantagem deste sistema  que
independentemente do que for escrito no ficheiro fonte, sempre teremos um
ficheiro de sada. Nunca aparecero erros que impeam a criao do ficheiro
final; pode acontecer que o resultado no seja o esperado, mas nunca existiro
erros de sintaxe. Esta forma de escrever documentos tem resultado ser muito
til na criao de sites na web onde qualquer pessoa pode contribuir, como por
exemplo a enciclopdia [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 verso HTML:

   parsewiki manual-pt.txt > manual-pt.html

Depois convm ler em simultneo as duas verses, comparando-as para
entender o funcionamento das regras de formatao. Quem souber processar
um ficheiro ''Docbook/XML'' ou ''LaTeX'' para obter uma verso para impresso,
poder tambm 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 comear na primeira coluna. Se deixarmos
espao no comeo da linha, esta ser interpretada como parte de uma listagem
de programa e ser apresentada textualmente no ficheiro de sada. As linhas de
este pargrafo no tm qualquer espao inicial, o que faz com que sejam unidas
preenchendo as margens do bloco que ocupa o pargrafo; o mesmo comportamento
no ser apropriado no caso de apresentarmos um fragmento de cdigo de um
programa, sendo preciso inserir espaos 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 pargrafo e comear outro, deixamos pelo menos uma linha em
branco. O ttulo de uma seco escreve-se entre dois smbolos =, sem deixar
espao no comeo da linha, mas deixando espao entre os smbolos = e o texto
do ttulo; por exemplo:
    = Seco 1 =

Para subseces de vrios nveis, usa-se mais do que um smbolo =; por
exemplo:
    === Seco de nvel 3 ===


= Listas =

Existem trs tipos de listas: listas sem enumerar, listas enumeradas e listas
descritivas (glossrios). Cada item numa lista deve ocupar apenas uma linha
e no devem ser deixadas linhas em branco a menos que quisermos fechar a lista.
Quando o contedo 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 comear por um asterisco (sempre
na primeira coluna); por exemplo:
* Pode-se deixar ou no espao a seguir a cada asterisco.
* A lista termina quando aparecer uma linha com algo diferente de * na primeira coluna.
* Podemos distribuir \
o contedo de cada item em vrias \
linhas, se usarmos o caracter de continuao de linha (\).
Esta parte do texto j no faz parte da lista, e vai fazer com que comece um
novo pargrafo, a pesar de no termos deixado linha em branco no ficheiro
fonte (a linha em branco neste caso  optativa).

== Listas enumeradas ==

# Funcionam em forma semelhante s anteriores.
# A diferena est em que em vez de *, usa-se #.
# J veremos mais para a frente como incluir uma lista dentro de outra.

== Listas descritivas ==

So listas de termos seguidos pelas suas descries, como um dicionrio ou un
glossrio. Cada item comea com ponto e coma (;) na primeira coluna,
seguido pelo termo, seguido por dois pontos (:) e finalmente a sua
definio, tudo na mesma linha. Por exemplo:

;HTML: Usado para publicar contedo 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 dvida o melhor formato para produzir textos cientficos de boa \
qualidade.

== Listas dentro de outras listas ==
Para incluir uma lista dentro de outra, deve-se aumentar o '''nvel'''
da lista (ou as listas) que estejam dentro das outras; por exemplo:

# Esta  uma lista de nvel 1
# Dentro de este segundo item vem uma lista de nvel 2:
** O nvel aumenta-se aumentando o nmero de caracteres iniciais.
** Neste caso temos usado 2 asteriscos em vez de um.
# Aqui continuamos com a nossa lista inicial. Se quisssemos que este\
 item comea-se uma nova lista independente da primeira, teramos\
 deixado uma linha em branco.

# Por exemplo aqui comemos uma nova lista.
# Que incluir uma lista descritiva:
;;opo -t: Um ficheiro com um modelo que ser usado em vez do modelo\
 padro.
;;opo -f: Formato de sada. 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 espao depois de [. Exemplo: orgulho-me de ser membro do
[http://www.gnu.org Projecto GNU].

Enlaces "internos", com uma URL que no comea por ,,http://,, tero
de ser escritos entre [[ e ]]. Por exemplo, se o documento fonte de este
manual estiver no mesmo directrio onde foi gerada a verso HTML,
a pgina 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 extenso reconhecida
como um formato grfico visvel pelos navegadores web, a URL ser
substituda pela imagem (quando o formato de sada for HTML ou XHTML).
Por exemplo http://savannah.gnu.org/icons/back.png

Se quisermos que a figura aparea aparte do texto, dever ser posta num
pargrafo separado:

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

(Esta figura s aparecer nas verses HTML e XHTML pois nos outros
formatos no  possvel 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 directrio local, o caminho e nome
completo devero ser escritos dentro de [[ e ]].  necessrio que o nome da
figura termine em alguma das extenses reconhecidas por ,,parsewiki,,

  jpg jpeg png bmp gif

(que podem vir tambm em maisculas). Se assim no for, ser necessrio criar
uma verso 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 extenso ,,.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
tambm vem em formato PNG (,,barra.png,,). Poderemos v-la em todos os
formatos de sada assim:

[[barra.png]]

A verso PostScript obtida com ,,latex,, e ,,dvips,, usar o ficheiro
,,barra.ps,,. A verso PDF produzida por ,,pdflatex,, usar o ficheiro
,,barra.png,,, j que no existe neste caso um ficheiro ,,barra.pdf,,.

= Outros tipos de letras =

Pode-se obter letra itlica usando dois apstrofos seguidos, ou usando uma
marca <em> como em HTML: ''assim'' ou tambm
<em>assim</em>. Para letra bold
usam-se trs apstrofos ou a marca <strong>: '''3 apstrofos''' ou
<strong>strong</strong>. Para obter letra com espaamento constante, como
numa mquina 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 cdigo fonte de este manual ver-se- que tenho usado
essa caracterstica para evitar confuses 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 continuao de linha.

= Meta informao =

Alguma informao optativa sobre o documento pode ser includa no comeo,
usando a sintaxe: {nome: contedo}. Se ''nome'' for algum na lista a seguir:

  title author date organization address version abstract copyright

o correspondente contedo ser usado na parte inicial do documento.
Pode-se usar qualquer outro nome que no no esteja na lista, mas o seu
contedo ser ignorado, a menos que
modifiquemos o modelo usado normalmente.
A meta informao sobre um documento dever vir toda ao comeo do documento,
antes de qualquer outro texto, e cada conjunto {nome: contedo} dever
ocupar uma nica linha. De outra forma seria processado como texto normal.

= Modelos ==

O ficheiro de sada, em qualquer um  dos quatro formatos que podem ser
produzidos por ,,parsewiki,, cria-se
a partir de uns modelos definidos pelo
prprio programa. O subdirectrio ,,templates,, no arquivo distribudo
com este programa traz cpias 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 opo ,,-t,, de parsewiki:
  parsewiki -f latex -t ~/modelo.tex ficheiro.txt > ficheiro.tex

= Concluses =

O sistema simples que temos documentado neste manual permite criar
documentos em forma fcil e rpida. Devido  sua simplicidade, no 
possvel esperar que possa ser usado o mesmo sistema para documentos mais
complexos; no entanto, este mtodo
pode servir como base para criar uma verso inicial que depois seja
tornada mais complexa a partir do ficheiro LaTeX ou DocBook criado com
este mtodo.

Esta  uma verso beta e por isso provavelmente cheia de erros.
Os planos futuros incluem a implementao de tabelas, bibliografias y figuras
com legendas.