21.3. Обновление документации
Пред. | Глава 21. Обновление системы и смена версии FreeBSD | След.

## 21.3. Обновление документации

Документация является неотъемлемой частью операционной системы FreeBSD. И хотя актуальная версия документации FreeBSD всегда доступна на сайте FreeBSD (http://www.freebsd.org/doc/), может быть удобно иметь под рукой актуальную локальную копию сайта FreeBSD, руководств, FAQ и статей.

В этом разделе описывается, как использовать исходный текст или Коллекцию Портов FreeBSD для организации актуальной локальной копии документации FreeBSD.

За информацией о редактировании и отправке изменений для документации обращайтесь к FreeBSD Documentation Project Primer for New Contributors (http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/).

### 21.3.1. Обновление документации из исходного кода

Для перестроения документации FreeBSD из исходного текста требуется набор инструментов, который не является частью основной системы FreeBSD. Требуемые инструменты, включая svn, можно установить из пакета или порта textproc/docproj, разработанного в рамках проекта документации FreeBSD.

После установки используйте svn для получения копии исходных текстов документации:

    # svn checkout https://svn.FreeBSD.org/doc/head /usr/doc

Первоначальная загрузка исходных текстов документации может занять некоторое время. Дайте ей завершиться.

Последующие обновления можно получить, выполнив:

    # svn update /usr/doc

После того как в `/usr/doc` была загружена актуальная копия исходных текстов, всё готово для обновления установленной документации.

Полное обновление всех доступных языковых версий можно выполнить, набрав команду:

    # cd /usr/doc
    # make install clean

Для обновления только указанной языковой версии команду `make` можно запустить в соответствующем подкаталоге `/usr/doc`:

    # cd /usr/doc/en_US.ISO8859-1
    # make install clean

Альтернативный способ обновления документации заключается в запуске следующей команды из из `/usr/doc` или подкаталога с желаемой языковой версией:

    # make update

Используемый при установке формат можно указать через `FORMATS`:

    # cd /usr/doc
    # make FORMATS='html html-split' install clean

Для упрощения процесса частичного обновления документации и построения только нужных переводов имеется несколько параметров. Их можно задать как на общесистемном уровне, указав в `/etc/make.conf`, так и непосредственно в команде `make`.

Данные параметры включают:

`DOC_LANG`

  Перечень языков и кодировок для построения и установки, например, `en_US.ISO8859-1` для англоязычной документации.

`FORMATS`

  Единый формат или набор форматов для построения. На данный момент поддерживаются `html`, `html-split`, `txt`, `ps` и `pdf`.

`DOCDIR`

  Путь для установки документации. По умолчанию `/usr/share/doc`.

Для получения других переменных `make`, также работающих во FreeBSD в качестве общесистемных, обратитесь к make.conf(5).

### 21.3.2. Обновление документации из портов

Основную работу выполнил Marc Fonvieille.

В предыдущем разделе был представлен метод обновления документации FreeBSD из исходных текстов. В этом разделе описывается альтернативный метод с использованием Коллекции Портов, который позволяет:

- Установить предварительно собранный пакет документации без необходимости локального построения чего-либо или установки инструментария документации.

- Выполнить построение исходных текстов документации через инфраструктуру портов, что несколько упрощает этапы загрузки и построения.

Данный метод обновления документации FreeBSD предоставляется портами и пакетами документации, которые ежемесячно обновляет Группа Менеджеров Дерева Документации FreeBSD `<doceng@FreeBSD.org>`. Они перечислены в Коллекции Портов FreeBSD в категории docs (http://www.freshports.org/docs/).

Порты документации организованы следующим образом:

- Пакет или порт misc/freebsd-doc-en устанавливает всю англоязычную документацию.

- Метапакет или порт misc/freebsd-doc-all устанавливает всю документацию на всех доступных языках.

- Имеются пакеты и порты для каждого перевода, например, misc/freebsd-doc-hu для венгерской документации.

При использовании двоичных пакетов документация FreeBSD будет установлена во всех доступных форматах для данного языка. Например, следующая команда установит последнюю версию пакета венгерской документации:

    # pkg install hu-freebsd-doc

### Примечание:

Для пакетов используется другая схема наименования, которая отличается от названия соответствующего порта: ``lang`-freebsd-doc`, где `lang` соответствует сокращённому языковому коду, такому как `hu` для венгерского или `zh_cn` для упрощённого китайского.

Чтобы указать используемый формат документации, для этого вместо установки готового пакета нужно собрать порт самостоятельно. Ниже приводится пример построения и установки английской документации:

    # cd /usr/ports/misc/freebsd-doc-en
    # make install clean

В порте имеется меню конфигурации, в котором можно указать нужный формат. По умолчанию выбирается HTML с разделителями, такой как на `http://www.FreeBSD.org`, а также PDF.

Иначе, при построении порта документации можно указать параметры `make`, которые включают в себя:

`WITH_HTML`

  Документ в формате HTML на одной странице. Сформированная документация сохраняется в файле `article.html` или `book.html`.

`WITH_PDF`

  Сформированная документация сохраняется в файле `article.pdf` или `book.pdf`.

`DOCBASE`

  Указывает место размещения документации. По умолчанию `/usr/local/share/doc/freebsd`.

В примере ниже демонстрируется использование переменных для установки венгерской документации в PDF в указанный каталог:

    # cd /usr/ports/misc/freebsd-doc-hu
    # make -DWITH_PDF DOCBASE=share/doc/freebsd/hu install clean

Пакеты или порты документации обновляются согласно инструкциям в Глава 5, Установка приложений: порты и пакеты. Например, следующая команда выполняет обновление установленной документации на венгерском языке с помощью ports-mgmt/portmaster в режиме использования только готовых пакетов:

    # portmaster -PP hu-freebsd-doc

Пред. | Наверх | След.
21.2. Обновление FreeBSD | Начало | 21.4. Использование ветви разработки

Этот, и другие документы, могут быть скачаны с https://download.freebsd.org/ftp/doc/.

По вопросам, связанным с FreeBSD, прочитайте документацию прежде чем писать в <questions@FreeBSD.org>.
По вопросам, связанным с этой документацией, пишите в рассылку <doc@FreeBSD.org>.