Usando o Mallard para documentação geral

Na qualidade de médico de família e comunidade, tenho que lidar com uma variedade de problemas muito grande. (Confira meu blog sobre Saúde da Famíla!) Na maioria das situações, as informações de que preciso já foram assimiladas. Em outras situações, preciso consultar a Internet, ou um livro sobre medicamentos, ou uma lista com os códigos para todas as doenças conhecidas pelo homem (e viva o Classix). Mas existe também um meio-campo, de informações que talvez eu esqueça, ou pequenas listas de dados, e para isso eu tenho usado há alguns meses o Mallard.

O Mallard é o novo sistema de documentação do GNOME. Tem uma ênfase em documentos avulsos (em vez de aninhados) e focados cada um num tópico, como na Wikipédia. De quebra, traz uma nova linguagem XML, muito mais fácil que a do DocBook, usada até então. A Equipe de Documentação do GNOME está convertendo a documentação do GNOME aplicativo por aplicativo, e as pessoas envolvidas parecem estar gostando da experiência.

Deixando de lado a sintaxe específica para software (telas, código-fonte etc.), o Mallard é muito adequado para qualquer documento que seja consultado através de um computador. É claro que não faltam alternativas, mas para mim tudo se encaixou perfeitamente. É claro que ser parte do GNOME também ajuda!

Cada assunto fica num arquivo, e todos os arquivos estão num mesmo diretório. Para abrir o diretório, basta executar yelp $DIRETÓRIO — vale até criar um lançador na barra de ferramentas ou na área de trabalho (vamos ver como isso fica com o GNOME Shell). Também é possível converter para HTML ou XHTML usando o gnome-doc-tool, e então abrir com o navegador comum. A única limitação séria do Mallard é que, por enquanto, o caminho do diretório não pode conter caracteres não ASCII (cedilha, acento, til…).

Existia um projeto de editor amigável para o Mallard, mas até hoje não vi o produto. Agora está sendo desenvolvida uma interface web para a edição da documentação do GNOME. Não resolve muito o meu problema, mas tudo bem. Basta editar os arquivos XML no editor de textos favorito, o que no meu caso é o gedit. (Também gosto muito do Vim, mas não para XML. Vai entender.) O destaque de sintaxe ajuda muito, e a ferramenta de inserção de trechos (para destaque XML, não Mallard) também. A documentação on-line do Mallard é muito boa, um dia desses tenho que dar um jeito de copiar para o meu disco rígido. (Nem sempre tenho acesso à Internet.)

Em suma, o Mallard é uma ótima forma de manter documentação, seja para software ou para outros fins. Sugiro a todos que confiram o tutorial de dez minutos, para sentir como funciona!

3 respostas em “Usando o Mallard para documentação geral

    • Eu também gosto do txt2tags, e até comecei a usá-lo com essa finalidade. Mas com o Mallard o processo estava funcionando mais redondo para mim, inclusive porque a atualização do índice é automática. Sem contar com a folha de estilo, que é bem adequada🙂

Deixe uma resposta

Preencha os seus dados abaixo ou clique em um ícone para log in:

Logotipo do WordPress.com

Você está comentando utilizando sua conta WordPress.com. Sair / Alterar )

Imagem do Twitter

Você está comentando utilizando sua conta Twitter. Sair / Alterar )

Foto do Facebook

Você está comentando utilizando sua conta Facebook. Sair / Alterar )

Foto do Google+

Você está comentando utilizando sua conta Google+. Sair / Alterar )

Conectando a %s