6.3 Informação Específica do Documento

6.3.1.1.1 Makefile

O Makefile define algumas variáveis as quais afetam a forma como o fonte SGML é convertido para outros formatos, e lista os vários arquivos fonte que compõem o Handbook. Ele também inclui um arquivo padrão chamado doc.project.mk, o qual contém o restante do código responsável por realizar a conversão dos documentos de um formato para outro.

6.3.1.1.2 book.xml

Este é o documento de mais alto nível do Handbook. Ele contém as declarações DOCTYPE do Handbook, assim como os elementos que descrevem a estrutura do Handbook.

O book.xml utiliza entidades de parâmetro para carregar os arquivos com extensão .ent. Estes arquivos (descritos abaixo) definem as entidades gerais as quais são utilizadas ao longo de todo o Handbook.

6.3.1.1.3 directory/chapter.xml

Cada capítulo do Handbook é armazenado em um arquivo chamado chapter.xml localizado em um diretório separado dos outros capítulos. Cada diretório é nomeado depois do valor do atributo id no elemento <chapter>.

Por exemplo, se um dos arquivos de capítulos contiver:

<chapter id="kernelconfig">
...
</chapter>

Então ele será chamado de chapter.xml e será armazenadao no diretório kernelconfig . Em geral, todo o conteúdo do capítulo será mantido neste arquivo.

Quando a versão HTML do Handbook for produzida, será gerado um arquivo kernelconfig.html. Isto ocorre devido ao valor do atributo id e não está relacionado ao nome do diretório.

Nas versões anteriores do Handbook os arquivos eram armazenados no mesmo diretório que o book.xml, e depois nomeados a partir do valor do atributo id presente no elemento <chapter> do arquivo. Agora, é possível incluir imagens em cada capítulo. As imagens de cada capítulo do Handbook são armazenadas dentro de share/images/books/handbook. Observe que as versões localizadas destas imagens devem ser colocadas no mesmo diretório com o código fonte SGML de cada capítulo. Colisões de namespace são inevitáveis, e é muito mais simples trabalhar com vários diretórios que contenham poucos arquivos em cada um, do que trabalhar com um diretório que contenha muitos arquivos.

Um exame rápido vai mostrar que existem muitos diretórios com um único arquivo chapter.xml, incluindo basics/chapter.xml, introduction/chapter.xml, e printing/chapter.xml.

Cada arquivo chapter.xml não será um documento SGML completo. Em particular, eles não terão as suas próprias linhas DOCTYPE no início do arquivo.

Isto é uma infelicidade pois torna impossível tratá-los como arquivos SGML genéricos e simplesmente convertê-los para HTML, RTF, PS, e outros formatos da mesma forma que o Handbook principal é gerado. Isto irá forçá-lo a reconstruir o Handbook inteiro sempre que você desejar ver o efeito de uma alteração realizada em apenas um capítulo.