A documentação é parte integrante do sistema operacional FreeBSD. Enquanto uma versão atualizada da documentação do FreeBSD está sempre disponível no site do FreeBSD (https://www.freebsd.org/doc/), pode ser útil ter uma cópia local atualizada do site do FreeBSD, manuais, FAQ e artigos.
Esta seção descreve como usar os fontes ou a Coleção de Ports do FreeBSD para manter uma cópia local da documentação do FreeBSD atualizada.
Para obter informações sobre como editar e enviar correções para a documentação, consulte o Primer do Projeto de Documentação do FreeBSD para Novos Colaboradores (https://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/).
Recompilar a documentação do FreeBSD a partir do código-fonte requer uma coleção de ferramentas que não fazem parte do sistema básico do FreeBSD. As ferramentas necessárias podem ser instaladas a partir do pacote textproc/docproj ou do port desenvolvido pelo Projeto de Documentação do FreeBSD.
Uma vez instalado, use o svnlite para buscar uma cópia limpa dos fontes da documentação:
#
svnlite checkout https://svn.FreeBSD.org/doc/head /usr/doc
O download inicial dos fontes da documentação pode demorar um pouco. Deixe executar até completar.
Futuras atualizações dos fontes da documentação podem ser obtidas executando:
#
svnlite update /usr/doc
Depois que um snapshot atualizado dos fontes da documentação for obtido e disponibilizado em /usr/doc
, tudo estará pronto para uma atualização da documentação instalada.
Uma atualização completa de todos os idiomas disponíveis pode ser realizada digitando:
#
cd /usr/doc
#
make install clean
Se uma atualização de apenas um idioma específico for desejada, o make
pode ser executado em um subdiretório específico de idioma do /usr/doc
:
#
cd /usr/doc/en_US.ISO8859-1
#
make install clean
Uma maneira alternativa de atualizar a documentação é executar este comando a partir do /usr/doc
ou do subdiretório específico do idioma desejado:
#
make update
Os formatos de saída que serão instalados podem ser especificados definindo o parâmetro FORMATS
:
#
cd /usr/doc
#
make FORMATS='html html-split' install clean
Várias opções estão disponíveis para facilitar o processo de atualização de apenas partes da documentação ou a construção de traduções específicas. Estas opções podem ser configuradas como opções de todo o sistema no /etc/make.conf
, ou como opções de linha de comando passadas para o make
.
As opções incluem:
DOC_LANG
A lista de idiomas e codificações para compilar e instalar, como en_US.ISO8859-1
para documentação em inglês.
FORMATS
Um formato único ou uma lista de formatos de saída a serem criados. Atualmente os formatos suportados são, html
, html-split
, txt
, ps
, e pdf
.
DOCDIR
Onde instalar a documentação. O padrão é /usr/share/doc
.
Para mais variáveis do make
suportadas como opções system-wide no FreeBSD, consulte make.conf(5).
A seção anterior apresentou um método para atualizar a documentação do FreeBSD a partir do código fonte. Esta seção descreve um método alternativo que usa a Coleção de Ports e possibilita:
Instalar pacotes pré-compilados da documentação, sem precisar compilar nada localmente ou instalar o conjunto de ferramentas de documentação.
Compilar o código fonte da documentação por meio do framework de ports, facilitando o check-out e as etapas de compilação.
Este método de atualização da documentação do FreeBSD é suportado por um conjunto de ports e pacotes de documentação que são atualizados mensalmente pela Equipe de Engenharia da Documentação <doceng@FreeBSD.org>
. Eles estão listados na Coleção de Ports do FreeBSD, na categoria docs (http://www.freshports.org/docs/).
A organização dos ports de documentação é a seguinte:
O pacote ou port misc/freebsd-doc-en instala toda a documentação em inglês.
O meta-pacote ou port do pacote misc/freebsd-doc-all instala toda a documentação em todos os idiomas disponíveis.
Existe um pacote e um port para cada tradução, como misc/freebsd-doc-hu para a documentação húngara.
Quando pacotes binários são usados, a documentação do FreeBSD será instalada em todos os formatos disponíveis para o idioma especificado. Por exemplo, o comando a seguir instalará o pacote mais recente da documentação em húngaro:
#
pkg install hu-freebsd-doc
Os pacotes usam um formato que difere do nome do port correspondente:
, onde lang
-freebsd-doclang
é o formato abreviado do código de idioma, como hu
para húngaro, ou zh_cn
para chinês simplificado.
Para especificar o formato da documentação, compile o port em vez de instalar o pacote. Por exemplo, para compilar e instalar a documentação em inglês:
#
cd /usr/ports/misc/freebsd-doc-en
#
make install clean
O port fornece um menu de configuração no qual o formato para compilar e instalar pode ser especificado. Por padrão, o HTML dividido, semelhante ao formato usado em http://www.FreeBSD.org
e o PDF estão selecionados.
Alternativamente, várias opções make
podem ser especificadas ao compilar um port de documentação, incluindo:
WITH_HTML
Cria o formato HTML com um único arquivo HTML por documento. A documentação formatada é salva em um arquivo chamado article.html
ou book.html
.
WITH_PDF
A documentação formatada é salva em um arquivo chamado article.pd
ou book.pdf
.
DOCBASE
Especifica onde instalar a documentação. O padrão é /usr/local/share/doc/freebsd
.
Este exemplo usa variáveis para instalar a documentação húngara como um arquivo PDF no diretório especificado:
#
cd /usr/ports/misc/freebsd-doc-hu
#
make -DWITH_PDF DOCBASE=share/doc/freebsd/hu install clean
Pacotes ou ports de documentação podem ser atualizados usando as instruções em Capítulo 4, Instalando Aplicativos: Pacotes e Ports. Por exemplo, o seguinte comando atualiza a documentação húngara instalada usando ports-mgmt/portmaster através do uso apenas de pacotes:
#
portmaster -PP hu-freebsd-doc
All FreeBSD documents are available for download at https://download.freebsd.org/ftp/doc/
Questions that are not answered by the
documentation may be
sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.