6.3. Informação Específica do Documento

Esta sessão contém observações específicas sobre documentos particulares controlados pelo FDP.

6.3.1. O Handbook

books/handbook/

O Handbook é escrito de forma a obedecer a versão estendida do DTD DocBook utilizado pelo projeto FreeBSD.

O Handbook é organizado como um book Docbook. Ele está dividido em partes, e cada uma delas pode conter diversos chapters (Capítulos). Os chapters estão subdivididos em seções (sect1) e subseções (sect2, sect3) e assim por diante.

6.3.1.1. Organização Fisíca

Existem diversos arquivos e diretórios dentro do diretório handbook.

Note:

A organização do Handbook pode mudar ao longo do tempo, e este documento pode ficar defasado no detalhamento destas alterações organizacionais. Se você tiver alguma pergunta sobre como o Handbook é organizado, por favor entre em contato com a lista de discussão do projeto de documentação do FreeBSD.

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.

Important:

Os capítulos e/ou diretórios não devem ser nomeados de forma que reflitam sua ordem no Handbook. Esta ordenação pode mudar com uma reorganização do conteúdo do Handbook; este tipo de reorganização não deve (geralmente) incluir a necessidade de renomear os arquivos (a menos que um capítulo inteiro esteja sendo promovido ou rebaixado na hierarquia).

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.

Este, e outros documentos, podem ser obtidos em ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/

Para perguntas sobre FreeBSD, leia a documentação antes de contatar <questions@FreeBSD.org>.

Para perguntas sobre esta documentação, envie e-mail para <doc@FreeBSD.org>.