Документация является неотъемлемой частью операционной системы 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/).
Для перестроения документации 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).
В предыдущем разделе был представлен метод обновления документации 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-doclang соответствует
сокращённому языковому коду, такому как
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
Этот, и другие документы, могут быть скачаны с https://download.freebsd.org/ftp/doc/.
По вопросам, связанным с FreeBSD, прочитайте
документацию прежде чем писать в
<questions@FreeBSD.org>.
По вопросам, связанным с этой документацией, пишите в рассылку
<doc@FreeBSD.org>.