git: 9368c9279b - main - Split Russian porter's handbook

The branch main has been updated by carlavilla:

URL: https://cgit.FreeBSD.org/doc/commit/?id=9368c9279be9891602c4630228a8a4ced8f1c302

commit 9368c9279be9891602c4630228a8a4ced8f1c302
Author:     Sergio Carlavilla Delgado <[email protected]>
AuthorDate: 2021-11-27 12:38:04 +0000
Commit:     Sergio Carlavilla Delgado <[email protected]>
CommitDate: 2021-11-27 12:38:04 +0000

    Split Russian porter's handbook
---
 .../content/ru/books/porters-handbook/_index.adoc  |  26 +-
 .../content/ru/books/porters-handbook/book.adoc    |  68 +++
 .../ru/books/porters-handbook/chapters-order.adoc  |  32 +-
 .../keeping-up/{chapter.adoc => _index.adoc}       |   0
 .../makefiles/{chapter.adoc => _index.adoc}        |  10 +-
 .../new-port/{chapter.adoc => _index.adoc}         |   2 +-
 .../pkg-files/{chapter.adoc => _index.adoc}        |   2 +-
 .../plist/{chapter.adoc => _index.adoc}            |   4 +-
 .../porting-dads/{chapter.adoc => _index.adoc}     |   2 +-
 .../porting-samplem/{chapter.adoc => _index.adoc}  |   0
 .../porting-why/{chapter.adoc => _index.adoc}      |   0
 .../quick-porting/{chapter.adoc => _index.adoc}    |   6 +-
 .../security/{chapter.adoc => _index.adoc}         |   0
 .../slow-porting/{chapter.adoc => _index.adoc}     |   2 +-
 .../special/{chapter.adoc => _index.adoc}          |  10 +-
 .../testing/{chapter.adoc => _index.adoc}          |   6 +-
 .../upgrading/{chapter.adoc => _index.adoc}        |   4 +-
 .../uses/{chapter.adoc => _index.adoc}             | 579 +++++++++++++++------
 .../versions/{chapter.adoc => _index.adoc}         |   0
 19 files changed, 521 insertions(+), 232 deletions(-)

diff --git a/documentation/content/ru/books/porters-handbook/_index.adoc b/documentation/content/ru/books/porters-handbook/_index.adoc
index 1b6f7d092c..0395f5d5e7 100644
--- a/documentation/content/ru/books/porters-handbook/_index.adoc
+++ b/documentation/content/ru/books/porters-handbook/_index.adoc
@@ -4,21 +4,22 @@ authors:
   - author: The FreeBSD Documentation Project
 copyright: 2000-2020 The FreeBSD Documentation Project
 trademarks: ["freebsd", "sun", "unix", "general"]
+next: books/porters-handbook/porting-why
+add_single_page_link: true
 isIndex: true
 ---
 
 = Руководство FreeBSD по созданию портов
 :doctype: book
 :toc: macro
-:toclevels: 2
+:toclevels: 1
 :icons: font
 :sectnums:
 :sectnumlevels: 6
 :partnums:
 :source-highlighter: rouge
 :experimental:
-:book: true
-:pdf: false
+:images-path: books/porters-handbook/
 
 ifdef::env-beastie[]
 ifdef::backend-html5[]
@@ -44,25 +45,8 @@ endif::[]
 
 '''
 
-toc::[]
+include::{chapters-path}toc.adoc[]
 
 include::{chapters-path}toc-tables.adoc[]
 
 include::{chapters-path}toc-examples.adoc[]
-
-include::{chapters-path}porting-why/chapter.adoc[leveloffset=+1]
-include::{chapters-path}new-port/chapter.adoc[leveloffset=+1]
-include::{chapters-path}quick-porting/chapter.adoc[leveloffset=+1]
-include::{chapters-path}slow-porting/chapter.adoc[leveloffset=+1]
-include::{chapters-path}makefiles/chapter.adoc[leveloffset=+1]
-include::{chapters-path}special/chapter.adoc[leveloffset=+1]
-include::{chapters-path}plist/chapter.adoc[leveloffset=+1]
-include::{chapters-path}pkg-files/chapter.adoc[leveloffset=+1]
-include::{chapters-path}testing/chapter.adoc[leveloffset=+1]
-include::{chapters-path}upgrading/chapter.adoc[leveloffset=+1]
-include::{chapters-path}security/chapter.adoc[leveloffset=+1]
-include::{chapters-path}porting-dads/chapter.adoc[leveloffset=+1]
-include::{chapters-path}porting-samplem/chapter.adoc[leveloffset=+1]
-include::{chapters-path}keeping-up/chapter.adoc[leveloffset=+1]
-include::{chapters-path}uses/chapter.adoc[leveloffset=+1]
-include::{chapters-path}versions/chapter.adoc[leveloffset=+1]
diff --git a/documentation/content/ru/books/porters-handbook/book.adoc b/documentation/content/ru/books/porters-handbook/book.adoc
new file mode 100644
index 0000000000..c10afd18bc
--- /dev/null
+++ b/documentation/content/ru/books/porters-handbook/book.adoc
@@ -0,0 +1,68 @@
+---
+title: Руководство FreeBSD по созданию портов
+authors: 
+  - author: The FreeBSD Documentation Project
+copyright: 2000-2020 The FreeBSD Documentation Project
+trademarks: ["freebsd", "sun", "unix", "general"]
+add_split_page_link: true
+---
+
+= FreeBSD Porter's Handbook
+:doctype: book
+:toc: macro
+:toclevels: 2
+:icons: font
+:sectnums:
+:sectnumlevels: 6
+:partnums:
+:source-highlighter: rouge
+:experimental:
+:book: true
+:pdf: false
+
+ifdef::env-beastie[]
+ifdef::backend-html5[]
+include::shared/authors.adoc[]
+include::shared/mirrors.adoc[]
+include::shared/releases.adoc[]
+include::shared/attributes/attributes-{{% lang %}}.adoc[]
+include::shared/{{% lang %}}/teams.adoc[]
+include::shared/{{% lang %}}/mailing-lists.adoc[]
+include::shared/{{% lang %}}/urls.adoc[]
+:chapters-path: content/{{% lang %}}/books/porters-handbook/
+endif::[]
+ifdef::backend-pdf,backend-epub3[]
+:chapters-path:
+include::../../../../../shared/asciidoctor.adoc[]
+endif::[]
+endif::[]
+
+ifndef::env-beastie[]
+:chapters-path:
+include::../../../../../shared/asciidoctor.adoc[]
+endif::[]
+
+'''
+
+toc::[]
+
+include::{chapters-path}toc-tables.adoc[]
+
+include::{chapters-path}toc-examples.adoc[]
+
+include::{chapters-path}porting-why/_index.adoc[leveloffset=+1]
+include::{chapters-path}new-port/_index.adoc[leveloffset=+1]
+include::{chapters-path}quick-porting/_index.adoc[leveloffset=+1]
+include::{chapters-path}slow-porting/_index.adoc[leveloffset=+1]
+include::{chapters-path}makefiles/_index.adoc[leveloffset=+1]
+include::{chapters-path}special/_index.adoc[leveloffset=+1]
+include::{chapters-path}plist/_index.adoc[leveloffset=+1]
+include::{chapters-path}pkg-files/_index.adoc[leveloffset=+1]
+include::{chapters-path}testing/_index.adoc[leveloffset=+1]
+include::{chapters-path}upgrading/_index.adoc[leveloffset=+1]
+include::{chapters-path}security/_index.adoc[leveloffset=+1]
+include::{chapters-path}porting-dads/_index.adoc[leveloffset=+1]
+include::{chapters-path}porting-samplem/_index.adoc[leveloffset=+1]
+include::{chapters-path}keeping-up/_index.adoc[leveloffset=+1]
+include::{chapters-path}uses/_index.adoc[leveloffset=+1]
+include::{chapters-path}versions/_index.adoc[leveloffset=+1]
diff --git a/documentation/content/ru/books/porters-handbook/chapters-order.adoc b/documentation/content/ru/books/porters-handbook/chapters-order.adoc
index f7a766c744..80ccba6333 100644
--- a/documentation/content/ru/books/porters-handbook/chapters-order.adoc
+++ b/documentation/content/ru/books/porters-handbook/chapters-order.adoc
@@ -1,16 +1,16 @@
-porting-why/chapter.adoc
-new-port/chapter.adoc
-quick-porting/chapter.adoc
-slow-porting/chapter.adoc
-makefiles/chapter.adoc
-special/chapter.adoc
-plist/chapter.adoc
-pkg-files/chapter.adoc
-testing/chapter.adoc
-upgrading/chapter.adoc
-security/chapter.adoc
-porting-dads/chapter.adoc
-porting-samplem/chapter.adoc
-keeping-up/chapter.adoc
-uses/chapter.adoc
-versions/chapter.adoc
+porting-why/_index.adoc
+new-port/_index.adoc
+quick-porting/_index.adoc
+slow-porting/_index.adoc
+makefiles/_index.adoc
+special/_index.adoc
+plist/_index.adoc
+pkg-files/_index.adoc
+testing/_index.adoc
+upgrading/_index.adoc
+security/_index.adoc
+porting-dads/_index.adoc
+porting-samplem/_index.adoc
+keeping-up/_index.adoc
+uses/_index.adoc
+versions/_index.adoc
diff --git a/documentation/content/ru/books/porters-handbook/keeping-up/chapter.adoc b/documentation/content/ru/books/porters-handbook/keeping-up/_index.adoc
similarity index 100%
rename from documentation/content/ru/books/porters-handbook/keeping-up/chapter.adoc
rename to documentation/content/ru/books/porters-handbook/keeping-up/_index.adoc
diff --git a/documentation/content/ru/books/porters-handbook/makefiles/chapter.adoc b/documentation/content/ru/books/porters-handbook/makefiles/_index.adoc
similarity index 98%
rename from documentation/content/ru/books/porters-handbook/makefiles/chapter.adoc
rename to documentation/content/ru/books/porters-handbook/makefiles/_index.adoc
index 721539ccb6..a8cc2643e9 100644
--- a/documentation/content/ru/books/porters-handbook/makefiles/chapter.adoc
+++ b/documentation/content/ru/books/porters-handbook/makefiles/_index.adoc
@@ -1176,7 +1176,7 @@ PATCHFILES=	patch1:test
 ** `fetch-list`: работает так же, как старая цель `fetch-list` с тем исключением, что она группирует, как и `do-fetch`.
 ** `master-sites` и `patch-sites`: (несовместимы со старыми версиями) только возвращают элементы группы `DEFAULT`; на самом деле они выполняют цели `master-sites-default` и `patch-sites-default` соответственно.
 + 
-Более того, использование целей `master-sites-all` или `patch-sites-all` предпочтительно для непосредственной проверки `MASTER_SITES` или `PATCH_SITES`. Также работа прямой проверки в последующих версиях не гарантируется. Посмотрите <<porting-master-sites-n-new-port-targets-master-sites-all>> для получения более дополнительной информации об этих новых целях.
+Более того, использование целей `master-sites-all` или `patch-sites-all` предпочтительно для непосредственной проверки `MASTER_SITES` или `PATCH_SITES`. Также работа прямой проверки в последующих версиях не гарантируется. Посмотрите <<porting-master-sites-n-new-port-targets-master-sites-all, B>> для получения более дополнительной информации об этих новых целях.
 
 . Новые цели построения портов
 .. Имеются цели `master-sites-_n_` и `patch-sites-_n_`, которые будут перечислять элементы соответствующей группы _n_ из `MASTER_SITES` и `PATCH_SITES` соответственно. К примеру, `master-sites-DEFAULT` и `patch-sites-DEFAULT` обе будут возвращать элементы группы `DEFAULT`, `master-sites-test` и `patch-sites-test` группы `test` и так далее.
@@ -1254,7 +1254,7 @@ COMMENT=	Cat chasing a mouse all over the screen
 [[makefile-portscout]]
 == `PORTSCOUT`
 
-Portscout являет собой автоматизированное средство проверки доступности дистрибутивных файлов для Коллекции Портов FreeBSD, подробное описание которого предоставляет <<distfile-survey>>.
+Portscout являет собой автоматизированное средство проверки доступности дистрибутивных файлов для Коллекции Портов FreeBSD, подробное описание которого предоставляет crossref:keeping-up[distfile-survey, Portscout: сканер дистрибутивных файлов портов FreeBSD].
 
 Переменная `PORTSCOUT` задаёт специальные условия, ограничивающие работу Portscout - сканера дистрибутивных файлов.
 
@@ -1456,7 +1456,7 @@ USE_GCC=X.Y
 |Для сборки порта требуется GCC (gcc или {gcc-plus-plus}). Некоторым портам подходит любая версия, для других требуются последние современные версии. Обычно используется со значением `any` (в этом случае используется встроенный GCC в тех версиях FreeBSD, в состав которых он всё ещё входит, или устанавливается порт `lang/gcc`, когда Clang является компилятором C/C++ по умолчанию) или `yes` (всегда используется стабильная современная версия GCC из порта `lang/gcc`). Также Ð
 ² значении переменной можно указать точную версию, например `4.7`. Минимально допустимую версию можно указать 
 как `4.6+`. GCC из основной системы используется в случае, если его версия удовлетворяет запрошенной, иначе собирается подходящая версии компилятора из порта с соответствующей коррекцией переменных `CC` и `CXX`.
 |===
 
-Переменные, относящиеся к gmake и сценарию [.filename]#configure#, описаны в <<building>>, а autoconf, automake и libtool описаны в <<using-autotools>>. Переменные, связанные с Perl, описаны в <<using-perl>>. Переменные X11 перечислены в <<using-x11>>. <<using-gnome>> работает с переменными GNOME и <<using-kde>> с KDE. <<using-java>> описывает переменные Java, а <<using-php>> содержит информацию об Apache, PHP и модулях PEAR. Python обсуждается в <<using-python>>, а Ruby в <<using-ruby>>. <<using-sdl>> предоставляет переменные, используемые для приложений SDL, Ð
 ¸, наконец, <<using-xfce>> содержит информацию о приложении Xfce.
+Переменные, относящиеся к gmake и сценарию [.filename]#configure#, описаны в crossref:special[building, Механизмы построения], а autoconf, automake и libtool описаны в crossref:special[using-autotools, Использование GNU Autotools]. Переменные, связанные с Perl, описаны в crossref:special[using-perl, Использование Perl]. Переменные X11 перечислены в crossref:special[using-x11, Использование X11]. crossref:special[using-gnome, Использование GNOME] работает с переменными GNOME и crossref:special[using-kde, Использование KDE] с KDE. crossref:special[using-java, Использование Jav
 a] описывает переменные Java, а crossref:special[using-php, Веб-приложения, Apache и PHP] содержит информацию об Apache, PHP и модулях P
 EAR. Python обсуждается в crossref:special[using-python, Использование Python], а Ruby в crossref:special[using-ruby, Использование Ruby]. crossref:special[using-sdl, Использование SDL] предоставляет переменные, используемые для приложений SDL, и, наконец, crossref:special[using-xfce, Использование Xfce] содержит информацию о приложении Xfce.
 
 === Минимальная версия зависимости
 
@@ -2218,7 +2218,7 @@ NO_WRKSUBDIR=	yes
 
 [NOTE]
 ====
-Переменные регистрации конфликта автоматически определяют переменную `IGNORE`, которая более подробно описана в <<dads-noinstall>>.
+Переменные регистрации конфликта автоматически определяют переменную `IGNORE`, которая более подробно описана в crossref:porting-dads[dads-noinstall, "Пометка неустанавливаемого порта как `BROKEN`, `FORBIDDEN` или `IGNORE` "].
 ====
 
 При удалении одного из конфликтующих портов целесообразно сохранить записи `CONFLICTS` в тех других портах в течении нескольких месяцев, чтобы позаботиться о тех пользователей, которые обновляются от случая к случаю.
@@ -2321,7 +2321,7 @@ post-install:
 
 Создайте для вашего порта новый каталог. Имя каталога должно соответствовать тому, что представляет из себя порт. Обычно это означает `PORTNAME`. Однако, если вы думаете, что пользователь захочет иметь разные версии порта, установленные одновременно, то вы можете использовать полное имя `PKGNAME`.
 
-Поскольку устанавливаются только файлы, перечисленные в [.filename]#pkg-plist#, безопасным способом будет устанавливать документацию в `STAGEDIR` всегда (смотрите <<staging>>). Следовательно, блоки `.if` нужны только для файлов достаточно большого размера, установка которых влечёт значительные накладные расходы на операции ввода/вывода.
+Поскольку устанавливаются только файлы, перечисленные в [.filename]#pkg-plist#, безопасным способом будет устанавливать документацию в `STAGEDIR` всегда (смотрите crossref:special[staging, Staging]). Следовательно, блоки `.if` нужны только для файлов достаточно большого размера, установка которых влечёт значительные накладные расходы на операции ввода/вывода.
 
 [.programlisting]
 ....
diff --git a/documentation/content/ru/books/porters-handbook/new-port/chapter.adoc b/documentation/content/ru/books/porters-handbook/new-port/_index.adoc
similarity index 97%
rename from documentation/content/ru/books/porters-handbook/new-port/chapter.adoc
rename to documentation/content/ru/books/porters-handbook/new-port/_index.adoc
index 43b61bce99..e4a0c67481 100644
--- a/documentation/content/ru/books/porters-handbook/new-port/chapter.adoc
+++ b/documentation/content/ru/books/porters-handbook/new-port/_index.adoc
@@ -44,7 +44,7 @@ endif::[]
 
 Итак, вы интересуетесь, как создать собственный порт или обновить существующий? Великолепно!
 
-Ниже находятся некоторые указания по созданию нового порта для FreeBSD. Если вы хотите обновить существующий порт, вы должны прочесть их, а затем <<port-upgrading>>.
+Ниже находятся некоторые указания по созданию нового порта для FreeBSD. Если вы хотите обновить существующий порт, вы должны прочесть их, а затем crossref:upgrading[port-upgrading, Обновление отдельного порта].
 
 Если этот документ недостаточно подробен, вы должны обратиться к файлу [.filename]#/usr/ports/Mk/bsd.port.mk#, который включается в make-файл каждого порта. Он хорошо прокомментирован, и даже если вы не занимаетесь хакингом make-файлов каждодневно, из него вы сможете узнать много нового. Кроме того, конкретные вопросы можно задать, послав письмо на адрес {freebsd-ports}.
 
diff --git a/documentation/content/ru/books/porters-handbook/pkg-files/chapter.adoc b/documentation/content/ru/books/porters-handbook/pkg-files/_index.adoc
similarity index 99%
rename from documentation/content/ru/books/porters-handbook/pkg-files/chapter.adoc
rename to documentation/content/ru/books/porters-handbook/pkg-files/_index.adoc
index 5f98929394..7b641bf91b 100644
--- a/documentation/content/ru/books/porters-handbook/pkg-files/chapter.adoc
+++ b/documentation/content/ru/books/porters-handbook/pkg-files/_index.adoc
@@ -5,7 +5,7 @@ next: books/porters-handbook/testing
 ---
 
 [[pkg-files]]
-= Файлы [.filename]#pkg-*#
+= Файлы pkg-*
 :doctype: book
 :toc: macro
 :toclevels: 1
diff --git a/documentation/content/ru/books/porters-handbook/plist/chapter.adoc b/documentation/content/ru/books/porters-handbook/plist/_index.adoc
similarity index 99%
rename from documentation/content/ru/books/porters-handbook/plist/chapter.adoc
rename to documentation/content/ru/books/porters-handbook/plist/_index.adoc
index db57d34ca3..1f84971b10 100644
--- a/documentation/content/ru/books/porters-handbook/plist/chapter.adoc
+++ b/documentation/content/ru/books/porters-handbook/plist/_index.adoc
@@ -1,11 +1,11 @@
 ---
-title: Глава 7. Продвинутые практики [.filename]#pkg-plist#
+title: Глава 7. Продвинутые практики pkg-plist
 prev: books/porters-handbook/special
 next: books/porters-handbook/pkg-files
 ---
 
 [[plist]]
-= Продвинутые практики [.filename]#pkg-plist#
+= Продвинутые практики pkg-plist
 :doctype: book
 :toc: macro
 :toclevels: 1
diff --git a/documentation/content/ru/books/porters-handbook/porting-dads/chapter.adoc b/documentation/content/ru/books/porters-handbook/porting-dads/_index.adoc
similarity index 99%
rename from documentation/content/ru/books/porters-handbook/porting-dads/chapter.adoc
rename to documentation/content/ru/books/porters-handbook/porting-dads/_index.adoc
index 1960a211a4..28f6049c6a 100644
--- a/documentation/content/ru/books/porters-handbook/porting-dads/chapter.adoc
+++ b/documentation/content/ru/books/porters-handbook/porting-dads/_index.adoc
@@ -348,7 +348,7 @@ IGNORE=	unsupported on recent versions
 
 Правильным способом подать сигнал для [.filename]#Makefile# о том, что порт не может быть установлен из-за какого-то внешнего фактора (например, пользователь указал недопустимую комбинацию опций построения), является установка непустого значения для `IGNORE`. Это значение будет сформатировано и показано пользователю во время `make install`.
 
-Использование для этих целей `.error` является распространенной ошибкой. Проблема в том, что в этой ситуации будут повреждены многие инструменты автоматизации, работающие с деревом портов. Наибольшим образом это распространено при попытке построить [.filename]#/usr/ports/INDEX# (смотрите <<make-describe>>). Тем не менее, даже более простые команды, такие как `make maintainer`, в этом случае также вернут ошибку. Это не является приемлемым.
+Использование для этих целей `.error` является распространенной ошибкой. Проблема в том, что в этой ситуации будут повреждены многие инструменты автоматизации, работающие с деревом портов. Наибольшим образом это распространено при попытке построить [.filename]#/usr/ports/INDEX# (смотрите crossref:testing[make-describe, Запуск `make describe`]). Тем не менее, даже более простые команды, такие как `make maintainer`, в этом случае также вернут ошибку. Это не является приемлемым.
 
 [[dot-error-breaks-index]]
 .Как избегать использования `.error`
diff --git a/documentation/content/ru/books/porters-handbook/porting-samplem/chapter.adoc b/documentation/content/ru/books/porters-handbook/porting-samplem/_index.adoc
similarity index 100%
rename from documentation/content/ru/books/porters-handbook/porting-samplem/chapter.adoc
rename to documentation/content/ru/books/porters-handbook/porting-samplem/_index.adoc
diff --git a/documentation/content/ru/books/porters-handbook/porting-why/chapter.adoc b/documentation/content/ru/books/porters-handbook/porting-why/_index.adoc
similarity index 100%
rename from documentation/content/ru/books/porters-handbook/porting-why/chapter.adoc
rename to documentation/content/ru/books/porters-handbook/porting-why/_index.adoc
diff --git a/documentation/content/ru/books/porters-handbook/quick-porting/chapter.adoc b/documentation/content/ru/books/porters-handbook/quick-porting/_index.adoc
similarity index 98%
rename from documentation/content/ru/books/porters-handbook/quick-porting/chapter.adoc
rename to documentation/content/ru/books/porters-handbook/quick-porting/_index.adoc
index 87e1275c42..bebfdd67ee 100644
--- a/documentation/content/ru/books/porters-handbook/quick-porting/chapter.adoc
+++ b/documentation/content/ru/books/porters-handbook/quick-porting/_index.adoc
@@ -171,12 +171,12 @@ PLIST_DIRS=	lib/X11/oneko
 
 [NOTE]
 ====
-Несколько портов могут совместно использовать общий каталог. В этом случае `PLIST_DIRS` следует заменить на `PLIST_DIRSTRY`, так чтобы каталог удалялся только если он пуст, а иначе игнорировался. Использование `PLIST_DIRS` и `PLIST_DIRSTRY` аналогично `@dirrm` и `@dirrmtry` в [.filename]#pkg-plist#, описание которых входит в <<plist-dir-cleaning>>.
+Несколько портов могут совместно использовать общий каталог. В этом случае `PLIST_DIRS` следует заменить на `PLIST_DIRSTRY`, так чтобы каталог удалялся только если он пуст, а иначе игнорировался. Использование `PLIST_DIRS` и `PLIST_DIRSTRY` аналогично `@dirrm` и `@dirrmtry` в [.filename]#pkg-plist#, описание которых входит в crossref:plist[plist-dir-cleaning,Очистка пустых каталогов].
 ====
 
 Обратной стороной такого способа перечисления файлов и каталогов порта является невозможность использования последовательностей команд, описанных в man:pkg-create[8]. Поэтому он подходит для простых портов, что делает их ещё более простыми. Одновременно с этим положительным моментом является уменьшение количества файлов в коллекции портов. Пожалуйста, подумайте над использованием этой техники, прежде чем создавать [.filename]#pkg-plist#.
 
-Далее мы увидим, как можно использовать файлы [.filename]#pkg-plist# и `PLIST_FILES` выполнения <<plist,более сложных задач>>.
+Далее мы увидим, как можно использовать файлы [.filename]#pkg-plist# и `PLIST_FILES` выполнения crossref:plist[plist,более сложных задач].
 
 [[porting-checksum]]
 == Создание файла с контрольной суммой
@@ -221,7 +221,7 @@ PLIST_DIRS=	lib/X11/oneko
 [[porting-submitting]]
 == Посылка нового порта
 
-Перед посылкой нового порта прочитайте раздел о том, что <<porting-dads,можно и нельзя>> делать.
+Перед посылкой нового порта прочитайте раздел о том, что crossref:porting-dads[porting-dads,можно и нельзя] делать.
 
 Когда вы наконец довольны своим первым портом, единственное, что осталось сделать, это включить его в основное дерево портов FreeBSD и осчастливить этим всех остальных. Нам не нужен ни каталог [.filename]#work#, ни пакет [.filename]#pkgname.tgz#, так что удалите их прямо сейчас.
 
diff --git a/documentation/content/ru/books/porters-handbook/security/chapter.adoc b/documentation/content/ru/books/porters-handbook/security/_index.adoc
similarity index 100%
rename from documentation/content/ru/books/porters-handbook/security/chapter.adoc
rename to documentation/content/ru/books/porters-handbook/security/_index.adoc
diff --git a/documentation/content/ru/books/porters-handbook/slow-porting/chapter.adoc b/documentation/content/ru/books/porters-handbook/slow-porting/_index.adoc
similarity index 99%
rename from documentation/content/ru/books/porters-handbook/slow-porting/chapter.adoc
rename to documentation/content/ru/books/porters-handbook/slow-porting/_index.adoc
index 1d7cbc61e7..2cadd40028 100644
--- a/documentation/content/ru/books/porters-handbook/slow-porting/chapter.adoc
+++ b/documentation/content/ru/books/porters-handbook/slow-porting/_index.adoc
@@ -61,7 +61,7 @@ endif::[]
 .. Если задана переменная `HAS_CONFIGURE` или `GNU_CONFIGURE`, то запускается скрипт [.filename]#WRKSRC/configure#.
 
 . Выполняется цель `build`. Она отвечает за переход в собственный рабочий каталог порта (`WRKSRC`) и его построение.
-. Выполняется цель `stage`. Конечный набор построенных файлов помещается во временный каталог (`STAGEDIR`, смотрите <<staging>>). Иерархия этого каталога отражает иерархию каталогов системы, в которую данный пакет будет устанавливаться.
+. Выполняется цель `stage`. Конечный набор построенных файлов помещается во временный каталог (`STAGEDIR`, смотрите crossref:special[staging,Staging]). Иерархия этого каталога отражает иерархию каталогов системы, в которую данный пакет будет устанавливаться.
 . Выполняется цель `install`. В систему копируются файлы, перечисленные в pkg-plist порта.
 ====
 
diff --git a/documentation/content/ru/books/porters-handbook/special/chapter.adoc b/documentation/content/ru/books/porters-handbook/special/_index.adoc
similarity index 99%
rename from documentation/content/ru/books/porters-handbook/special/chapter.adoc
rename to documentation/content/ru/books/porters-handbook/special/_index.adoc
index c46eb9a002..ac01c34875 100644
--- a/documentation/content/ru/books/porters-handbook/special/chapter.adoc
+++ b/documentation/content/ru/books/porters-handbook/special/_index.adoc
@@ -47,7 +47,7 @@ endif::[]
 [[staging]]
 == Staging
 
-[.filename]#bsd.port.mk# ожидает от портов работу с "каталогом сборки". Это означает, что порт должен устанавливать файлы не напрямую в назначенные каталоги (то есть, например, под `PREFIX`), а в отдельный каталог, из которого затем собирается пакет. Во многих случаях привилегии root для этого не требуются, что делает возможным сборку пакетов из-под непривилегированного пользователя. В режиме staging порт собирается и устанавливается в каталог сборки `STAGED
 IR`. Пакет создается из каталога сборки и затем устанавливается в систему. В инструментарии automake такая концеп
 ция именуется `DESTDIR`; в прочем, в FreeBSD `DESTDIR` имеет собственное значение (смотрите <<porting-prefix>>).
+[.filename]#bsd.port.mk# ожидает от портов работу с "каталогом сборки". Это означает, что порт должен устанавливать файлы не напрямую в назначенные каталоги (то есть, например, под `PREFIX`), а в отдельный каталог, из которого затем собирается пакет. Во многих случаях привилегии root для этого не требуются, что делает возможным сборку пакетов из-под непривилегированного пользователя. В режиме staging порт собирается и устанавливается в каталог сборки `STAGED
 IR`. Пакет создается из каталога сборки и затем устанавливается в систему. В инструментарии automake такая концеп
 ция именуется `DESTDIR`; в прочем, в FreeBSD `DESTDIR` имеет собственное значение (смотрите crossref:testing[porting-prefix, `PREFIX` и `DESTDIR`]).
 
 Если для порта всё ещё требуются системные привилегии при выполнении цели `package`, то в [.filename]#Makefile# должна быть добавлена следующая строка:
 
@@ -425,7 +425,7 @@ USE_AUTOTOOLS=	aclocal:version
 
 === Простой вариант использования
 
-Если для вашего порта требуется `gettext`, добавьте `USES= gettext`, и ваш порт унаследует зависимость от package:devel/gettext[]. <<uses-makefiles>> содержит перечень других значений для использования `gettext`.
+Если для вашего порта требуется `gettext`, добавьте `USES= gettext`, и ваш порт унаследует зависимость от package:devel/gettext[]. crossref:makefiles[uses-makefiles, `USES`] содержит перечень других значений для использования `gettext`.
 
 Довольно распространенным случаем является использование в порте `gettext` и `configure`. Как правило, GNU `configure` способен находить `gettext` автоматически. Если он все же не сможет это сделать, то подсказки для размещения `gettext` можно передать через переменные окружения `CPPFLAGS` и `LDFLAGS`:
 
@@ -1103,7 +1103,7 @@ USE_QT4=	moc_build qmake_build rcc_build uic_build
 |Каталог, в который устанавливаются JAR-файлы из других портов. По умолчанию: [.filename]#${LOCALBASE}/shared/java/classes#.
 |===
 
-Соответствующие записи определяются в обоих переменных `PLIST_SUB` (описана в <<plist-sub>>) и `SUB_LIST`.
+Соответствующие записи определяются в обоих переменных `PLIST_SUB` (описана в crossref:plist[plist-sub,Изменение содержимого pkg-plist в зависимости от make-переменных]) и `SUB_LIST`.
 
 [[java-building-with-ant]]
 === Построение с Ant
@@ -1141,7 +1141,7 @@ do-install:
 
 Вне зависимости от типа вашего порта (библиотека это или приложение), дополнительная документация должна устанавливаться <<install-documentation,в тоже самое место>>, что и для других портов. Известно, что в зависимости от используемой версии JDK утилита JavaDoc генерирует различные наборы файлов. Для портов, которые не привязаны к использованию определённой версии JDK, таким образом становится проблематичным определить список файлов для упаковки (
 [.filename]#pkg-plist#). Это одна из причин, по которой создателям портов настоятельно рекомендуется использовать макÑ
 €Ð¾Ñ `PORTDOCS`. Более того, даже если вы сможете угадать набор файлов, который будет сгенерирован утилитой `javadoc`, размер получающегося файла [.filename]#pkg-plist# голосует за использование `PORTDOCS`.
 
-Значением по умолчанию для переменной `DATADIR` является [.filename]#${PREFIX}/shared/${PORTNAME}#. Хорошей идеей является переопределение для Java-портов значения `DATADIR` как [.filename]#${JAVASHAREDIR}/${PORTNAME}#. На самом деле `DATADIR` автоматически добавляется к `PLIST_SUB` (это описано в <<plist-sub>>), так что вы сможете использовать `%%DATADIR%%` непосредственно в [.filename]#pkg-plist#.
+Значением по умолчанию для переменной `DATADIR` является [.filename]#${PREFIX}/shared/${PORTNAME}#. Хорошей идеей является переопределение для Java-портов значения `DATADIR` как [.filename]#${JAVASHAREDIR}/${PORTNAME}#. На самом деле `DATADIR` автоматически добавляется к `PLIST_SUB` (это описано в crossref:plist[plist-sub,Изменение содержимого pkg-plist в зависимости от make-переменных]), так что вы сможете использовать `%%DATADIR%%` непосредственно в [.filename]#pkg-plist#.
 
 Что касается выбора между построением портов Java из исходных текстов или их прямой установкой из бинарных дистрибутивов, то на момент создания этого текста определённой политики на этот счёт не существует. Однако участники http://www.freebsd.org/java/[Проекта FreeBSD Java] рекомендуют создателям портов строить их из исходных текстов, если эта задача является несложной.
 
@@ -1149,7 +1149,7 @@ do-install:
 
 Хотя в базе сообщений об ошибках для соответствующих PR имеется категория `java`, она относится к работе над портированием JDK, которые проводит Проект FreeBSD Java. Таким образом, вы должны относить свой Java-порт, как и любой другой, к категории `ports`, если решаемый вами вопрос не относится ни к реализации JDK, ни к [.filename]#bsd.java.mk#.
 
-Похожим образом определена политика по отношению к `CATEGORIES` порта Java, которая подробно описана в <<makefile-categories>>.
+Похожим образом определена политика по отношению к `CATEGORIES` порта Java, которая подробно описана в crossref:makefiles[makefile-categories, Разделение по категориям].
 
 [[using-php]]
 == Веб-приложения, Apache и PHP
diff --git a/documentation/content/ru/books/porters-handbook/testing/chapter.adoc b/documentation/content/ru/books/porters-handbook/testing/_index.adoc
similarity index 92%
rename from documentation/content/ru/books/porters-handbook/testing/chapter.adoc
rename to documentation/content/ru/books/porters-handbook/testing/_index.adoc
index 98b7c82e1f..a40e23725e 100644
--- a/documentation/content/ru/books/porters-handbook/testing/chapter.adoc
+++ b/documentation/content/ru/books/porters-handbook/testing/_index.adoc
@@ -49,7 +49,7 @@ endif::[]
 
 [NOTE]
 ====
-Возможность генерировать этот файл очень важна вне зависимости от того, какие параметры присутствуют в [.filename]#make.conf#, поэтому, пожалуйста, избегайте, таких вещей, как использование декларации `.error`, когда (к примеру) требования к зависимости не было удовлетворено. (Смотрите <<dads-dot-error>>.)
+Возможность генерировать этот файл очень важна вне зависимости от того, какие параметры присутствуют в [.filename]#make.conf#, поэтому, пожалуйста, избегайте, таких вещей, как использование декларации `.error`, когда (к примеру) требования к зависимости не было удовлетворено. (Смотрите crossref:porting-dads[dads-dot-error, Избегайте использования конструкции `.error`].)
 ====
 
 Если `make describe` выдаёт строчку, а не ошибку, то для вас это пройдёт безболезненно. Обратитесь к файлу [.filename]#bsd.port.mk#, чтобы выяснить значение выдаваемых строк.
@@ -59,7 +59,7 @@ endif::[]
 [[testing-portlint]]
 == Portlint
 
-Проверьте свою работу командой <<porting-portlint,`portlint`>> перед тем, как её отослать или перенести в дерево портов. `portlint` предупреждает вас о многих распространённых ошибках, как функциональных, так и стилистических. Для нового (или скопированного внутри хранилища) порта самым подходящим является запуск `portlint -A`; для уже существующего порта достаточно будет запустить `portlint -C`.
+Проверьте свою работу командой crossref:quick-porting[porting-portlint,`portlint`] перед тем, как её отослать или перенести в дерево портов. `portlint` предупреждает вас о многих распространённых ошибках, как функциональных, так и стилистических. Для нового (или скопированного внутри хранилища) порта самым подходящим является запуск `portlint -A`; для уже существующего порта достаточно будет запустить `portlint -C`.
 
 Так как для обнаружения ошибок `portlint` использует эвристические методы, то им могут выдаваться и ошибочные предупреждения. Кроме того, время от времени нечто, отмечаемое как некорректность, из-за ограничений механизма создания портов не может быть сделано никак иначе. Если вы сомневаетесь, то лучше всего спросить в {freebsd-ports}.
 
@@ -95,7 +95,7 @@ endif::[]
 
 Если что-то было установлено за пределами `PREFIX`, то процесс создания пакета сообщит об отсутствии файлов.
 
-Это также стоит проверить с использованием поддержки каталога сборки (смотрите <<staging>>):
+Это также стоит проверить с использованием поддержки каталога сборки (смотрите crossref:special[staging, Staging]):
 
 [source,shell]
 ....
diff --git a/documentation/content/ru/books/porters-handbook/upgrading/chapter.adoc b/documentation/content/ru/books/porters-handbook/upgrading/_index.adoc
similarity index 98%
rename from documentation/content/ru/books/porters-handbook/upgrading/chapter.adoc
rename to documentation/content/ru/books/porters-handbook/upgrading/_index.adoc
index 8996df3362..6314418994 100644
--- a/documentation/content/ru/books/porters-handbook/upgrading/chapter.adoc
+++ b/documentation/content/ru/books/porters-handbook/upgrading/_index.adoc
@@ -79,7 +79,7 @@ endif::[]
 Повторяем еще раз - для посылки обновлений существующих портов используйте утилиту man:diff[1], а не man:shar[1]! Это поможет понять коммиттерам портов, что именно было изменено.
 ====
 
-Теперь, когда вы проделали всё это, прочитайте о том, как поддерживать актуальное состояние, в <<keeping-up>>.
+Теперь, когда вы проделали всё это, прочитайте о том, как поддерживать актуальное состояние, в crossref:keeping-up[keeping-up, Актуализация].
 
 [[svn-diff]]
 == Использование Subversion для создания патчей
@@ -105,7 +105,7 @@ endif::[]
 % svn remove deleted_file
 ....
 
-Убедитесь, что вы проверяете порт в соответствии с рекомендуемым порядком проверки, описанным в <<porting-testing>> и <<porting-portlint>>.
+Убедитесь, что вы проверяете порт в соответствии с рекомендуемым порядком проверки, описанным в crossref:quick-porting[porting-testing, Тестирование порта] и crossref:quick-porting[porting-portlint, Проверка вашего порта утилитой `portlint`].
 
 [source,shell]
 ....
diff --git a/documentation/content/ru/books/porters-handbook/uses/chapter.adoc b/documentation/content/ru/books/porters-handbook/uses/_index.adoc
similarity index 55%
rename from documentation/content/ru/books/porters-handbook/uses/chapter.adoc
rename to documentation/content/ru/books/porters-handbook/uses/_index.adoc
index 2862084668..b9944e68d9 100644
--- a/documentation/content/ru/books/porters-handbook/uses/chapter.adoc
+++ b/documentation/content/ru/books/porters-handbook/uses/_index.adoc
@@ -46,56 +46,51 @@ endif::[]
 [[uses-intro]]
 == An Introduction to `USES`
 
-`USES` macros make it easy to declare requirements and settings for a port. They can add dependencies, change building behavior, add metadata to packages, and so on, all by selecting simple, preset values.
+`USES` macros make it easy to declare requirements and settings for a port.
+They can add dependencies, change building behavior, add metadata to packages, and so on, all by selecting simple, preset values.
 
-Each section in this chapter describes a possible value for `USES`, along with its possible arguments. Arguments are appeneded to the value after a colon (`:`). Multiple arguments are separated by commas (`,`).
+Each section in this chapter describes a possible value for `USES`, along with its possible arguments.
+Arguments are appended to the value after a colon (`:`).
+Multiple arguments are separated by commas (`,`).
 
 [[uses-intro-ex1]]
 .Using Multiple Values
 [example]
 ====
-
 [.programlisting]
 ....
 USES=	bison perl
 ....
-
 ====
 
 [[uses-intro-ex2]]
 .Adding an Argument
 [example]
 ====
-
 [.programlisting]
 ....
 USES=	tar:xz
 ....
-
 ====
 
 [[uses-intro-ex3]]
 .Adding Multiple Arguments
 [example]
 ====
-
 [.programlisting]
 ....
 USES=	drupal:7,theme
 ....
-
 ====
 
 [[uses-intro-ex4]]
 .Mixing it All Together
 [example]
 ====
-
 [.programlisting]
 ....
 USES=	pgsql:9.3+ cpe python:2.7,build
 ....
-
 ====
 
 [[uses-7z]]
@@ -103,21 +98,30 @@ USES=	pgsql:9.3+ cpe python:2.7,build
 
 Possible arguments: (none), `p7zip`, `partial`
 
-Extract using man:7z[1] instead of man:bsdtar[1] and sets `EXTRACT_SUFX=.7z`. The `p7zip` option forces a dependency on the `7z` from package:archivers/p7zip[] if the one from the base system is not able to extract the files. `EXTRACT_SUFX` is not changed if the `partial` option is used, this can be used if the main distribution file does not have a [.filename]#.7z# extension.
+Extract using man:7z[1] instead of man:bsdtar[1] and sets `EXTRACT_SUFX=.7z`.
+The `p7zip` option forces a dependency on the `7z` from package:archivers/p7zip[] if the one from the base system is not able to extract the files.
+`EXTRACT_SUFX` is not changed if the `partial` option is used, this can be used if the main distribution file does not have a [.filename]#.7z# extension.
 
 [[uses-ada]]
 == `ada`
 
 Possible arguments: (none), `5`, `6`
 
-Depends on an Ada-capable compiler, and sets `CC` accordingly. Defaults to use gcc 5 from ports. Use the `:__X__` version option to force building with a different version.
+Depends on an Ada-capable compiler, and sets `CC` accordingly.
+Defaults to use gcc 5 from ports.
+Use the `:_X_` version option to force building with a different version.
 
 [[uses-autoreconf]]
 == `autoreconf`
 
 Possible arguments: (none), `build`
 
-Runs `autoreconf`. It encapsulates the `aclocal`, `autoconf`, `autoheader`, `automake`, `autopoint`, and `libtoolize` commands. Each command applies to [.filename]#${AUTORECONF_WRKSRC}/configure.ac# or its old name, [.filename]#${AUTORECONF_WRKSRC}/configure.in#. If [.filename]#configure.ac# defines subdirectories with their own [.filename]#configure.ac# using `AC_CONFIG_SUBDIRS`, `autoreconf` will recursively update those as well. The `:build` argument only adds build time dependencies on those tools but does not run `autoreconf`. A port can set `AUTORECONF_WRKSRC` if `WRKSRC` does not contain the path to [.filename]#configure.ac#.
+Runs `autoreconf`.
+It encapsulates the `aclocal`, `autoconf`, `autoheader`, `automake`, `autopoint`, and `libtoolize` commands.
+Each command applies to [.filename]#${AUTORECONF_WRKSRC}/configure.ac# or its old name, [.filename]#${AUTORECONF_WRKSRC}/configure.in#.
+If [.filename]#configure.ac# defines subdirectories with their own [.filename]#configure.ac# using `AC_CONFIG_SUBDIRS`, `autoreconf` will recursively update those as well.
+The `:build` argument only adds build time dependencies on those tools but does not run `autoreconf`.
+A port can set `AUTORECONF_WRKSRC` if `WRKSRC` does not contain the path to [.filename]#configure.ac#.
 
 [[uses-blaslapack]]
 == `blaslapack`
@@ -131,26 +135,37 @@ Adds dependencies on Blas / Lapack libraries.
 
 Possible arguments: (none), `48`, `5` (default), `6`
 
-Add dependency on the Berkeley DB library. Default to package:databases/db5[]. It can also depend on package:databases/db48[] when using the `:48` argument or package:databases/db6[] with `:6`. It is possible to declare a range of acceptable values, `:48+` finds the highest installed version, and falls back to 4.8 if nothing else is installed. `INVALID_BDB_VER` can be used to specify versions which do not work with this port. The framework exposes the following variables to the port:
+Add dependency on the Berkeley DB library.
+Default to package:databases/db5[].
+It can also depend on package:databases/db48[] when using the `:48` argument or package:databases/db6[] with `:6`.
+It is possible to declare a range of acceptable values, `:48+` finds the highest installed version, and falls back to 4.8 if nothing else is installed.
+`INVALID_BDB_VER` can be used to specify versions which do not work with this port.
+The framework exposes the following variables to the port:
 
 `BDB_LIB_NAME`::
-The name of the Berkeley DB library. For example, when using package:databases/db5[], it contains `db-5.3`.
+The name of the Berkeley DB library.
+For example, when using package:databases/db5[], it contains `db-5.3`.
 
 `BDB_LIB_CXX_NAME`::
-The name of the Berkeley DBC++ library. For example, when using package:databases/db5[], it contains `db_cxx-5.3`.
+The name of the Berkeley DBC++ library.
+For example, when using package:databases/db5[], it contains `db_cxx-5.3`.
 
 `BDB_INCLUDE_DIR`::
-The location of the Berkeley DB include directory. For example, when using package:databases/db5[], it will contain `${LOCALBASE}/include/db5`.
+The location of the Berkeley DB include directory.
+For example, when using package:databases/db5[], it will contain `${LOCALBASE}/include/db5`.
 
 `BDB_LIB_DIR`::
-The location of the Berkeley DB library directory. For example, when using package:databases/db5[], it contains `${LOCALBASE}/lib`.
+The location of the Berkeley DB library directory.
+For example, when using package:databases/db5[], it contains `${LOCALBASE}/lib`.
 
 `BDB_VER`::
-The detected Berkeley DB version. For example, if using `USES=bdb:48+` and Berkeley DB 5 is installed, it contains `5`.
+The detected Berkeley DB version.
+For example, if using `USES=bdb:48+` and Berkeley DB 5 is installed, it contains `5`.
 
 [IMPORTANT]
 ====
-package:databases/db48[] is deprecated and unsupported. It must not be used by any port.
+package:databases/db48[] is deprecated and unsupported.
+It must not be used by any port.
 ====
 
 [[uses-bison]]
@@ -165,23 +180,32 @@ Uses package:devel/bison[] By default, with no arguments or with the `build` arg
 
 [IMPORTANT]
 ====
-Ports should not be created for Haskell libraries, see <<haskell-libs>> for more information.
+Ports should not be created for Haskell libraries, see crossref:special[haskell-libs,Haskell Libraries] for more information.
 ====
 
 Possible arguments: (none), `hpack`
 
-Sets default values and targets used to build Haskell software using Cabal. A build dependency on the Haskell compiler port (GHC) is added. If `hpack` argument is given, a build dependency on package:devel/hs-hpack[] is added and `hpack` is invoked at configuration step to generate .cabal file.
+Sets default values and targets used to build Haskell software using Cabal.
+A build dependency on the Haskell compiler port (GHC) is added.
+If `hpack` argument is given, a build dependency on package:devel/hs-hpack[] is added and `hpack` is invoked at configuration step to generate.
+cabal file.
 
 The framework provides the following variables:
 
 `USE_CABAL`::
-If the software uses Haskell dependencies, list them in this variable. Each item should be present on Hackage and be listed in form `packagename-_0.1.2_`. Dependencies can have revisions, which are specified after the `_` symbol. Automatic generation of dependency list is supported, see <<using-cabal>>.
+If the software uses Haskell dependencies, list them in this variable.
+Each item should be present on Hackage and be listed in form `packagename-_0.1.2_`.
+Dependencies can have revisions, which are specified after the `_` symbol.
+Automatic generation of dependency list is supported, see crossref:special[using-cabal,Building Haskell Applications with `cabal`].
 
 `CABAL_FLAGS`::
-List of flags to be passed to `cabal-install` during the configuring and building stage. The flags are passed verbatim.
+List of flags to be passed to `cabal-install` during the configuring and building stage.
+The flags are passed verbatim.
 
 `EXECUTABLES`::
-List of executable files installed by the port. Default value: `${PORTNAME}`. Items from this list are automatically added to pkg-plist.
+List of executable files installed by the port.
+Default value: `${PORTNAME}`.
+Items from this list are automatically added to pkg-plist.
 
 `SKIP_CABAL_PLIST`::
 If defined, do not add items from `${EXECUTABLES}` to pkg-plist.
@@ -193,7 +217,8 @@ Adds items to `${USE_CABAL}` depending on `opt` option.
 Adds items to `${EXECUTABLES}` depending on `opt` option.
 
 `opt_CABAL_FLAGS`::
-If `opt` is enabled, append the value to `${CABAL_FLAGS}`. Otherwise, append `-value` to disable the flag.
+If `opt` is enabled, append the value to `${CABAL_FLAGS}`.
+Otherwise, append `-value` to disable the flag.
 
 `FOO_DATADIR_VARS`::
 For an executable named `FOO` list Haskell packages, whose data files should be accessible by the executable.
@@ -203,38 +228,53 @@ For an executable named `FOO` list Haskell packages, whose data files should be
 
 Possible arguments: (none)
 
-Uses Cargo for configuring, building, and testing. It can be used to port Rust applications that use the Cargo build system. For more information see <<using-cargo>>.
+Uses Cargo for configuring, building, and testing.
+It can be used to port Rust applications that use the Cargo build system.
+For more information see crossref:special[using-cargo,Building Rust Applications with `cargo`].
 
 [[uses-charsetfix]]
 == `charsetfix`
 
 Possible arguments: (none)
 
-Prevents the port from installing [.filename]#charset.alias#. This must be installed only by package:converters/libiconv[]. `CHARSETFIX_MAKEFILEIN` can be set to a path relative to `WRKSRC` if [.filename]#charset.alias# is not installed by [.filename]#${WRKSRC}/Makefile.in#.
+Prevents the port from installing [.filename]#charset.alias#.
+This must be installed only by package:converters/libiconv[].
+`CHARSETFIX_MAKEFILEIN` can be set to a path relative to `WRKSRC` if [.filename]#charset.alias# is not installed by [.filename]#${WRKSRC}/Makefile.in#.
 
 [[uses-cmake]]
 == `cmake`
 
-Possible arguments: (none), `insource`, `noninja`, `run`
+Possible arguments: (none), `insource`, `noninja`, `run`, `testing`
 
-Uses CMake for configuring and building.
+Use CMake for configuring the port and generating a build system.
 
-By default an out-of-source build is performed, leaving the sources in `WRKSRC` free from build artifacts. With the `insource` argument, an in-source build will be performed instead. Setting it should be the exception when a regular out-of-source build does not work.
+By default an out-of-source build is performed, leaving the sources in `WRKSRC` free from build artifacts.
+With the `insource` argument, an in-source build will be performed instead.
+This argument should be an exception, used only when a regular out-of-source build does not work.
 
-By default Ninja is used for the build. In some cases this does not work correctly. With the `noninja` argument, the build will fallback to using regular `make` for builds. It should only be used if a Ninja-based build does not work.
+By default Ninja (package:devel/ninja[]) is used for the build.
+In some cases this does not work correctly.
+With the `noninja` argument, the build will use regular `make` for builds.
+This argument should only be used if a Ninja-based build does not work.
 
 With the `run` argument, a run dependency is registered in addition to a build dependency.
 
-For more information see <<using-cmake>>.
+With the `testing` argument, a test-target is added that uses CTest.
+When running tests the port will be re-configured for testing and re-built.
+
+For more information see crossref:special[using-cmake,Using `cmake`].
 
 [[uses-compiler]]
 == `compiler`
 
-Possible arguments: (none), `env` (default, implicit), `{c-plus-plus}17-lang`, `{c-plus-plus}14-lang`, `{c-plus-plus}11-lang`, `gcc-{c-plus-plus}11-lib`, `{c-plus-plus}11-lib`, `{c-plus-plus}0x`, `c11`, `openmp`, `nestedfct`, `features`
+Possible arguments: (none), `env` (default, implicit), `{c-plus-plus}17-lang`, `{c-plus-plus}14-lang`, `{c-plus-plus}11-lang`, `gcc-{c-plus-plus}11-lib`, `{c-plus-plus}11-lib`, `{c-plus-plus}0x`, `c11`, `nestedfct`, `features`
 
-Determines which compiler to use based on any given wishes. Use `{c-plus-plus}17-lang` if the port needs a {c-plus-plus}17-capable compiler, `{c-plus-plus}14-lang` if the port needs a {c-plus-plus}14-capable compiler, `{c-plus-plus}11-lang` if the port needs a {c-plus-plus}11-capable compiler, `gcc-{c-plus-plus}11-lib` if the port needs the `g++` compiler with a {c-plus-plus}11 library, or `{c-plus-plus}11-lib` if the port needs a {c-plus-plus}11-ready standard library. If the port needs a compiler understanding {c-plus-plus}0X, C11, OpenMP, or nested functions, the corresponding parameters should be used.
+Determines which compiler to use based on any given wishes.
+Use `{c-plus-plus}17-lang` if the port needs a {c-plus-plus}17-capable compiler, `{c-plus-plus}14-lang` if the port needs a {c-plus-plus}14-capable compiler, `{c-plus-plus}11-lang` if the port needs a {c-plus-plus}11-capable compiler, `gcc-{c-plus-plus}11-lib` if the port needs the `g++` compiler with a {c-plus-plus}11 library, or `{c-plus-plus}11-lib` if the port needs a {c-plus-plus}11-ready standard library.
+If the port needs a compiler understanding {c-plus-plus}0X, C11 or nested functions, the corresponding parameters should be used.
 
-Use `features` to request a list of features supported by the default compiler. After including [.filename]#bsd.port.pre.mk# the port can inspect the results using these variables:
+Use `features` to request a list of features supported by the default compiler.
+After including [.filename]#bsd.port.pre.mk# the port can inspect the results using these variables:
 
 * `COMPILER_TYPE`: the default compiler on the system, either gcc or clang
 * `ALT_COMPILER_TYPE`: the alternative compiler on the system, either gcc or clang. Only set if two compilers are present in the base system.
@@ -248,10 +288,11 @@ Use `features` to request a list of features supported by the default compiler.
 
 Possible arguments: (none)
 
-Include Common Platform Enumeration (CPE) information in package manifest as a CPE 2.3 formatted string. See the http://scap.nist.gov/specifications/cpe/[CPE specification] for details. To add CPE information to a port, follow these steps:
+Include Common Platform Enumeration (CPE) information in package manifest as a CPE 2.3 formatted string.
+See the http://scap.nist.gov/specifications/cpe/[CPE specification] for details.
+To add CPE information to a port, follow these steps:
 
 [.procedure]
-====
 . Search for the official CPE entry for the software product either by using the NVD's http://web.nvd.nist.gov/view/cpe/search[CPE search engine] or in the http://static.nvd.nist.gov/feeds/xml/cpe/dictionary/official-cpe-dictionary_v2.3.xml[official CPE dictionary] (warning, very large XML file). _Do not ever make up CPE data._
 . Add `cpe` to `USES` and compare the result of `make -V CPE_STR` to the CPE dictionary entry. Continue one step at a time until `make -V CPE_STR` is correct.
 . If the product name (second field, defaults to `PORTNAME`) is incorrect, define `CPE_PRODUCT`.
@@ -261,21 +302,24 @@ Include Common Platform Enumeration (CPE) information in package manifest as a C
 . If it is still not correct, check [.filename]#Mk/Uses/cpe.mk# for additional details, or contact the {ports-secteam}.
 . Derive as much as possible of the CPE name from existing variables such as `PORTNAME` and `PORTVERSION`. Use variable modifiers to extract the relevant portions from these variables rather than hardcoding the name.
 . _Always_ run `make -V CPE_STR` and check the output before committing anything that changes `PORTNAME` or `PORTVERSION` or any other variable which is used to derive `CPE_STR`.
-====
 
 [[uses-cran]]
 == `cran`
 
 Possible arguments: (none), `auto-plist`, `compiles`
 
-Uses the Comprehensive R Archive Network. Specify `auto-plist` to automatically generate [.filename]#pkg-plist#. Specify `compiles` if the port has code that need to be compiled.
+Uses the Comprehensive R Archive Network.
+Specify `auto-plist` to automatically generate [.filename]#pkg-plist#.
+Specify `compiles` if the port has code that need to be compiled.
 
 [[uses-desktop-file-utils]]
 == `desktop-file-utils`
 
 Possible arguments: (none)
 
-Uses update-desktop-database from package:devel/desktop-file-utils[]. An extra post-install step will be run without interfering with any post-install steps already in the port [.filename]#Makefile#. A line with <<plist-keywords-desktop-file-utils,`@desktop-file-utils`>> will be added to the plist.
+Uses update-desktop-database from package:devel/desktop-file-utils[].
+An extra post-install step will be run without interfering with any post-install steps already in the port [.filename]#Makefile#.
+A line with <<plist-keywords-desktop-file-utils,`@desktop-file-utils`>> will be added to the plist.
 
 [[uses-desthack]]
 == `desthack`
@@ -289,14 +333,19 @@ Changes the behavior of GNU configure to properly support `DESTDIR` in case the
 
 Possible arguments: (none), _ARGS_
 
-Set up a virtual display environment. If the environment variable `DISPLAY` is not set, then Xvfb is added as a build dependency, and `CONFIGURE_ENV` is extended with the port number of the currently running instance of Xvfb. The _ARGS_ parameter defaults to `install` and controls the phase around which to start and stop the virtual display.
+Set up a virtual display environment.
+If the environment variable `DISPLAY` is not set, then Xvfb is added as a build dependency, and `CONFIGURE_ENV` is extended with the port number of the currently running instance of Xvfb.
+The _ARGS_ parameter defaults to `install` and controls the phase around which to start and stop the virtual display.
 
 [[uses-dos2unix]]
 == `dos2unix`
 
 Possible arguments: (none)
 
-The port has files with line endings in DOS format which need to be converted. Several variables can be set to control which files will be converted. The default is to convert _all_ files, including binaries. See <<slow-patch-automatic-replacements>> for examples.
+The port has files with line endings in DOS format which need to be converted.
+Several variables can be set to control which files will be converted.
+The default is to convert _all_ files, including binaries.
+See crossref:slow-porting[slow-patch-automatic-replacements,Simple Automatic Replacements] for examples.
 
 * `DOS2UNIX_REGEX`: match file names based on a regular expression.
 * `DOS2UNIX_FILES`: match literal file names.
@@ -308,21 +357,33 @@ The port has files with line endings in DOS format which need to be converted. S
 
 Possible arguments: `7`, `module`, `theme`
 
-Automate installation of a port that is a Drupal theme or module. Use with the version of Drupal that the port is expecting. For example, `USES=drupal:7,module` says that this port creates a Drupal 6 module. A Drupal 7 theme can be specified with `USES=drupal:7,theme`.
+Automate installation of a port that is a Drupal theme or module.
+Use with the version of Drupal that the port is expecting.
+For example, `USES=drupal:7,module` says that this port creates a Drupal 6 module.
+A Drupal 7 theme can be specified with `USES=drupal:7,theme`.
+
+[[uses-eigen]]
+== `eigen`
+
+Possible arguments: 2, 3, build (default), run
+
+Add dependency on package:math/eigen[].
 
 [[uses-fakeroot]]
 == `fakeroot`
 
 Possible arguments: (none)
 
-Changes some default behavior of build systems to allow installing as a user. See https://wiki.debian.org/FakeRoot[] for more information on `fakeroot`.
+Changes some default behavior of build systems to allow installing as a user.
+See https://wiki.debian.org/FakeRoot[] for more information on `fakeroot`.
 
 [[uses-fam]]
 == `fam`
 
 Possible arguments: (none), `fam`, `gamin`
 
-Uses a File Alteration Monitor as a library dependency, either package:devel/fam[] or package:devel/gamin[]. End users can set WITH_FAM_SYSTEM to specify their preference.
+Uses a File Alteration Monitor as a library dependency, either package:devel/fam[] or package:devel/gamin[].
+End users can set WITH_FAM_SYSTEM to specify their preference.
 
 [[uses-firebird]]
 == `firebird`
@@ -336,7 +397,10 @@ Add a dependency to the client library of the Firebird database.
 
 Possible arguments: (none), `fc`, `fcfontsdir` (default), `fontsdir`, `none`
 
-Adds a runtime dependency on tools needed to register fonts. Depending on the argument, add a `<<plist-keywords-fc,@fc>> ${FONTSDIR}` line, `<<plist-keywords-fcfontsdir,@fcfontsdir>> ${FONTSDIR}` line, `<<plist-keywords-fontsdir,@fontsdir>> ${FONTSDIR}` line, or no line if the argument is `none`, to the plist. `FONTSDIR` defaults to [.filename]#${PREFIX}/shared/fonts/${FONTNAME}# and `FONTNAME` to `${PORTNAME}`. Add `FONTSDIR` to `PLIST_SUB` and `SUB_LIST`
+Adds a runtime dependency on tools needed to register fonts.
+Depending on the argument, add a `crossref:plist[plist-keywords-fc,@fc] ${FONTSDIR}` line, `crossref:plist[plist-keywords-fcfontsdir,@fcfontsdir] ${FONTSDIR}` line, `crossref:plist[plist-keywords-fontsdir,@fontsdir] ${FONTSDIR}` line, or no line if the argument is `none`, to the plist.
+`FONTSDIR` defaults to [.filename]#${PREFIX}/share/fonts/${FONTNAME}# and `FONTNAME` to `${PORTNAME}`.
+Add `FONTSDIR` to `PLIST_SUB` and `SUB_LIST`
 
 [[uses-fortran]]
 == `fortran`
@@ -357,42 +421,53 @@ The port will depend on the FUSE library and handle the dependency on the kernel
 
 Possible arguments: (none), `noautoplist`
 
-Handle building with RubyGems. If `noautoplist` is used, the packing list is not generated automatically.
+Handle building with RubyGems.
+If `noautoplist` is used, the packing list is not generated automatically.
 
 [[uses-gettext]]
 == `gettext`
 
 Possible arguments: (none)
 
-Deprecated. Will include both <<uses-gettext-runtime,`gettext-runtime`>> and <<uses-gettext-tools,`gettext-tools`>>.
+Deprecated.
+Will include both <<uses-gettext-runtime,`gettext-runtime`>> and <<uses-gettext-tools,`gettext-tools`>>.
 
 [[uses-gettext-runtime]]
 == `gettext-runtime`
 
 Possible arguments: (none), `lib` (default), `build`, `run`
 
-Uses package:devel/gettext-runtime[]. By default, with no arguments or with the `lib` argument, implies a library dependency on [.filename]#libintl.so#. `build` and `run` implies, respectively a build-time and a run-time dependency on [.filename]#gettext#.
+Uses package:devel/gettext-runtime[].
+By default, with no arguments or with the `lib` argument, implies a library dependency on [.filename]#libintl.so#.
+`build` and `run` implies, respectively a build-time and a run-time dependency on [.filename]#gettext#.
 
 [[uses-gettext-tools]]
 == `gettext-tools`
 
 Possible arguments: (none), `build` (default), `run`
 
-Uses package:devel/gettext-tools[]. By default, with no argument, or with the `build` argument, a build time dependency on [.filename]#msgfmt# is registered. With the `run` argument, a run-time dependency is registered.
+Uses package:devel/gettext-tools[].
+By default, with no argument, or with the `build` argument, a build time dependency on [.filename]#msgfmt# is registered.
+With the `run` argument, a run-time dependency is registered.
 
 [[uses-ghostscript]]
 == `ghostscript`
 
 Possible arguments: _X_, `build`, `run`, `nox11`
 
-A specific version _X_ can be used. Possible versions are `7`, `8`, `9`, and `agpl` (default). `nox11` indicates that the `-nox11` version of the port is required. `build` and `run` add build- and run-time dependencies on Ghostscript. The default is both build- and run-time dependencies.
+A specific version _X_ can be used. Possible versions are `7`, `8`, `9`, and `agpl` (default).
+`nox11` indicates that the `-nox11` version of the port is required.
+`build` and `run` add build- and run-time dependencies on Ghostscript.
+The default is both build- and run-time dependencies.
 
 [[uses-gl]]
 == `gl`
 
 Possible arguments: (none)
 
-Provides an easy way to depend on GL components. The components should be listed in `USE_GL`. The available components are:
+Provides an easy way to depend on GL components.
+The components should be listed in `USE_GL`.
+The available components are:
 
 `egl`::
 add a library dependency on [.filename]#libEGL.so# from package:graphics/libglvnd[]
@@ -430,7 +505,9 @@ Uses package:devel/gmake[] as a build-time dependency and sets up the environmen
 
 Possible arguments: (none)
 
-Provides an easy way to depend on GNOME components. The components should be listed in `USE_GNOME`. The available components are:
+Provides an easy way to depend on GNOME components.
+The components should be listed in `USE_GNOME`.
+The available components are:
 
 * `atk`
 * `atkmm`
@@ -514,7 +591,8 @@ Provides an easy way to depend on GNOME components. The components should be lis
 * `vte`
 * `vte3`
 
-The default dependency is build- and run-time, it can be changed with `:build` or `:run`. For example:
+The default dependency is build- and run-time, it can be changed with `:build` or `:run`.
+For example:
 
 [.programlisting]
 ....
@@ -522,30 +600,45 @@ USES=		gnome
 USE_GNOME=	gnomemenus3:build intlhack
 ....
 
-See <<using-gnome>> for more information.
+See crossref:special[using-gnome,Using GNOME] for more information.
 
 [[uses-go]]
 == `go`
 
 [IMPORTANT]
 ====
-Ports should not be created for Go libs, see <<go-libs>> for more information.
+Ports should not be created for Go libs, see crossref:special[go-libs,Go Libraries] for more information.
 ====
 
 Possible arguments: (none), `modules`, `no_targets`, `run`
 
-Sets default values and targets used to build Go software. A build dependency on the Go compiler port selected via `GO_PORT` is added. By default the build is performed in GOPATH mode. If Go software uses modules, the modules-aware mode can be switched on with `modules` argument. `no_targets` will setup build environment like `GO_ENV`, `GO_BUILDFLAGS` but skip creating `post-extract` and `do-{build,install,test}` targets. `run` will also add a run dependency on what is in `GO_PORT`.
+Sets default values and targets used to build Go software.
+A build dependency on the Go compiler port selected via `GO_PORT` is added.
+By default the build is performed in GOPATH mode.
+If Go software uses modules, the modules-aware mode can be switched on with `modules` argument.
+`no_targets` will setup build environment like `GO_ENV`, `GO_BUILDFLAGS` but skip creating `post-extract` and `do-{build,install,test}` targets.
+`run` will also add a run dependency on what is in `GO_PORT`.
 
 The build process is controlled by several variables:
 
+`GO_MODULE`::
+The name of the application module as specified by the `module` directive in `go.mod`.
+In most cases, this is the only required variable for ports that use Go modules.
+
 `GO_PKGNAME`::
-The name of the Go package when building in GOPATH mode. This is the directory that will be created in `${GOPATH}/src`. If not set explicitly and `GH_SUBDIR` or `GL_SUBDIR` is present, `GO_PKGNAME` will be inferred from it. It is not needed when building in modules-aware mode.
+The name of the Go package when building in GOPATH mode.
+This is the directory that will be created in `${GOPATH}/src`.
+If not set explicitly and `GH_SUBDIR` or `GL_SUBDIR` is present, `GO_PKGNAME` will be inferred from it.
*** 895 LINES SKIPPED ***