Primer do Projeto de Documentação do FreeBSD para novos colaboradores
Anterior | Capítulo 6 Estruturando Documentos Sob `doc/` | Próxima

# 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 `<part>`es, e cada uma delas pode conter diversos `<chapter>`s (Capítulos). Os `<chapter>`s 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`.

> Nota: 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`.

> Importante: 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.

Anterior | Principal | Próxima
Os Diretórios de ``idioma`.`codificação`` | Acima | O processo de construção da documentação

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>.