{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 como em HTML: ''assim'' ou também assim. Para letra bold usam-se três apóstrofos ou a marca : '''3 apóstrofos''' ou strong. Para obter letra com espaçamento constante, como numa máquina de escrever, usam-se duas comas ou a marca ; 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 sem uma 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.