Primer do Projeto de Documentação do FreeBSD para novos colaboradores
Anterior | Capítulo 7 O processo de construção da documentação | Próxima

# 7.2 Entendendo `Makefile`s na árvore da documentação

Há três tipos principais de `Makefile`s na árvore do projeto de documentção do FreeBSD.

- Os `Makefile`s de subdiretório simplesmente passam comandos para os diretórios abaixo dele.

- Os `Makefile`s de documentação descrevem o(s) documento(s) que deve(m) ser produzido(s) a partir deste diretório.

- Os Make includes são os responsáveis pela produção do documento, e geralmente possuem o nome no formato `doc.`xxx`.mk`.

## 7.2.1 `Makefile`s de Subdiretórios

Estes `Makefile`s geralmente tem a forma:

    SUBDIR =articles
    SUBDIR+=books

    COMPAT_SYMLINK = en

    DOC_PREFIX?= ${.CURDIR}/..
    .include "${DOC_PREFIX}/share/mk/doc.project.mk"

Resumidamente, as primeiras quatro linhas não vazias definem as variáveis do make, `SUBDIR`, `COMPAT_SYMLINK`, e `DOC_PREFIX`.

A primeira declaração da variável `SUBDIR`, tanto quanto a declaração da variável `COMPAT_SYMLINK`, mostra como atribuir um valor a uma variável, sobrescrevendo qualquer valor anterior que a mesma contenha.

A segunda declaração da variável `SUBDIR` mostra como um valor é adicionado ao valor atual de uma variável. A variável `SUBDIR` agora é composta por `articles books`.

A declaração do `DOC_PREFIX` mostra como um valor é atribuído para uma variável, mas somente se ela ainda não estiver definida. Isto é útil se o `DOC_PREFIX` não for onde este `Makefile` pensa que é - o usuário pode cancelar e fornecer o valor correto.

Agora o que tudo isso significa? O `SUBDIR` lista quais subdiretórios abaixo do atual devem ser incluídos no processo de compilação durante a geração do documento.

O `COMPAT_SYMLINK` é específico para compatibilizar os links simbólicos que ligam os idiomas a sua codificação oficial (por exemplo o `doc/en` deve apontar para `en_US.ISO-8859-1`).

O `DOC_PREFIX` é o caminho para a raíz da árvore do projeto de documentação do FreeBSD. O qual nem sempre é facil de encontrar, e que também pode ser facilmente sobrescrito, para permitir flexibilidade. O `.CURDIR` é uma variável interna do make que contém o caminho para o diretório atual.

A linha final inclui o arquivo principal do projeto de documentação do FreeBSD, o `doc.project.mk`, ele é o responsável por converter estas variáveis em instruções de compilação para uso do make.

## 7.2.2 `Makefile`s de Documentação

Estes `Makefile`s ajustam várias variáveis do make as quais descrevem como construir a documentação contida em um determinado diretório.

Aqui está um exemplo:

    MAINTAINER=nik@FreeBSD.org

    DOC?= book

    FORMATS?= html-split html

    INSTALL_COMPRESSED?= gz
    INSTALL_ONLY_COMPRESSED?=

    # SGML content
    SRCS=  book.xml

    DOC_PREFIX?= ${.CURDIR}/../../..

    .include "$(DOC_PREFIX)/share/mk/docproj.docbook.mk"

A variável `MAINTAINER` é uma muito importante. Esta variável fornece a habilidade de reivindicar a propriedade sobre um documento no projeto de documentação do FreeBSD, é por meio dela que você recebe a responsabilidade de mantê-lo.

`DOC` é o nome (sem a extensão `.xml`) do principal documento criado por este diretório. A variável `SRCS` lista todos os arquivos individuais que compõem o documento. Ela também deve incluir os arquivos importantes, nos quais qualquer mudança deve resultar em uma reconstrução.

O `FORMATS` indica os formatos nos quais o documento deve ser gerado por padrão. O `INSTALL_COMPRESSED` contém a lista padrão das técnicas de compressão que devem ser usadas no documento depois que ele é gerado. A variável `INSTALL_ONLY_COMPRESS`, nula por padrão, deve ser definida para um valor não nulo apenas se você desejar gerar exclusivamente a versão compactada do documento.

> Nota: Nós abordamos a atribuição das variáveis opcionais na seção anterior.

Você também já deve estar familiarizado com a atribuição da variável `DOC_PREFIX` e com as instruções de include.

Anterior | Principal | Próxima
O processo de construção da documentação | Acima | Includes do Make do projeto de documentação do FreeBSD

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