21 files changed, 303 insertions, 285 deletions

diff --git a/documentation/content/en/books/porters-handbook/_index.adoc b/documentation/content/en/books/porters-handbook/_index.adoc
index 4d1f9c2a8e..0a2f7a0c11 100644
--- a/documentation/content/en/books/porters-handbook/_index.adoc
+++ b/documentation/content/en/books/porters-handbook/_index.adoc
@@ -3,80 +3,20 @@ title: FreeBSD Porter's Handbook
 authors: 
   - author: The FreeBSD Documentation Project
 copyright: 2000-2020 The FreeBSD Documentation Project
-releaseinfo: "$FreeBSD$" 
-trademarks: ["freebsd", "sun", "unix", "general"] 
+trademarks: ["freebsd", "sun", "unix", "general"]
+next: books/porters-handbook/porting-why
 ---
 
 = FreeBSD Porter's Handbook
 :doctype: book
 :toc: macro
-:toclevels: 2
+:toclevels: 1
 :icons: font
-:xrefstyle: basic
-:relfileprefix: ../
-:outfilesuffix:
 :sectnums:
 :sectnumlevels: 6
-:partnums:
-:chapter-signifier: Chapter
-:part-signifier: Part
 :source-highlighter: rouge
 :experimental:
-:skip-front-matter:
-
-ifeval::["{backend}" == "html5"]
-include::shared/mirrors.adoc[]
-include::shared/authors.adoc[]
-include::shared/releases.adoc[]
-include::shared/en/mailing-lists.adoc[]
-include::shared/en/teams.adoc[]
-include::shared/en/urls.adoc[]
-:chapters-path: content/en/books/porters-handbook/
-endif::[]
-
-ifeval::["{backend}" == "pdf"]
-include::../../../../shared/mirrors.adoc[]
-include::../../../../shared/authors.adoc[]
-include::../../../../shared/releases.adoc[]
-include::../../../../shared/en/mailing-lists.adoc[]
-include::../../../../shared/en/teams.adoc[]
-include::../../../../shared/en/urls.adoc[]
-:chapters-path:
-endif::[]
-
-ifeval::["{backend}" == "epub3"]
-include::../../../../shared/mirrors.adoc[]
-include::../../../../shared/authors.adoc[]
-include::../../../../shared/releases.adoc[]
-include::../../../../shared/en/mailing-lists.adoc[]
-include::../../../../shared/en/teams.adoc[]
-include::../../../../shared/en/urls.adoc[]
-:chapters-path:
-endif::[]
 
 '''
 
-toc::[]
-
-include::{chapters-path}toc-tables.adoc[]
-
-include::{chapters-path}toc-examples.adoc[]
-
-include::{chapters-path}porting-why/chapter.adoc[leveloffset=+1, lines=7..21;32..-1]
-include::{chapters-path}new-port/chapter.adoc[leveloffset=+1, lines=7..21;32..-1]
-include::{chapters-path}quick-porting/chapter.adoc[leveloffset=+1, lines=7..21;32..-1]
-include::{chapters-path}slow-porting/chapter.adoc[leveloffset=+1, lines=7..21;32..-1]
-include::{chapters-path}makefiles/chapter.adoc[leveloffset=+1, lines=7..22;33..-1]
-include::{chapters-path}special/chapter.adoc[leveloffset=+1, lines=7..21;32..-1]
-include::{chapters-path}flavors/chapter.adoc[leveloffset=+1, lines=7..21;32..-1]
-include::{chapters-path}plist/chapter.adoc[leveloffset=+1, lines=7..21;32..-1]
-include::{chapters-path}pkg-files/chapter.adoc[leveloffset=+1, lines=7..21;32..-1]
-include::{chapters-path}testing/chapter.adoc[leveloffset=+1, lines=7..21;32..-1]
-include::{chapters-path}upgrading/chapter.adoc[leveloffset=+1, lines=7..21;32..-1]
-include::{chapters-path}security/chapter.adoc[leveloffset=+1, lines=7..21;32..-1]
-include::{chapters-path}porting-dads/chapter.adoc[leveloffset=+1, lines=7..23;34..-1]
-include::{chapters-path}porting-samplem/chapter.adoc[leveloffset=+1, lines=7..21;32..-1]
-include::{chapters-path}order/chapter.adoc[leveloffset=+1, lines=7..21;32..-1]
-include::{chapters-path}keeping-up/chapter.adoc[leveloffset=+1, lines=7..21;32..-1]
-include::{chapters-path}uses/chapter.adoc[leveloffset=+1, lines=7..22;33..-1]
-include::{chapters-path}versions/chapter.adoc[leveloffset=+1, lines=6..20;31..-1]
+include::content/en/books/porters-handbook/toc.adoc[]
diff --git a/documentation/content/en/books/porters-handbook/book.adoc b/documentation/content/en/books/porters-handbook/book.adoc
new file mode 100644
index 0000000000..3c56e705f4
--- /dev/null
+++ b/documentation/content/en/books/porters-handbook/book.adoc
@@ -0,0 +1,81 @@
+---
+title: FreeBSD Porter's Handbook
+authors: 
+  - author: The FreeBSD Documentation Project
+copyright: 2000-2020 The FreeBSD Documentation Project
+trademarks: ["freebsd", "sun", "unix", "general"] 
+---
+
+= FreeBSD Porter's Handbook
+:doctype: book
+:toc: macro
+:toclevels: 2
+:icons: font
+:xrefstyle: basic
+:relfileprefix: ../
+:outfilesuffix:
+:sectnums:
+:sectnumlevels: 6
+:partnums:
+:chapter-signifier: Chapter
+:part-signifier: Part
+:source-highlighter: rouge
+:experimental:
+:skip-front-matter:
+
+ifeval::["{backend}" == "html5"]
+include::shared/mirrors.adoc[]
+include::shared/authors.adoc[]
+include::shared/releases.adoc[]
+include::shared/en/mailing-lists.adoc[]
+include::shared/en/teams.adoc[]
+include::shared/en/urls.adoc[]
+:chapters-path: content/en/books/porters-handbook/
+endif::[]
+
+ifeval::["{backend}" == "pdf"]
+include::../../../../shared/mirrors.adoc[]
+include::../../../../shared/authors.adoc[]
+include::../../../../shared/releases.adoc[]
+include::../../../../shared/en/mailing-lists.adoc[]
+include::../../../../shared/en/teams.adoc[]
+include::../../../../shared/en/urls.adoc[]
+:chapters-path:
+endif::[]
+
+ifeval::["{backend}" == "epub3"]
+include::../../../../shared/mirrors.adoc[]
+include::../../../../shared/authors.adoc[]
+include::../../../../shared/releases.adoc[]
+include::../../../../shared/en/mailing-lists.adoc[]
+include::../../../../shared/en/teams.adoc[]
+include::../../../../shared/en/urls.adoc[]
+:chapters-path:
+endif::[]
+
+'''
+
+toc::[]
+
+include::{chapters-path}toc-tables.adoc[]
+
+include::{chapters-path}toc-examples.adoc[]
+
+include::{chapters-path}porting-why/_index.adoc[leveloffset=+1, lines=7..21;32..-1]
+include::{chapters-path}new-port/_index.adoc[leveloffset=+1, lines=7..21;32..-1]
+include::{chapters-path}quick-porting/_index.adoc[leveloffset=+1, lines=7..21;32..-1]
+include::{chapters-path}slow-porting/_index.adoc[leveloffset=+1, lines=7..21;32..-1]
+include::{chapters-path}makefiles/_index.adoc[leveloffset=+1, lines=7..22;33..-1]
+include::{chapters-path}special/_index.adoc[leveloffset=+1, lines=7..21;32..-1]
+include::{chapters-path}flavors/_index.adoc[leveloffset=+1, lines=7..21;32..-1]
+include::{chapters-path}plist/_index.adoc[leveloffset=+1, lines=7..21;32..-1]
+include::{chapters-path}pkg-files/_index.adoc[leveloffset=+1, lines=7..21;32..-1]
+include::{chapters-path}testing/_index.adoc[leveloffset=+1, lines=7..21;32..-1]
+include::{chapters-path}upgrading/_index.adoc[leveloffset=+1, lines=7..21;32..-1]
+include::{chapters-path}security/_index.adoc[leveloffset=+1, lines=7..21;32..-1]
+include::{chapters-path}porting-dads/_index.adoc[leveloffset=+1, lines=7..23;34..-1]
+include::{chapters-path}porting-samplem/_index.adoc[leveloffset=+1, lines=7..21;32..-1]
+include::{chapters-path}order/_index.adoc[leveloffset=+1, lines=7..21;32..-1]
+include::{chapters-path}keeping-up/_index.adoc[leveloffset=+1, lines=7..21;32..-1]
+include::{chapters-path}uses/_index.adoc[leveloffset=+1, lines=7..22;33..-1]
+include::{chapters-path}versions/_index.adoc[leveloffset=+1, lines=6..20;31..-1]
diff --git a/documentation/content/en/books/porters-handbook/chapters-order.adoc b/documentation/content/en/books/porters-handbook/chapters-order.adoc
index 3aaba51a43..81f5b000cb 100644
--- a/documentation/content/en/books/porters-handbook/chapters-order.adoc
+++ b/documentation/content/en/books/porters-handbook/chapters-order.adoc
@@ -1,18 +1,18 @@
-porting-why/chapter.adoc
-new-port/chapter.adoc
-quick-porting/chapter.adoc
-slow-porting/chapter.adoc
-makefiles/chapter.adoc
-special/chapter.adoc
-flavors/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
-order/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
+flavors/_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
+order/_index.adoc
+keeping-up/_index.adoc
+uses/_index.adoc
+versions/_index.adoc
diff --git a/documentation/content/en/books/porters-handbook/flavors/chapter.adoc b/documentation/content/en/books/porters-handbook/flavors/_index.adoc
index dd17300133..0e540c204d 100644
--- a/documentation/content/en/books/porters-handbook/flavors/chapter.adoc
+++ b/documentation/content/en/books/porters-handbook/flavors/_index.adoc
@@ -180,7 +180,7 @@ lite_PKGNAMESUFFIX=	-lite
 [[flavors-auto-php]]
 == `USES=php` and Flavors
 
-When using <<uses-php,`php`>> with one of these arguments, `phpize`, `ext`, `zend`, or `pecl`, the port will automatically have `FLAVORS` filled in with the PHP versions it supports.
+When using crossref:uses[uses-php,`php`] with one of these arguments, `phpize`, `ext`, `zend`, or `pecl`, the port will automatically have `FLAVORS` filled in with the PHP versions it supports.
 
 [[flavors-auto-php-ex1]]
 .Simple `USES=php` Extension
@@ -246,7 +246,7 @@ When adding a dependency on a PHP flavored port, use `@${PHP_FLAVOR}`. _Never_ u
 [[flavors-auto-python]]
 == `USES=python` and Flavors
 
-When using <<uses-python,`python`>> and `USE_PYTHON=distutils`, the port will automatically have `FLAVORS` filled in with the Python versions it supports.
+When using crossref:uses[uses-python,`python`] and `USE_PYTHON=distutils`, the port will automatically have `FLAVORS` filled in with the Python versions it supports.
 
 [[flavors-auto-python-ex1]]
 .Simple `USES=python`
@@ -330,8 +330,8 @@ USES=	python:3.5+
 [[flavors-auto-lua]]
 == `USES=lua` and Flavors
 
-When using <<uses-lua,`lua:module`>> or <<uses-lua,`lua:flavors`>>, the port will automatically have `FLAVORS` filled in with the Lua versions it supports. However, it is not expected that ordinary applications (rather than Lua modules) should use this feature; most applications that embed or otherwise use Lua should simply use `USES=lua`.
+When using crossref:uses[uses-lua,`lua:module`] or crossref:uses[uses-lua,`lua:flavors`], the port will automatically have `FLAVORS` filled in with the Lua versions it supports. However, it is not expected that ordinary applications (rather than Lua modules) should use this feature; most applications that embed or otherwise use Lua should simply use `USES=lua`.
 
 `LUA_FLAVOR` is available (and must be used) to depend on the correct version of dependencies regardless of whether the port used the `flavors` or `module` parameters.
 
-See <<using-lua,Using Lua>> for further information.
+See crossref:special[using-lua,Using Lua] for further information.
diff --git a/documentation/content/en/books/porters-handbook/keeping-up/chapter.adoc b/documentation/content/en/books/porters-handbook/keeping-up/_index.adoc
index b95cd8488b..b95cd8488b 100644
--- a/documentation/content/en/books/porters-handbook/keeping-up/chapter.adoc
+++ b/documentation/content/en/books/porters-handbook/keeping-up/_index.adoc
diff --git a/documentation/content/en/books/porters-handbook/makefiles/chapter.adoc b/documentation/content/en/books/porters-handbook/makefiles/_index.adoc
index bcfae7facc..f198adc83b 100644
--- a/documentation/content/en/books/porters-handbook/makefiles/chapter.adoc
+++ b/documentation/content/en/books/porters-handbook/makefiles/_index.adoc
@@ -30,7 +30,7 @@ include::shared/en/urls.adoc[]
 
 toc::[]
 
-Configuring the [.filename]#Makefile# is pretty simple, and again we suggest looking at existing examples before starting. Also, there is a <<porting-samplem,sample Makefile>> in this handbook, so take a look and please follow the ordering of variables and sections in that template to make the port easier for others to read.
+Configuring the [.filename]#Makefile# is pretty simple, and again we suggest looking at existing examples before starting. Also, there is a crossref:porting-samplem[porting-samplem,sample Makefile] in this handbook, so take a look and please follow the ordering of variables and sections in that template to make the port easier for others to read.
 
 Consider these problems in sequence during the design of the new [.filename]#Makefile#:
 
@@ -1538,7 +1538,7 @@ USE_GITHUB=	nodefault
 
 [IMPORTANT]
 ====
-When using `USE_GITHUB=nodefault`, the [.filename]#Makefile# must set `DISTFILES` in its <<porting-order-portname,top block>>. The definition should be:
+When using `USE_GITHUB=nodefault`, the [.filename]#Makefile# must set `DISTFILES` in its crossref:porting-order[porting-order-portname,top block]. The definition should be:
 
 [.programlisting]
 ....
@@ -1888,7 +1888,7 @@ DISTNAME=	foo
 EXTRACT_SUFX=	.tar.gzip
 ....
 
-The `USES=tar[:__xxx__]`, `USES=lha` or `USES=zip` automatically set `EXTRACT_SUFX` to the most common archives extensions as necessary, see <<uses,Using `USES` Macros>> for more details. If neither of these are set then `EXTRACT_SUFX` defaults to `.tar.gz`.
+The `USES=tar[:__xxx__]`, `USES=lha` or `USES=zip` automatically set `EXTRACT_SUFX` to the most common archives extensions as necessary, see crossref:uses[uses,Using `USES` Macros] for more details. If neither of these are set then `EXTRACT_SUFX` defaults to `.tar.gz`.
 
 [NOTE]
 ====
@@ -2829,7 +2829,7 @@ Redistribution of the distribution files is permitted. The distribution files wi
 
 [[licenses-license_perms-no-dist-mirror]]
 `no-dist-mirror`::
-Redistribution of the distribution files is prohibited. This is equivalent to setting <<porting-restrictions-restricted,`RESTRICTED`>>. The distribution files will _not_ be added to the FreeBSD `MASTER_SITE_BACKUP` CDN.
+Redistribution of the distribution files is prohibited. This is equivalent to setting crossref:special[porting-restrictions-restricted,`RESTRICTED`]. The distribution files will _not_ be added to the FreeBSD `MASTER_SITE_BACKUP` CDN.
 
 [[licenses-license_perms-dist-sell]]
 `dist-sell`::
@@ -2837,7 +2837,7 @@ Selling of distribution files is permitted. The distribution files will be prese
 
 [[licenses-license_perms-no-dist-sell]]
 `no-dist-sell`::
-Selling of distribution files is prohibited. This is equivalent to setting <<porting-restrictions-no_cdrom,`NO_CDROM`>>.
+Selling of distribution files is prohibited. This is equivalent to setting crossref:special[porting-restrictions-no_cdrom,`NO_CDROM`].
 
 [[licenses-license_perms-pkg-mirror]]
 `pkg-mirror`::
@@ -2845,7 +2845,7 @@ Free redistribution of package is permitted. The package will be distributed on
 
 [[licenses-license_perms-no-pkg-mirror]]
 `no-pkg-mirror`::
-Free redistribution of package is prohibited. Equivalent to setting <<porting-restrictions-no_package,`NO_PACKAGE`>>. The package will _not_ be distributed from the FreeBSD package CDN https://pkg.freebsd.org/[https://pkg.freebsd.org/].
+Free redistribution of package is prohibited. Equivalent to setting crossref:special[porting-restrictions-no_package,`NO_PACKAGE`]. The package will _not_ be distributed from the FreeBSD package CDN https://pkg.freebsd.org/[https://pkg.freebsd.org/].
 
 [[licenses-license_perms-pkg-sell]]
 `pkg-sell`::
@@ -2853,7 +2853,7 @@ Selling of package is permitted. The package will be present on the installer im
 
 [[licenses-license_perms-no-pkg-sell]]
 `no-pkg-sell`::
-Selling of package is prohibited. This is equivalent to setting <<porting-restrictions-no_cdrom,`NO_CDROM`>>. The package will _not_ be present on the installer images.
+Selling of package is prohibited. This is equivalent to setting crossref:special[porting-restrictions-no_cdrom,`NO_CDROM`]. The package will _not_ be present on the installer images.
 
 [[licenses-license_perms-auto-accept]]
 `auto-accept`::
@@ -3072,7 +3072,7 @@ LICENSE_COMB=	multi
 [[makefile-portscout]]
 == `PORTSCOUT`
 
-Portscout is an automated distfile check utility for the FreeBSD Ports Collection, described in detail in <<distfile-survey,Portscout: the FreeBSD Ports Distfile Scanner>>.
+Portscout is an automated distfile check utility for the FreeBSD Ports Collection, described in detail in crossref:keeping-up[distfile-survey,Portscout: the FreeBSD Ports Distfile Scanner].
 
 `PORTSCOUT` defines special conditions within which the Portscout distfile scanner is restricted.
 
@@ -3225,7 +3225,7 @@ The dependency is checked from within the `extract` target. The _target_ part ca
 
 [NOTE]
 ====
-Use this variable only if the extraction does not already work (the default assumes `tar`) and cannot be made to work using `USES=tar`, `USES=lha` or `USES=zip` described in <<uses,Using `USES` Macros>>.
+Use this variable only if the extraction does not already work (the default assumes `tar`) and cannot be made to work using `USES=tar`, `USES=lha` or `USES=zip` described in crossref:uses[uses,Using `USES` Macros].
 ====
 
 [[makefile-patch_depends]]
@@ -3252,11 +3252,10 @@ Parameters can be added to define different features and dependencies used by th
 USES= feature[:arguments]
 ....
 
-For the complete list of values, please see <<uses,Using `USES` Macros>>.
+For the complete list of values, please see crossref:uses[uses,Using `USES` Macros].
 
 [WARNING]
 ====
-
 `USES` cannot be assigned after inclusion of [.filename]#bsd.port.pre.mk#.
 ====
 
@@ -3296,7 +3295,7 @@ The port requires GCC (`gcc` or `{g-plus-plus}`) to build. Some ports need any G
 
 |===
 
-Variables related to gmake and [.filename]#configure# are described in <<building,Building Mechanisms>>, while autoconf, automake and libtool are described in <<using-autotools,Using GNU Autotools>>. Perl related variables are described in <<using-perl,Using Perl>>. X11 variables are listed in <<using-x11,Using X11>>. <<using-gnome,Using Gnome>> deals with GNOME and <<using-kde,Using KDE>> with KDE related variables. <<using-java,Using Java>> documents Java variables, while <<using-php,Web Applications, Apache and PHP>> contains information on Apache, PHP and PEAR modules. Python is discussed in <<using-python,Using Python>>, while Ruby in <<using-ruby,Using Ruby>>. <<using-sdl,Using SDL>> provides variables used for SDL applications and finally, <<using-xfce,Using Xfce>> contains information on Xfce.
+Variables related to gmake and [.filename]#configure# are described in crossref:special[building,Building Mechanisms], while autoconf, automake and libtool are described in crossref:special[using-autotools,Using GNU Autotools]. Perl related variables are described in crossref:special[using-perl,Using Perl]. X11 variables are listed in crossref:special[using-x11,Using X11]. crossref:special[using-gnome,Using Gnome] deals with GNOME and crossref:special[using-kde,Using KDE] with KDE related variables. crossref:special[using-java,Using Java] documents Java variables, while crossref:special[using-php,Web Applications, Apache and PHP] contains information on Apache, PHP and PEAR modules. Python is discussed in crossref:special[using-python,Using Python], while Ruby in crossref:special[using-ruby,Using Ruby]. crossref:special[using-sdl,Using SDL] provides variables used for SDL applications and finally, crossref:special[using-xfce,Using Xfce] contains information on Xfce.
 
 [[makefile-version-dependency]]
 === Minimal Version of a Dependency
@@ -4558,7 +4557,7 @@ There are three different variables to register a conflict between packages and
 
 [NOTE]
 ====
-The conflict variables automatically set the variable `IGNORE`, which is more fully documented in <<dads-noinstall,Marking a Port Not Installable with `BROKEN`, `FORBIDDEN`, or `IGNORE`>>.
+The conflict variables automatically set the variable `IGNORE`, which is more fully documented in crossref:porting-dads[dads-noinstall,Marking a Port Not Installable with `BROKEN`, `FORBIDDEN`, or `IGNORE`].
 ====
 
 When removing one of several conflicting ports, it is advisable to retain `CONFLICTS` in those other ports for a few months to cater for users who only update once in a while.
@@ -4649,7 +4648,7 @@ The `install` phase is very important to the end user because it adds files to t
 [[install-macros]]
 === `INSTALL_*` Macros
 
-Use the macros provided in [.filename]#bsd.port.mk# to ensure correct modes of files in the port's `*-install` targets. Set ownership directly in [.filename]#pkg-plist# with the corresponding entries, such as `@(_owner_,_group_,)`, `@owner _owner_`, and `@group _group_`. These operators work until overridden, or until the end of [.filename]#pkg-plist#, so remember to reset them after they are no longer needed. The default ownership is `root:wheel`. See <<plist-keywords-base,Base Keywords>> for more information.
+Use the macros provided in [.filename]#bsd.port.mk# to ensure correct modes of files in the port's `*-install` targets. Set ownership directly in [.filename]#pkg-plist# with the corresponding entries, such as `@(_owner_,_group_,)`, `@owner _owner_`, and `@group _group_`. These operators work until overridden, or until the end of [.filename]#pkg-plist#, so remember to reset them after they are no longer needed. The default ownership is `root:wheel`. See crossref:plist[plist-keywords-base,Base Keywords] for more information.
 
 * `INSTALL_PROGRAM` is a command to install binary executables.
 * `INSTALL_SCRIPT` is a command to install executable scripts.
@@ -4694,7 +4693,7 @@ Use man:file[1] on a file to determine if it has been stripped. Binaries are rep
 ====
 When `WITH_DEBUG` is defined, elf files _must not_ be stripped.
 
-The variables (`STRIP_CMD`, `INSTALL_PROGRAM`, `INSTALL_LIB`, ...) and <<uses,`USES`>> provided by the framework handle this automatically.
+The variables (`STRIP_CMD`, `INSTALL_PROGRAM`, `INSTALL_LIB`, ...) and crossref:uses[uses,`USES`] provided by the framework handle this automatically.
 
 Some software, add `-s` to their `LDFLAGS`, in this case, either remove `-s` if `WITH_DEBUG` is set, or remove it unconditionally and use `STRIP_CMD` in `post-install`.
 ====
@@ -4702,7 +4701,7 @@ Some software, add `-s` to their `LDFLAGS`, in this case, either remove `-s` if
 [[install-copytree]]
 === Installing a Whole Tree of Files
 
-Sometimes, a large number of files must be installed while preserving their hierarchical organization. For example, copying over a whole directory tree from `WRKSRC` to a target directory under `PREFIX`. Note that `PREFIX`, `EXAMPLESDIR`, `DATADIR`, and other path variables must always be prepended with `STAGEDIR` to respect staging (see <<staging,Staging>>).
+Sometimes, a large number of files must be installed while preserving their hierarchical organization. For example, copying over a whole directory tree from `WRKSRC` to a target directory under `PREFIX`. Note that `PREFIX`, `EXAMPLESDIR`, `DATADIR`, and other path variables must always be prepended with `STAGEDIR` to respect staging (see crossref:special[staging,Staging]).
 
 Two macros exist for this situation. The advantage of using these macros instead of `cp` is that they guarantee proper file ownership and permissions on target files. The first macro, `COPYTREE_BIN`, will set all the installed files to be executable, thus being suitable for installing into [.filename]#PREFIX/bin#. The second macro, `COPYTREE_SHARE`, does not set executable permissions on files, and is therefore suitable for installing files under [.filename]#PREFIX/share# target.
 
@@ -4743,7 +4742,7 @@ If the software has some documentation other than the standard man and info page
 
 Create a new directory for the port. The directory name is `DOCSDIR`. This usually equals `PORTNAME`. However, if the user might want different versions of the port to be installed at the same time, the whole `PKGNAME` can be used.
 
-Since only the files listed in [.filename]#pkg-plist# are installed, it is safe to always install documentation to `STAGEDIR` (see <<staging,Staging>>). Hence `.if` blocks are only needed when the installed files are large enough to cause significant I/O overhead.
+Since only the files listed in [.filename]#pkg-plist# are installed, it is safe to always install documentation to `STAGEDIR` (see crossref:special[staging,Staging]). Hence `.if` blocks are only needed when the installed files are large enough to cause significant I/O overhead.
 
 [.programlisting]
 ....
@@ -4768,7 +4767,7 @@ Here are some handy variables and how they are expanded by default when used in
 The `DOCS` option only controls additional documentation installed in `DOCSDIR`. It does not apply to standard man pages and info pages. Things installed in `EXAMPLESDIR` are controlled by the `EXAMPLES` option.
 ====
 
-These variables are exported to `PLIST_SUB`. Their values will appear there as pathnames relative to [.filename]#PREFIX# if possible. That is, [.filename]#share/doc/PORTNAME# will be substituted for `%%DOCSDIR%%` in the packing list by default, and so on. (See more on [.filename]#pkg-plist# substitution <<plist-sub,here>>.)
+These variables are exported to `PLIST_SUB`. Their values will appear there as pathnames relative to [.filename]#PREFIX# if possible. That is, [.filename]#share/doc/PORTNAME# will be substituted for `%%DOCSDIR%%` in the packing list by default, and so on. (See more on [.filename]#pkg-plist# substitution crossref:plist[plist-sub,here].)
 
 All conditionally installed documentation files and directories are included in [.filename]#pkg-plist# with the `%%PORTDOCS%%` prefix, for example:
 
@@ -4789,7 +4788,7 @@ PORTDOCS=	README.* ChangeLog docs/*
 ====
 The equivalents of `PORTDOCS` for files installed under `DATADIR` and `EXAMPLESDIR` are `PORTDATA` and `PORTEXAMPLES`, respectively.
 
-The contents of [.filename]#pkg-message# are displayed upon installation. See <<porting-message,the section on using [.filename]#pkg-message#>> for details. [.filename]#pkg-message# does not need to be added to [.filename]#pkg-plist#.
+The contents of [.filename]#pkg-message# are displayed upon installation. See crossref:pkg-files[porting-message,the section on using [.filename]#pkg-message#] for details. [.filename]#pkg-message# does not need to be added to [.filename]#pkg-plist#.
 ====
 
 [[install-subdirs]]
@@ -4836,7 +4835,7 @@ USES=	python:3.4+,build
 BINARY_ALIAS=	python3=${PYTHON_CMD}
 ....
 
-See <<using-python,Using Python>> for more information about `USES=python`.
+See crossref:special[using-python,Using Python] for more information about `USES=python`.
 ====
 
 [NOTE]
diff --git a/documentation/content/en/books/porters-handbook/new-port/chapter.adoc b/documentation/content/en/books/porters-handbook/new-port/_index.adoc
index aec419af0a..32eee5a9ea 100644
--- a/documentation/content/en/books/porters-handbook/new-port/chapter.adoc
+++ b/documentation/content/en/books/porters-handbook/new-port/_index.adoc
@@ -31,7 +31,7 @@ toc::[]
 
 Interested in making a new port, or upgrading existing ports? Great!
 
-What follows are some guidelines for creating a new port for FreeBSD. To upgrade an existing port, read this, then read <<port-upgrading,Upgrading a Port>>.
+What follows are some guidelines for creating a new port for FreeBSD. To upgrade an existing port, read this, then read crossref:port-upgrading[port-upgrading,Upgrading a Port].
 
 When this document is not sufficiently detailed, refer to [.filename]#/usr/ports/Mk/bsd.port.mk#, which is included by all port [.filename]#Makefiles#. Even those not hacking [.filename]##Makefile##s daily can gain much knowledge from it. Additionally, specific questions can be sent to the {freebsd-ports}.
 
diff --git a/documentation/content/en/books/porters-handbook/order/chapter.adoc b/documentation/content/en/books/porters-handbook/order/_index.adoc
index 398f3cf645..ff8e404f44 100644
--- a/documentation/content/en/books/porters-handbook/order/chapter.adoc
+++ b/documentation/content/en/books/porters-handbook/order/_index.adoc
@@ -62,23 +62,23 @@ In the following blocks, only set the variables that are required by the port. D
 
 This block is the most important. It defines the port name, version, distribution file location, and category. The variables must be in this order:
 
-* <<makefile-portname,`PORTNAME`>>
-* <<makefile-versions,`PORTVERSION`][<<portversion-footnote, 1>>>>
-* <<makefile-versions,`DISTVERSIONPREFIX`>>
-* <<makefile-versions,`DISTVERSION`][<<portversion-footnote, 1>>>>
-* <<makefile-versions,`DISTVERSIONSUFFIX`>>
-* <<makefile-portrevision,`PORTREVISION`>>
-* <<makefile-portepoch,`PORTEPOCH`>>
-* <<makefile-categories,`CATEGORIES`>>
-* <<makefile-master_sites,`MASTER_SITES`>>
-* <<makefile-master_sites-shorthand,`MASTER_SITE_SUBDIR`>> (deprecated)
-* <<porting-pkgnameprefix-suffix,`PKGNAMEPREFIX`>>
-* <<porting-pkgnameprefix-suffix,`PKGNAMESUFFIX`>>
-* <<makefile-distname,`DISTNAME`>>
-* <<makefile-extract_sufx,`EXTRACT_SUFX`>>
-* <<makefile-distfiles-definition,`DISTFILES`>>
-* <<makefile-dist_subdir,`DIST_SUBDIR`>>
-* <<makefile-extract_only,`EXTRACT_ONLY`>>
+* crossref:makefiles[makefile-portname,`PORTNAME`]
+* crossref:makefiles[makefile-versions,`PORTVERSION`][<<portversion-footnote, 1>>]
+* crossref:makefiles[makefile-versions,`DISTVERSIONPREFIX`]
+* crossref:makefiles[makefile-versions,`DISTVERSION`][<<portversion-footnote, 1>>]
+* crossref:makefiles[makefile-versions,`DISTVERSIONSUFFIX`]
+* crossref:makefiles[makefile-portrevision,`PORTREVISION`]
+* crossref:makefiles[makefile-portepoch,`PORTEPOCH`]
+* crossref:makefiles[makefile-categories,`CATEGORIES`]
+* crossref:makefiles[makefile-master_sites,`MASTER_SITES`]
+* crossref:makefiles[makefile-master_sites-shorthand,`MASTER_SITE_SUBDIR`] (deprecated)
+* crossref:makefiles[porting-pkgnameprefix-suffix,`PKGNAMEPREFIX`]
+* crossref:makefiles[porting-pkgnameprefix-suffix,`PKGNAMESUFFIX`]
+* crossref:makefiles[makefile-distname,`DISTNAME`]
+* crossref:makefiles[makefile-extract_sufx,`EXTRACT_SUFX`]
+* crossref:makefiles[makefile-distfiles-definition,`DISTFILES`]
+* crossref:makefiles[makefile-dist_subdir,`DIST_SUBDIR`]
+* crossref:makefiles[makefile-extract_only,`EXTRACT_ONLY`]
 
 [[portversion-footnote]]
 [IMPORTANT]
@@ -91,31 +91,31 @@ Only one of PORTVERSION and DISTVERSION can be used.
 
 This block is optional. The variables are:
 
-* <<porting-patchfiles,`PATCH_SITES`>>
-* <<porting-patchfiles,`PATCHFILES`>>
-* <<porting-patchfiles,`PATCH_DIST_STRIP`>>
+* crossref:makefiles[porting-patchfiles,`PATCH_SITES`]
+* crossref:makefiles[porting-patchfiles,`PATCHFILES`]
+* crossref:makefiles[porting-patchfiles,`PATCH_DIST_STRIP`]
 
 [[porting-order-maintainer]]
 == `MAINTAINER` Block
 
 This block is mandatory. The variables are:
 
-* <<makefile-maintainer,`MAINTAINER`>>
-* <<makefile-comment,`COMMENT`>>
+* crossref:makefiles[makefile-maintainer,`MAINTAINER`]
+* crossref:makefiles[makefile-comment,`COMMENT`]
 
 [[porting-order-license]]
 == `LICENSE` Block
 
 This block is optional, although it is highly recommended. The variables are:
 
-* <<licenses-license,`LICENSE`>>
-* <<licenses-license_comb,`LICENSE_COMB`>>
-* <<licenses-license_groups,`LICENSE_GROUPS`>> or `LICENSE_GROUPS_NAME`
-* <<licenses-license_name,`LICENSE_NAME`>> or `LICENSE_NAME_NAME`
-* <<licenses-license_text,`LICENSE_TEXT`>> or `LICENSE_TEXT_NAME`
-* <<licenses-license_file,`LICENSE_FILE`>> or `LICENSE_FILE_NAME`
-* <<licenses-license_perms,`LICENSE_PERMS`>> or `LICENSE_PERMS_NAME_`
-* <<licenses-license_distfiles,`LICENSE_DISTFILES`>> or `LICENSE_DISTFILES_NAME`
+* crossref:makefiles[licenses-license,`LICENSE`]
+* crossref:makefiles[licenses-license_comb,`LICENSE_COMB`]
+* crossref:makefiles[licenses-license_groups,`LICENSE_GROUPS`] or `LICENSE_GROUPS_NAME`
+* crossref:makefiles[licenses-license_name,`LICENSE_NAME`] or `LICENSE_NAME_NAME`
+* crossref:makefiles[licenses-license_text,`LICENSE_TEXT`] or `LICENSE_TEXT_NAME`
+* crossref:makefiles[licenses-license_file,`LICENSE_FILE`] or `LICENSE_FILE_NAME`
+* crossref:makefiles[licenses-license_perms,`LICENSE_PERMS`] or `LICENSE_PERMS_NAME_`
+* crossref:makefiles[licenses-license_distfiles,`LICENSE_DISTFILES`] or `LICENSE_DISTFILES_NAME`
 
 If there are multiple licenses, sort the different LICENSE_VAR_NAME variables by license name.
 
@@ -124,21 +124,21 @@ If there are multiple licenses, sort the different LICENSE_VAR_NAME variables by
 
 This block is optional. The variables are:
 
-* <<dads-deprecated,`DEPRECATED`>>
-* <<dads-deprecated,`EXPIRATION_DATE`>>
-* <<dads-noinstall,`FORBIDDEN`>>
-* <<dads-noinstall,`BROKEN`>>
-* <<dads-noinstall,`BROKEN_*`>>
-* <<dads-noinstall,`IGNORE`>>
-* <<dads-noinstall,`IGNORE_*`>>
-* <<dads-noinstall,`ONLY_FOR_ARCHS`>>
-* <<dads-noinstall,`ONLY_FOR_ARCHS_REASON*`>>
-* <<dads-noinstall,`NOT_FOR_ARCHS`>>
-* <<dads-noinstall,`NOT_FOR_ARCHS_REASON*`>>
+* crossref:porting-dads[dads-deprecated,`DEPRECATED`]
+* crossref:porting-dads[dads-deprecated,`EXPIRATION_DATE`]
+* crossref:porting-dads[dads-noinstall,`FORBIDDEN`]
+* crossref:porting-dads[dads-noinstall,`BROKEN`]
+* crossref:porting-dads[dads-noinstall,`BROKEN_*`]
+* crossref:porting-dads[dads-noinstall,`IGNORE`]
+* crossref:porting-dads[dads-noinstall,`IGNORE_*`]
+* crossref:porting-dads[dads-noinstall,`ONLY_FOR_ARCHS`]
+* crossref:porting-dads[dads-noinstall,`ONLY_FOR_ARCHS_REASON*`]
+* crossref:porting-dads[dads-noinstall,`NOT_FOR_ARCHS`]
+* crossref:porting-dads[dads-noinstall,`NOT_FOR_ARCHS_REASON*`]
 
 [NOTE]
 ====
-`BROKEN_*` and `IGNORE_*` can be any generic variables, for example, `IGNORE_amd64`, `BROKEN_FreeBSD_10`, etc. With the exception of variables that depend on a <<uses,`USES`>>, place those in <<porting-order-uses>>. For instance, `IGNORE_WITH_PHP` only works if <<xuses-php,`php`>> is set, and `BROKEN_SSL` only if <<uses-ssl,`ssl`>> is set.
+`BROKEN_*` and `IGNORE_*` can be any generic variables, for example, `IGNORE_amd64`, `BROKEN_FreeBSD_10`, etc. With the exception of variables that depend on a crossref:uses[uses,`USES`], place those in <<porting-order-uses>>. For instance, `IGNORE_WITH_PHP` only works if crossref:uses[xuses-php,`php`] is set, and `BROKEN_SSL` only if crossref:uses[uses-ssl,`ssl`] is set.
 
 If the port is marked BROKEN when some conditions are met, and such conditions can only be tested after including [.filename]#bsd.port.options.mk# or [.filename]#bsd.port.pre.mk#, then those variables should be set later, in <<porting-order-rest>>.
 ====
@@ -148,12 +148,12 @@ If the port is marked BROKEN when some conditions are met, and such conditions c
 
 This block is optional. The variables are:
 
-* <<makefile-fetch_depends,`FETCH_DEPENDS`>>
-* <<makefile-extract_depends,`EXTRACT_DEPENDS`>>
-* <<makefile-patch_depends,`PATCH_DEPENDS`>>
-* <<makefile-build_depends,`BUILD_DEPENDS`>>
-* <<makefile-lib_depends,`LIB_DEPENDS`>>
-* <<makefile-run_depends,`RUN_DEPENDS`>>
+* crossref:makefiles:[makefile-fetch_depends,`FETCH_DEPENDS`]
+* crossref:makefiles:[makefile-extract_depends,`EXTRACT_DEPENDS`]
+* crossref:makefiles:[makefile-patch_depends,`PATCH_DEPENDS`]
+* crossref:makefiles:[makefile-build_depends,`BUILD_DEPENDS`]
+* crossref:makefiles:[makefile-lib_depends,`LIB_DEPENDS`]
+* crossref:makefiles:[makefile-run_depends,`RUN_DEPENDS`]
 * `TEST_DEPENDS`
 
 [[porting-order-flavors]]
@@ -161,7 +161,7 @@ This block is optional. The variables are:
 
 This block is optional.
 
-Start this section with defining `FLAVORS`. Continue with the possible Flavors helpers. See <<flavors-using,Using FLAVORS>> for more Information.
+Start this section with defining `FLAVORS`. Continue with the possible Flavors helpers. See crossref:flavors[flavors-using,Using FLAVORS] for more Information.
 
 Constructs setting variables not available as helpers using `.if ${FLAVOR:U} == foo` should go in their respective sections below.
 
@@ -170,10 +170,10 @@ Constructs setting variables not available as helpers using `.if ${FLAVOR:U} ==
 
 Start this section with defining `USES`, and then possible `USE_x`.
 
-Keep related variables close together. For example, if using <<makefile-master_sites-github,`USE_GITHUB`>>, always put the `GH_*` variables right after it.
+Keep related variables close together. For example, if using crossref:makefiles[makefile-master_sites-github,`USE_GITHUB`], always put the `GH_*` variables right after it.
 
 [[porting-order-variables]]
-== Standard [.filename]#bsd.port.mk# Variables
+== Standard bsd.port.mk Variables
 
 This section block is for variables that can be defined in [.filename]#bsd.port.mk# that do not belong in any of the previous section blocks.
 
@@ -182,7 +182,7 @@ Order is not important, however try to keep similar variables together. For exam
 [[porting-order-options]]
 == Options and Helpers
 
-If the port uses the <<makefile-options,options framework>>, define `OPTIONS_DEFINE` and `OPTIONS_DEFAULT` first, then the other `OPTIONS_*` variables first, then the `*_DESC` descriptions, then the options helpers. Try and sort all of those alphabetically.
+If the port uses the crossref:makefiles[makefile-options,options framework], define `OPTIONS_DEFINE` and `OPTIONS_DEFAULT` first, then the other `OPTIONS_*` variables first, then the `*_DESC` descriptions, then the options helpers. Try and sort all of those alphabetically.
 
 [[porting-order-options-ex1]]
 .Options Variables Order Example
@@ -237,7 +237,6 @@ After all the variables are defined, the optional man:make[1] targets can be def
 
 [TIP]
 ====
-
 When using options helpers target keep them alphabetically sorted, but keep the `*-on` before the `*-off`. When also using the main target, keep the main target before the optional ones:
 
 [.programlisting]
@@ -254,5 +253,4 @@ post-install-X11-on:
 post-install-X11-off:
 	# Install bits that should be there if X11 is disabled
 ....
-
 ====
diff --git a/documentation/content/en/books/porters-handbook/pkg-files/chapter.adoc b/documentation/content/en/books/porters-handbook/pkg-files/_index.adoc
index 3185c4e180..9a8bd74cea 100644
--- a/documentation/content/en/books/porters-handbook/pkg-files/chapter.adoc
+++ b/documentation/content/en/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
@@ -32,7 +32,7 @@ toc::[]
 There are some tricks we have not mentioned yet about the [.filename]#pkg-*# files that come in handy sometimes.
 
 [[porting-message]]
-== [.filename]#pkg-message#
+== pkg-message
 
 To display a message when the package is installed, place the message in [.filename]#pkg-message#. This capability is often useful to display additional installation steps to be taken after a `pkg install` or `pkg upgrade`.
 
@@ -192,7 +192,7 @@ When displaying a message on upgrade, it is important to limit when it is being
 ====
 
 [[pkg-install]]
-== [.filename]#pkg-install#
+== pkg-install
 
 If the port needs to execute commands when the binary package is installed with `pkg add` or `pkg install`, use [.filename]#pkg-install#. This script will automatically be added to the package. It will be run twice by `pkg`, the first time as `${SH} pkg-install ${PKGNAME} PRE-INSTALL` before the package is installed, and the second time as `${SH} pkg-install ${PKGNAME} POST-INSTALL` after it has been installed. `$2` can be tested to determine which mode the script is being run in. The `PKG_PREFIX` environmental variable will be set to the package installation directory.
 
@@ -202,7 +202,7 @@ This script is here to help you set up the package so that it is as ready to use
 ====
 
 [[pkg-deinstall]]
-== [.filename]#pkg-deinstall#
+== pkg-deinstall
 
 This script executes when a package is removed.
 
@@ -214,9 +214,9 @@ This script is here to help you set up the package so that it is as ready to use
 ====
 
 [[pkg-names]]
-== Changing the Names of [.filename]#pkg-*#
+== Changing the Names of pkg-*
 
-All the names of [.filename]#pkg-\*# are defined using variables that can be changed in the [.filename]#Makefile# if needed. This is especially useful when sharing the same [.filename]#pkg-*# files among several ports or when it is necessary to write to one of these files. See <<porting-wrkdir,writing to places other than `WRKDIR`>> for why it is a bad idea to write directly into the directory containing the [.filename]#pkg-*# files.
+All the names of [.filename]#pkg-\*# are defined using variables that can be changed in the [.filename]#Makefile# if needed. This is especially useful when sharing the same [.filename]#pkg-*# files among several ports or when it is necessary to write to one of these files. See crossref:porting-dads[porting-wrkdir,writing to places other than `WRKDIR`] for why it is a bad idea to write directly into the directory containing the [.filename]#pkg-*# files.
 
 Here is a list of variable names and their default values. (`PKGDIR` defaults to `${MASTERDIR}`.)
 
diff --git a/documentation/content/en/books/porters-handbook/plist/chapter.adoc b/documentation/content/en/books/porters-handbook/plist/_index.adoc
index 7fed24b734..e1868a6f4f 100644
--- a/documentation/content/en/books/porters-handbook/plist/chapter.adoc
+++ b/documentation/content/en/books/porters-handbook/plist/_index.adoc
@@ -5,7 +5,7 @@ next: books/porters-handbook/pkg-files
 ---
 
 [[plist]]
-= Advanced [.filename]#pkg-plist# Practices
+= Advanced pkg-plist Practices
 :doctype: book
 :toc: macro
 :toclevels: 1
@@ -30,9 +30,9 @@ include::shared/en/urls.adoc[]
 toc::[]
 
 [[plist-sub]]
-== Changing [.filename]#pkg-plist# Based on Make Variables
+== Changing pkg-plist Based on Make Variables
 
-Some ports, particularly the `p5-` ports, need to change their [.filename]#pkg-plist# depending on what options they are configured with (or version of `perl`, in the case of `p5-` ports). To make this easy, any instances in [.filename]#pkg-plist# of `%%OSREL%%`, `%%PERL_VER%%`, and `%%PERL_VERSION%%` will be substituted appropriately. The value of `%%OSREL%%` is the numeric revision of the operating system (for example, `4.9`). `%%PERL_VERSION%%` and `%%PERL_VER%%` is the full version number of `perl` (for example, `5.8.9`). Several other `%%_VARS_%%` related to port's documentation files are described in <<install-documentation,the relevant section>>.
+Some ports, particularly the `p5-` ports, need to change their [.filename]#pkg-plist# depending on what options they are configured with (or version of `perl`, in the case of `p5-` ports). To make this easy, any instances in [.filename]#pkg-plist# of `%%OSREL%%`, `%%PERL_VER%%`, and `%%PERL_VERSION%%` will be substituted appropriately. The value of `%%OSREL%%` is the numeric revision of the operating system (for example, `4.9`). `%%PERL_VERSION%%` and `%%PERL_VER%%` is the full version number of `perl` (for example, `5.8.9`). Several other `%%_VARS_%%` related to port's documentation files are described in crossref:makefiles[install-documentation,the relevant section].
 
 To make other substitutions, set `PLIST_SUB` with a list of `_VAR=VALUE_` pairs and instances of `%%_VAR_%%` will be substituted with _VALUE_ in [.filename]#pkg-plist#.
 
@@ -46,7 +46,7 @@ PLIST_SUB=	OCTAVE_VERSION=${OCTAVE_VERSION}
 
 in the [.filename]#Makefile# and use `%%OCTAVE_VERSION%%` wherever the version shows up in [.filename]#pkg-plist#. When the port is upgraded, it will not be necessary to edit dozens (or in some cases, hundreds) of lines in [.filename]#pkg-plist#.
 
-If files are installed conditionally on the options set in the port, the usual way of handling it is prefixing [.filename]#pkg-plist# lines with a `%%OPT%%` for lines needed when the option is enabled, or `%%NO_OPT%%` when the option is disabled, and adding `OPTIONS_SUB=yes` to the [.filename]#Makefile#. See <<options_sub,`OPTIONS_SUB`>> for more information.
+If files are installed conditionally on the options set in the port, the usual way of handling it is prefixing [.filename]#pkg-plist# lines with a `%%OPT%%` for lines needed when the option is enabled, or `%%NO_OPT%%` when the option is disabled, and adding `OPTIONS_SUB=yes` to the [.filename]#Makefile#. See crossref:makefiles[options_sub,`OPTIONS_SUB`] for more information.
 
 For instance, if there are files that are only installed when the `X11` option is enabled, and [.filename]#Makefile# has:
 
@@ -125,7 +125,7 @@ Instead, install sample files with a [.filename]#filename.sample# extension. The
 @sample etc/orbit.conf.sample
 ....
 
-If there is a very good reason not to install a working configuration file by default, only list the sample filename in [.filename]#pkg-plist#, without the `@sample` followed by a space part, and add a <<porting-message,message>> pointing out that the user must copy and edit the file before the software will work.
+If there is a very good reason not to install a working configuration file by default, only list the sample filename in [.filename]#pkg-plist#, without the `@sample` followed by a space part, and add a crossref:pkg-files[porting-message,message] pointing out that the user must copy and edit the file before the software will work.
 
 [TIP]
 ====
@@ -166,7 +166,7 @@ While the use of dynamic package lists is not forbidden, maintainers should use
 
 First, make sure the port is almost complete, with only [.filename]#pkg-plist# missing. Running `make makeplist` will show an example for [.filename]#pkg-plist#. The output of `makeplist` must be double checked for correctness as it tries to automatically guess a few things, and can get it wrong.
 
-User configuration files should be installed as [.filename]#filename.sample#, as it is described in <<plist-config>>. [.filename]#info/dir# must not be listed and appropriate [.filename]#install-info# lines must be added as noted in the <<makefile-info,info files>> section. Any libraries installed by the port must be listed as specified in the <<porting-shlibs,shared libraries>> section.
+User configuration files should be installed as [.filename]#filename.sample#, as it is described in <<plist-config>>. [.filename]#info/dir# must not be listed and appropriate [.filename]#install-info# lines must be added as noted in the crossref:makefiles[makefile-info,info files] section. Any libraries installed by the port must be listed as specified in the crossref:special[porting-shlibs,shared libraries]  section.
 
 [[plist-autoplist-regex]]
 === Expanding `PLIST_SUB` with Regular Expressions
@@ -262,20 +262,20 @@ The arguments are optional. If only the group and mode need to be changed, use:
 [WARNING]
 ====
 
-If a keyword is used on an <<makefile-options,optional>> entry, it must to be added after the helper:
+If a keyword is used on an crossref:makefiles[makefile-options,optional] entry, it must to be added after the helper:
 
 [.programlisting]
 ....
 %%FOO%%@sample etc/orbit.conf.sample
 ....
 
-This is because the options plist helpers are used to comment out the line, so they need to be put first. See <<options_sub,`OPTIONS_SUB`>> for more information.
+This is because the options plist helpers are used to comment out the line, so they need to be put first. See crossref:makefiles[options_sub,`OPTIONS_SUB`] for more information.
 ====
 
 [[plist-keywords-desktop-file-utils]]
 === `@desktop-file-utils`
 
-Will run `update-desktop-database -q` after installation and deinstallation. _Never_ use directly, add <<uses-desktop-file-utils,`USES=desktop-file-utils`>> to the [.filename]#Makefile#.
+Will run `update-desktop-database -q` after installation and deinstallation. _Never_ use directly, add crossref:uses[uses-desktop-file-utils,`USES=desktop-file-utils`] to the [.filename]#Makefile#.
 
 [[plist-keywords-fc]]
 === `@fc` _directory_
@@ -300,7 +300,7 @@ Runs `glib-compile-schemas` on installation and deinstallation.
 [[plist-keywords-info]]
 === `@info` _file_
 
-Add the file passed as argument to the plist, and updates the info document index on installation and deinstallation. Additionally, it removes the index if empty on deinstallation. This should never be used manually, but always through `INFO`. See <<makefile-info,Info Files>> for more information.
+Add the file passed as argument to the plist, and updates the info document index on installation and deinstallation. Additionally, it removes the index if empty on deinstallation. This should never be used manually, but always through `INFO`. See crossref:makefiles[makefile-info,Info Files] for more information.
 
 [[plist-keywords-kld]]
 === `@kld` _directory_
@@ -334,7 +334,7 @@ On installation, add the full path to _file_ to [.filename]#/etc/shells#, while
 [[plist-keywords-terminfo]]
 === `@terminfo`
 
-Do not use by itself. If the port installs [.filename]#*.terminfo# files, add <<uses-terminfo,USES=terminfo>> to its [.filename]#Makefile#.
+Do not use by itself. If the port installs [.filename]#*.terminfo# files, add crossref:uses[uses-terminfo,USES=terminfo] to its [.filename]#Makefile#.
 
 On installation and deinstallation, if `tic` is present, refresh [.filename]#${PREFIX}/shared/misc/terminfo.db# from the [.filename]#*.terminfo# files in [.filename]#${PREFIX}/shared/misc#.
 
diff --git a/documentation/content/en/books/porters-handbook/porting-dads/chapter.adoc b/documentation/content/en/books/porters-handbook/porting-dads/_index.adoc
index 699e3c5b85..abb3fcbdd9 100644
--- a/documentation/content/en/books/porters-handbook/porting-dads/chapter.adoc
+++ b/documentation/content/en/books/porters-handbook/porting-dads/_index.adoc
@@ -39,7 +39,7 @@ Here is a list of common dos and don'ts that are encountered during the porting
 [[porting-wrkdir]]
 == `WRKDIR`
 
-Do not write anything to files outside `WRKDIR`. `WRKDIR` is the only place that is guaranteed to be writable during the port build (see link:{handbook}#PORTS-CD[ installing ports from a CDROM] for an example of building ports from a read-only tree). The [.filename]##pkg-*## files can be modified by <<pkg-names,redefining a variable>> rather than overwriting the file.
+Do not write anything to files outside `WRKDIR`. `WRKDIR` is the only place that is guaranteed to be writable during the port build (see link:{handbook}#PORTS-CD[ installing ports from a CDROM] for an example of building ports from a read-only tree). The [.filename]##pkg-*## files can be modified by crossref:pkg-files[pkg-names,redefining a variable] rather than overwriting the file.
 
 [[porting-wrkdirprefix]]
 == `WRKDIRPREFIX`
@@ -71,10 +71,10 @@ to the proper place in the [.filename]#.c# file.
 #endif
 ....
 
-A complete list of `{freebsd-version}` values is available in <<versions,__FreeBSD_version Values>>.
+A complete list of `{freebsd-version}` values is available in crossref:versions[versions,__FreeBSD_version Values].
 
 [[dads-after-port-mk]]
-== Writing Something After [.filename]#bsd.port.mk#
+== Writing Something After bsd.port.mk
 
 Do not write anything after the `.include <bsd.port.mk>` line. It usually can be avoided by including [.filename]#bsd.port.pre.mk# somewhere in the middle of the [.filename]#Makefile# and [.filename]#bsd.port.post.mk# at the end.
 
@@ -103,13 +103,13 @@ Here are some important variables defined in [.filename]#bsd.port.pre.mk# (this
 |The release version of the operating system (for example, `2.1.5` or `2.2.7`)
 
 |`OSVERSION`
-|The numeric version of the operating system; the same as <<versions,`{freebsd-version}`>>.
+|The numeric version of the operating system; the same as crossref:versions[versions,`{freebsd-version}`].
 
 |`LOCALBASE`
 |The base of the "local" tree (for example, `/usr/local`)
 
 |`PREFIX`
-|Where the port installs itself (see <<porting-prefix,more on `PREFIX`>>).
+|Where the port installs itself (see crossref:testing[porting-prefix,more on `PREFIX`]).
 |===
 
 [NOTE]
@@ -250,7 +250,7 @@ Some build systems such as CMake, ninja, and GNU configure are set up for verbos
 Do send applicable changes and patches to the upstream maintainer for inclusion in the next release of the code. This makes updating to the next release that much easier.
 
 [[dads-readme]]
-== [.filename]#README.html#
+== README.html
 
 [.filename]#README.html# is not part of the port, but generated by `make readme`. Do not include this file in patches or commits.
 
@@ -262,7 +262,7 @@ If `make readme` fails, make sure that the default value of `ECHO_MSG` has not b
 [[dads-noinstall]]
 == Marking a Port Not Installable with `BROKEN`, `FORBIDDEN`, or `IGNORE`
 
-In certain cases, users must be prevented from installing a port. There are several variables that can be used in a port's [.filename]#Makefile# to tell the user that the port cannot be installed. The value of these make variables will be the reason that is shown to users for why the port refuses to install itself. Please use the correct make variable. Each variable conveys radically different meanings, both to users and to automated systems that depend on [.filename]##Makefile##s, such as <<build-cluster,the ports build cluster>>, <<freshports,FreshPorts>>, and <<portsmon,portsmon>>.
+In certain cases, users must be prevented from installing a port. There are several variables that can be used in a port's [.filename]#Makefile# to tell the user that the port cannot be installed. The value of these make variables will be the reason that is shown to users for why the port refuses to install itself. Please use the correct make variable. Each variable conveys radically different meanings, both to users and to automated systems that depend on [.filename]##Makefile##s, such as crossref:keeping-up[build-cluster,the ports build cluster], crossref:keeping-up[freshports,FreshPorts], and crossref:keeping-up[portsmon,portsmon].
 
 [[dads-noinstall-variables]]
 === Variables
@@ -288,7 +288,7 @@ For instance, use `BROKEN` when a port:
 +
 [NOTE]
 ====
-If a port would conflict with a currently installed port (for example, if they install a file in the same place that performs a different function), <<conflicts,use `CONFLICTS` instead>>. `CONFLICTS` will set `IGNORE` by itself.
+If a port would conflict with a currently installed port (for example, if they install a file in the same place that performs a different function), crossref:makefiles[conflicts,use `CONFLICTS` instead]. `CONFLICTS` will set `IGNORE` by itself.
 ====
 
 [[dads-noinstall-notes]]
@@ -388,7 +388,7 @@ There is no set policy on how much notice to give. Current practice seems to be
 
 The correct way for a [.filename]#Makefile# to signal that the port cannot be installed due to some external factor (for instance, the user has specified an illegal combination of build options) is to set a non-blank value to `IGNORE`. This value will be formatted and shown to the user by `make install`.
 
-It is a common mistake to use `.error` for this purpose. The problem with this is that many automated tools that work with the ports tree will fail in this situation. The most common occurrence of this is seen when trying to build [.filename]#/usr/ports/INDEX# (see <<make-describe,Running `make describe`>>). However, even more trivial commands such as `make maintainer` also fail in this scenario. This is not acceptable.
+It is a common mistake to use `.error` for this purpose. The problem with this is that many automated tools that work with the ports tree will fail in this situation. The most common occurrence of this is seen when trying to build [.filename]#/usr/ports/INDEX# (see crossref:testing[make-describe,Running `make describe`]). However, even more trivial commands such as `make maintainer` also fail in this scenario. This is not acceptable.
 
 [[dot-error-breaks-index]]
 .How to Avoid Using `.error`
@@ -410,7 +410,7 @@ IGNORE=option is not supported
 ====
 
 [[dads-sysctl]]
-== Usage of [.filename]#sysctl#
+== Usage of sysctl
 
 The usage of [.filename]#sysctl# is discouraged except in targets. This is because the evaluation of any ``makevar``s, such as used during `make index`, then has to run the command, further slowing down that process.
 
diff --git a/documentation/content/en/books/porters-handbook/porting-samplem/chapter.adoc b/documentation/content/en/books/porters-handbook/porting-samplem/_index.adoc
index 9a7dbc37a2..c835d0009b 100644
--- a/documentation/content/en/books/porters-handbook/porting-samplem/chapter.adoc
+++ b/documentation/content/en/books/porters-handbook/porting-samplem/_index.adoc
@@ -5,7 +5,7 @@ next: books/porters-handbook/order
 ---
 
 [[porting-samplem]]
-= A Sample [.filename]#Makefile#
+= A Sample Makefile
 :doctype: book
 :toc: macro
 :toclevels: 1
@@ -31,7 +31,7 @@ toc::[]
 
 Here is a sample [.filename]#Makefile# that can be used to create a new port. Make sure to remove all the extra comments (ones between brackets).
 
-The format shown is the recommended one for ordering variables, empty lines between sections, and so on. This format is designed so that the most important information is easy to locate. We recommend using <<porting-portlint,portlint>> to check the [.filename]#Makefile#.
+The format shown is the recommended one for ordering variables, empty lines between sections, and so on. This format is designed so that the most important information is easy to locate. We recommend using crossref:quick-porting[porting-portlint,portlint] to check the [.filename]#Makefile#.
 
 [.programlisting]
 ....
diff --git a/documentation/content/en/books/porters-handbook/porting-why/chapter.adoc b/documentation/content/en/books/porters-handbook/porting-why/_index.adoc
index 66ee06036a..66ee06036a 100644
--- a/documentation/content/en/books/porters-handbook/porting-why/chapter.adoc
+++ b/documentation/content/en/books/porters-handbook/porting-why/_index.adoc
diff --git a/documentation/content/en/books/porters-handbook/quick-porting/chapter.adoc b/documentation/content/en/books/porters-handbook/quick-porting/_index.adoc
index 1c22755703..27227a5b15 100644
--- a/documentation/content/en/books/porters-handbook/quick-porting/chapter.adoc
+++ b/documentation/content/en/books/porters-handbook/quick-porting/_index.adoc
@@ -29,13 +29,13 @@ include::shared/en/urls.adoc[]
 
 toc::[]
 
-This section describes how to quickly create a new port. For applications where this quick method is not adequate, the full "Slow Porting" process is described in <<slow-porting,Slow Porting>>.
+This section describes how to quickly create a new port. For applications where this quick method is not adequate, the full "Slow Porting" process is described in crossref:slow-porting[slow-porting,Slow Porting].
 
 First, get the original tarball and put it into `DISTDIR`, which defaults to [.filename]#/usr/ports/distfiles#.
 
 [NOTE]
 ====
-These steps assume that the software compiled out-of-the-box. In other words, absolutely no changes were required for the application to work on a FreeBSD system. If anything had to be changed, refer to <<slow-porting,Slow Porting>>.
+These steps assume that the software compiled out-of-the-box. In other words, absolutely no changes were required for the application to work on a FreeBSD system. If anything had to be changed, refer to crossref:slow-porting[slow-porting,Slow Porting].
 ====
 
 [NOTE]
@@ -51,7 +51,7 @@ This setting enables the "developer mode" that displays deprecation warnings and
 ====
 
 [[porting-makefile]]
-== Writing the [.filename]#Makefile#
+== Writing the Makefile
 
 The minimal [.filename]#Makefile# would look something like this:
 
@@ -70,7 +70,7 @@ COMMENT=	Cat chasing a mouse all over the screen
 .include <bsd.port.mk>
 ....
 
-Try to figure it out. Do not worry about the contents of the `$FreeBSD$` line, it will be filled in automatically by Subversion when the port is imported to our main ports tree. A more detailed example is shown in the <<porting-samplem,sample Makefile>> section.
+Try to figure it out. Do not worry about the contents of the `$FreeBSD$` line, it will be filled in automatically by Subversion when the port is imported to our main ports tree. A more detailed example is shown in the crossref:porting-samplem[porting-samplem,sample Makefile] section.
 
 [[porting-desc]]
 == Writing the Description Files
@@ -86,7 +86,7 @@ This is a longer description of the port. One to a few paragraphs concisely expl
 ====
 This is _not_ a manual or an in-depth description on how to use or compile the port! _Please be careful when copying from the [.filename]#README# or manpage_. Too often they are not a concise description of the port or are in an awkward format. For example, manpages have justified spacing, which looks particularly bad with monospaced fonts.
 
-On the other hand, the content of [.filename]#pkg-descr# must be longer than the <<makefile-comment,`COMMENT`>> line from the Makefile. It must explain in more depth what the port is all about.
+On the other hand, the content of [.filename]#pkg-descr# must be longer than the crossref:makefiles[makefile-comment,`COMMENT` line from the Makefile. It must explain in more depth what the port is all about.
 ====
 
 A well-written [.filename]#pkg-descr# describes the port completely enough that users would not have to consult the documentation or visit the website to understand what the software does, how it can be useful, or what particularly nice features it has. Mentioning certain requirements like a graphical toolkit, heavy dependencies, runtime environment, or implementation languages help users decide whether this port will work for them.
@@ -159,12 +159,12 @@ Usage of `PLIST_FILES` should not be abused. When looking for the origin of a fi
 
 [TIP]
 ====
-If a port needs to create an empty directory, or creates directories outside of [.filename]#${PREFIX}# during installation, refer to <<plist-dir-cleaning,Cleaning Up Empty Directories>> for more information.
+If a port needs to create an empty directory, or creates directories outside of [.filename]#${PREFIX}# during installation, refer to crossref:plist:plist-dir-cleaning,Cleaning Up Empty Directories] for more information.
 ====
 
 [TIP]
 ====
-As `PLIST_FILES` is a man:make[1] variable, any entry with spaces must be quoted. For example, if using keywords described in man:pkg-create[8] and <<plist-keywords,Expanding Package List with Keywords>>, the entry must be quoted.
+As `PLIST_FILES` is a man:make[1] variable, any entry with spaces must be quoted. For example, if using keywords described in man:pkg-create[8] and crossref:plist[plist-keywords,Expanding Package List with Keywords], the entry must be quoted.
 
 [.programlisting]
 ....
@@ -172,7 +172,7 @@ PLIST_FILES=	"@sample ${ETCDIR}/oneko.conf.sample"
 ....
 ====
 
-Later we will see how [.filename]#pkg-plist# and `PLIST_FILES` can be used to fulfill <<plist,more sophisticated tasks>>.
+Later we will see how [.filename]#pkg-plist# and `PLIST_FILES` can be used to fulfill crossref:plist[plist,more sophisticated tasks].
 
 [[porting-checksum]]
 == Creating the Checksum File
@@ -189,7 +189,7 @@ Make sure that the port rules do exactly what is desired, including packaging up
 * The port can be installed using the `install` target. This verifies that the install script works correctly.
 * The port can be deinstalled properly using the `deinstall` target. This verifies that the deinstall script works correctly.
 * The port only has access to network resources during the `fetch` target phase. This is important for package builders, such as package:ports-mgmt/poudriere[].
-* Make sure that `make package` can be run as a normal user (that is, not as `root`). If that fails, the software may need to be patched. See also <<uses-fakeroot,`fakeroot`>> and <<uses-uidfix,`uidfix`>>.
+* Make sure that `make package` can be run as a normal user (that is, not as `root`). If that fails, the software may need to be patched. See also crossref:uses[uses-fakeroot,`fakeroot`] and crossref:uses[uses-uidfix,`uidfix`].
 
 [.procedure]
 .Procedure: Recommended Test Ordering
@@ -202,12 +202,12 @@ Make sure that the port rules do exactly what is desired, including packaging up
 
 Make certain no warnings are shown in any of the stages.
 
-Thorough automated testing can be done with package:ports-mgmt/poudriere[] from the Ports Collection, see <<testing-poudriere,Poudriere>> for more information. It maintains `jails` where all of the steps shown above can be tested without affecting the state of the host system.
+Thorough automated testing can be done with package:ports-mgmt/poudriere[] from the Ports Collection, see crossref:testing[testing-poudriere,Poudriere] for more information. It maintains `jails` where all of the steps shown above can be tested without affecting the state of the host system.
 
 [[porting-portlint]]
 == Checking the Port with `portlint`
 
-Please use `portlint` to see if the port conforms to our guidelines. The package:ports-mgmt/portlint[] program is part of the ports collection. In particular, check that the <<porting-samplem,Makefile>> is in the right shape and the <<porting-pkgname,package>> is named appropriately.
+Please use `portlint` to see if the port conforms to our guidelines. The package:ports-mgmt/portlint[] program is part of the ports collection. In particular, check that the crossref:porting-samplem[porting-samplem,Makefile] is in the right shape and the crossref:porting-pkgname[porting-pkgname,package] is named appropriately.
 
 [IMPORTANT]
 ====
@@ -217,7 +217,7 @@ Do not blindly follow the output of `portlint`. It is a static lint tool and som
 [[porting-submitting]]
 == Submitting the New Port
 
-Before submitting the new port, read the <<porting-dads,DOs and DON'Ts>> section.
+Before submitting the new port, read the crossref:porting-dads[porting-dads,DOs and DON'Ts] section.
 
 Once happy with the port, the only thing remaining is to put it in the main FreeBSD ports tree and make everybody else happy about it too.
 
diff --git a/documentation/content/en/books/porters-handbook/security/chapter.adoc b/documentation/content/en/books/porters-handbook/security/_index.adoc
index 18069eaa7e..d2919d9774 100644
--- a/documentation/content/en/books/porters-handbook/security/chapter.adoc
+++ b/documentation/content/en/books/porters-handbook/security/_index.adoc
@@ -41,14 +41,14 @@ A security vulnerability is all different. First, it may remain unnoticed for ye
 [[security-fix]]
 == Fixing Security Vulnerabilities
 
-While on the subject of ports and packages, a security vulnerability may initially appear in the original distribution or in the port files. In the former case, the original software developer is likely to release a patch or a new version instantly. Update the port promptly with respect to the author's fix. If the fix is delayed for some reason, either <<dads-noinstall,mark the port as `FORBIDDEN`>> or introduce a patch file to the port. In the case of a vulnerable port, just fix the port as soon as possible. In either case, follow <<port-upgrading,the standard procedure for submitting changes>> unless having rights to commit it directly to the ports tree.
+While on the subject of ports and packages, a security vulnerability may initially appear in the original distribution or in the port files. In the former case, the original software developer is likely to release a patch or a new version instantly. Update the port promptly with respect to the author's fix. If the fix is delayed for some reason, either crossref:porting-dads[dads-noinstall,mark the port as `FORBIDDEN`] or introduce a patch file to the port. In the case of a vulnerable port, just fix the port as soon as possible. In either case, follow crossref:port-upgrading[port-upgrading,the standard procedure for submitting changes] unless having rights to commit it directly to the ports tree.
 
 [IMPORTANT]
 ====
 Being a ports committer is not enough to commit to an arbitrary port. Remember that ports usually have maintainers, must be respected.
 ====
 
-Please make sure that the port's revision is bumped as soon as the vulnerability has been closed. That is how the users who upgrade installed packages on a regular basis will see they need to run an update. Besides, a new package will be built and distributed over FTP and WWW mirrors, replacing the vulnerable one. Bump `PORTREVISION` unless `DISTVERSION` has changed in the course of correcting the vulnerability. That is, bump `PORTREVISION` if adding a patch file to the port, but do not bump it if updating the port to the latest software version and thus already touched `DISTVERSION`. Please refer to the <<makefile-naming-revepoch,corresponding section>> for more information.
+Please make sure that the port's revision is bumped as soon as the vulnerability has been closed. That is how the users who upgrade installed packages on a regular basis will see they need to run an update. Besides, a new package will be built and distributed over FTP and WWW mirrors, replacing the vulnerable one. Bump `PORTREVISION` unless `DISTVERSION` has changed in the course of correcting the vulnerability. That is, bump `PORTREVISION` if adding a patch file to the port, but do not bump it if updating the port to the latest software version and thus already touched `DISTVERSION`. Please refer to the crossref:makefiles[makefile-naming-revepoch,corresponding section] for more information.
 
 [[security-notify]]
 == Keeping the Community Informed
diff --git a/documentation/content/en/books/porters-handbook/slow-porting/chapter.adoc b/documentation/content/en/books/porters-handbook/slow-porting/_index.adoc
index d89c0b074f..0df377f3d1 100644
--- a/documentation/content/en/books/porters-handbook/slow-porting/chapter.adoc
+++ b/documentation/content/en/books/porters-handbook/slow-porting/_index.adoc
@@ -47,7 +47,7 @@ But do not worry, not many people understand exactly how [.filename]#bsd.port.mk
 .. If `HAS_CONFIGURE` or `GNU_CONFIGURE` is set, [.filename]#WRKSRC/configure# is run.
 
 . The `build` target is run. This is responsible for descending into the port's private working directory (`WRKSRC`) and building it.
-. The `stage` target is run. This puts the final set of built files into a temporary directory (`STAGEDIR`, see <<staging,Staging>>). The hierarchy of this directory mirrors that of the system on which the package will be installed.
+. The `stage` target is run. This puts the final set of built files into a temporary directory (`STAGEDIR`, see crossref:special[staging,Staging]). The hierarchy of this directory mirrors that of the system on which the package will be installed.
 . The `package` target is run. This creates a package using the files from the temporary directory created during the `stage` target and the port's [.filename]#pkg-plist#.
 . The `install` target is run. This installs the package created during the `package` target into the host system.
 
@@ -69,7 +69,7 @@ Now that what goes on when the user types `make install` is better understood, l
 
 Get the original sources (normally) as a compressed tarball ([.filename]#foo.tar.gz# or [.filename]#foo.tar.bz2#) and copy it into `DISTDIR`. Always use _mainstream_ sources when and where possible.
 
-Set the variable `MASTER_SITES` to reflect where the original tarball resides. Shorthand definitions exist for most mainstream sites in [.filename]#bsd.sites.mk#. Please use these sites-and the associated definitions-if at all possible, to help avoid the problem of having the same information repeated over again many times in the source base. As these sites tend to change over time, this becomes a maintenance nightmare for everyone involved. See <<makefile-master_sites,`MASTER_SITES`>> for details.
+Set the variable `MASTER_SITES` to reflect where the original tarball resides. Shorthand definitions exist for most mainstream sites in [.filename]#bsd.sites.mk#. Please use these sites-and the associated definitions-if at all possible, to help avoid the problem of having the same information repeated over again many times in the source base. As these sites tend to change over time, this becomes a maintenance nightmare for everyone involved. See crossref:makefiles[makefile-master_sites,`MASTER_SITES`] for details.
 
 If there is no FTP/HTTP site that is well-connected to the net, or can only find sites that have irritatingly non-standard formats, put a copy on a reliable FTP or HTTP server (for example, a home page).
 
@@ -77,7 +77,7 @@ If a convenient and reliable place to put the distfile cannot be found, we can "
 
 If the port's distfile changes all the time without any kind of version update by the author, consider putting the distfile on a home page and listing it as the first `MASTER_SITES`. Try to talk the port author out of doing this; it really does help to establish some kind of source code control. Hosting a specific version will prevent users from getting `checksum mismatch` errors, and also reduce the workload of maintainers of our FTP site. Also, if there is only one master site for the port, it is recommended to house a backup on a home page and list it as the second `MASTER_SITES`.
 
-If the port requires additional patches that are available on the Internet, fetch them too and put them in `DISTDIR`. Do not worry if they come from a site other than where the main source tarball comes, we have a way to handle these situations (see the description of <<porting-patchfiles,PATCHFILES>> below).
+If the port requires additional patches that are available on the Internet, fetch them too and put them in `DISTDIR`. Do not worry if they come from a site other than where the main source tarball comes, we have a way to handle these situations (see the description of crossref:makefiles[porting-patchfiles,PATCHFILES] below).
 
 [[slow-modifying]]
 == Modifying the Port
@@ -106,7 +106,7 @@ After all changes have been made, `cd` back to the port directory. Use `make mak
 [TIP]
 ====
 
-Use `BINARY_ALIAS` to substitute hardcoded commands during the build and avoid patching build files. See <<binary-alias,Use `BINARY_ALIAS` to Rename Commands Instead of Patching the Build>> for more information.
+Use `BINARY_ALIAS` to substitute hardcoded commands during the build and avoid patching build files. See crossref:makefiles[binary-alias,Use `BINARY_ALIAS` to Rename Commands Instead of Patching the Build] for more information.
 ====
 
 [[slow-patch-rules]]
@@ -233,7 +233,7 @@ EXTRA_PATCHES=	${PATCHDIR}/extra-patch-fbsd10
 .Optionally Applying a Patch
 [example]
 ====
-When an <<makefile-options,option>> requires a patch, use ``opt_EXTRA_PATCHES`` and ``opt_EXTRA_PATCHES_OFF`` to make the patch conditional on the `opt` option. See <<options-variables,Generic Variables Replacement, `OPT_VARIABLE` and `OPT_VARIABLE_OFF`>> for more information.
+When an crossref:makefiles[makefile-options,option] requires a patch, use ``opt_EXTRA_PATCHES`` and ``opt_EXTRA_PATCHES_OFF`` to make the patch conditional on the `opt` option. See crossref:makefiles[options-variables,Generic Variables Replacement, `OPT_VARIABLE` and `OPT_VARIABLE_OFF`] for more information.
 
 [.programlisting]
 ....
diff --git a/documentation/content/en/books/porters-handbook/special/chapter.adoc b/documentation/content/en/books/porters-handbook/special/_index.adoc
index 8bf35a4a22..d01f331efa 100644
--- a/documentation/content/en/books/porters-handbook/special/chapter.adoc
+++ b/documentation/content/en/books/porters-handbook/special/_index.adoc
@@ -34,11 +34,11 @@ This section explains the most common things to consider when creating a port.
 [[staging]]
 == Staging
 
-[.filename]#bsd.port.mk# expects ports to work with a "stage directory". This means that a port must not install files directly to the regular destination directories (that is, under `PREFIX`, for example) but instead into a separate directory from which the package is then built. In many cases, this does not require root privileges, making it possible to build packages as an unprivileged user. With staging, the port is built and installed into the stage directory, `STAGEDIR`. A package is created from the stage directory and then installed on the system. Automake tools refer to this concept as `DESTDIR`, but in FreeBSD, `DESTDIR` has a different meaning (see <<porting-prefix,`PREFIX` and `DESTDIR`>>).
+[.filename]#bsd.port.mk# expects ports to work with a "stage directory". This means that a port must not install files directly to the regular destination directories (that is, under `PREFIX`, for example) but instead into a separate directory from which the package is then built. In many cases, this does not require root privileges, making it possible to build packages as an unprivileged user. With staging, the port is built and installed into the stage directory, `STAGEDIR`. A package is created from the stage directory and then installed on the system. Automake tools refer to this concept as `DESTDIR`, but in FreeBSD, `DESTDIR` has a different meaning (see crossref:testing[porting-prefix,`PREFIX` and `DESTDIR`]).
 
 [NOTE]
 ====
-No port _really_ needs to be root. It can mostly be avoided by using <<uses-uidfix,`USES=uidfix`>>. If the port still runs commands like man:chown[8], man:chgrp[1], or forces owner or group with man:install[1] then use <<uses-fakeroot,`USES=fakeroot`>> to fake those calls. Some patching of the port's [.filename]#Makefiles# will be needed.
+No port _really_ needs to be root. It can mostly be avoided by using crossref:uses[uses-uidfix,`USES=uidfix`]. If the port still runs commands like man:chown[8], man:chgrp[1], or forces owner or group with man:install[1] then use crossref:uses[uses-fakeroot,`USES=fakeroot`] to fake those calls. Some patching of the port's [.filename]#Makefiles# will be needed.
 ====
 
 Meta ports, or ports that do not install files themselves but only depend on other ports, must avoid needlessly extracting the man:mtree[8] to the stage directory. This is the basic directory layout of the package, and these empty directories will be seen as orphans. To prevent man:mtree[8] extraction, add this line:
@@ -161,7 +161,7 @@ Please double-check, often this is not necessary at all or can be avoided throug
 
 When installing 32-bit libraries on 64-bit system, use `USE_LDCONFIG32` instead.
 
-If the software uses <<using-autotools,autotools>>, and specifically `libtool`, add <<uses-libtool,`USES=libtool`>>.
+If the software uses <<using-autotools,autotools>>, and specifically `libtool`, add crossref:uses[uses-libtool,`USES=libtool`].
 
 When the major library version number increments in the update to the new port version, all other ports that link to the affected library must have their `PORTREVISION` incremented, to force recompilation with the new library version.
 
@@ -268,7 +268,7 @@ If the port uses GNU make, add `gmake` to `USES`.
 
 `MAKE_CMD` can be used to reference the specific command configured by the `USES` setting in the port's [.filename]#Makefile#. Only use `MAKE_CMD` within the application [.filename]#Makefile#s in `WRKSRC` to call the `make` implementation expected by the ported software.
 
-If the port is an X application that uses imake to create [.filename]##Makefile##s from [.filename]##Imakefile##s, set `USES= imake`.. See the <<uses-imake,`USES=imake`>> section of <<uses,Using `USES` Macros>> for more details.
+If the port is an X application that uses imake to create [.filename]##Makefile##s from [.filename]##Imakefile##s, set `USES= imake`.. See the crossref:uses[uses-imake,`USES=imake`] section of crossref:uses[uses,Using `USES` Macros] for more details.
 
 If the port's source [.filename]#Makefile# has something other than `all` as the main build target, set `ALL_TARGET` accordingly. The same goes for `install` and `INSTALL_TARGET`.
 
@@ -381,7 +381,7 @@ CMAKE_ARGS=	-DVAR1:BOOL=TRUE -DVAR2:BOOL=TRUE -DVAR3:BOOL=FALSE
 
 [IMPORTANT]
 ======
-This is only for the default values off `CMAKE_ARGS`. The helpers described in <<options-cmake_bool,`OPT_CMAKE_BOOL` and `OPT_CMAKE_BOOL_OFF`>> use the same semantics, but for optional values.
+This is only for the default values off `CMAKE_ARGS`. The helpers described in crossref:makefiles[options-cmake_bool,`OPT_CMAKE_BOOL` and `OPT_CMAKE_BOOL_OFF`] use the same semantics, but for optional values.
 ======
 
 ====
@@ -650,7 +650,7 @@ PULSEAUDIO_VARS=	CARGO_FEATURES+=pulseaudio_backend
 .Listing Crate Licenses
 [example]
 ====
-Crates have their own licenses. It is important to know what they are when adding a `LICENSE` block to the port (see <<licenses,Licenses>>). The helper target `cargo-crates-licenses` will try to list all the licenses of all crates defined in `CARGO_CRATES`.
+Crates have their own licenses. It is important to know what they are when adding a `LICENSE` block to the port (see crossref:makefiles[licenses,Licenses]). The helper target `cargo-crates-licenses` will try to list all the licenses of all crates defined in `CARGO_CRATES`.
 
 [source,shell]
 ....
@@ -666,7 +666,7 @@ byteorder-1.2.2     Unlicense/MIT
 
 [NOTE]
 ======
-The license names `make cargo-crates-licenses` outputs are SPDX 2.1 licenses expression which do not match the license names defined in the ports framework. They need to be translated to the names from <<licenses-license-list,Predefined License List>>.
+The license names `make cargo-crates-licenses` outputs are SPDX 2.1 licenses expression which do not match the license names defined in the ports framework. They need to be translated to the names from crossref:makefiles[licenses-license-list,Predefined License List].
 ======
 
 ====
@@ -707,7 +707,7 @@ MESON_ARGS=	-Dfoo=enabled
 [[using-go]]
 === Building Go Applications
 
-For ports that use Go, define `USES=go`. Refer to <<uses-go,`go`>> for a list of variables that can be set to control the build process.
+For ports that use Go, define `USES=go`. Refer to crossref:uses[uses-go,`go`] for a list of variables that can be set to control the build process.
 
 [[go-ex1]]
 .Creating a Port for a Go Modules Based Application
@@ -858,7 +858,7 @@ will install `dnscrypt-proxy` to `${PREFIX}/sbin`.
 [[using-cabal]]
 === Building Haskell Applications with `cabal`
 
-For ports that use Cabal, build system defines `USES=cabal`. Refer to <<uses-cabal,`cabal`>> for a list of variables that can be set to control the build process.
+For ports that use Cabal, build system defines `USES=cabal`. Refer to crossref:uses[uses-cabal,`cabal`] for a list of variables that can be set to control the build process.
 
 [[cabal-ex1]]
 .Creating a Port for a Hackage-hosted Haskell Application
@@ -956,7 +956,7 @@ If you are not testing your port in a clean environment like with Poudriere, rem
 [[using-autotools]]
 == Using GNU Autotools
 
-If a port needs any of the GNU Autotools software, add `USES=autoreconf`. See <<uses-autoreconf,`autoreconf`>> for more information.
+If a port needs any of the GNU Autotools software, add `USES=autoreconf`. See crossref:uses[uses-autoreconf,`autoreconf`] for more information.
 
 [[using-gettext]]
 == Using GNU `gettext`
@@ -964,7 +964,7 @@ If a port needs any of the GNU Autotools software, add `USES=autoreconf`. See <<
 [[using-gettext-basic]]
 === Basic Usage
 
-If the port requires `gettext`, set `USES= gettext`, and the port will inherit a dependency on [.filename]#libintl.so# from package:devel/gettext[]. Other values for `gettext` usage are listed in <<uses-gettext,`USES=gettext`>>.
+If the port requires `gettext`, set `USES= gettext`, and the port will inherit a dependency on [.filename]#libintl.so# from package:devel/gettext[]. Other values for `gettext` usage are listed in crossref:uses[uses-gettext,`USES=gettext`].
 
 A rather common case is a port using `gettext` and `configure`. Generally, GNU `configure` should be able to locate `gettext` automatically.
 
@@ -1021,7 +1021,7 @@ PLIST_SUB+=		NLS="@comment "
 .include <bsd.port.mk>
 ....
 
-The next item on the to-do list is to arrange so that the message catalog files are included in the packing list conditionally. The [.filename]#Makefile# part of this task is already provided by the idiom. It is explained in the section on <<plist-sub,advanced [.filename]#pkg-plist# practices>>. In a nutshell, each occurrence of `%%NLS%%` in [.filename]#pkg-plist# will be replaced by "`@comment `" if NLS is disabled, or by a null string if NLS is enabled. Consequently, the lines prefixed by `%%NLS%%` will become mere comments in the final packing list if NLS is off; otherwise the prefix will be just left out. Then insert `%%NLS%%` before each path to a message catalog file in [.filename]#pkg-plist#. For example:
+The next item on the to-do list is to arrange so that the message catalog files are included in the packing list conditionally. The [.filename]#Makefile# part of this task is already provided by the idiom. It is explained in the section on  crossref:plist[plist-sub,advanced [.filename]#pkg-plist# practices]. In a nutshell, each occurrence of `%%NLS%%` in [.filename]#pkg-plist# will be replaced by "`@comment `" if NLS is disabled, or by a null string if NLS is enabled. Consequently, the lines prefixed by `%%NLS%%` will become mere comments in the final packing list if NLS is off; otherwise the prefix will be just left out. Then insert `%%NLS%%` before each path to a message catalog file in [.filename]#pkg-plist#. For example:
 
 [.programlisting]
 ....
@@ -1029,7 +1029,7 @@ The next item on the to-do list is to arrange so that the message catalog files
 %%NLS%%share/locale/no/LC_MESSAGES/foobar.mo
 ....
 
-In high complexity cases, more advanced techniques may be needed, such as <<plist-dynamic,dynamic packing list generation>>.
+In high complexity cases, more advanced techniques may be needed, such as crossref:plist[plist-dynamic,dynamic packing list generation].
 
 [[using-gettext-catalog-directories]]
 === Handling Message Catalog Directories
@@ -1043,7 +1043,7 @@ If `MASTER_SITES` is set to `CPAN`, the correct subdirectory is usually selected
 
 The exception to this rule is when the relevant directory does not exist or the distfile does not exist in that directory. In such case, using author's id as `MASTER_SITE_SUBDIR` is allowed. The `CPAN:AUTHOR` macro can be used, which will be translated to the hashed author directory. For example, `CPAN:AUTHOR` will be converted to `authors/id/A/AU/AUTHOR`.
 
-When a port needs Perl support, it must set `USES=perl5` with the optional `USE_PERL5` described in <<uses-perl5,the perl5 USES description>>.
+When a port needs Perl support, it must set `USES=perl5` with the optional `USE_PERL5` described in crossref:uses[uses-perl5,the perl5 USES description].
 
 [[using-perl-variables]]
 .Read-Only Variables for Ports That Use Perl
@@ -1053,7 +1053,7 @@ When a port needs Perl support, it must set `USES=perl5` with the optional `USE_
 | Means
 
 |`PERL`
-|The full path of the Perl 5 interpreter, either in the system or installed from a port, but without the version number. Use this when the software needs the path to the Perl interpreter. To replace "``#!``"lines in scripts, use <<uses-shebangfix,`shebangfix`>>.
+|The full path of the Perl 5 interpreter, either in the system or installed from a port, but without the version number. Use this when the software needs the path to the Perl interpreter. To replace "``#!``"lines in scripts, use crossref:uses[uses-shebangfix,`shebangfix`].
 
 |`PERL_VERSION`
 |The full version of Perl installed (for example, `5.8.9`).
@@ -1183,9 +1183,9 @@ USE_PERL5=	modbuildtiny
 [[x11-variables]]
 === X.Org Components
 
-The X11 implementation available in The Ports Collection is X.Org. If the application depends on X components, add `USES= xorg` and set `USE_XORG` to the list of required components. A full list can be found in <<uses-xorg,`xorg`>>.
+The X11 implementation available in The Ports Collection is X.Org. If the application depends on X components, add `USES= xorg` and set `USE_XORG` to the list of required components. A full list can be found in crossref:uses[uses-xorg,`xorg`].
 
-The Mesa Project is an effort to provide free OpenGL implementation. To specify a dependency on various components of this project, use `USES= gl` and `USE_GL`. See <<uses-gl,`gl`>> for a full list of available components. For backwards compatibility, the value of `yes` maps to `glu`.
+The Mesa Project is an effort to provide free OpenGL implementation. To specify a dependency on various components of this project, use `USES= gl` and `USE_GL`. See crossref:uses[uses-gl,`gl`] for a full list of available components. For backwards compatibility, the value of `yes` maps to `glu`.
 
 [[use-xorg-example]]
 .`USE_XORG` Example
@@ -1246,7 +1246,7 @@ If the port installs fonts for the X Window System, put them in [.filename]#LOCA
 [[x11-fake-display]]
 === Getting a Fake `DISPLAY` with Xvfb
 
-Some applications require a working X11 display for compilation to succeed. This poses a problem for machines that operate headless. When this variable is used, the build infrastructure will start the virtual framebuffer X server. The working `DISPLAY` is then passed to the build. See <<uses-display,`USES=display`>> for the possible arguments.
+Some applications require a working X11 display for compilation to succeed. This poses a problem for machines that operate headless. When this variable is used, the build infrastructure will start the virtual framebuffer X server. The working `DISPLAY` is then passed to the build. See crossref:uses[uses-display,`USES=display`] for the possible arguments.
 
 [.programlisting]
 ....
@@ -1262,7 +1262,7 @@ Desktop entries (http://standards.freedesktop.org/desktop-entry-spec/latest/[a F
 [[desktop-entries-predefined]]
 ==== Using Predefined [.filename]#.desktop# Files
 
-Ports that include predefined [.filename]#*.desktop# must include those files in [.filename]#pkg-plist# and install them in the [.filename]#$LOCALBASE/share/applications# directory. The <<install-macros,`INSTALL_DATA` macro>> is useful for installing these files.
+Ports that include predefined [.filename]#*.desktop# must include those files in [.filename]#pkg-plist# and install them in the [.filename]#$LOCALBASE/share/applications# directory. The crossref:makefiles[install-macros,`INSTALL_DATA` macro] is useful for installing these files.
 
 [[updating-desktop-database]]
 ==== Updating Desktop Database
@@ -1765,7 +1765,7 @@ For further help with a GNOME port, look at some of the link:https://www.FreeBSD
 
 [NOTE]
 ====
-For ports that are part of Qt itself, see <<uses-qt-dist,`qt-dist`>>.
+For ports that are part of Qt itself, see crossref:uses[uses-qt-dist,`qt-dist`].
 ====
 
 [[qt-common]]
@@ -2945,9 +2945,9 @@ do-install:
 	cd ${WRKDIR}/${PORTDIRNAME} && ${COPYTREE_SHARE} \* ${WEBAPPDIR}/${PORTDIRNAME}
 ....
 
-Regardless of the type of port (library or application), the additional documentation is installed in the <<install-documentation,same location>> as for any other port. The Javadoc tool is known to produce a different set of files depending on the version of the JDK that is used. For ports that do not enforce the use of a particular JDK, it is therefore a complex task to specify the packing list ([.filename]#pkg-plist#). This is one reason why porters are strongly encouraged to use `PORTDOCS`. Moreover, even if the set of files that will be generated by `javadoc` can be predicted, the size of the resulting [.filename]#pkg-plist# advocates for the use of `PORTDOCS`.
+Regardless of the type of port (library or application), the additional documentation is installed in the crossref:makefiles[install-documentation,same location] as for any other port. The Javadoc tool is known to produce a different set of files depending on the version of the JDK that is used. For ports that do not enforce the use of a particular JDK, it is therefore a complex task to specify the packing list ([.filename]#pkg-plist#). This is one reason why porters are strongly encouraged to use `PORTDOCS`. Moreover, even if the set of files that will be generated by `javadoc` can be predicted, the size of the resulting [.filename]#pkg-plist# advocates for the use of `PORTDOCS`.
 
-The default value for `DATADIR` is [.filename]#${PREFIX}/share/${PORTNAME}#. It is a good idea to override `DATADIR` to [.filename]#${JAVASHAREDIR}/${PORTNAME}# for Java ports. Indeed, `DATADIR` is automatically added to `PLIST_SUB` (documented in <<plist-sub,Changing pkg-plist Based on Make Variables>>) so use `%%DATADIR%%` directly in [.filename]#pkg-plist#.
+The default value for `DATADIR` is [.filename]#${PREFIX}/share/${PORTNAME}#. It is a good idea to override `DATADIR` to [.filename]#${JAVASHAREDIR}/${PORTNAME}# for Java ports. Indeed, `DATADIR` is automatically added to `PLIST_SUB` (documented in crossref:plist[plist-sub,Changing pkg-plist Based on Make Variables]) so use `%%DATADIR%%` directly in [.filename]#pkg-plist#.
 
 As for the choice of building Java ports from source or directly installing them from a binary distribution, there is no defined policy at the time of writing. However, people from the https://www.freebsd.org/java/[FreeBSD Java Project] encourage porters to have their ports built from source whenever it is a trivial task.
 
@@ -2955,7 +2955,7 @@ All the features that have been presented in this section are implemented in [.f
 
 Although there is a `java` category for PRs, it refers to the JDK porting effort from the FreeBSD Java project. Therefore, submit the Java port in the `ports` category as for any other port, unless the issue is related to either a JDK implementation or [.filename]#bsd.java.mk#.
 
-Similarly, there is a defined policy regarding the `CATEGORIES` of a Java port, which is detailed in <<makefile-categories,Categorization>>.
+Similarly, there is a defined policy regarding the `CATEGORIES` of a Java port, which is detailed in crossref:makefiles[makefile-categories,Categorization].
 
 [[using-php]]
 == Web Applications, Apache and PHP
@@ -3032,7 +3032,7 @@ Do not depend on Apache unless the web app explicitly needs Apache. Respect that
 [[php-variables]]
 === PHP
 
-PHP web applications declare their dependency on it with `USES=php`. See <<uses-php,`php`>> for more information.
+PHP web applications declare their dependency on it with `USES=php`. See crossref:uses[uses-php,`php`] for more information.
 
 [[php-pear]]
 === PEAR Modules
@@ -3063,7 +3063,7 @@ USES=	pear
 
 [TIP]
 ====
-PEAR modules will automatically be flavorized using <<flavors-auto-php,PHP flavors>>.
+PEAR modules will automatically be flavorized using crossref:flavors[flavors-auto-php,PHP flavors].
 ====
 
 [NOTE]
@@ -3119,7 +3119,7 @@ SOCKETS_USE=	PHP=sockets
 
 [TIP]
 ====
-As Horde modules are also PEAR modules they will also automatically be flavorized using <<lavors-auto-php,PHP flavors>>.
+As Horde modules are also PEAR modules they will also automatically be flavorized using crossref:flavors[flavors-auto-php,PHP flavors].
 ====
 
 [[using-python]]
@@ -3152,7 +3152,7 @@ PKGNAMEPREFIX=	${PYTHON_PKGNAMEPREFIX}
 |The port will use an unique prefix, typically `PYTHON_PKGNAMEPREFIX` for certain directories, such as `EXAMPLESDIR` and `DOCSDIR` and also will append a suffix, the python version from `PYTHON_VER`, to binaries and scripts to be installed. This allows ports to be installed for different Python versions at the same time, which otherwise would install conflicting files.
 
 |`USE_PYTHON=flavors`
-|The port does not use distutils but still supports multiple Python versions. `FLAVORS` will be set to the supported Python versions. See <<flavors-auto-python,`USES`=python and Flavors>> for more information.
+|The port does not use distutils but still supports multiple Python versions. `FLAVORS` will be set to the supported Python versions. See crossref:flavors[flavors-auto-python,`USES`=python and Flavors]for more information.
 
 |`USE_PYTHON=optsuffix`
 |If the current Python version is not the default version, the port will gain `PKGNAMESUFFIX=${PYTHON_PKGNAMESUFFIX}`. Only useful with flavors.
@@ -3203,7 +3203,7 @@ A complete list of available variables can be found in [.filename]#/usr/ports/Mk
 
 [IMPORTANT]
 ====
-All dependencies to Python ports using <<flavors-auto-python,Python flavors>> (either with `USE_PYTHON=distutils` or `USE_PYTHON=flavors`) must have the Python flavor appended to their origin using `@${PY_FLAVOR}`. See <<python-Makefile>>.
+All dependencies to Python ports using crossref:flavors[flavors-auto-python,Python flavors] (either with `USE_PYTHON=distutils` or `USE_PYTHON=flavors`) must have the Python flavor appended to their origin using `@${PY_FLAVOR}`. See <<python-Makefile>>.
 ====
 
 [[python-Makefile]]
@@ -3273,7 +3273,7 @@ The Ports Collection supports parallel installation of multiple Tcl/Tk versions.
 | path of the Tk C header files
 |===
 
-See the <<uses-tcl,`USES=tcl`>> and <<uses-tk,`USES=tk`>> of <<uses,Using `USES` Macros>> for a full description of those variables. A complete list of those variables is available in [.filename]#/usr/ports/Mk/Uses/tcl.mk#.
+See the crossref:uses[uses-tcl,`USES=tcl`] and crossref:uses[uses-tk,`USES=tk`] of crossref:uses[uses,Using `USES` Macros] for a full description of those variables. A complete list of those variables is available in [.filename]#/usr/ports/Mk/Uses/tcl.mk#.
 
 [[using-ruby]]
 == Using Ruby
@@ -3748,7 +3748,7 @@ USES=	lua:flavors
 
 This operates the same way as the `module` parameter described above, but without the assumption that the package should be documented as a Lua module (so `LUA_DOCSDIR` and `LUA_EXAMPLESDIR` are not defined by default). However, the port may choose to define `LUA_DOCSUBDIR` as a suitable subdirectory name (usually the port's `PORTNAME` as long as this does not conflict with the `PORTNAME` of any module), in which case the framework will define both `LUA_DOCSDIR` and `LUA_EXAMPLESDIR`. 
 
-As with module ports, a flavored port should avoid installing files that would conflict between versions. Typically this is done by adding `LUA_VER_STR` as a suffix to program names (e.g. using <<uses-uniquefiles,`uniquefiles`>>), and otherwise using either `LUA_VER` or `LUA_VER_STR` as part of any other files or subdirectories used outside of `LUA_MODLIBDIR` and `LUA_MODSHAREDIR`. 
+As with module ports, a flavored port should avoid installing files that would conflict between versions. Typically this is done by adding `LUA_VER_STR` as a suffix to program names (e.g. using crossref:uses[uses-uniquefiles,`uniquefiles`]), and otherwise using either `LUA_VER` or `LUA_VER_STR` as part of any other files or subdirectories used outside of `LUA_MODLIBDIR` and `LUA_MODSHAREDIR`. 
 
 [[lua-defined-variables]]
 === Defined Variables
@@ -4076,16 +4076,16 @@ Use one of the `USES` macros from <<using-databases-uses>> to add a dependency o
 | USES Macro
 
 |Berkeley DB
-|<<uses-bdb,`bdb`>>
+|crossref:uses[uses-bdb,`bdb`]
 
 |MariaDB, MySQL, Percona
-|<<uses-mysql,`mysql`>>
+|crossref:uses[uses-mysql,`mysql`]
 
 |PostgreSQL
-|<<uses-pgsql,`pgsql`>>
+|crossref:uses[uses-pgsql,`pgsql`]
 
 |SQLite
-|<<uses-sqlite,`sqlite`>>
+|crossref:uses[uses-sqlite,`sqlite`]
 |===
 
 [[using-databases-bdb-ex1]]
@@ -4097,7 +4097,7 @@ Use one of the `USES` macros from <<using-databases-uses>> to add a dependency o
 USES=	bdb:6
 ....
 
-See <<uses-bdb,`bdb`>> for more information.
+See crossref:uses[uses-bdb,`bdb`] for more information.
 ====
 
 [[using-databases-mysql-ex1]]
@@ -4111,7 +4111,7 @@ When a port needs the MySQL client library add
 USES=	mysql
 ....
 
-See <<[uses-mysql,`mysql`>> for more information.
+See crossref:uses[uses-mysql,`mysql`] for more information.
 ====
 
 [[using-databases-pgsql-ex1]]
@@ -4126,7 +4126,7 @@ USES=		pgsql:9.6+
 WANT_PGSQL=	server
 ....
 
-See <<uses-pgsql,`pgsql`>> for more information.
+See crossref:uses[uses-pgsql,`pgsql`] for more information.
 ====
 
 [[using-databases-sqlite-ex1]]
@@ -4138,7 +4138,7 @@ See <<uses-pgsql,`pgsql`>> for more information.
 USES=	sqlite:3
 ....
 
-See <<uses-sqlite,`sqlite`>> for more information.
+See crossref:uses[uses-sqlite,`sqlite`] for more information.
 ====
 
 [[rc-scripts]]
@@ -4153,7 +4153,7 @@ With a mythical port called _doorman_, which needs to start a _doormand_ daemon.
 USE_RC_SUBR=	doormand
 ....
 
-Multiple scripts may be listed and will be installed. Scripts must be placed in the [.filename]#files# subdirectory and a `.in` suffix must be added to their filename. Standard `SUB_LIST` expansions will be ran against this file. Use of the `%%PREFIX%%` and `%%LOCALBASE%%` expansions is strongly encouraged as well. More on `SUB_LIST` in <<using-sub-files,the relevant section>>.
+Multiple scripts may be listed and will be installed. Scripts must be placed in the [.filename]#files# subdirectory and a `.in` suffix must be added to their filename. Standard `SUB_LIST` expansions will be ran against this file. Use of the `%%PREFIX%%` and `%%LOCALBASE%%` expansions is strongly encouraged as well. More on `SUB_LIST` in crossref:pkg-files[using-sub-files,the relevant section].
 
 As of FreeBSD 6.1-RELEASE, local [.filename]#rc.d# scripts (including those installed by ports) are included in the overall man:rcorder[8] of the base system.
 
@@ -4222,7 +4222,7 @@ in their [.filename]#rc.conf.local#, and a variable substitution using ":=" woul
 
 [IMPORTANT]
 ====
-Ports _must not_ start and stop their services when installing and deinstalling. Do not abuse the [.filename]#plist# keywords described in <<plist-keywords-base-exec,`@preexec command,@postexec command,@preunexec command,@postunexec command`>> by running commands that modify the currently running system, including starting or stopping services.
+Ports _must not_ start and stop their services when installing and deinstalling. Do not abuse the [.filename]#plist# keywords described in crossref:plist[plist-keywords-base-exec,`@preexec command,@postexec command,@preunexec command,@postunexec command`] by running commands that modify the currently running system, including starting or stopping services.
 ====
 
 [[rc-scripts-checklist]]
diff --git a/documentation/content/en/books/porters-handbook/testing/chapter.adoc b/documentation/content/en/books/porters-handbook/testing/_index.adoc
index 3db84e6b32..8e4c910ed3 100644
--- a/documentation/content/en/books/porters-handbook/testing/chapter.adoc
+++ b/documentation/content/en/books/porters-handbook/testing/_index.adoc
@@ -36,7 +36,7 @@ Several of the FreeBSD port maintenance tools, such as man:portupgrade[1], rely
 
 [NOTE]
 ====
-It is important to be able to generate this file no matter what options are present in [.filename]#make.conf#, so please avoid doing things such as using `.error` statements when (for instance) a dependency is not satisfied. (See <<dads-dot-error,Avoid Use of the `.error` Construct>>.)
+It is important to be able to generate this file no matter what options are present in [.filename]#make.conf#, so please avoid doing things such as using `.error` statements when (for instance) a dependency is not satisfied. (See crossref:porting-dads[dads-dot-error,Avoid Use of the `.error` Construct].)
 ====
 
 If `make describe` produces a string rather than an error message, everything is probably safe. See [.filename]#bsd.port.mk# for the meaning of the string produced.
@@ -46,7 +46,7 @@ Also note that running a recent version of `portlint` (as specified in the next
 [[testing-portlint]]
 == Portlint
 
-Do check the port with <<porting-portlint,`portlint`>> before submitting or committing it. `portlint` warns about many common errors, both functional and stylistic. For a new (or repocopied) port, `portlint -A` is the most thorough; for an existing port, `portlint -C` is sufficient.
+Do check the port with crossref:quick-porting[porting-portlint,`portlint`] before submitting or committing it. `portlint` warns about many common errors, both functional and stylistic. For a new (or repocopied) port, `portlint -A` is the most thorough; for an existing port, `portlint -C` is sufficient.
 
 Since `portlint` uses heuristics to try to figure out errors, it can produce false positive warnings. In addition, occasionally something that is flagged as a problem really cannot be done in any other way due to limitations in the ports framework. When in doubt, the best thing to do is ask on {freebsd-ports}.
 
@@ -82,7 +82,7 @@ Make sure the application is not installing things in [.filename]#/usr/local# in
 
 If anything is installed outside of `PREFIX`, the package creation process will complain that it cannot find the files.
 
-In addition, it is worth checking the same with the stage directory support (see <<staging,Staging>>):
+In addition, it is worth checking the same with the stage directory support (see crossref:special[staging,Staging]):
 
 [source,shell]
 ....
diff --git a/documentation/content/en/books/porters-handbook/upgrading/chapter.adoc b/documentation/content/en/books/porters-handbook/upgrading/_index.adoc
index 01722aca52..ed78762bfa 100644
--- a/documentation/content/en/books/porters-handbook/upgrading/chapter.adoc
+++ b/documentation/content/en/books/porters-handbook/upgrading/_index.adoc
@@ -35,7 +35,7 @@ When working with more than a few ports, it will probably be easier to use Subve
 
 The next step is to see if there is an update already pending. To do this, there are two options. There is a searchable interface to the https://bugs.freebsd.org/search/[FreeBSD Problem Report (PR) or bug database]. Select `Ports & Packages` in the `Product` multiple select menu, and enter the name of the port in the `Summary` field.
 
-However, sometimes people forget to put the name of the port into the Summary field in an unambiguous fashion. In that case, try searching in the `Comment` field in the `Detailled Bug Information` section, or try the <<portsmon,FreeBSD Ports Monitoring System>> (also known as `portsmon`). This system attempts to classify port PRs by portname. To search for PRs about a particular port, use the http://portsmon.FreeBSD.org/portoverview.py[Overview of One Port].
+However, sometimes people forget to put the name of the port into the Summary field in an unambiguous fashion. In that case, try searching in the `Comment` field in the `Detailled Bug Information` section, or try the crossref:keeping-up[portsmon,FreeBSD Ports Monitoring System] (also known as `portsmon`). This system attempts to classify port PRs by portname. To search for PRs about a particular port, use the http://portsmon.FreeBSD.org/portoverview.py[Overview of One Port].
 
 If there is no pending PR, the next step is to send an email to the port's maintainer, as shown by `make maintainer`. That person may already be working on an upgrade, or have a reason to not upgrade the port right now (because of, for example, stability problems of the new version), and there is no need to duplicate their work. Note that unmaintained ports are listed with a maintainer of `ports@FreeBSD.org`, which is just the general ports mailing list, so sending mail there probably will not help in this case.
 
@@ -55,7 +55,7 @@ Otherwise, either use the `svn diff` method (<<svn-diff>>) or copy the contents
 If some files have been added, copied, moved, or removed, add this information to the problem report so that the committer picking up the patch will know what man:svn[1] commands to run.
 ====
 
-To simplify common operations with patch files, use `make makepatch` as described in <<slow-patch,Patching>>. Other tools exists, like [.filename]#/usr/ports/Tools/scripts/patchtool.py#. Before using it, please read [.filename]#/usr/ports/Tools/scripts/README.patchtool#.
+To simplify common operations with patch files, use `make makepatch` as described in crossref:slow-porting[slow-patch,Patching]. Other tools exists, like [.filename]#/usr/ports/Tools/scripts/patchtool.py#. Before using it, please read [.filename]#/usr/ports/Tools/scripts/README.patchtool#.
 
 If the port is unmaintained, and you are actively using it, please consider volunteering to become its maintainer. FreeBSD has over 4000 ports without maintainers, and this is an area where more volunteers are always needed. (For a detailed description of the responsibilities of maintainers, refer to the section in the link:{developers-handbook}#POLICIES-MAINTAINER[Developer's Handbook].)
 
@@ -73,7 +73,7 @@ If the upgrade is motivated by security concerns or a serious fault in the curre
 Please use man:diff[1] or `svn diff` to create updates to existing ports. Other formats include the whole file and make it impossible to see just what has changed. When diffs are not included, the entire update might be ignored.
 ====
 
-Now that all of that is done, read about how to keep up-to-date in <<keeping-up,Keeping Up>>.
+Now that all of that is done, read about how to keep up-to-date in crossref:keeping-up[keeping-up,Keeping Up].
 
 [[svn-diff]]
 == Using Subversion to Make Patches
@@ -101,7 +101,7 @@ While in the port directory, make any changes that are needed. If adding, copyin
 % svn remove deleted_file
 ....
 
-Make sure to check the port using the checklist in <<porting-testing,Testing the Port>> and <<porting-portlint,Checking the Port with `portlint`>>.
+Make sure to check the port using the checklist in crossref:quick-porting[porting-testing,Testing the Port] and crossref:quick-porting[porting-portlint,Checking the Port with `portlint`].
 
 [source,shell]
 ....
@@ -145,10 +145,10 @@ If files have been added, copied, moved, or removed, include the man:svn[1] `add
 Send the patch following the link:{problem-reports}#pr-writing/[problem report submission guidelines].
 
 [[moved-and-updating-files]]
-== [.filename]#UPDATING# and [.filename]#MOVED#
+== UPDATING and MOVED
 
 [[moved-and-updating-updating]]
-=== [.filename]#/usr/ports/UPDATING#
+=== /usr/ports/UPDATING
 
 If upgrading the port requires special steps like changing configuration files or running a specific program, it must be documented in this file. The format of an entry in this file is:
 
@@ -186,7 +186,7 @@ It is recommended that the AFFECTS line contains a glob matching all the ports a
 ====
 
 [[moved-and-updating-moved]]
-=== [.filename]#/usr/ports/MOVED#
+=== /usr/ports/MOVED
 
 This file is used to list moved or removed ports. Each line in the file is made up of the name of the port, where the port was moved, when, and why. If the port was removed, the section detailing where it was moved can be left blank. Each section must be separated by the `|` (pipe) character, like so:
 
diff --git a/documentation/content/en/books/porters-handbook/uses/chapter.adoc b/documentation/content/en/books/porters-handbook/uses/_index.adoc
index a99e81bc51..41d7a5f73a 100644
--- a/documentation/content/en/books/porters-handbook/uses/chapter.adoc
+++ b/documentation/content/en/books/porters-handbook/uses/_index.adoc
@@ -144,7 +144,7 @@ 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,Haskell Libraries>> 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`
@@ -154,7 +154,7 @@ Sets default values and targets used to build Haskell software using Cabal. A bu
 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,Building Haskell Applications with `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.
@@ -182,7 +182,7 @@ 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,Building Rust Applications with `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`
@@ -204,7 +204,7 @@ By default Ninja is used for the build. In some cases this does not work correct
 
 With the `run` argument, a run dependency is registered in addition to a build dependency.
 
-For more information see <<using-cmake,Using `cmake`>>.
+For more information see crossref:special[using-cmake,Using `cmake`].
 
 [[uses-compiler]]
 == `compiler`
@@ -273,7 +273,7 @@ Set up a virtual display environment. If the environment variable `DISPLAY` is n
 
 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,Simple 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.
@@ -320,7 +320,7 @@ 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}/share/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`
@@ -503,14 +503,14 @@ USES=		gnome
 USE_GNOME=	gnomemenus3:build intlhack
 ....
 
-See <<using-gnome,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,Go Libraries>> 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`
@@ -551,7 +551,7 @@ The Go compiler port to use. By default this is package:lang/go[] but can be set
 This variable must not be set by individual ports!
 ====
 
-See <<using-go,Building Go Applications>> for usage examples.
+See crossref:special[using-go,Building Go Applications] for usage examples.
 
 [[uses-gperf]]
 == `gperf`
@@ -622,14 +622,14 @@ GSSAPI_NONE_CONFIGURE_ON=	--without-gssapi
 
 Possible arguments: (none)
 
-Add buildtime and runtime dependencies on package:devel/pear-channel-horde[]. Other Horde dependencies can be added with `USE_HORDE_BUILD` and `USE_HORDE_RUN`. See <<php-horde,Horde Modules>> for more information.
+Add buildtime and runtime dependencies on package:devel/pear-channel-horde[]. Other Horde dependencies can be added with `USE_HORDE_BUILD` and `USE_HORDE_RUN`. See crossref:special[php-horde,Horde Modules] for more information.
 
 [[uses-iconv]]
 == `iconv`
 
 Possible arguments: (none), `lib`, `build`, `patch`, `translit`, `wchar_t`
 
-Uses `iconv` functions, either from the port package:converters/libiconv[] as a build-time and run-time dependency, or from the base system. By default, with no arguments or with the `lib` argument, implies `iconv` with build-time and run-time dependencies. `build` implies a build-time dependency, and `patch` implies a patch-time dependency. If the port uses the `WCHAR_T` or `//TRANSLIT` iconv extensions, add the relevant arguments so that the correct iconv is used. For more information see <<using-iconv,Using `iconv`>>.
+Uses `iconv` functions, either from the port package:converters/libiconv[] as a build-time and run-time dependency, or from the base system. By default, with no arguments or with the `lib` argument, implies `iconv` with build-time and run-time dependencies. `build` implies a build-time dependency, and `patch` implies a patch-time dependency. If the port uses the `WCHAR_T` or `//TRANSLIT` iconv extensions, add the relevant arguments so that the correct iconv is used. For more information see crossref:special[using-iconv,Using `iconv`].
 
 [[uses-imake]]
 == `imake`
@@ -643,7 +643,7 @@ Add package:devel/imake[] as a build-time dependency and run `xmkmf -a` during t
 
 Possible arguments: `5`
 
-Add dependency on KDE components. See <<using-kde,Using KDE>> for more information.
+Add dependency on KDE components. See crossref:special[using-kde,Using KDE] for more information.
 
 [[uses-kmod]]
 == `kmod`
@@ -656,7 +656,7 @@ Fills in the boilerplate for kernel module ports, currently:
 * Set `SSP_UNSAFE`.
 * Set `IGNORE` if the kernel sources are not found in `SRC_BASE`.
 * Define `KMODDIR` to [.filename]#/boot/modules# by default, add it to `PLIST_SUB` and `MAKE_ENV`, and create it upon installation. If `KMODDIR` is set to [.filename]#/boot/kernel#, it will be rewritten to [.filename]#/boot/modules#. This prevents breaking packages when upgrading the kernel due to [.filename]#/boot/kernel# being renamed to [.filename]#/boot/kernel.old# in the process.
-* Handle cross-referencing kernel modules upon installation and deinstallation, using <<plist-keywords-kld,`@kld`>>.
+* Handle cross-referencing kernel modules upon installation and deinstallation, using crossref:plist[plist-keywords-kld,`@kld`].
 * If the `debug` argument is given, the port can install a debug version of the module into [.filename]#KERN_DEBUGDIR#/[.filename]#KMODDIR#. By default, `KERN_DEBUGDIR` is copied from `DEBUGDIR` and set to [.filename]#/usr/lib/debug#. The framework will take care of creating and removing any required directories.
 
 [[uses-lha]]
@@ -785,14 +785,14 @@ The default version is set by the usual `DEFAULT_VERSIONS` mechanism, unless a v
 
 Applications using Lua are normally built for only a single Lua version. However, library modules intended to be loaded by Lua code should use the `module` option to build with multiple flavors.
 
-For more information see <<using-lua,Using Lua>>.
+For more information see crossref:special[using-lua,Using Lua].
 
 [[uses-lxqt]]
 == `lxqt`
 
 Possible arguments: (none)
 
-Handle dependencies for the LXQt Desktop Environment. Use `USE_LXQT` to select the components needed for the port. See <<[using-lxqt,Using LXQt>> for more information.
+Handle dependencies for the LXQt Desktop Environment. Use `USE_LXQT` to select the components needed for the port. See crossref:special[using-lxqt,Using LXQt] for more information.
 
 [[uses-makeinfo]]
 == `makeinfo`
@@ -849,7 +849,7 @@ USE_MATE=	menus:build intlhack
 
 Possible arguments: (none)
 
-Provide support for Meson based projects. For more information see <<using-meson,Using `meson`>>.
+Provide support for Meson based projects. For more information see crossref:special[using-meson,Using `meson`].
 
 [[uses-metaport]]
 == `metaport`
@@ -927,7 +927,7 @@ If the port <<uses-cmake,`USES=cmake`>> it will look for [.filename]#CMakeLists.
 
 Possible arguments: `env`
 
-Adds a dependency on package:devel/pear[]. It will setup default behavior for software using the PHP Extension and Application Repository. Using the `env` arguments only sets up the PEAR environment variables. See <<php-pear,PEAR Modules>> for more information.
+Adds a dependency on package:devel/pear[]. It will setup default behavior for software using the PHP Extension and Application Repository. Using the `env` arguments only sets up the PEAR environment variables. See crossref:special[php-pear,PEAR Modules] for more information.
 
 [[uses-perl5]]
 == `perl5`
@@ -942,7 +942,7 @@ Depends on Perl. The configuration is done using `USE_PERL5`.
 
 `USE_PERL5` defaults to `build run`. When using `configure`, `modbuild`, or `modbuildtiny`, `build` and `run` are implied.
 
-See <<using-perl,Using Perl>> for more information.
+See crossref:special[using-perl,Using Perl] for more information.
 
 [[uses-pgsql]]
 == `pgsql`
@@ -1000,7 +1000,7 @@ Needs the embedded library version of PHP.
 Provide defaults for fetching PHP extensions from the PECL repository. Enables flavors.
 
 `flavors`::
-Enable automatic <<flavors-auto-php,PHP flavors>> generation. Flavors will be generated for all PHP versions, except the ones present in <<uses-php-ignore,`IGNORE_WITH_PHP`>>.
+Enable automatic crossref:flavors[flavors-auto-php,PHP flavors] generation. Flavors will be generated for all PHP versions, except the ones present in <<uses-php-ignore,`IGNORE_WITH_PHP`>>.
 
 `noflavors`::
 Disable automatic PHP flavors generation. _Must only_ be used with extensions provided by PHP itself.
@@ -1121,7 +1121,7 @@ USE_PYQT=	core doc_build designer_run
 
 Possible arguments: (none), `_X.Y_`, `_X.Y+_`, `_-X.Y_`, `_X.Y-Z.A_`, `patch`, `build`, `run`, `test`
 
-Uses Python. A supported version or version range can be specified. If Python is only needed at build time, run time or for the tests, it can be set as a build, run or test dependency with `build`, `run`, or `test`. If Python is also needed during the patch phase, use `patch`. See <<using-python, Using Python>> for more information.
+Uses Python. A supported version or version range can be specified. If Python is only needed at build time, run time or for the tests, it can be set as a build, run or test dependency with `build`, `run`, or `test`. If Python is also needed during the patch phase, use `patch`. See crossref:special[using-python, Using Python] for more information.
 
 `PYTHON_NO_DEPENDS=yes` can be used when the variables exported by the framework are needed but a dependency on Python is not. It can happen when using with <<uses-shebangfix,`USES=shebangfix`>>, and the goal is only to fix the shebangs but not add a dependency on Python.
 
@@ -1137,14 +1137,14 @@ Uses package:mail/qmail[]. With the `build` argument, it implies `qmail` as a bu
 
 Possible arguments: (none), `norecursive`, `outsource`, `no_env`, `no_configure`
 
-Uses QMake for configuring. For more information see <<using-qmake,Using `qmake`>>.
+Uses QMake for configuring. For more information see crossref:special[using-qmake,Using `qmake`].
 
 [[uses-qt]]
 == `qt`
 
 Possible arguments: `5`, `no_env`
 
-Add dependency on Qt components. `no_env` is passed directly to `USES= qmake`. See <<using-qt,Using Qt>> for more information.
+Add dependency on Qt components. `no_env` is passed directly to `USES= qmake`. See crossref:special[using-qt,Using Qt] for more information.
 
 [[uses-qt-dist]]
 == `qt-dist`
@@ -1215,14 +1215,14 @@ The directory where the Samba shared libraries are available.
 
 Possible arguments: (none)
 
-Provide support for the use of package:devel/scons[]. See <<using-scons,Using `scons`>> for more information.
+Provide support for the use of package:devel/scons[]. See crossref:special[using-scons,Using `scons`] for more information.
 
 [[uses-shared-mime-info]]
 == `shared-mime-info`
 
 Possible arguments: (none)
 
-Uses update-mime-database from package:misc/shared-mime-info[]. This uses will automatically add a post-install step in such a way that the port itself still can specify there own post-install step if needed. It also add an <<plist-keywords-shared-mime-info,`@shared-mime-info`>> entry to the plist.
+Uses update-mime-database from package:misc/shared-mime-info[]. This uses will automatically add a post-install step in such a way that the port itself still can specify there own post-install step if needed. It also add an crossref:plist[plist-keywords-shared-mime-info,`@shared-mime-info`] entry to the plist.
 
 [[uses-shebangfix]]
 == `shebangfix`
@@ -1432,7 +1432,7 @@ Add a dependency on Tcl. A specific version can be requested using _version_. Th
 
 Possible arguments: (none)
 
-Adds <<plist-keywords-terminfo,`@terminfo`>> to the [.filename]#plist#. Use when the port installs [.filename]#*.terminfo# files in [.filename]#${PREFIX}/share/misc#.
+Adds crossref:plist[plist-keywords-terminfo,`@terminfo`] to the [.filename]#plist#. Use when the port installs [.filename]#*.terminfo# files in [.filename]#${PREFIX}/share/misc#.
 
 [[uses-tk]]
 == `tk`
@@ -1491,7 +1491,7 @@ These variables can be adjusted:
 
 Possible arguments: (none), `gtk2`
 
-Provide support for Xfce related ports. See <<using-xfce,Using Xfce>> for details.
+Provide support for Xfce related ports. See crossref:special[using-xfce,Using Xfce] for details.
 
 The `gtk2` argument specifies that the port requires GTK2 support. It adds additional features provided by some core components, for example, package:x11/libxfce4menu[] and package:x11-wm/xfce4-panel[].
 
diff --git a/documentation/content/en/books/porters-handbook/versions/chapter.adoc b/documentation/content/en/books/porters-handbook/versions/_index.adoc
index 201081035c..201081035c 100644
--- a/documentation/content/en/books/porters-handbook/versions/chapter.adoc
+++ b/documentation/content/en/books/porters-handbook/versions/_index.adoc