23.3. Atualizando o Conjunto de Documentação

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

23.3.1. Atualizando a documentação a partir do código-fonte

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

23.3.2. Atualizando a documentação a partir do ports

Baseado no trabalho de Marc Fonvieille.

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

Nota:

Os pacotes usam um formato que difere do nome do port correspondente: lang-freebsd-doc, onde lang é 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>.