Make your own free website on Tripod.com

Documentação do sistema

Neste capítulo, serão mostradas as ferramentas de documentação disponíveis no Linux. Para documentar o sistema e elaborar um manual de usuário, foi adotado o DocBook e, para documentação das API's das classes, foi usado o DOxygen. Essas ferramentas são muito interessantes porque a partir de um único código fonte, elas geram documentação em vários formatos como páginas web (HTML), PostScript (PS), Portable Document Format (PDF) entre outros.

Documentando o sistema com o DocBook

Para escrever a documentação do sistema, bem como criar manual de utilização, podería ser escolhido qualquer processador de texto disponível no mercado, porém isso deixa o desenvolvedor preso ao formato que o processador escolhido disponibiliza, além do que no momento de escrever o texto, deve-se estar preocupado com a formatação do documento.

Para que o sistema possa ser mais flexível, a documentação deve estar disponível nos mais variados formatos que podem ser do gosto de quem vai usar, ou estudar essa documentação. Felizmente, existe o DocBook, uma ferramenta para escrever textos técnicos que, a partir de um arquivo ou conjunto de arquivos escritos em formato XML ou SGML, ele consegue gerar o documento nos formatos mais populares entre a comunidade do software livre.

Um outro motivo que levou a adotar essa ferramenta, foi que ela é recomentada pela TLDP - The Linux Documentation Project entidade que padroniza a documentação em sistemas Linux.

O DocBook, não é um programa, nem um processador de textos. Ele na verdade é um DTD (Document Type Definition - Definição de Tipo de Documento). Assim como o HTML, ele é uma linguagem de marcação definida em SGML/XML. Ao instalar o DocBook no sistema, devem ser instaladas também algumas ferramentas que vão ler o arquivo SGML/XML e, de acordo com o DTD e as folhas de estilo, vão gerar o documento final. Essa conversão é feita usando um dos scripts disponibilizados pelas distribuições Linux. Para gerar o documento em formato HTML, usa-se o docbook2html. Para gerar em Postscript, é usado o docbook2ps.

A grande vantagem de usar esse tipo de ferramenta para escrever a documentação, é que não é preciso se preocupar com a forma com que o documento será gerado, mas apenas com seu conteúdo. Ao escrever um parágrafo, não é informado ao DocBook o espaçamento ou o tamanho das letras, apenas é dito onde começa e onde termina o parágrafo. Também não é necessário se preocupar em montar índices, lista de tabelas e figuras. Quando as ferramentas forem processar o arquivo, estes elementos são criados automaticamente.

Um exemplo de documento escrito usando o DocBook é este trabalho. Ele foi escrito em formato SGML e depois foi processado para gerar o documento final. Esse modo de escrever pode poupar um bocado de tempo do autor, que tem a única preocupação de escrever o texto, de entender o conteúdo. A formatação é toda feita pelo DTD com as folhas de estilo.

Na Figura 1, é mostrado um trecho do fonte deste documento em formato SGML. Note que são usadas tags similares às do HTML para indicar o início e o fim de um tipo de texto (parágrafo, texto itálico).

<para>
Para ilustrar o funcionamento do Umbrello, ser&aacute;
mostrado como definir a classe
<classname>DListaFormaPagto</classname>.
Esta classe &eacute; respons&aacute;vel por obter
os dados das formas de pagamento do banco de dados para
que seja elaborada uma lista que ser&aacute; exibida
ao usu&aacute;rio. Depois de criada a classe, deve-se
dar um duplo clique sobre ela para abrir a janela de
propriedades que &eacute; onde s&atilde;o
informados os atributos, m&eacute;todos e
documenta&ccedil;&atilde;o da classe.
</para>
<para>
A primeira tarefa &eacute; documentar a classe,
indicando para que ela serve e fornecendo uma
vis&atilde;o geral sobre seu funcionamento.
N&atilde;o &eacute; necess&aacute;rio neste
momento entrar em detalhes sobre os atributos e
m&eacute;todos porque eles ter&atilde;o sua
pr&oacute;pria documenta&ccedil;&atilde;o.
</para>

<figure>
  <title>Umbrello - documentando uma classe</title>
  <graphic format="png" align="center" scale="25"
    fileref="figuras/umbrello08.png">
</figure>

Figura 1. Trecho de um arquivo no formato SGML

Para escrever o arquivo SGML, pode ser usado qualquer editor de texto que consiga gravar texto puro. Se for usado processador de texto como OpenOffice ou Word, deve-se ter o cuidado de, ao gravar o arquivo, selecionar o formato texto, para que ele não seja gravado no formato proprietário do processador escolhido.

Depois do documento todo digitado, deve-se usar um dos scripts disponíveis para gerar o documento em sua forma final. O Docbook gera o documento em uma forma padrão que pode ser alterada. Para fazer essa alteração, deve-se trabalhar com as folhas de estilo que define a forma final do documento.

Para aprender como escrever documentos usando o DocBook, é indicada a leitura de [DOCBOOK], que é um guia para o DTD, També é recomendada a leitura de [DSSSL] e [XSLT] para aprender a trabalhar com folhas de estilo para gerar o documento final a partir de fontes SGML e XML respectivamente.