Documentação Web

Colaboração: Rubens Queiroz de Almeida

Data de Publicação: 19 de Janeiro de 2005

A citação de documentos localizados na Internet é algo extremamente complicado devido à grande rapidez com que documentos são publicados, alterados e removidos. Coletâneas de links de um ou mais anos frequentemente apresentam uma alta taxa de documentos não mais existentes ou que mudaram de lugar.

Por esta razão, sempre que as normas de distribuição dos documentos o permitirem, é conveniente obter uma cópia dos documentos referenciados de forma a que se possa ter ao alcance a informação necessária sempre que dela precisarmos, mesmo que ele venha a ser removido da web.

Para nos auxiliar nesta tarefa existe a ferramenta HTMLDOC. Esta ferramenta, na versão 1.18.24, é hoje distribuída sob uma licença comercial e uma licença livre. A versão comercial, pacote básico, é encontrada no site da empresa Easy Software Products, por um preço de U$ 49,95. . O código fonte pode ser encontrado em um site separado. Neste site você encontra o código fonte, que pode ser compilado para uso em sistemas GNU/Linux, Macintosh, Solaris e Windows. Não são distribuídas neste site versões compiladas. Softwares distribuídos sob a licença GPL podem ser usados, distribuídos e modificados livremente.

A empresa criadora do HTMLDOC é também a desenvolvedora do CUPS (Common Unix Printing System) e do EPM (ESP Package Manager), também distribuídos sob a GPL. O sistema CUPS é um dos sistemas de impressão mais conhecidos e usados em plataformas GNU/Linux. Para o sistema Debian GNU/Linux, o software pode ser instalado diretamente, fazendo parte dos repositórios da distribuição.

Resumidamente, a principal funcionalidade do software HTMLDOC é a criação de livros cujo conteúdo possa ser obtido a partir do download de páginas Web. A coletânea pode conter, opcionalmente, um sumário. As páginas podem também ser formatadas incluindo cabeçalho e rodapé configurados segundo alguns parâmetros pré-definidos.

Os livros gerados desta forma podem ser salvos em três formatos: PDF, PostScript e HTML. É recomendável que qualquer material disponibilizado via Web seja distribuído em dois ou mais formatos, para atender a pessoas com necessidades especiais, que podem não ter softwares adequados para visualizar documentos em um formato determinado, como por exemplo PDF.

Para começar a criar sua coletânea, clique no botão Add URL, ou Add File, caso você queira incluir um endereço Web (URL) ou um arquivo residente em seu computador.

Em seguida aparecerá uma tela onde você poderá então fornecer o elemento desejado:

Faça assim para todos os documentos que deseja incluir. Encerrada esta etapa podemos solicitar então que o documento seja gerado. Para tal precisamos especificar a forma como desejamos que o documento seja criado:

Como podemos ver pela figura abaixo, existem diversas opções para a geração do arquivo. Selecione neste passo as alternativas que são mais adequadas. Para gerar o documento clique no botão Generate.

O que foi explicado até o momento cobre as funcionalidades mais básicas. Entretanto podemos especificar, para geração de documentos PDF, a versão do padrão PDF desejado, se desejamos ativar os links e especificar também a forma como estes links serão assinalados no texto, etc.

Podemos também especificar a forma como o sumário será gerado. Por padrão, itens de marcação de título <H1> até <H6>, são entendidos como seções do texto. H1 indica um capítulo, gerando quebra de página no documento gerado. Documentos que usam estas marcações para efeito visual e não como elementos divisores do documento podem ser representados de forma errada no documento final.

Como exemplo de documento criado com o software HTMLDOC, gostaria de citar o livro Free as in Freedom, disponível para download, da biblioteca digital de software livre do Centro de Computação da Unicamp.

Mas para aprender mesmo é necessário estudar as diferentes opções oferecidas, avaliar o resultado final, fazendo o refinamento necessário até se chegar ao ponto desejado. É uma alternativa livre de grande valor e certamente muitas aplicações interessantes e úteis podem ser desenvolvidas.

Fonte: Boletim EAD Centro de Computação da Unicamp