Diferenças entre edições de "Ajuda:Predefinições"

Revisão das 18h09min de 29 de setembro de 2010

Para articular todo o mecanismo de protecção, de documentação, de desenvolvimento e de testes das predefinições, cada predefinição pode ser dividida em várias páginas.

Em geral, na página da predefinição em si coloca-se somente o código da mesma. Todos os restantes elementos são colocados noutras páginas adicionais, que têm o mesmo nome da predefinição mais certos sufixos chave (terminações, adicionadas após o nome da página). Ver abaixo os sufixos em uso.

Estas páginas adicionais são opcionais, podendo não existir para muitas predefinições. Pode-se aceder a todas as páginas adicionais (ou criá-las se não existirem) seguindo os links da caixa que aparece no topo da página de cada predefinição.

Um exemplo prático desta separação em diversas páginas e da formatação adoptada no Think Finance para cada página, pode ser seguido na predefinição {{chamada para artigo (pp)}}. Por favor, utilize um formato semelhante ao criar novas predefinições.

Páginas das predefinições

Cada predefinição pode ser constituída por várias páginas, cujos nomes são:

• Predefinição:<nome>

Página do código - esta é a página da predefinição, com o código da mesma.

• Predefinição:<nome>/doc

Página da documentação - esta é a página de documentação da predefinição (identificada pelo sufixo /doc). Ela é incluída (transcluded) na página do código usando {{documentation}}.

• Predefinição:<nome>/cat

Página da categoria - nesta página deve colocar a categoria da predefinição. A predefinição {{documentation}} atribui esta categoria à página do código e categoriza automaticamente todas as restantes páginas noutras categorias próprias.

• Predefinição:<nome>/doc/parameterlist

Página dos parâmetros - esta página deve listar os parâmetros que a predefinição aceita, e as suas combinações mais comuns. Ela deve ser incluída (transcluded) na página de documentação e apresentada ao utilizador quando os parâmetros são incorrectamente usados.

• Predefinição:<nome>/dev

Página de desenvolvimento - esta página normalmente contém o mesmo código que a página do código, mas que pode ser alterado para fazer experiências e melhoramentos, sem alterar o código da predefinição. Os resultados podem ser verificados na página de testes antes de migrar o novo código para a página do código.

• Predefinição:<nome>/tst

Página de testes - esta página deve conter casos de teste para verificar o comportamento da predefinição em diferentes cenários de utilização, incluindo os casos limite nos quais as predefinições devem, mesmo assim, ter um comportamento elegante. Cada caso de teste deve ser chamado duas vezes: uma usando a página do código e uma segunda usando a página de desenvolvimento. Isto permite verificar facilmente o efeito de qualquer alteração.

Ligação entre as páginas

O elemento chave de ligação entre as páginas é a predefinição {{documentation}}, que deve ser colocada em todas as páginas de cada predefinição. Ela apresenta no topo das páginas da predefinição uma caixa com ligações para todas as outras páginas, permitindo a navegação fácil entre elas. As ligações apresentadas nesta caixa funcionam como é normal na wiki, mostrando se a página destino da ligação existe, ou não.

Categorização das páginas

Somente a página do código deve ser categorizada.

Vantagens do mecanismo de separação

Este mecanismo suporta o processo de desenvolvimento e melhoramento das predefinições, permitindo alterar o código na página de desenvolvimento e comparar os resultados do código novo com os do antigo na página de testes, sem que as novas versões sejam visíveis para os leitores da wiki até estarem finalizadas.

Para além de articular o mecanismo de desenvolvimento, a separação dos diferentes elementos permite que somente a página do código esteja protegida contra edições. Os utilizadores podem continuar a alterar as restantes páginas, por exemplo introduzindo melhorias na documentação ou experimentando alterações ao código na página de desenvolvimento, porque estas não estão protegidas. Para que uma alteração ao código, feita na página de desenvolvimento, seja adoptada na wiki, o utilizador deve pedir a um administrador que a migre para a página do código.

Um efeito final da separação dos elementos para fora da página do código, é que reduz o montante de processamento da wiki. Sempre que cada predefinição é usada, a wiki só precisa tratar a página do código, não tendo de processar todo o restante conteúdo, como teria se todos os elementos estivessem numa única página.