Esta sessão contém observações específicas sobre documentos particulares controlados pelo FDP.
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.
Existem diversos arquivos e diretórios dentro do
diretório handbook
.
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.
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.
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.
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:
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
.
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>.