D46480.diff
No OneTemporary
Actions

Size

322 KB

Referenced Files

None

Subscribers

None

D46480.diff
View Options

This file is larger than 256 KB, so syntax highlighting was skipped.

	diff --git a/documentation/content/en/articles/building-products/_index.adoc b/documentation/content/en/articles/building-products/_index.adoc
	--- a/documentation/content/en/articles/building-products/_index.adoc
	+++ b/documentation/content/en/articles/building-products/_index.adoc
	@@ -62,7 +62,8 @@
	FreeBSD today is well-known as a high-performance server operating system.
	It is deployed on millions of web servers and internet-facing hosts worldwide.
	FreeBSD code also forms an integral part of many products, ranging from appliances such as network routers, firewalls, and storage devices, to personal computers.
	-Portions of FreeBSD have also been used in commercial shrink-wrapped software (see <<freebsd-intro>>).
	+Portions of FreeBSD have also been used in commercial shrink-wrapped software
	+(see crossref:building-products[freebsd-intro]).

	In this article we look at the link:https://www.FreeBSD.org/[FreeBSD project] as a software engineering resource-as a collection of building blocks and processes which you can use to build products.

	@@ -95,21 +96,24 @@

	The rest of the article is structured as follows:

	-* <<freebsd-intro>> introduces the FreeBSD project, explores its organizational structure, key technologies and release engineering processes.
	-* <<freebsd-collaboration>> describes ways to collaborate with the FreeBSD project. It examines common pitfalls encountered by corporates working with voluntary projects like FreeBSD.
	-* <<conclusion>> concludes.
	+* crossref:building-products[freebsd-intro] introduces the FreeBSD project, explores its organizational structure, key technologies and release engineering processes.
	+* crossref:building-products[freebsd-collaboration] describes ways to collaborate with the FreeBSD project. It examines common pitfalls encountered by corporates working with voluntary projects like FreeBSD.
	+* crossref:building-products[conclusion] concludes.

	[[freebsd-intro]]
	== FreeBSD as a set of building blocks

	FreeBSD makes an excellent foundation on which to build products:

	-* FreeBSD source code is distributed under a liberal BSD license facilitating its adoption in commercial products <<Mon2005>> with minimum hassle.
	+* FreeBSD source code is distributed under a liberal BSD license facilitating
	+ its adoption in commercial products crossref:building-products[Mon2005] with minimum hassle.
	* The FreeBSD project has excellent engineering practices that can be leveraged.
	* The project offers exceptional transparency into its workings, allowing organizations using its code to plan effectively for the future.
	-* The culture of the FreeBSD project, carried over from the Computer Science Research Group at The University of California, Berkeley <<McKu1999-1>>, fosters high-quality work. Some features in FreeBSD define the state of the art.
	+* The culture of the FreeBSD project, carried over from the Computer Science
	+ Research Group at The University of California, Berkeley
	+ crossref:building-products[McKu1999-1], fosters high-quality work. Some features in FreeBSD define the state of the art.

	-<<GoldGab2005>> examines the business reasons for using open-source in greater detail.
	+crossref:building-products[GoldGab2005] examines the business reasons for using open-source in greater detail.
	For organizations, the benefits of using FreeBSD components in their products include a shorter time to market, lower development costs and lower development risks.

	=== Building with FreeBSD
	@@ -157,7 +161,9 @@
	FreeBSD's in-kernel Netgraph (man:netgraph[4]) framework allows kernel networking modules to be connected together in flexible ways.
	* Support for storage technologies: Fibre Channel, SCSI, software and hardware RAID, ATA and SATA.
	+
	-FreeBSD supports a number of filesystems, and its native UFS2 filesystem supports soft updates, snapshots and very large filesystem sizes (16TB per filesystem) <<McKu1999>>.
	+FreeBSD supports a number of filesystems, and its native UFS2 filesystem
	+supports soft updates, snapshots and very large filesystem sizes (16TB per
	+ filesystem) crossref:building-products[McKu1999].
	+
	FreeBSD's in-kernel GEOM (man:geom[4]) framework allows kernel storage modules to be composed in flexible ways.
	* Over {numports} ported applications, both commercial and open-source, managed via the FreeBSD ports collection.
	@@ -179,14 +185,17 @@

	FreeBSD does not have "corporate" committers.
	Individual committers are required to take responsibility for the changes they introduce to the code.
	-The extref:{committers-guide}[FreeBSD Committer's guide] <<ComGuide>> documents the rules and responsibilities for committers.
	+The extref:{committers-guide}[FreeBSD Committer's guide]
	+crossref:building-products[ComGuide] documents the rules and responsibilities for committers.

	-FreeBSD's project model is examined in detail in <<Nik2005>>.
	+FreeBSD's project model is examined in detail in
	+crossref:building-products[Nik2005].

	=== FreeBSD Release Engineering Processes

	FreeBSD's release engineering processes play a major role in ensuring that its released versions are of a high quality.
	-At any point of time, FreeBSD's volunteers support multiple code lines (<<fig-freebsd-branches, FreeBSD Release Branches>>):
	+At any point of time, FreeBSD's volunteers support multiple code lines
	+(crossref:building-products[fig-freebsd-branches, FreeBSD Release Branches]):

	* New features and disruptive code enters on the development branch, also known as the _-CURRENT_ branch.
	* _-STABLE_ branches are code lines that are branched from HEAD at regular intervals. Only tested code is allowed onto a -STABLE branch. New features are allowed once they have been tested and stabilized in the -CURRENT branch.
	@@ -204,7 +213,8 @@
	The release engineering team publishes a link:https://www.FreeBSD.org/releng/[road map] for future releases of FreeBSD on the project's web site.
	The dates laid down in the road map are not deadlines; FreeBSD is released when its code and documentation are ready.

	-FreeBSD's release engineering processes are described in <<RelEngDoc>>.
	+FreeBSD's release engineering processes are described in
	+crossref:building-products[RelEngDoc].

	[[freebsd-collaboration]]
	== Collaborating with FreeBSD
	@@ -217,7 +227,7 @@
	The best projects to collaborate with are the ones that are __live__; i.e., with an active community, clear goals and a transparent working style.

	* FreeBSD has an active developer community around it. At the time of writing there are many thousands of contributors from every populated continent in the world and over 300 individuals with write access to the project's source repositories.
	-* The goals of the FreeBSD project are <<Hub1994>>:
	+* The goals of the FreeBSD project are crossref:building-products[Hub1994]:

	** To develop a high-quality operating system for popular computer hardware, and,
	** To make our work available to all under a liberal license.
	@@ -232,18 +242,24 @@
	Volunteer driven projects operate under different rules than for-profit corporates.
	A common mistake that companies make when venturing into the open-source world is that of underplaying these differences.

	-Motivation. Most contributions to FreeBSD are done voluntarily without monetary rewards entering the picture. The factors that motivate individuals are complex, ranging from altruism, to an interest in solving the kinds of problems that FreeBSD attempts to solve. In this environment, "elegance is never optional"<<Nor1993>>.
	+Motivation. Most contributions to FreeBSD are done voluntarily without
	+monetary rewards entering the picture. The factors that motivate individuals are
	+complex, ranging from altruism, to an interest in solving the kinds of problems
	+that FreeBSD attempts to solve. In this environment, "elegance is never
	+optional"crossref:building-products[Nor1993].

	The Long Term View. FreeBSD traces its roots back nearly twenty years to the work of the Computer Science Research Group at the University of California Berkeley.footnote:[FreeBSD's source repository contains a history of the project since its inception, and there are CDROMs available that contain earlier code from the CSRG.] A number of the original CSRG developers remain associated with the project.

	-The project values long-term perspectives <<Nor2001>>. A frequent acronym encountered in the project is DTRT, which stands for "Do The Right Thing".
	+The project values long-term perspectives crossref:building-products[Nor2001]. A frequent acronym encountered in the project is DTRT, which stands for "Do The Right Thing".

	Development Processes. Computer programs are tools for communication: at one level programmers communicate their intentions using a precise notation to a tool (a compiler) that translates their instructions to executable code.
	At another level, the same notation is used for communication of intent between two programmers.

	Formal specifications and design documents are seldom used in the project.
	-Clear and well-written code and well-written change logs (<<fig-change-log, A sample change log entry>>) are used in their place.
	-FreeBSD development happens by "rough consensus and running code"<<Carp1996>>.
	+Clear and well-written code and well-written change logs
	+(crossref:building-products[fig-change-log, A sample change log entry]) are used in their place.
	+FreeBSD development happens by "rough consensus and running
	+code"crossref:building-products[Carp1996].

	[.programlisting]
	....
	@@ -281,7 +297,10 @@
	+
	Track FreeBSD source code. The project makes it easy to mirror its SVN repository using extref:{committers-guide}[svnsync, svn-advanced-use-setting-up-svnsync]. Having the complete history of the source is useful when debugging complex problems and offers valuable insight into the intentions of the original developers. Use a capable source control system that allows you to easily merge changes between the upstream FreeBSD code base and your own in-house code.
	+
	-<<fig-svn-blame, An annotated source listing generated using `svn blame`>> shows a portion of an annotated listing of the file referenced by the change log in <<fig-change-log, A sample change log entry>>.
	+crossref:building-products[fig-svn-blame, An annotated source listing generated
	+using `svn blame`] shows a portion of an annotated listing of the file
	+referenced by the change log in crossref:building-products[fig-change-log, A
	+sample change log entry].
	The ancestry of each line of the source is clearly visible.
	Annotated listings showing the history of every file that is part of FreeBSD are https://svnweb.freebsd.org/[available on the web].
	+
	@@ -325,7 +344,8 @@
	The http://www.bsdcertification.org/[BSD Certification Group] offers certification for all the major BSD derived OSes.
	+
	For less critical needs, you can ask for help on the link:https://lists.freebsd.org/[project mailing lists].
	-A useful guide to follow when asking for help is given in <<Ray2004>>.
	+A useful guide to follow when asking for help is given in
	+crossref:building-products[Ray2004].
	Publicize your involvement::
	You are not required to publicize your use of FreeBSD, but doing so helps both your effort as well as that of the project.
	+
	diff --git a/documentation/content/en/articles/committers-guide/_index.adoc b/documentation/content/en/articles/committers-guide/_index.adoc
	--- a/documentation/content/en/articles/committers-guide/_index.adoc
	+++ b/documentation/content/en/articles/committers-guide/_index.adoc
	@@ -49,7 +49,7 @@
	Almost all FreeBSD developers have commit rights to one or more repositories.
	However, a few developers do not, and some of the information here applies to them as well.
	(For instance, some people only have rights to work with the Problem Report database.)
	-Please see <<non-committers>> for more information.
	+Please see crossref:committers-guide[non-committers] for more information.

	This document may also be of interest to members of the FreeBSD community who want to learn more about how the project works.

	@@ -74,7 +74,7 @@
	\|`ref.FreeBSD.org`, `universe.freeBSD.org` (see also link:https://www.FreeBSD.org/internal/machines/[FreeBSD Project Hosts])

	\|_SMTP Host_
	-\|`smtp.FreeBSD.org:587` (see also <<smtp-setup>>).
	+\|`smtp.FreeBSD.org:587` (see also crossref:committers-guide[smtp-setup]).

	\|`_src/_` Git Repository
	\|`ssh://git@gitrepo.FreeBSD.org/src.git`
	@@ -98,7 +98,8 @@
	\|`stable/n` (`n`-STABLE), `main` (-CURRENT)
	\|===

	-man:ssh[1] is required to connect to the project hosts. For more information, see <<ssh.guide>>.
	+man:ssh[1] is required to connect to the project hosts. For more information,
	+ see crossref:committers-guide[ssh.guide].

	Useful links:

	@@ -187,7 +188,8 @@
	Protect the private key and passphrase.
	If either the private key or passphrase may have been compromised or disclosed, immediately notify mailto:accounts@FreeBSD.org[accounts@FreeBSD.org] and revoke the key.

	-Committing the new key is shown in <<commit-steps, Steps for New Committers>>.
	+Committing the new key is shown in crossref:committers-guide[commit-steps, Steps
	+for New Committers].

	[[kerberos-ldap]]
	== Kerberos and LDAP web Password for FreeBSD Cluster
	@@ -472,7 +474,7 @@
	* tag https://cgit.freebsd.org/src/tag/?h=release/13.2.0[release/13.2.0] on the https://cgit.freebsd.org/src/log/?h=releng/13.2[releng/13.2] branch.

	===== Repositories
	-Please see the <<admin,Administrative Details>> for the latest information on where to get FreeBSD sources.
	+Please see the crossref:committers-guide[admin,Administrative Details] for the latest information on where to get FreeBSD sources.
	$URL below can be obtained from that page.

	Note: The project doesn't use submodules as they are a poor fit for our workflows and development model.
	@@ -1335,7 +1337,8 @@
	....

	As above, I used `-m` for simplicity, but you should likely create a commit message that explains what a Glorb is and why you'd use a Nitz to get it.
	-Not everybody will know so, for your actual commit, you should follow the <<commit-log-message,commit log message>> section instead of emulating the brief style used here.
	+Not everybody will know so, for your actual commit, you should follow the
	+crossref:committers-guide[commit-log-message,commit log message] section instead of emulating the brief style used here.

	==== Now import it into our repository

	@@ -1388,7 +1391,7 @@

	. All the right files, and none of the wrong ones, were merged into contrib/glorbnitz.
	. No other changes are in the tree.
	-. The commit messages look <<commit-log-message,good>>. It should contain a summary of what's changed since the last merge to the FreeBSD `main` branch and any caveats.
	+. The commit messages look crossref:committers-guide[commit-log-message,good]. It should contain a summary of what's changed since the last merge to the FreeBSD `main` branch and any caveats.
	. UPDATING should be updated if there is anything of note, such as user visible changes, important upgrade concerns, etc.

	[NOTE]
	@@ -1515,7 +1518,7 @@

	===== Finding the Subversion Revision

	-You'll need to make sure that you've fetched the notes (see the <<git-mini-daily-use>> for details).
	+You'll need to make sure that you've fetched the notes (see the crossref:committers-guide[git-mini-daily-use]for details).
	Once you have these, notes will show up in the git log command like so:

	[source,shell]
	@@ -1946,7 +1949,8 @@

	The following instructions show how to set up a user-generated branch, based on the FreeBSD `main` branch, and push it to GitHub.

	-Before you begin, make sure that your local Git repo is up to date and has the correct origins set <<keeping_current,as shown above.>>
	+Before you begin, make sure that your local Git repo is up to date and has the
	+correct origins set crossref:committers-guide[keeping_current,as shown above].

	[source,shell]
	````
	@@ -1968,7 +1972,8 @@
	freebsd https://git.freebsd.org/src.git (fetch)
	freebsd ssh://git@gitrepo.freebsd.org/src.git (push)
	....
	-With this in place you can create a branch <<keeping_a_local_branch,as shown above.>>
	+With this in place you can create a branch
	+crossref:committers-guide[keeping_a_local_branch,as shown above].

	[source,shell]
	....
	@@ -2034,7 +2039,8 @@
	Similar steps can be used to pull branches from other repositories and land those.
	When committing pull requests from others, one should take extra care to examine all the changes to ensure they are exactly as represented.

	-Before beginning, make sure that the local Git repo is up to date and has the correct origins set <<keeping_current,as shown above.>>
	+Before beginning, make sure that the local Git repo is up to date and has the
	+correct origins set crossref:committers-guide[keeping_current,as shown above].
	In addition, make sure to have the following origins:
	[source,shell]
	....
	@@ -2103,7 +2109,7 @@
	[[vcs-history]]
	== Version Control History

	-The project has moved to <<git-primer,git>>.
	+The project has moved to crossref:committers-guide[git-primer,git].

	The FreeBSD source repository switched from CVS to Subversion on May 31st, 2008.
	The first real SVN commit is __r179447__.
	@@ -2173,7 +2179,7 @@
	Add an entry for each additional mentor/mentee relationship in the bottom section.
	. Generate a Kerberos Password
	+
	-See <<kerberos-ldap>> to generate or set a Kerberos account for use with other FreeBSD services like the link:https://bugs.freebsd.org/bugzilla/[bug-tracking database] (you get a bug-tracking account as part of that step).
	+See crossref:committers-guide[kerberos-ldap] to generate or set a Kerberos account for use with other FreeBSD services like the link:https://bugs.freebsd.org/bugzilla/[bug-tracking database] (you get a bug-tracking account as part of that step).
	. Optional: Enable Wiki Account
	+
	link:https://wiki.freebsd.org[FreeBSD Wiki] Account - A wiki account allows sharing projects and ideas.
	@@ -2222,7 +2228,8 @@
	. Point your mail client at `smtp.FreeBSD.org:587`.
	. Enable STARTTLS.
	. Ensure your `From:` address is set to `_yourusername_@FreeBSD.org`.
	-. For authentication, you can use your FreeBSD Kerberos username and password (see <<kerberos-ldap>>). The `_yourusername_/mail` principal is preferred, as it is only valid for authenticating to mail resources.
	+. For authentication, you can use your FreeBSD Kerberos username and password
	+ (see crossref:committers-guide[kerberos-ldap]). The `_yourusername_/mail` principal is preferred, as it is only valid for authenticating to mail resources.
	+
	[NOTE]
	======
	@@ -2372,7 +2379,8 @@

	When the mentor decides that a mentee has learned the ropes and is ready to commit on their own, the mentor announces it with a commit to [.filename]#mentors#.
	This file is in the [.filename]#admin# orphan branch of each repository.
	-Detailed information on how to access these branches can be found in <<admin-branch>>.
	+Detailed information on how to access these branches can be found in
	+crossref:committers-guide[admin-branch].

	[[pre-commit-review]]
	== Pre-Commit Review
	@@ -2922,7 +2930,8 @@
	====
	. Log in using your old account.
	. Open new bug. Choose `Services` as the Product, and `Bug Tracker` as the Component. In bug description list accounts you wish to be merged.
	-. Log in using `FreeBSD.org` account and post comment to newly opened bug to confirm ownership. See <<kerberos-ldap>> for more details on how to generate or set a password for your `FreeBSD.org` account.
	+. Log in using `FreeBSD.org` account and post comment to newly opened bug to
	+ confirm ownership. See crossref:committers-guide[kerberos-ldap] for more details on how to generate or set a password for your `FreeBSD.org` account.
	. If there are more than two accounts to merge, post comments from each of them.
	====

	@@ -2942,7 +2951,8 @@
	[.procedure]
	====
	. Change your Phabricator account email to your `FreeBSD.org` email.
	-. Open new bug on our bug tracker using your `FreeBSD.org` account, see <<bugzilla>> for more information. Choose `Services` as the Product, and `Code Review` as the Component. In bug description request that your Phabricator account be renamed, and provide a link to your Phabricator user. For example, `https://reviews.freebsd.org/p/bob_example.com/`
	+. Open new bug on our bug tracker using your `FreeBSD.org` account, see
	+ crossref:committers-guide[bugzilla] for more information. Choose `Services` as the Product, and `Code Review` as the Component. In bug description request that your Phabricator account be renamed, and provide a link to your Phabricator user. For example, `https://reviews.freebsd.org/p/bob_example.com/`
	====

	[IMPORTANT]
	@@ -3097,7 +3107,7 @@
	After all, you made many contributions before you became a committer.
	Always remember that.
	+
	-Consider the points raised under <<respect,Respect other committers>> and apply them also to contributors.
	+Consider the points raised under crossref:committers-guide[respect,Respect other committers] and apply them also to contributors.
	. Discuss any significant change _before_ committing.
	+
	The repository is not where changes are initially submitted for correctness or argued over, that happens first in the mailing lists or by use of the Phabricator service.
	@@ -3154,7 +3164,8 @@
	If your changes are anywhere else, make sure you can still make world.
	If your changes are to a branch, make sure your testing occurs with a machine which is running that code.
	If you have a change which also may break another architecture, be sure and test on all supported architectures.
	-Please ensure your change works for <<compilers,supported toolchains>>.
	+Please ensure your change works for
	+crossref:committers-guide[compilers,supported toolchains].
	Please refer to the https://www.FreeBSD.org/internal/[FreeBSD Internal Page] for a list of available resources.
	As other architectures are added to the FreeBSD supported platforms list, the appropriate shared testing resources will be made available.
	. Do not commit to contributed software without _explicit_ approval from the respective maintainers.
	@@ -3445,7 +3456,8 @@
	[[ports-qa-add-new]]
	==== How do I add a new port?

	-Adding a port to the tree is relatively simple. Once the port is ready to be added, as explained later <<ports-qa-add-new-extra,here>>, you need to add the port's directory entry in the category's [.filename]#Makefile#.
	+Adding a port to the tree is relatively simple. Once the port is ready to be
	+added, as explained later crossref:committers-guide[ports-qa-add-new-extra,here], you need to add the port's directory entry in the category's [.filename]#Makefile#.
	In this [.filename]#Makefile#, ports are listed in alphabetical order and added to the `SUBDIR` variable, like this:

	[.programlisting]
	@@ -3462,7 +3474,7 @@
	....
	[TIP]
	====
	-Don't forget to <<port-commit-message-formats,setup git hooks for the ports tree as explained here>>; a specific hook has been developed to verify the category's [.filename]#Makefile#.
	+Don't forget to crossref:committers-guide[port-commit-message-formats,setup git hooks for the ports tree as explained here]; a specific hook has been developed to verify the category's [.filename]#Makefile#.
	====

	[[ports-qa-add-new-extra]]
	@@ -3565,7 +3577,8 @@
	During that time, build problems were fixed, and the release packages were built.
	This practice is no longer used, as the packages for the releases are built from the current stable, quarterly branch.

	-For more information on how to merge commits to the quarterly branch, see <<ports-qa-misc-request-mfh>>.
	+For more information on how to merge commits to the quarterly branch, see
	+crossref:committers-guide[ports-qa-misc-request-mfh].

	[[ports-qa-quarterly]]
	=== Quarterly Branches
	@@ -3714,16 +3727,16 @@
	Almost all of this document will apply to these developers as well (except things specific to commits and the mailing list memberships that go with them).
	In particular, we recommend that you read:

	-* <<admin>>
	-* <<conventions-everyone>>
	+* crossref:committers-guide[admin]
	+* crossref:committers-guide[conventions-everyone]
	+
	[NOTE]
	====
	Get your mentor to add you to the "Additional Contributors" ([.filename]#doc/shared/contrib-additional.adoc#), if you are not already listed there.
	====
	-* <<developer.relations>>
	-* <<ssh.guide>>
	-* <<rules>>
	+* crossref:committers-guide[developer.relations]
	+* crossref:committers-guide[ssh.guide]
	+* crossref:committers-guide[rules]

	[[google-analytics]]
	== Information About Google Analytics
	diff --git a/documentation/content/en/articles/contributing/_index.adoc b/documentation/content/en/articles/contributing/_index.adoc
	--- a/documentation/content/en/articles/contributing/_index.adoc
	+++ b/documentation/content/en/articles/contributing/_index.adoc
	@@ -150,9 +150,9 @@

	* Find some cool or useful software and extref:{porters-handbook}[create a port] for it.
	* There are a large number of ports that have no maintainer.
	-Become a maintainer and <<adopt-port>>.
	-* If you have created or adopted a port, be aware of <<maintain-port>>.
	-* When you are looking for a quick challenge you could <<fix-broken>>.
	+Become a maintainer and crossref:contributing[adopt-port].
	+* If you have created or adopted a port, be aware of crossref:contributing[maintain-port].
	+* When you are looking for a quick challenge you could crossref:contributing[fix-broken].

	=== Pick one of the items from the Ideas page

	@@ -196,7 +196,8 @@
	Misdirected patches may be redirected to a more appropriate forum for the patch to be resolved.

	Pull requests submitted to the ports repository may or may not see action, based on the whims of developers.
	-For now, you will have a better experience if you follow the ports submission process <<ports-contributing>>.
	+For now, you will have a better experience if you follow the ports submission
	+process crossref:contributing[ports-contributing].

	The docs team also accepts pull requests via GitHub, but has not established any policy for them yet.

	@@ -332,7 +333,7 @@

	==== How to adopt the port

	-First make sure you understand your <<maintain-port>>.
	+First make sure you understand your crossref:contributing[maintain-port].
	Also read the extref:{porters-handbook}[Porter's Handbook].
	_Please do not commit yourself to more than you feel you can comfortably handle._

	@@ -414,11 +415,11 @@
	It is common for a port to work on one branch or platform and fail on another.
	** Make sure your port's dependencies are complete.
	The recommended way of doing this is by installing your own ports tinderbox.
	-See <<resources>> for more information.
	+See crossref:contributing[resources] for more information.
	** Check that the packing list is up to date.
	This involves adding in any new files and directories and removing unused entries.
	** Verify your port using man:portlint[1] as a guide.
	-See <<resources>> for important information about using portlint.
	+See crossref:contributing[resources] for important information about using portlint.
	** Consider whether changes to your port might cause any other ports to break.
	If this is the case, coordinate the changes with the maintainers of those ports.
	This is especially important if your update changes the shared library version; in this case, at the very least, the dependent ports will need to get a `PORTREVISION` bump so that they will automatically be upgraded by automated tools such as package:ports-mgmt/poudriere[].
	diff --git a/documentation/content/en/articles/contributors/_index.adoc b/documentation/content/en/articles/contributors/_index.adoc
	--- a/documentation/content/en/articles/contributors/_index.adoc
	+++ b/documentation/content/en/articles/contributors/_index.adoc
	@@ -61,7 +61,8 @@
	Abstract

	This article lists individuals and organizations who have made a contribution to FreeBSD.
	-To see the current list of FreeBSD Committers you can take a look at the following <<staff-committers, list>>.
	+To see the current list of FreeBSD Committers you can take a look at the
	+following crossref:contributors[staff-committers, list].

	'''

	diff --git a/documentation/content/en/articles/freebsd-releng/_index.adoc b/documentation/content/en/articles/freebsd-releng/_index.adoc
	--- a/documentation/content/en/articles/freebsd-releng/_index.adoc
	+++ b/documentation/content/en/articles/freebsd-releng/_index.adoc
	@@ -88,28 +88,28 @@

	The following sections of this article describe:

	-<<releng-prep>>::
	+crossref:freebsd-releng[releng-prep]::
	General information and preparation before starting the release cycle.

	-<<releng-website>>::
	+crossref:freebsd-releng[releng-website]::
	Website Changes During the Release Cycle

	-<<releng-terms>>::
	+crossref:freebsd-releng[releng-terms]::
	Terminology and general information, such as the "code slush" and "code freeze", used throughout this document.

	-<<releng-head>>::
	+crossref:freebsd-releng[releng-head]::
	The Release Engineering process for a "dot-zero" release.

	-<<releng-stable>>::
	+crossref:freebsd-releng[releng-stable]::
	The Release Engineering process for a "point" release.

	-<<releng-building>>::
	+crossref:freebsd-releng[releng-building]::
	Information related to the specific procedures to build installation medium.

	-<<releng-mirrors>>::
	+crossref:freebsd-releng[releng-mirrors]::
	Procedures to publish installation medium.

	-<<releng-wrapup>>::
	+crossref:freebsd-releng[releng-wrapup]::
	Wrapping up the release cycle.

	[[releng-prep]]
	@@ -361,7 +361,7 @@
	For the first `ALPHA` build, the `BRANCH` value in [.filename]#sys/conf/newvers.sh# needs to be changed from `CURRENT` to `ALPHA1`.
	For subsequent `ALPHA` builds, increment each `ALPHA__N__` value by one.

	-See <<releng-building>> for information on building the `ALPHA` images.
	+See crossref:freebsd-releng[releng-building] for information on building the `ALPHA` images.

	[[releng-head-branching]]
	=== Creating the {branchStablex} Branch
	@@ -741,7 +741,8 @@
	The completed Errata Notice template should be emailed together with either a patch against the {branchReleng} branch or a list of revisions from the {branchStable} branch.

	For Errata Notice requests immediately following the release, the request should be emailed to both the {teamRe} and the {teamSecteam}.
	-Once the {branchReleng} branch has been handed over to the {teamSecteam} as described in <<releng-wrapup-handoff>>, Errata Notice requests should be sent to the {teamSecteam}.
	+Once the {branchReleng} branch has been handed over to the {teamSecteam} as
	+described in crossref:freebsd-releng[releng-wrapup-handoff], Errata Notice requests should be sent to the {teamSecteam}.

	[[releng-wrapup-handoff]]
	=== Handoff to the {teamSecteam}
	diff --git a/documentation/content/en/articles/gjournal-desktop/_index.adoc b/documentation/content/en/articles/gjournal-desktop/_index.adoc
	--- a/documentation/content/en/articles/gjournal-desktop/_index.adoc
	+++ b/documentation/content/en/articles/gjournal-desktop/_index.adoc
	@@ -385,7 +385,7 @@
	The journal probably fills up before it has a chance to get committed (flushed) to disk.
	Keep in mind the size of the journal depends on the usage load, and not the size of the data provider.
	If your disk activity is high, you need a larger partition for the journal.
	-See the note in the <<understanding-journaling>> section.
	+See the note in the crossref:gjournal-desktop[understanding-journaling] section.

	=== I made some mistake during configuration, and I cannot boot normally now. Can this be fixed some way?

	diff --git a/documentation/content/en/articles/hubs/_index.adoc b/documentation/content/en/articles/hubs/_index.adoc
	--- a/documentation/content/en/articles/hubs/_index.adoc
	+++ b/documentation/content/en/articles/hubs/_index.adoc
	@@ -191,7 +191,7 @@

	The best way to mirror the FTP area is rsync.
	You can install the port package:net/rsync[] and then use rsync to sync with your upstream host.
	-rsync is already mentioned in <<mirror-serv-rsync>>.
	+rsync is already mentioned in crossref:hubs[mirror-serv-rsync].
	Since rsync access is not required, your preferred upstream site may not allow it.
	You may need to hunt around a little bit to find a site that allows rsync access.

	@@ -308,7 +308,9 @@
	Additionally there exists a hierarchy of mirrors, which is described in terms of __tiers__.
	The master sites are not referred to but can be described as __Tier-0__.
	Mirrors that mirror from these sites can be considered __Tier-1__, mirrors of __Tier-1__-mirrors, are __Tier-2__, etc.
	-Official sites are encouraged to be of a low __tier__, but the lower the tier the higher the requirements in terms as described in <<mirror-requirements>>.
	+Official sites are encouraged to be of a low __tier__, but the lower the tier
	+the higher the requirements in terms as described in
	+crossref:hubs[mirror-requirements].
	Also access to low-tier-mirrors may be restricted, and access to master sites is definitely restricted.
	The __tier__-hierarchy is not reflected by DNS and generally not documented anywhere except for the master sites.
	However, official mirrors with low numbers like 1-4, are usually _Tier-1_ (this is just a rough hint, and there is no rule).
	@@ -322,7 +324,8 @@
	[[mirror-where-simple]]
	==== I Just Want to Mirror from Somewhere!

	-If you have no special intentions or requirements, the statement in <<mirror-where-where>> applies.
	+If you have no special intentions or requirements, the statement in
	+crossref:hubs[mirror-where-where] applies.
	This means:

	[.procedure]
	@@ -335,9 +338,10 @@
	[[mirror-where-official]]
	==== I am an Official Mirror, What is the Right Site for Me?

	-In general the description in <<mirror-where-simple>> still applies.
	+In general the description in crossref:hubs[mirror-where-simple] still applies.
	Of course you may want to put some weight on the fact that your upstream should be of a low tier.
	-There are some other considerations about _official_ mirrors that are described in <<mirror-official>>.
	+There are some other considerations about _official_ mirrors that are described
	+in crossref:hubs[mirror-official].

	[[mirror-where-master]]
	==== I Want to Access the Master Sites!
	@@ -359,7 +363,7 @@
	This is the master site for the FTP fileset.

	`ftp-master.FreeBSD.org` provides rsync access, in addition to FTP.
	-Refer to <<mirror-ftp-rsync>>.
	+Refer to crossref:hubs[mirror-ftp-rsync].

	Mirrors are also encouraged to allow rsync access for the FTP contents, since they are __Tier-1__-mirrors.

	diff --git a/documentation/content/en/articles/ipsec-must/_index.adoc b/documentation/content/en/articles/ipsec-must/_index.adoc
	--- a/documentation/content/en/articles/ipsec-must/_index.adoc
	+++ b/documentation/content/en/articles/ipsec-must/_index.adoc
	@@ -52,8 +52,8 @@
	[[problem]]
	== The Problem

	-First, lets assume you have <<ipsec-install>>.
	-How do you know it is <<caveat>>? Sure, your connection will not work if it is misconfigured, and it will work when you finally get it right.
	+First, lets assume you have crossref::ipsec-must[ipsec-install].
	+How do you know it is crossref::ipsec-must[caveat]? Sure, your connection will not work if it is misconfigured, and it will work when you finally get it right.
	man:netstat[1] will list it. But can you independently confirm it?

	[[solution]]
	@@ -73,13 +73,14 @@

	Ueli Maurer's "Universal Statistical Test for Random Bit Generators"(https://web.archive.org/web/20011115002319/http://www.geocities.com/SiliconValley/Code/4704/universal.pdf[MUST]) quickly measures the entropy of a sample.
	It uses a compression-like algorithm.
	-<<code>> for a variant which measures successive (~quarter megabyte) chunks of a file.
	+crossref::ipsec-must[code] for a variant which measures successive (~quarter megabyte) chunks of a file.

	[[tcpdump]]
	=== Tcpdump

	We also need a way to capture the raw network data.
	-A program called man:tcpdump[1] lets you do this, if you have enabled the _Berkeley Packet Filter_ interface in your <<kernel>>.
	+A program called man:tcpdump[1] lets you do this, if you have enabled the
	+_Berkeley Packet Filter_ interface in your crossref::ipsec-must[kernel].

	The command:

	@@ -99,9 +100,9 @@
	[.procedure]
	====
	. Open a window to an IPsec host and another window to an insecure host.
	-. Now start <<tcpdump>>.
	+. Now start crossref::ipsec-must[tcpdump].
	. In the "secure" window, run the UNIX(R) command man:yes[1], which will stream the `y` character. After a while, stop this. Switch to the insecure window, and repeat. After a while, stop.
	-. Now run <<code>> on the captured packets. You should see something like the following. The important thing to note is that the secure connection has 93% (6.7) of the expected value (7.18), and the "normal" connection has 29% (2.1) of the expected value.
	+. Now run crossref::ipsec-must[code] on the captured packets. You should see something like the following. The important thing to note is that the secure connection has 93% (6.7) of the expected value (7.18), and the "normal" connection has 29% (2.1) of the expected value.
	+
	[source,shell]
	....
	diff --git a/documentation/content/en/articles/ldap-auth/_index.adoc b/documentation/content/en/articles/ldap-auth/_index.adoc
	--- a/documentation/content/en/articles/ldap-auth/_index.adoc
	+++ b/documentation/content/en/articles/ldap-auth/_index.adoc
	@@ -187,7 +187,8 @@
	====

	This will create a self-signed certificate that can be used for the directives in [.filename]#slapd.conf#, where [.filename]#cert.crt# and [.filename]#cacert.crt# are the same file.
	-If you are going to use many OpenLDAP servers (for replication via `slurpd`) you will want to see <<ssl-ca>> to generate a CA key and use it to sign individual server certificates.
	+If you are going to use many OpenLDAP servers (for replication via `slurpd`) you
	+will want to see crossref:ldap-auth[ssl-ca] to generate a CA key and use it to sign individual server certificates.

	Once this is done, put the following in [.filename]#/etc/rc.conf#:

	@@ -317,7 +318,8 @@
	[[client]]
	== Client Configuration

	-The client should already have OpenLDAP libraries from <<ldap-connect-client>>, but if you are installing several client machines you will need to install package:net/openldap26-client[] on each of them.
	+The client should already have OpenLDAP libraries from
	+crossref:ldap-auth[ldap-connect-client], but if you are installing several client machines you will need to install package:net/openldap26-client[] on each of them.

	FreeBSD requires two ports to be installed to authenticate against an LDAP server, package:security/pam_ldap[] and package:net/nss_ldap[].

	@@ -491,7 +493,8 @@
	Unfortunately, as of the time this was written FreeBSD did not support changing user passwords with man:passwd[1].
	As a result of this, most administrators are left to implement a solution themselves.
	I provide some examples here.
	-Note that if you write your own password change script, there are some security issues you should be made aware of; see <<security-passwd>>
	+Note that if you write your own password change script, there are some security
	+issues you should be made aware of; see crossref:ldap-auth[security-passwd]

	[[chpw-shell]]
	.Shell Script for Changing Passwords
	diff --git a/documentation/content/en/articles/license-guide/_index.adoc b/documentation/content/en/articles/license-guide/_index.adoc
	--- a/documentation/content/en/articles/license-guide/_index.adoc
	+++ b/documentation/content/en/articles/license-guide/_index.adoc
	@@ -248,13 +248,13 @@
	Some files in the FreeBSD software collection contain a copyright statement, an SPDX-License-Identifier tag and an explicit license.
	The explicit license takes precedence over the SPDX-License-Identifier tag.
	The SPDX-License-Identifier tag is the project's best effort attempt to characterize the license, but is only informative for automated tools.
	-See <<expressions,SPDX-License-Identifier Expressions>> for how to interpret the expression.
	+See crossref:license-guide[expressions,SPDX-License-Identifier Expressions] for how to interpret the expression.

	=== Only Copyright and SPDX-License-Identifier expression.

	Some files in the tree contain detached licenses.
	These files contain only a copyright notice and an SPDX-License-Identifier expression, but no explicit license.
	-See <<expressions,SPDX-License-Identifier Expressions>> for how to interpret the expression.
	+See crossref:license-guide[expressions,SPDX-License-Identifier Expressions] for how to interpret the expression.
	Note: the expressions allowed for detached licenses by the project are a subset of the expressions used informationally or that are defined by the standard.

	The license for files containing only the SPDX-License-Identifier should be construed to be
	diff --git a/documentation/content/en/articles/pam/_index.adoc b/documentation/content/en/articles/pam/_index.adoc
	--- a/documentation/content/en/articles/pam/_index.adoc
	+++ b/documentation/content/en/articles/pam/_index.adoc
	@@ -411,16 +411,18 @@
	[[pam-config-breakdown]]
	=== Breakdown of a Configuration Line

	-As explained in <<pam-config-file>>, each line in [.filename]#/etc/pam.conf# consists of four or more fields: the service name, the facility name, the control flag, the module name, and zero or more module arguments.
	+As explained in crossref:pam[pam-config-file], each line in [.filename]#/etc/pam.conf# consists of four or more fields: the service name, the facility name, the control flag, the module name, and zero or more module arguments.

	The service name is generally (though not always) the name of the application the statement applies to.
	If you are unsure, refer to the individual application's documentation to determine what service name it uses.

	Note that if you use [.filename]#/etc/pam.d/# instead of [.filename]#/etc/pam.conf#, the service name is specified by the name of the policy file, and omitted from the actual configuration lines, which then start with the facility name.

	-The facility is one of the four facility keywords described in <<pam-facilities-primitives>>.
	+The facility is one of the four facility keywords described in
	+crossref:pam[pam-facilities-primitives].

	-Likewise, the control flag is one of the four keywords described in <<pam-chains-policies>>, describing how to interpret the return code from the module.
	+Likewise, the control flag is one of the four keywords described in
	+ crossref:pam[pam-chains-policies], describing how to interpret the return code from the module.
	Linux-PAM supports an alternate syntax that lets you specify the action to associate with each possible return code, but this should be avoided as it is non-standard and closely tied in with the way Linux-PAM dispatches service calls (which differs greatly from the way Solaris(TM) and OpenPAM do it.)
	Unsurprisingly, OpenPAM does not support this syntax.

	@@ -622,7 +624,7 @@
	Note that it uses the OpenPAM-specific man:openpam_ttyconv[3] conversation function, which is prototyped in [.filename]#security/openpam.h#.
	If you wish build this application on a system with a different PAM library, you will have to provide your own conversation function.
	A robust conversation function is surprisingly difficult to implement;
	-the one presented in <<pam-sample-conv>> is a good starting point, but should not be used in real-world applications.
	+the one presented in crossref:pam[pam-sample-conv] is a good starting point, but should not be used in real-world applications.

	[.programlisting]
	....
	diff --git a/documentation/content/en/articles/pr-guidelines/_index.adoc b/documentation/content/en/articles/pr-guidelines/_index.adoc
	--- a/documentation/content/en/articles/pr-guidelines/_index.adoc
	+++ b/documentation/content/en/articles/pr-guidelines/_index.adoc
	@@ -121,11 +121,11 @@

	While handling problem reports, either as a developer who has direct access to the Problem Reports database or as a contributor who browses the database and submits followups with patches, comments, suggestions or change requests, you will come across several different types of PRs.

	-* <<pr-unassigned>>
	-* <<pr-assigned>>
	-* <<pr-dups>>
	-* <<pr-stale>>
	-* <<pr-misfiled-notpr>>
	+* crossref:pr-guidelines[pr-unassigned]
	+* crossref:pr-guidelines[pr-assigned]
	+* crossref:pr-guidelines[pr-dups]
	+* crossref:pr-guidelines[pr-stale]
	+* crossref:pr-guidelines[pr-misfiled-notpr]

	The following sections describe what each different type of PRs is used for, when a PR belongs to one of these types, and what treatment each different type receives.

	diff --git a/documentation/content/en/articles/rc-scripting/_index.adoc b/documentation/content/en/articles/rc-scripting/_index.adoc
	--- a/documentation/content/en/articles/rc-scripting/_index.adoc
	+++ b/documentation/content/en/articles/rc-scripting/_index.adoc
	@@ -91,7 +91,7 @@
	Finally, an important part of the [.filename]#rc.d# framework is man:rcorder[8], which helps [.filename]#/etc/rc# to run the small scripts orderly with respect to dependencies between them.
	It can help [.filename]#/etc/rc.shutdown#, too, because the proper order for the shutdown sequence is opposite to that of startup.

	-The BSD [.filename]#rc.d# design is described in <<lukem, the original article by Luke Mewburn>>, and the [.filename]#rc.d# components are documented in great detail in <<manpages, the respective manual pages>>.
	+The BSD [.filename]#rc.d# design is described in crossref:rc-scripting[lukem, the original article by Luke Mewburn], and the [.filename]#rc.d# components are documented in great detail in crossref:rc-scripting[manpages, the respective manual pages].
	However, it might not appear obvious to an [.filename]#rc.d# newbie how to tie the numerous bits and pieces together to create a well-styled script for a particular task.
	Therefore this article will try a different approach to describe [.filename]#rc.d#.
	It will show which features should be used in a number of typical cases, and why.
	@@ -186,7 +186,7 @@
	Now it is the right time to choose a unique name for our script once and for all.
	We will use it in a number of places while developing the script.
	The content of the name variable needs to match the script name,
	-some parts of FreeBSD (e.g., <<rcng-service-jails, service jails>> and the cpuset feature of the rc framework) depend upon this.
	+some parts of FreeBSD (e.g., crossref:rc-scripting[rcng-service-jails, service jails] and the cpuset feature of the rc framework) depend upon this.
	As such the filename shall also not contain characters which may be troublesome in scripting (e.g., do not use a hyphen "-" and others).

	[NOTE]
	@@ -367,7 +367,8 @@
	You should additionally set `command_interpreter` to let man:rc.subr[8] know the actual name of the process if `$command` is a script.

	For each [.filename]#rc.d# script, there is an optional man:rc.conf[5] variable that takes precedence over `command`.
	-Its name is constructed as follows: `${name}_program`, where `name` is the mandatory variable we discussed <<name-var, earlier>>.
	+Its name is constructed as follows: `${name}_program`, where `name` is the
	+mandatory variable we discussed crossref:rc-scripting[name-var, earlier].
	E.g., in this case it will be `mumbled_program`.
	It is man:rc.subr[8] that arranges `${name}_program` to override `command`.

	@@ -450,7 +451,7 @@
	_Never_ include dashed options, like `-X` or `--foo`, in `command_args`.
	The contents of `command_args` will appear at the end of the final command line, hence they are likely to follow arguments present in `${name}_flags`; but most commands will not recognize dashed options after ordinary arguments.
	A better way of passing additional options to `$command` is to add them to the beginning of `${name}_flags`.
	-Another way is to modify `rc_flags` <<rc-flags, as shown later>>.
	+Another way is to modify `rc_flags` crossref:rc-scripting[rc-flags, as shown later].
	====

	➋ A good-mannered daemon should create a _pidfile_ so that its process can be found more easily and reliably.
	@@ -677,7 +678,7 @@
	The required service may fail to start or just be disabled in man:rc.conf[5].
	Obviously, man:rcorder[8] cannot track such details, and man:rc[8] will not do that either.
	Consequently, the application started by our script should be able to cope with any required services being unavailable.
	-In certain cases, we can help it as discussed <<forcedep, below>>
	+In certain cases, we can help it as discussed crossref:rc-scripting[forcedep, below]
	====

	[[keywords]]➍ As we remember from the above text, man:rcorder[8] keywords can be used to select or leave out some scripts.
	diff --git a/documentation/content/en/articles/releng/_index.adoc b/documentation/content/en/articles/releng/_index.adoc
	--- a/documentation/content/en/articles/releng/_index.adoc
	+++ b/documentation/content/en/articles/releng/_index.adoc
	@@ -105,19 +105,19 @@

	The following sections of this article describe:

	-<<release-proc>>::
	+crossref:releng[release-proc]::
	The different phases of the release engineering process leading up to the actual system build.

	-<<release-build>>::
	+crossref:releng[release-build]::
	The actual build process.

	-<<extensibility>>::
	+crossref:releng[extensibility]::
	How the base release may be extended by third parties.

	-<<lessons-learned>>::
	+crossref:releng[lessons-learned]::
	Some of the lessons learned through the release of FreeBSD 4.4.

	-<<future>>::
	+crossref:releng[future]::
	Future directions of development.

	[[release-proc]]
	diff --git a/documentation/content/en/articles/remote-install/_index.adoc b/documentation/content/en/articles/remote-install/_index.adoc
	--- a/documentation/content/en/articles/remote-install/_index.adoc
	+++ b/documentation/content/en/articles/remote-install/_index.adoc
	@@ -70,7 +70,7 @@

	[.procedure]
	====
	-. As we have mentioned in the <<background>> section, many of the reputable server hosting companies provide some kind of rescue system, which is booted from their LAN and accessible over SSH. They usually provide this support to help their customers fix broken operating systems. As this article will explain, it is possible to install FreeBSD with the help of these rescue systems.
	+. As we have mentioned in the crossref:remote-install[background] section, many of the reputable server hosting companies provide some kind of rescue system, which is booted from their LAN and accessible over SSH. They usually provide this support to help their customers fix broken operating systems. As this article will explain, it is possible to install FreeBSD with the help of these rescue systems.
	+
	. The next section of this article will describe how to configure, and build minimalistic FreeBSD on the local machine. That version will eventually be running on the remote machine from a ramdisk, which will allow us to install a complete FreeBSD operating system from an FTP mirror using the sysinstall utility.
	. The rest of this article will describe the installation procedure itself, as well as the configuration of the ZFS file system.
	diff --git a/documentation/content/en/articles/solid-state/_index.adoc b/documentation/content/en/articles/solid-state/_index.adoc
	--- a/documentation/content/en/articles/solid-state/_index.adoc
	+++ b/documentation/content/en/articles/solid-state/_index.adoc
	@@ -108,7 +108,7 @@
	Remember that this value is in sectors by default.

	The fact that [.filename]#/var# is a read-write filesystem is an important distinction, as the [.filename]#/# partition (and any other partitions you may have on your flash media) should be mounted read-only.
	-Remember that in <<intro>> we detailed the limitations of flash memory - specifically the limited write capability.
	+Remember that in crossref:solid-state[intro] we detailed the limitations of flash memory - specifically the limited write capability.
	The importance of not mounting filesystems on flash media read-write, and the importance of not using a swap file, cannot be overstated.
	A swap file on a busy system can burn through a piece of flash media in less than one year.
	Heavy logging or temporary file creation and destruction can do the same.
	@@ -122,7 +122,9 @@

	A few applications in the average system will immediately begin to fail as a result of this change.
	For instance, cron will not run properly as a result of missing cron tabs in the [.filename]#/var# created by [.filename]#/etc/rc.d/var#, and syslog and dhcp will encounter problems as well as a result of the read-only filesystem and missing items in the [.filename]#/var# that [.filename]#/etc/rc.d/var# has created.
	-These are only temporary problems though, and are addressed, along with solutions to the execution of other common software packages in <<strategies>>.
	+These are only temporary problems though, and are addressed, along with
	+solutions to the execution of other common software packages in
	+crossref:solid-state[strategies].

	An important thing to remember is that a filesystem that was mounted read-only with [.filename]#/etc/fstab# can be made read-write at any time by issuing the command:

	@@ -242,7 +244,7 @@
	[[strategies]]
	== System Strategies for Small and Read Only Environments

	-In <<ro-fs>>, it was pointed out that the [.filename]#/var# filesystem constructed by [.filename]#/etc/rc.d/var# and the presence of a read-only root filesystem causes problems with many common software packages used with FreeBSD.
	+In crossref:solid-state[ro-fs], it was pointed out that the [.filename]#/var# filesystem constructed by [.filename]#/etc/rc.d/var# and the presence of a read-only root filesystem causes problems with many common software packages used with FreeBSD.
	In this article, suggestions for successfully running cron, syslog, ports installations, and the Apache web server will be provided.

	=== Cron
	@@ -269,7 +271,8 @@
	=== Ports Installation

	Before discussing the changes necessary to successfully use the ports tree, a reminder is necessary regarding the read-only nature of your filesystems on the flash media.
	-Since they are read-only, you will need to temporarily mount them read-write using the mount syntax shown in <<ro-fs>>.
	+Since they are read-only, you will need to temporarily mount them read-write
	+using the mount syntax shown in crossref:solid-state[ro-fs].
	You should always remount those filesystems read-only when you are done with any maintenance - unnecessary writes to the flash media could considerably shorten its lifespan.

	To make it possible to enter a ports directory and successfully run `make install`, we must create a packages directory on a non-memory filesystem that will keep track of our packages across reboots.
	diff --git a/documentation/content/en/articles/vinum/_index.adoc b/documentation/content/en/articles/vinum/_index.adoc
	--- a/documentation/content/en/articles/vinum/_index.adoc
	+++ b/documentation/content/en/articles/vinum/_index.adoc
	@@ -106,7 +106,7 @@
	This method is called _concatenation_ and has the advantage that the disks are not required to have any specific size relationships.
	It works well when the access to the virtual disk is spread evenly about its address space.
	When access is concentrated on a smaller area, the improvement is less marked.
	-<<vinum-concat, Concatenated Organization>> illustrates the sequence in which storage units are allocated in a concatenated organization.
	+crossref:vinum[vinum-concat, Concatenated Organization] illustrates the sequence in which storage units are allocated in a concatenated organization.

	[[vinum-concat]]
	.Concatenated Organization
	@@ -119,7 +119,7 @@

	`RAID` offers various forms of fault tolerance, though RAID-0 is somewhat misleading as it provides no redundancy.
	Striping requires somewhat more effort to locate the data, and it can cause additional I/O load where a transfer is spread over multiple disks, but it can also provide a more constant load across the disks.
	-<<vinum-striped, Striped Organization>> illustrates the sequence in which storage units are allocated in a striped organization.
	+crossref:vinum[vinum-striped, Striped Organization] illustrates the sequence in which storage units are allocated in a striped organization.

	[[vinum-striped]]
	.Striped Organization
	@@ -188,7 +188,7 @@
	* A _concatenated plex_ uses the address space of each subdisk in turn. Concatenated plexes are the most flexible as they can contain any number of subdisks, and the subdisks may be of different length. The plex may be extended by adding additional subdisks. They require less CPU time than striped plexes, though the difference in CPU overhead is not measurable. On the other hand, they are most susceptible to hot spots, where one disk is very active and others are idle.
	* A _striped plex_ stripes the data across each subdisk. The subdisks must all be the same size and there must be at least two subdisks to distinguish it from a concatenated plex. The greatest advantage of striped plexes is that they reduce hot spots. By choosing an optimum sized stripe, about 256 kB, the load can be evened out on the component drives. Extending a plex by adding new subdisks is so complicated that [.filename]#vinum# does not implement it.

	-<<vinum-comparison, [.filename]#vinum# Plex Organizations>> summarizes the advantages and disadvantages of each plex organization.
	+crossref:vinum[vinum-comparison, [.filename]#vinum# Plex Organizations] summarizes the advantages and disadvantages of each plex organization.

	[[vinum-comparison]]
	.[.filename]#vinum# Plex Organizations
	@@ -263,7 +263,7 @@
	....

	This output shows the brief listing format of man:gvinum[8].
	-It is represented graphically in <<vinum-simple-vol, A Simple [.filename]#vinum# Volume>>.
	+It is represented graphically in crossref:vinum[vinum-simple-vol, A Simple [.filename]#vinum# Volume].

	[[vinum-simple-vol]]
	.A Simple [.filename]#vinum# Volume
	@@ -319,7 +319,7 @@
	S mirror.p1.s0 State: empty PO: 0 B Size: 512 MB
	....

	-<<vinum-mirrored-vol, A Mirrored [.filename]#vinum# Volume>> shows the structure graphically.
	+crossref:vinum[vinum-mirrored-vol, A Mirrored [.filename]#vinum# Volume] shows the structure graphically.

	[[vinum-mirrored-vol]]
	.A Mirrored [.filename]#vinum# Volume
	@@ -384,7 +384,7 @@
	.A Striped [.filename]#vinum# Volume
	image::vinum-striped-vol.png[]

	-This volume is represented in <<vinum-striped-vol, A Striped [.filename]#vinum# Volume>>.
	+This volume is represented in crossref:vinum[vinum-striped-vol, A Striped [.filename]#vinum# Volume].
	The darkness of the stripes indicates the position within the plex address space, where the lightest stripes come first and the darkest last.

	=== Resilience and Performance
	@@ -412,7 +412,7 @@
	The subdisks of the second plex are offset by two drives from those of the first plex.
	This helps to ensure that writes do not go to the same subdisks even if a transfer goes over two drives.

	-<<vinum-raid10-vol, A Mirrored, Striped [.filename]#vinum# Volume>> represents the structure of this volume.
	+crossref:vinum[vinum-raid10-vol, A Mirrored, Striped [.filename]#vinum# Volume] represents the structure of this volume.

	[[vinum-raid10-vol]]
	.A Mirrored, Striped [.filename]#vinum# Volume
	@@ -672,7 +672,8 @@
	....

	It can be observed that the `size` parameter for the faked `a` partition matches the value outlined above, while the `offset` parameter is the sum of the offset within the [.filename]#vinum# partition `h`, and the offset of this partition within the device or slice.
	-This is a typical setup that is necessary to avoid the problem described in <<vinum-root-panic, Nothing Boots, the Bootstrap Panics>>.
	+This is a typical setup that is necessary to avoid the problem described in
	+crossref:vinum[vinum-root-panic, Nothing Boots, the Bootstrap Panics].
	The entire `a` partition is completely within the `h` partition containing all the [.filename]#vinum# data for this device.

	In the above example, the entire device is dedicated to [.filename]#vinum# and there is no leftover pre-[.filename]#vinum# root partition.
	diff --git a/documentation/content/en/books/arch-handbook/mac/_index.adoc b/documentation/content/en/books/arch-handbook/mac/_index.adoc
	--- a/documentation/content/en/books/arch-handbook/mac/_index.adoc
	+++ b/documentation/content/en/books/arch-handbook/mac/_index.adoc
	@@ -1978,7 +1978,7 @@
	\| Description
	\| Locking

	-3+\|See <<mac-mpo-create-mount>>.
	+3+\|See crossref:mac[mac-mpo-create-mount].
	\|===

	Fill out the labels on the mount point being created by the passed subject credential.
	@@ -4314,7 +4314,7 @@
	\| Locking

	\|`cred`
	-\|See <<mac-mpo-check-vnode-mmap>>.
	+\|See crossref:mac[mac-mpo-check-vnode-mmap].
	\|

	\|`vp`
	diff --git a/documentation/content/en/books/arch-handbook/smp/_index.adoc b/documentation/content/en/books/arch-handbook/smp/_index.adoc
	--- a/documentation/content/en/books/arch-handbook/smp/_index.adoc
	+++ b/documentation/content/en/books/arch-handbook/smp/_index.adoc
	@@ -54,7 +54,11 @@

	This document is a work-in-progress, and will be updated to reflect on-going design and implementation activities associated with the SMPng Project. Many sections currently exist only in outline form, but will be fleshed out as work proceeds. Updates or suggestions regarding the document may be directed to the document editors.

	-The goal of SMPng is to allow concurrency in the kernel. The kernel is basically one rather large and complex program. To make the kernel multi-threaded we use some of the same tools used to make other programs multi-threaded. These include mutexes, shared/exclusive locks, semaphores, and condition variables. For the definitions of these and other SMP-related terms, please see the <<smp-glossary>> section of this article.
	+The goal of SMPng is to allow concurrency in the kernel. The kernel is basically
	+one rather large and complex program. To make the kernel multi-threaded we use
	+some of the same tools used to make other programs multi-threaded. These include
	+mutexes, shared/exclusive locks, semaphores, and condition variables. For the
	+definitions of these and other SMP-related terms, please see the crossref:smp[smp-glossary] section of this article.

	[[smp-lock-fundamentals]]
	== Basic Tools and Locking Fundamentals
	diff --git a/documentation/content/en/books/arch-handbook/sound/_index.adoc b/documentation/content/en/books/arch-handbook/sound/_index.adoc
	--- a/documentation/content/en/books/arch-handbook/sound/_index.adoc
	+++ b/documentation/content/en/books/arch-handbook/sound/_index.adoc
	@@ -96,9 +96,13 @@
	....
	+
	Most sound drivers need to store additional private information about their device. A private data structure is usually allocated in the attach routine. Its address is passed to [.filename]#pcm# by the calls to `pcm_register()` and `mixer_init()`. [.filename]#pcm# later passes back this address as a parameter in calls to the sound driver interfaces.
	-* The sound driver attach routine should declare its MIXER or AC97 interface to [.filename]#pcm# by calling `mixer_init()`. For a MIXER interface, this causes in turn a call to <<xxxmixer-init,`xxxmixer_init()`>>.
	+* The sound driver attach routine should declare its MIXER or AC97 interface to
	+ [.filename]#pcm# by calling `mixer_init()`. For a MIXER interface, this causes
	+ in turn a call to crossref:sound[xxxmixer-init,`xxxmixer_init()`].
	* The sound driver attach routine declares its general CHANNEL configuration to [.filename]#pcm# by calling `pcm_register(dev, sc, nplay, nrec)`, where `sc` is the address for the device data structure, used in further calls from [.filename]#pcm#, and `nplay` and `nrec` are the number of play and record channels.
	-* The sound driver attach routine declares each of its channel objects by calls to `pcm_addchan()`. This sets up the channel glue in [.filename]#pcm# and causes in turn a call to <<xxxchannel-init,`xxxchannel_init()`>>.
	+* The sound driver attach routine declares each of its channel objects by calls
	+ to `pcm_addchan()`. This sets up the channel glue in [.filename]#pcm# and
	+ causes in turn a call to crossref:sound[xxxchannel-init,`xxxchannel_init()`].
	* The sound driver detach routine should call `pcm_unregister()` before releasing its resources.

	There are two possible methods to handle non-PnP devices:
	@@ -111,7 +115,8 @@
	[[oss-interfaces]]
	== Interfaces

	-The interface between the [.filename]#pcm# core and the sound drivers is defined in terms of <<kernel-objects,kernel objects>>.
	+The interface between the [.filename]#pcm# core and the sound drivers is defined
	+in terms of crossref:kobj[kernel-objects,kernel objects].

	There are two main interfaces that a sound driver will usually provide: _CHANNEL_ and either _MIXER_ or _AC97_.

	@@ -137,14 +142,16 @@

	When playing, the general transfer mechanism is as follows (reverse the idea for recording):

	-* [.filename]#pcm# initially fills up the buffer, then calls the sound driver's <<channel-trigger,`xxxchannel_trigger()`>> function with a parameter of PCMTRIG_START.
	+* [.filename]#pcm# initially fills up the buffer, then calls the sound driver's
	+ crossref:sound[channel-trigger,`xxxchannel_trigger()`] function with a parameter of PCMTRIG_START.
	* The sound driver then arranges to repeatedly transfer the whole memory area (`sndbuf_getbuf()`, `sndbuf_getsize()`) to the device, in blocks of `sndbuf_getblksz()` bytes. It calls back the `chn_intr()`[.filename]#pcm# function for each transferred block (this will typically happen at interrupt time).
	* `chn_intr()` arranges to copy new data to the area that was transferred to the device (now free), and make appropriate updates to the `snd_dbuf` structure.

	[[xxxchannel-init]]
	==== channel_init

	-`xxxchannel_init()` is called to initialize each of the play or record channels. The calls are initiated from the sound driver attach routine. (See the <<pcm-probe-and-attach,probe and attach section>>).
	+`xxxchannel_init()` is called to initialize each of the play or record channels.
	+The calls are initiated from the sound driver attach routine. (See the crossref:sound[pcm-probe-and-attach,probe and attach section).

	[.programlisting]
	....
	diff --git a/documentation/content/en/books/design-44bsd/_index.adoc b/documentation/content/en/books/design-44bsd/_index.adoc
	--- a/documentation/content/en/books/design-44bsd/_index.adoc
	+++ b/documentation/content/en/books/design-44bsd/_index.adoc
	@@ -77,12 +77,15 @@
	Details of the system-call mechanism are given in Chapter 3, as are descriptions of several kernel mechanisms that do not execute as the direct result of a process doing a system call.

	A _kernel_ in traditional operating-system terminology, is a small nucleus of software that provides only the minimal facilities necessary for implementing additional operating-system services.
	-In contemporary research operating systems -- such as Chorus <<biblio-rozier, [Rozier et al, 1988]>>, Mach <<biblio-accetta, [Accetta et al, 1986]>>, Tunis <<biblio-ewens, [Ewens et al, 1985]>>, and the V Kernel <<biblio-cheriton, [Cheriton, 1988]>> -- this division of functionality is more than just a logical one.
	+In contemporary research operating systems -- such as Chorus
	+crossref:design-44bsd[biblio-rozier, [Rozier et al, 1988]], Mach crossref:design-44bsd[biblio-accetta, [Accetta et al, 1986]], Tunis
	+crossref:design-44bsd[biblio-ewens, [Ewens et al, 1985]], and the V Kernel crossref:design-44bsd[biblio-cheriton, [Cheriton, 1988]] -- this division of functionality is more than just a logical one.
	Services such as filesystems and networking protocols are implemented as client application processes of the nucleus or kernel.

	The 4.4BSD kernel is not partitioned into multiple processes.
	This basic design decision was made in the earliest versions of UNIX.
	-The first two implementations by Ken Thompson had no memory mapping, and thus made no hardware-enforced distinction between user and kernel space <<biblio-ritchie, [Ritchie, 1988]>>.
	+The first two implementations by Ken Thompson had no memory mapping, and thus
	+made no hardware-enforced distinction between user and kernel space crossref:design-44bsd[biblio-ritchie, [Ritchie, 1988]].
	A message-passing system could have been implemented as readily as the actually implemented model of kernel and user processes.
	The monolithic kernel was chosen for simplicity and performance.
	And the early kernels were small; the inclusion of facilities such as networking into the kernel has increased its size.
	@@ -169,10 +172,10 @@
	\|HP/UX compatibility \|4,683 \|2.3
	\|===

	-<<table-mach-indep>> summarizes the machine-independent software that constitutes the 4.4BSD kernel for the HP300.
	+crossref:design-44bsd[table-mach-indep] summarizes the machine-independent software that constitutes the 4.4BSD kernel for the HP300.
	The numbers in column 2 are for lines of C source code, header files, and assembly language.
	Virtually all the software in the kernel is written in the C programming language; less than 2 percent is written in assembly language.
	-As the statistics in <<table-mach-dep>> show, the machine-dependent software, excluding HP/UX and device support, accounts for a minuscule 6.9 percent of the kernel.
	+As the statistics in crossref:design-44bsd[table-mach-dep] show, the machine-dependent software, excluding HP/UX and device support, accounts for a minuscule 6.9 percent of the kernel.

	Only a small part of the kernel is devoted to initializing the system.
	This code is used when the system is _bootstrapped_ into operation and is responsible for setting up the kernel hardware and software environment (see Chapter 14).
	@@ -226,7 +229,8 @@
	.Process lifecycle
	image:fig1.png[Process lifecycle]

	-The process lifecycle is depicted in <<fig-process-lifecycle>>.
	+The process lifecycle is depicted in
	+crossref:design-44bsd[fig-process-lifecycle].
	A process may create a new process that is a copy of the original by using the _fork_ system call.
	The _fork_ call returns twice: once in the parent process, where the return value is the process identifier of the child, and once in the child process, where the return value is 0.
	The parent-child relationship induces a hierarchical structure on the set of processes in the system.
	@@ -334,8 +338,11 @@
	Ultimately, 4.2BSD was shipped without the _mmap_ interface, because of pressure to make other features, such as networking, available.

	Further development of the _mmap_ interface continued during the work on 4.3BSD.
	-Over 40 companies and research groups participated in the discussions leading to the revised architecture that was described in the Berkeley Software Architecture Manual <<biblio-mckusick-1, [McKusick et al, 1994]>>.
	-Several of the companies have implemented the revised interface <<biblio-gingell, [Gingell et al, 1987]>>.
	+Over 40 companies and research groups participated in the discussions leading to
	+the revised architecture that was described in the Berkeley Software
	+Architecture Manual crossref:design-44bsd[biblio-mckusick-1, [McKusick et al, 1994]].
	+Several of the companies have implemented the revised interface
	+crossref:design-44bsd[biblio-gingell, [Gingell et al, 1987]].

	Once again, time pressure prevented 4.3BSD from providing an implementation of the interface.
	Although the latter could have been built into the existing 4.3BSD virtual-memory system, the developers decided not to put it in because that implementation was nearly 10 years old.
	@@ -347,7 +354,8 @@
	Attempts to improve the old implementation incrementally seemed doomed to failure.
	A completely new design, on the other hand, could take advantage of large memories, conserve disk transfers, and have the potential to run on multiprocessors.
	Consequently, the virtual-memory system was completely replaced in 4.4BSD.
	-The 4.4BSD virtual-memory system is based on the Mach 2.0 VM system <<biblio-tevanian, [Tevanian, 1987]>>. with updates from Mach 2.5 and Mach 3.0.
	+The 4.4BSD virtual-memory system is based on the Mach 2.0 VM system
	+crossref:design-44bsd[biblio-tevanian, [Tevanian, 1987]]. with updates from Mach 2.5 and Mach 3.0.
	It features efficient support for sharing, a clean separation of machine-independent and machine-dependent features, as well as (currently unused) multiprocessor support.
	Processes can map files anywhere in their address space.
	They can share parts of their address space by doing a shared mapping of the same file.
	@@ -381,7 +389,9 @@
	Demands for dynamic memory allocation in the kernel have increased as more services have been added.
	A generalized memory allocator reduces the complexity of writing code inside the kernel.
	Thus, the 4.4BSD kernel has a single memory allocator that can be used by any part of the system.
	-It has an interface similar to the C library routines _malloc_ and _free_ that provide memory allocation to application programs <<biblio-mckusick-2, [McKusick & Karels, 1988]>>.
	+It has an interface similar to the C library routines _malloc_ and _free_ that
	+provide memory allocation to application programs
	+crossref:design-44bsd[biblio-mckusick-2, [McKusick & Karels, 1988]].
	Like the C library interface, the allocation routine takes a parameter specifying the size of memory that is needed.
	The range of sizes for memory requests is not constrained; however, physical memory is allocated and is not paged.
	The free routine takes a pointer to the storage being freed, but does not require the size of the piece of memory being freed.
	@@ -395,7 +405,8 @@
	Different programs expect various levels of structure, but the kernel does not impose structure on I/O.
	For instance, the convention for text files is lines of ASCII characters separated by a single newline character (the ASCII line-feed character), but the kernel knows nothing about this convention.
	For the purposes of most programs, the model is further simplified to being a stream of data bytes, or an _I/O stream_.
	-It is this single common data form that makes the characteristic UNIX tool-based approach work <<biblio-kernighan, [Kernighan & Pike, 1984]>>.
	+It is this single common data form that makes the characteristic UNIX tool-based
	+approach work crossref:design-44bsd[biblio-kernighan, [Kernighan & Pike, 1984]].
	An I/O stream from one program can be fed as input to almost any other program.
	(This kind of traditional UNIX I/O stream should not be confused with the Eighth Edition stream I/O system or with the System V, Release 3 STREAMS, both of which can be accessed as traditional I/O streams.)

	@@ -556,7 +567,7 @@
	[[fig-small-fs]]
	image:fig2.png[A small filesystem]

	-a small one is shown in <<fig-small-fs>>.
	+a small one is shown in crossref:design-44bsd[fig-small-fs].
	Directories may contain subdirectories, and there is no inherent limitation to the depth with which directory nesting may occur.
	To protect the consistency of the filesystem, the kernel does not permit processes to write directly into directories.
	A filesystem may include not only plain files and directories, but also references to other objects, such as devices and sockets.
	@@ -671,7 +682,8 @@
	Laying out the contents of files on the storage media is the responsibility of the filestore. 4.4BSD supports three different filestore layouts:

	* The traditional Berkeley Fast Filesystem
	-* The log-structured filesystem, based on the Sprite operating-system design <<biblio-rosenblum, [Rosenblum & Ousterhout, 1992]>>
	+* The log-structured filesystem, based on the Sprite operating-system design
	+ crossref:design-44bsd[biblio-rosenblum, [Rosenblum & Ousterhout, 1992]]
	* A memory-based filesystem

	Although the organizations of these filestores are completely different, these differences are indistinguishable to the processes using the filestores.
	@@ -710,7 +722,9 @@
	The complexity of remote filesystems lies in maintaining cache consistency between the server and its many clients.

	Although many remote-filesystem protocols have been developed over the years, the most pervasive one in use among UNIX systems is the Network Filesystem (NFS), whose protocol and most widely used implementation were done by Sun Microsystems.
	-The 4.4BSD kernel supports the NFS protocol, although the implementation was done independently from the protocol specification <<biblio-macklem, [Macklem, 1994]>>.
	+The 4.4BSD kernel supports the NFS protocol, although the implementation was
	+done independently from the protocol specification
	+crossref:design-44bsd[biblio-macklem, [Macklem, 1994]].
	The NFS protocol is described in Chapter 9.

	[[overview-terminal]]
	diff --git a/documentation/content/en/books/dev-model/_index.adoc b/documentation/content/en/books/dev-model/_index.adoc
	--- a/documentation/content/en/books/dev-model/_index.adoc
	+++ b/documentation/content/en/books/dev-model/_index.adoc
	@@ -80,7 +80,7 @@
	However, a project model summarising how the project is structured is needed because of the increasing amount of project members.
	footnote:[This goes hand-in-hand with Brooks' law that adding another person to a late project will make it later since it will increase the communication needs . A project model is a tool to reduce the communication needs.]
	This paper will provide such a project model and is donated to the FreeBSD Documentation project where it can evolve together with the project so that it can at any point in time reflect the way the project works.
	-It is based on [<<thesis, Saers,2003>>].
	+It is based on [crossref:dev-model[thesis, Saers,2003]].

	I would like to thank the following people for taking the time to explain things that were unclear to me and for proofreading the document.

	@@ -103,23 +103,23 @@
	[[overview]]
	== Overview
	A project model is a means to reduce the communications overhead in a project.
	-As shown by [<<brooks, Brooks, 1995>>], increasing the number of project participants increases the communication in the project exponentionally.
	+As shown by [crossref:dev-model[brooks, Brooks, 1995]], increasing the number of project participants increases the communication in the project exponentionally.
	FreeBSD has during the past few years increased both its mass of active users and committers, and the communication in the project has risen accordingly.
	This project model will serve to reduce this overhead by providing an up-to-date description of the project.

	During the Core elections in 2002, Mark Murray stated "I am opposed to a long rule-book, as that satisfies lawyer-tendencies, and is counter to the technocentricity that the project so badly needs."
	-[<<bsd-election2002, FreeBSD, 2002B>>].
	+[crossref:dev-model[bsd-election2002, FreeBSD, 2002B]].
	This project model is not meant to be a tool to justify creating impositions for developers, but as a tool to facilitate coordination.
	It is meant as a description of the project, with an overview of how the different processes are executed.
	It is an introduction to how the FreeBSD project works.

	The FreeBSD project model will be described as of July 1st, 2004.
	-It is based on the Niels Jørgensen's paper [<<jorgensen2001, Jørgensen, 2001>>], FreeBSD's official documents, discussions on FreeBSD mailing lists and interviews with developers.
	+It is based on the Niels Jørgensen's paper [crossref:dev-model[jorgensen2001, Jørgensen, 2001]], FreeBSD's official documents, discussions on FreeBSD mailing lists and interviews with developers.

	After providing definitions of terms used, this document will outline the organisational structure (including role descriptions and communication lines), discuss the methodology model and after presenting the tools used for process control, it will present the defined processes.
	Finally it will outline major sub-projects of the FreeBSD project.

	-[<<freebsd-developer-handbook, FreeBSD, 2002A>>] Section 1.2 and 1.3 give the vision and the architectural guidelines for the project.
	+[crossref:dev-model[freebsd-developer-handbook, FreeBSD, 2002A]] Section 1.2 and 1.3 give the vision and the architectural guidelines for the project.
	The vision is "To produce the best UNIX-like operating system package possible, with due respect to the original software tools ideology as well as usability, performance and stability."
	The architectural guidelines help determine whether a problem that someone wants to be solved is within the scope of the project

	@@ -129,7 +129,8 @@
	[[ref-activity]]
	=== Activity

	-An "activity" is an element of work performed during the course of a project [<<ref-pmbok, PMI, 2000>>].
	+An "activity" is an element of work performed during the course of a project
	+[crossref:dev-model[ref-pmbok, PMI, 2000]].
	It has an output and leads towards an outcome.
	Such an output can either be an input to another activity or a part of the process' delivery.

	@@ -153,7 +154,9 @@

	An "outcome" is the final output of the process.
	This is synonymous with deliverable, that is defined as "any measurable, tangible, verifiable outcome, result or item that must be produced to complete a project or part of a project.
	-Often used more narrowly in reference to an external deliverable, which is a deliverable that is subject to approval by the project sponsor or customer" by [<<ref-pmbok, PMI, 2000>>].
	+Often used more narrowly in reference to an external deliverable, which is a
	+deliverable that is subject to approval by the project sponsor or customer" by
	+[crossref:dev-model[ref-pmbok, PMI, 2000]].
	Examples of outcomes are a piece of software, a decision made or a report written.

	[[ref-freebsd]]
	@@ -249,9 +252,9 @@

	The core utilities, known as userland, provide the interface that identifies FreeBSD, both user interface, shared libraries and external interfaces to connecting clients.
	Currently, 162 people are involved in userland development and maintenance, many being maintainers for their own part of the code.
	-Maintainership will be discussed in the <<role-maintainer>> section.
	+Maintainership will be discussed in the crossref:dev-model[role-maintainer] section.

	-Documentation is handled by <<sub-project-documentation>> and includes all documents surrounding the FreeBSD project, including the web pages.
	+Documentation is handled by crossref:dev-model[sub-project-documentation] and includes all documents surrounding the FreeBSD project, including the web pages.
	There were during 2004 101 people making commits to the FreeBSD Documentation Project.

	Ports is the collection of meta-data that is needed to make software packages build correctly on FreeBSD.
	@@ -260,7 +263,7 @@
	This allows automated tools to fetch, build and install the package.
	As of this writing, there are more than 12600 ports available.
	footnote:[Statistics are generated by counting the number of entries in the file fetched by portsdb by April 1st, 2005. portsdb is a part of the port sysutils/portupgrade.] , ranging from web servers to games, programming languages and most of the application types that are in use on modern computers.
	-Ports will be discussed further in the section <<sub-project-ports>>.
	+Ports will be discussed further in the section crossref:dev-model[sub-project-ports].

	[[methodology-model]]
	== Methodology model
	@@ -305,7 +308,8 @@
	\|code
	\|===

	-The "development release" is the FreeBSD-CURRENT ("-CURRENT") branch and the "production release" is the FreeBSD-STABLE branch ("-STABLE") [<<jorgensen2001, Jørgensen, 2001>>].
	+The "development release" is the FreeBSD-CURRENT ("-CURRENT") branch and the
	+"production release" is the FreeBSD-STABLE branch ("-STABLE") [crossref:dev-model[jorgensen2001, Jørgensen, 2001]].

	This is a model for one change, and shows that after coding, developers seek community review and try integrating it with their own systems.
	After integrating the change into the development release, called FreeBSD-CURRENT, it is tested by many users and developers in the FreeBSD community.
	@@ -397,7 +401,7 @@
	\|===

	The latest -CURRENT version is always referred to as -CURRENT, while the latest -STABLE release is always referred to as -STABLE.
	-In this figure, -STABLE refers to 4-STABLE while -CURRENT refers to 5.0-CURRENT following 5.0-RELEASE. [<<freebsd-releng, FreeBSD, 2002E>>]
	+In this figure, -STABLE refers to 4-STABLE while -CURRENT refers to 5.0-CURRENT following 5.0-RELEASE. [crossref:dev-model[freebsd-releng, FreeBSD, 2002E]]

	A "major release" is always made from the -CURRENT branch.
	However, the -CURRENT branch does not need to fork at that point in time, but can focus on stabilising.
	@@ -455,14 +459,16 @@
	[[role-contributor]]
	==== Contributor

	-A Contributor contributes to the FreeBSD project either as a developer, as an author, by sending problem reports, or in other ways contributing to the progress of the project. A contributor has no special privileges in the FreeBSD project. [<<freebsd-contributors, FreeBSD, 2002F>>]
	+A Contributor contributes to the FreeBSD project either as a developer, as an
	+author, by sending problem reports, or in other ways contributing to the
	+progress of the project. A contributor has no special privileges in the FreeBSD project. [crossref:dev-model[freebsd-contributors, FreeBSD, 2002F]]

	[[role-committer]]
	==== Committer

	A person who has the required privileges to add their code or documentation to the repository.
	A committer has made a commit within the past 12 months.
	-[<<freebsd-developer-handbook, FreeBSD, 2000A>>] An active committer is a committer who has made an average of one commit per month during that time.
	+[crossref:dev-model[freebsd-developer-handbook, FreeBSD, 2000A]] An active committer is a committer who has made an average of one commit per month during that time.

	It is worth noting that there are no technical barriers to prevent someone, once having gained commit privileges to the main- or a sub-project, to make commits in parts of that project's source the committer did not specifically get permission to modify.
	However, when wanting to make modifications to parts a committer has not been involved in before, they should read the logs to see what has happened in this area before, and also read the MAINTAINERS file to see if the maintainer of this part has any special requests on how changes in the code should be made.
	@@ -499,7 +505,7 @@
	[[role-doc-manager]]
	==== Documentation project manager

	-<<sub-project-documentation>> architect is responsible for defining and following up documentation goals for the committers in the Documentation project, which they supervise.
	+crossref:dev-model[sub-project-documentation] architect is responsible for defining and following up documentation goals for the committers in the Documentation project, which they supervise.

	Hat held by: The DocEng team mailto:doceng@FreeBSD.org[doceng@FreeBSD.org].
	The https://www.freebsd.org/internal/doceng/[ DocEng Charter].
	@@ -523,7 +529,8 @@
	* Coordinating with the Ports and Documentation teams to have an updated set of packages and documentation released with the new releases
	* Coordinating with the Security team so that pending releases are not affected by recently disclosed vulnerabilities.

	-Further information about the development process is available in the <<process-release-engineering>> section.
	+Further information about the development process is available in the
	+crossref:dev-model[process-release-engineering] section.

	[[role-releng]]
	Hat held by: the Release Engineering team mailto:re@FreeBSD.org[re@FreeBSD.org].
	@@ -547,13 +554,17 @@
	The Security Officer's main responsibility is to coordinate information exchange with others in the security community and in the FreeBSD project.
	The Security Officer is also responsible for taking action when security problems are reported and promoting proactive development behavior when it comes to security.

	-Because of the fear that information about vulnerabilities may leak out to people with malicious intent before a patch is available, only the Security Officer, consisting of an officer, a deputy and two <<role-core>> members, receive sensitive information about security issues.
	+Because of the fear that information about vulnerabilities may leak out to
	+people with malicious intent before a patch is available, only the Security
	+Officer, consisting of an officer, a deputy and two
	+crossref:dev-model[role-core] members, receive sensitive information about security issues.
	However, to create or implement a patch, the Security Officer has the Security Officer Team mailto:security-team@FreeBSD.org[security-team@FreeBSD.org] to help do the work.

	[[role-repo-manager]]
	==== Source Repository Manager

	-The Source Repository Manager is the only one who is allowed to directly modify the repository without using the <<tool-git>> tool.
	+The Source Repository Manager is the only one who is allowed to directly modify
	+the repository without using the crossref:dev-model[tool-git] tool.
	It is their responsibility to ensure that technical problems that arise in the repository are resolved quickly.
	The source repository manager has the authority to back out commits if this is necessary to resolve a Git technical problem.

	@@ -562,9 +573,11 @@
	[[role-election-manager]]
	==== Election Manager

	-The Election Manager is responsible for the <<process-core-election>> process.
	+The Election Manager is responsible for the
	+crossref:dev-model[process-core-election] process.
	The manager is responsible for running and maintaining the election system, and is the final authority should minor unforeseen events happen in the election process.
	-Major unforeseen events have to be discussed with the <<role-core>>
	+Major unforeseen events have to be discussed with the
	+crossref:dev-model[role-core]

	Hat held only during elections.

	@@ -572,14 +585,15 @@
	==== Web site Management

	The Web site Management hat is responsible for coordinating the rollout of updated web pages on mirrors around the world, for the overall structure of the primary web site and the system it is running upon.
	-The management needs to coordinate the content with <<sub-project-documentation>> and acts as maintainer for the "www" tree.
	+The management needs to coordinate the content with
	+crossref:dev-model[sub-project-documentation] and acts as maintainer for the "www" tree.

	Hat held by: the FreeBSD Webmasters mailto:www@FreeBSD.org[www@FreeBSD.org].

	[[role-ports-manager]]
	==== Ports Manager

	-The Ports Manager acts as a liaison between <<sub-project-ports>> and the core project, and all requests from the project should go to the ports manager.
	+The Ports Manager acts as a liaison between crossref:dev-model[sub-project-ports] and the core project, and all requests from the project should go to the ports manager.

	Hat held by: the Ports Management Team mailto:portmgr@FreeBSD.org[portmgr@FreeBSD.org].
	The https://www.freebsd.org/portmgr/charter/[Portmgr charter].
	@@ -675,8 +689,12 @@
	When a contributor is given committer status, they are assigned a mentor.
	The committer who recommended the new committer will, in the general case, take it upon themselves to be the new committers mentor.

	-When a contributor is given their commit bit, a <<tool-pgp>>-signed email is sent from either <<role-core-secretary>>, <<role-ports-manager>>, or nik@freebsd.org to both admins@freebsd.org, the assigned mentor, the new committer, and core confirming the approval of a new account.
	-The mentor then gathers a password line, <<tool-ssh2>> public key, and PGP key from the new committer and sends them to <<role-admin>>.
	+When a contributor is given their commit bit, a
	+crossref:dev-model[tool-pgp]-signed email is sent from either
	+crossref:dev-model[role-core-secretary], crossref:dev-model[role-ports-manager], or nik@freebsd.org to both admins@freebsd.org, the assigned mentor, the new committer, and core confirming the approval of a new account.
	+The mentor then gathers a password line, crossref:dev-model[tool-ssh2] public
	+key, and PGP key from the new committer and sends them to
	+crossref:dev-model[role-admin].
	When the new account is created, the mentor activates the commit bit and guides the new committer through the rest of the initial process.

	.Process summary: adding a new committer
	@@ -690,9 +708,10 @@

	Recall that a committer is considered to be someone who has committed code during the past 12 months.
	However, it is not until after 18 months of inactivity have passed that commit privileges are eligible to be revoked.
	-[<<freebsd-expiration-policy, FreeBSD, 2002H>>]
	+[crossref:dev-model[freebsd-expiration-policy, FreeBSD, 2002H]]
	There are, however, no automatic procedures for doing this.
	-For reactions concerning commit privileges not triggered by time, see <<process-reactions,section 1.5.8>>.
	+For reactions concerning commit privileges not triggered by time, see
	+crossref:dev-model[process-reactions,section 1.5.8].

	.Process summary: removing a committer
	image::proc-rm-committer.png[Refer to paragraph below for a screen-reader friendly version.]
	@@ -705,20 +724,23 @@

	Roles in this process:

	-. <<role-core>>
	-. <<role-contributor>>
	-. <<role-committer>>
	-. <<role-maintainer>>
	-. <<role-mentor>>
	+. crossref:dev-model[role-core]
	+. crossref:dev-model[role-contributor]
	+. crossref:dev-model[role-committer]
	+. crossref:dev-model[role-maintainer]
	+. crossref:dev-model[role-mentor]

	-[<<freebsd-bylaws, FreeBSD, 2000A>>] [<<freebsd-expiration-policy, FreeBSD, 2002H>>] [<<freebsd-new-account, FreeBSD, 2002I>>]
	+[crossref:dev-model[freebsd-bylaws, FreeBSD, 2000A]]
	+[crossref:dev-model[freebsd-expiration-policy, FreeBSD, 2002H]]
	+[crossref:dev-model[freebsd-new-account, FreeBSD, 2002I]]

	[[committing]]
	=== Committing code

	The committing of new or modified code is one of the most frequent processes in the FreeBSD project and will usually happen many times a day.
	Committing of code can only be done by a "committer".
	-Committers commit either code written by themselves, code submitted to them, or code submitted through a <<model-pr,problem report>>.
	+Committers commit either code written by themselves, code submitted to them, or
	+code submitted through a crossref:dev-model[model-pr,problem report].

	When code is written by the developer that is non-trivial, they should seek a code review from the community.
	This is done by sending mail to the relevant list asking for review.
	@@ -726,7 +748,8 @@
	This is called "pre-commit test".
	When contributed code is received, it should be reviewed by the committer and tested the same way.

	-When a change is committed to a part of the source that has been contributed from an outside <<role-vendor>>, the maintainer should ensure that the patch is contributed back to the vendor.
	+When a change is committed to a part of the source that has been contributed
	+from an outside crossref:dev-model[role-vendor], the maintainer should ensure that the patch is contributed back to the vendor.
	This is in line with the open source philosophy and makes it easier to stay in sync with outside projects as the patches do not have to be reapplied every time a new release is made.

	After the code has been available for review and no further changes are necessary, the code is committed into the development branch, -CURRENT.
	@@ -755,12 +778,13 @@

	Hats included in this process are:

	-. <<role-committer>>
	-. <<role-contributor>>
	-. <<role-vendor>>
	-. <<role-reviewer>>
	+. crossref:dev-model[role-committer]
	+. crossref:dev-model[role-contributor]
	+. crossref:dev-model[role-vendor]
	+. crossref:dev-model[role-reviewer]

	-[<<freebsd-committer, FreeBSD, 2001>>] [<<jorgensen2001, Jørgensen, 2001>>]
	+[crossref:dev-model[freebsd-committer, FreeBSD, 2001]]
	+[crossref:dev-model[jorgensen2001, Jørgensen, 2001]]

	[[process-core-election]]
	=== Core election
	@@ -797,17 +821,20 @@

	Hats in core elections are:

	-* <<role-core>>
	-* <<role-committer>>
	-* <<role-election-manager>>
	+* crossref:dev-model[role-core]
	+* crossref:dev-model[role-committer]
	+* crossref:dev-model[role-election-manager]

	-[<<freebsd-bylaws, FreeBSD, 2000A>>] [<<bsd-election2002, FreeBSD, 2002B>>] [<<freebsd-election, FreeBSD, 2002G>>]
	+[crossref:dev-model[freebsd-bylaws, FreeBSD, 2000A]]
	+[crossref:dev-model[bsd-election2002, FreeBSD, 2002B]]
	+[crossref:dev-model[freebsd-election, FreeBSD, 2002G]]

	[[new-features]]
	=== Development of new features

	Within the project there are sub-projects that are working on new features.
	-These projects are generally done by one person [<<jorgensen2001, Jørgensen, 2001>>].
	+These projects are generally done by one person
	+[crossref:dev-model[jorgensen2001, Jørgensen, 2001]].
	Every project is free to organise development as it sees fit.
	However, when the project is merged to the -CURRENT branch it must follow the project guidelines.
	When the code has been well tested in the -CURRENT branch and deemed stable enough and relevant to the -STABLE branch, it is merged to the -STABLE branch.
	@@ -816,7 +843,8 @@
	The wishes that come within the responsibility of a developer are given to that developer who prioritises their time between the request and their wishes.
	A common way to do this is maintain a TODO-list maintained by the project.
	Items that do not come within someone's responsibility are collected on TODO-lists unless someone volunteers to take the responsibility.
	-All requests, their distribution and follow-up are handled by the <<tool-bugzilla>> tool.
	+All requests, their distribution and follow-up are handled by the
	+crossref:dev-model[tool-bugzilla] tool.

	Requirements analysis happens in two ways.
	The requests that come in are discussed on mailing lists, both within the main project and in the sub-project that the request belongs to or is spawned by the request.
	@@ -843,7 +871,7 @@
	The maintainer's job is to make sure the code is in sync with the project the code comes from if it is contributed code, and apply patches submitted by the community or write fixes to issues that are discovered.

	The main bulk of work that is put into the FreeBSD project is maintenance.
	-[<<jorgensen2001, Jørgensen, 2001>>] has made a figure showing the life cycle of changes.
	+[crossref:dev-model[jorgensen2001, Jørgensen, 2001]] has made a figure showing the life cycle of changes.

	Jørgenssen's model for change integration

	@@ -900,13 +928,14 @@
	Although `send-pr` is available, users and developers are encouraged to submit issues using our https://bugs.freebsd.org/submit/[ problem report form].

	Problem reports are sent to an email address where it is inserted into the Problem Reports maintenance database.
	-A <<role-bugbuster>> classifies the problem and sends it to the correct group or maintainer within the project.
	+A crossref:dev-model[role-bugbuster] classifies the problem and sends it to the correct group or maintainer within the project.
	After someone has taken responsibility for the report, the report is being analysed.
	This analysis includes verifying the problem and thinking out a solution for the problem.
	Often feedback is required from the report originator or even from the FreeBSD community.
	Once a patch for the problem is made, the originator may be asked to try it out.
	Finally, the working patch is integrated into the project, and documented if applicable.
	-It there goes through the regular maintenance cycle as described in section <<model-maintenance>>.
	+It there goes through the regular maintenance cycle as described in section
	+crossref:dev-model[model-maintenance].
	These are the states a problem report can be in: open, analyzed, feedback, patched, suspended and closed.
	The suspended state is for when further progress is not possible due to the lack of information or for when the task would require so much work that nobody is working on it at the moment.

	@@ -920,16 +949,17 @@

	The roles included in this process are:

	-. <<role-problem-originator>>
	-. <<role-maintainer>>
	-. <<role-bugbuster>>
	+. crossref:dev-model[role-problem-originator]
	+. crossref:dev-model[role-maintainer]
	+. crossref:dev-model[role-bugbuster]

	-[<<freebsd-handle-pr, FreeBSD, 2002C>>]. [<<freebsd-send-pr, FreeBSD, 2002D>>]
	+[crossref:dev-model[freebsd-handle-pr, FreeBSD, 2002C]].
	+[crossref:dev-model[freebsd-send-pr, FreeBSD, 2002D]]

	[[process-reactions]]
	=== Reacting to misbehavior

	-[<<freebsd-committer, FreeBSD, 2001>>] has a number of rules that committers should follow.
	+[crossref:dev-model[freebsd-committer, FreeBSD, 2001]] has a number of rules that committers should follow.
	However, it happens that these rules are broken.
	The following rules exist in order to be able to react to misbehavior.
	They specify what actions will result in how long a suspension of the committer's commit privileges.
	@@ -939,7 +969,7 @@
	* Commit wars - 5 days to all participating parties
	* Impolite or inappropriate behavior - 5 days

	-[<<ref-freebsd-trenches, Lehey, 2002>>]
	+[crossref:dev-model[ref-freebsd-trenches, Lehey, 2002]]

	For the suspensions to be efficient, any single core member can implement a suspension before discussing it on the "core" mailing list.
	Repeat offenders can, with a 2/3 vote by core, receive harsher penalties, including permanent removal of commit privileges.
	@@ -951,8 +981,8 @@

	Hats involved in this process:

	-* <<role-core>>
	-* <<role-committer>>
	+* crossref:dev-model[role-core]
	+* crossref:dev-model[role-committer]

	[[process-release-engineering]]
	=== Release engineering
	@@ -982,7 +1012,8 @@
	Updates are less likely to be allowed during this period, except for important bug fixes and security updates.
	In this final period, all releases are considered release candidates.
	At the end of the release process, a release is created with the new version number, including binary distributions on web sites and the creation of CD-ROM images.
	-However, the release is not considered "really released" until a <<tool-pgp>>-signed message stating exactly that, is sent to the mailing list freebsd-announce; anything labelled as a "release" before that may well be in-process and subject to change before the PGP-signed message is sent. footnote:[Many commercial vendors use these images to create CD-ROMs that are sold in retail outlets.].
	+However, the release is not considered "really released" until a
	+crossref:dev-model[tool-pgp]-signed message stating exactly that, is sent to the mailing list freebsd-announce; anything labelled as a "release" before that may well be in-process and subject to change before the PGP-signed message is sent. footnote:[Many commercial vendors use these images to create CD-ROMs that are sold in retail outlets.].

	The releases of the -CURRENT-branch (that is, all releases that end with ".0") are very similar, but with twice as long timeframe.
	It starts 8 weeks prior to the release with announcement of the release time line.
	@@ -993,7 +1024,9 @@
	However, development on the main development branch can continue.
	Other than these differences, the release engineering processes are alike.

	-.0 releases go into their own branch and are aimed mainly at early adopters. The branch then goes through a period of stabilisation, and it is not until the <<role-releng, Release Engineering Team>> decides the demands to stability have been satisfied that the branch becomes -STABLE and -CURRENT targets the next major version. While this for the majority has been with .1 versions, this is not a demand.
	+*.0 releases go into their own branch and are aimed mainly at early adopters.
	+The branch then goes through a period of stabilisation, and it is not until the
	+crossref:dev-model[role-releng, Release Engineering Team] decides the demands to stability have been satisfied that the branch becomes -STABLE and -CURRENT targets the next major version. While this for the majority has been with *.1 versions, this is not a demand.

	Most releases are made when a given date that has been deemed a long enough time since the previous release comes.
	A target is set for having major releases every 18 months and minor releases every 4 months.
	@@ -1010,7 +1043,9 @@
	. Warn mirrors
	. Publish release

	-[<<freebsd-releng, FreeBSD, 2002E>>]
	+// Keep the spaces around the external square bracket to avoid a warning in the
	+// PDF converter
	+[ crossref:dev-model[freebsd-releng, FreeBSD, 2002E] ]

	[[tools]]
	== Tools
	@@ -1039,7 +1074,8 @@
	The FreeBSD Project uses it to run 16 general lists, 60 technical lists, 4 limited lists and 5 lists with Git commit logs.
	It is also used for many mailing lists set up and used by other people and projects in the FreeBSD community.
	General lists are lists for the general public, technical lists are mainly for the development of specific areas of interest, and closed lists are for internal communication not intended for the general public.
	-The majority of all the communication in the project goes through these 85 lists [<<ref-bsd-handbook, FreeBSD, 2003A>>, Appendix C].
	+The majority of all the communication in the project goes through these 85 lists
	+[crossref:dev-model[ref-bsd-handbook, FreeBSD, 2003A], Appendix C].

	[[tool-pgp]]
	=== Pretty Good Privacy
	@@ -1071,13 +1107,13 @@
	.Number of ports added between 1995 and 2022 [[fig-ports]]
	image::portsstatus.svg

	-<<fig-ports>> shows the number of ports available to FreeBSD in the period 1995 to 2022.
	+crossref:dev-model[fig-ports] shows the number of ports available to FreeBSD in the period 1995 to 2022.
	It looks like the curve has first grown exponentially, and then from the middle of 2001 to the middle of 2007 grown linearly at a rate of about 2000 ports/year, before its growth rate gets lower.

	As the external software described by the port often is under continued development, the amount of work required to maintain the ports is already large, and increasing.
	This has led to the ports part of the FreeBSD project gaining a more empowered structure, and is more and more becoming a sub-project of the FreeBSD project.

	-Ports has its own core team with the <<role-ports-manager>> as its leader, and this team can appoint committers without FreeBSD Core's approval.
	+Ports has its own core team with the crossref:dev-model[role-ports-manager] as its leader, and this team can appoint committers without FreeBSD Core's approval.
	Unlike in the FreeBSD Project, where a lot of maintenance frequently is rewarded with a commit bit, the ports sub-project contains many active maintainers that are not committers.

	Unlike the main project, the ports tree is not branched.
	@@ -1104,7 +1140,9 @@
	This is done so that there is always an updated version of the documentation for each version.
	Only documentation errors are corrected in the security branches.

	-Like the ports sub-project, the Documentation project can appoint documentation committers without FreeBSD Core's approval. [<<freebsd-doceng-charter, FreeBSD, 2003B>>].
	+Like the ports sub-project, the Documentation project can appoint documentation
	+committers without FreeBSD Core's approval.
	+[crossref:dev-model[freebsd-doceng-charter, FreeBSD, 2003B]].

	The Documentation project has extref:{fdp-primer}[a primer].
	This is used both to introduce new project members to the standard tools and syntaxes and to act as a reference when working on the project.
	diff --git a/documentation/content/en/books/developers-handbook/ipv6/_index.adoc b/documentation/content/en/books/developers-handbook/ipv6/_index.adoc
	--- a/documentation/content/en/books/developers-handbook/ipv6/_index.adoc
	+++ b/documentation/content/en/books/developers-handbook/ipv6/_index.adoc
	@@ -78,7 +78,8 @@

	** IPv4 compatible address is not supported.
	** automatic tunneling (described in 4.3 of this RFC) is not supported.
	-** man:gif[4] interface implements IPv[46]-over-IPv[46] tunnel in a generic way, and it covers "configured tunnel" described in the spec. See <<gif,23.5.1.5>> in this document for details.
	+** man:gif[4] interface implements IPv[46]-over-IPv[46] tunnel in a generic way,
	+ and it covers "configured tunnel" described in the spec. See crossref:ipv6[gif,23.5.1.5] in this document for details.

	* RFC1981: Path MTU Discovery for IPv6
	* RFC2080: RIPng for IPv6
	@@ -112,15 +113,15 @@
	* RFC2460: IPv6 specification
	* RFC2461: Neighbor discovery for IPv6

	-** See <<neighbor-discovery,23.5.1.2>> in this document for details.
	+** See crossref:ipv6[neighbor-discovery,23.5.1.2] in this document for details.

	* RFC2462: IPv6 Stateless Address Autoconfiguration

	-** See <<ipv6-pnp,23.5.1.4>> in this document for details.
	+** See crossref:ipv6[ipv6-pnp,23.5.1.4] in this document for details.

	* RFC2463: ICMPv6 for IPv6 specification

	-** See <<icmpv6,23.5.1.9>> in this document for details.
	+** See crossref:ipv6[icmpv6,23.5.1.9] in this document for details.

	* RFC2464: Transmission of IPv6 Packets over Ethernet Networks
	* RFC2465: MIB for IPv6: Textual Conventions and General Group
	@@ -135,11 +136,12 @@
	* RFC2497: Transmission of IPv6 packet over ARCnet Networks
	* RFC2553: Basic Socket Interface Extensions for IPv6

	-** IPv4 mapped address (3.7) and special behavior of IPv6 wildcard bind socket (3.8) are supported. See <<ipv6-wildcard-socket,23.5.1.12>> in this document for details.
	+** IPv4 mapped address (3.7) and special behavior of IPv6 wildcard bind socket
	+ (3.8) are supported. See crossref:ipv6[ipv6-wildcard-socket,23.5.1.12] in this document for details.

	* RFC2675: IPv6 Jumbograms

	-** See <<ipv6-jumbo,23.5.1.7>> in this document for details.
	+** See crossref:ipv6[ipv6-jumbo,23.5.1.7] in this document for details.

	* RFC2710: Multicast Listener Discovery for IPv6
	* RFC2711: IPv6 router alert option
	@@ -153,7 +155,7 @@
	* [.filename]#draft-itojun-ipv6-tcp-to-anycast-00#: Disconnecting TCP connection toward IPv6 anycast address
	* [.filename]#draft-yamamoto-wideipv6-comm-model-00#

	-** See <<ipv6-sas,23.5.1.6>> in this document for details.
	+** See crossref:ipv6[ipv6-sas,23.5.1.6] in this document for details.

	* [.filename]#draft-ietf-ipngwg-scopedaddr-format-00.txt#: An Extension of Format for IPv6 Scoped Addresses

	@@ -312,7 +314,7 @@
	This is to protect hosts from malicious (or misconfigured) routers that advertise very short prefix lifetime.
	There was an update from Jim Bound to ipngwg mailing list (look for "(ipng 6712)" in the archive) and it is implemented Jim's update.

	-See <<neighbor-discovery,23.5.1.2>> in the document for relationship between DAD and autoconfiguration.
	+See crossref:ipv6[neighbor-discovery,23.5.1.2] in the document for relationship between DAD and autoconfiguration.

	[[gif]]
	==== Generic Tunnel Interface
	@@ -331,7 +333,7 @@
	_Please be warned_.

	gif can be configured to be ECN-friendly.
	-See <<ipsec-ecn,23.5.4.5>> for ECN-friendliness of tunnels, and man:gif[4] for how to configure.
	+See crossref:ipv6[ipsec-ecn,23.5.4.5] for ECN-friendliness of tunnels, and man:gif[4] for how to configure.

	If you would like to configure an IPv4-in-IPv6 tunnel with gif interface, read man:gif[4] carefully.
	You will need to remove IPv6 link-local address automatically assigned to the gif interface.
	@@ -350,7 +352,8 @@
	. If there is no address that satisfies the above condition, and destination address is site local scope, choose a site local address assigned to one of the interfaces on the sending node.
	. If there is no address that satisfies the above condition, choose the address associated with the routing table entry for the destination. This is the last resort, which may cause scope violation.

	-For instance, ::1 is selected for ff01::1, fe80:1::200:f8ff:fe01:6317 for fe80:1::2a0:24ff:feab:839b (note that embedded interface index - described in <<ipv6-scope-index,23.5.1.3>> - helps us choose the right source address.
	+For instance, ::1 is selected for ff01::1, fe80:1::200:f8ff:fe01:6317 for
	+fe80:1::2a0:24ff:feab:839b (note that embedded interface index - described in crossref:ipv6[ipv6-scope-index,23.5.1.3] - helps us choose the right source address.
	Those embedded indices will not be on the wire).
	If the outgoing interface has multiple address for the scope, a source is selected longest match basis (rule 3).
	Suppose 2001:0DB8:808:1:200:f8ff:fe01:6317 and 2001:0DB8:9:124:200:f8ff:fe01:6317 are given to the outgoing interface. 2001:0DB8:808:1:200:f8ff:fe01:6317 is chosen as the source for the destination 2001:0DB8:800::1.
	diff --git a/documentation/content/en/books/developers-handbook/tools/_index.adoc b/documentation/content/en/books/developers-handbook/tools/_index.adoc
	--- a/documentation/content/en/books/developers-handbook/tools/_index.adoc
	+++ b/documentation/content/en/books/developers-handbook/tools/_index.adoc
	@@ -67,7 +67,7 @@
	FreeBSD offers an excellent development environment.
	Compilers for C and C++ and an assembler come with the basic system, not to mention classic UNIX(R) tools such as `sed` and `awk`.
	If that is not enough, there are many more compilers and interpreters in the Ports collection.
	-The following section, <<tools-programming,Introduction to Programming>>, lists some of the available options.
	+The following section, crossref:tools[tools-programming,Introduction to Programming], lists some of the available options.
	FreeBSD is very compatible with standards such as POSIX(R) and ANSI C, as well with its own BSD heritage, so it is possible to write applications that will compile and run with little or no modification on a wide range of platforms.

	However, all this power can be rather overwhelming at first if you have never written programs on a UNIX(R) platform before.
	@@ -185,7 +185,7 @@

	As the edit-compile-run-debug cycle is rather tedious when using separate programs, many commercial compiler makers have produced Integrated Development Environments (IDEs for short).
	FreeBSD does not include an IDE in the base system, but package:devel/kdevelop[] is available in the Ports Collection and many use Emacs for this purpose.
	-Using Emacs as an IDE is discussed in <<emacs>>.
	+Using Emacs as an IDE is discussed in crossref:tools[emacs].

	[[tools-compiling]]
	== Compiling with `cc`
	@@ -372,7 +372,7 @@

	==== Fascinating stuff, but what I am supposed to do now?

	-Use a debugger to analyze the core (see <<debugging>>).
	+Use a debugger to analyze the core (see crossref:tools[debugging]).

	==== When my program dumped core, it said something about a segmentation fault. What is that?

	diff --git a/documentation/content/en/books/developers-handbook/x86/_index.adoc b/documentation/content/en/books/developers-handbook/x86/_index.adoc
	--- a/documentation/content/en/books/developers-handbook/x86/_index.adoc
	+++ b/documentation/content/en/books/developers-handbook/x86/_index.adoc
	@@ -1064,7 +1064,7 @@
	[NOTE]
	====
	This approach to buffered input/output still contains a hidden danger.
	-I will discuss-and fix-it later, when I talk about the <<x86-buffered-dark-side,dark side of buffering>>.
	+I will discuss-and fix-it later, when I talk about the crossref:x86[x86-buffered-dark-side,dark side of buffering].
	====

	[[x86-ungetc]]
	@@ -1073,7 +1073,7 @@
	[WARNING]
	====
	This may be a somewhat advanced topic, mostly of interest to programmers familiar with the theory of compilers.
	-If you wish, you may <<x86-command-line,skip to the next section>>, and perhaps read this later.
	+If you wish, you may crossref:x86[x86-command-line,skip to the next section], and perhaps read this later.
	====

	While our sample program does not require it, more sophisticated filters often need to look ahead.
	diff --git a/documentation/content/en/books/fdp-primer/editor-config/_index.adoc b/documentation/content/en/books/fdp-primer/editor-config/_index.adoc
	--- a/documentation/content/en/books/fdp-primer/editor-config/_index.adoc
	+++ b/documentation/content/en/books/fdp-primer/editor-config/_index.adoc
	@@ -52,7 +52,7 @@
	[[editor-config-vim]]
	== Vim

	-Install from package:editors/vim[], then follow the configuration instructions in <<editor-config-vim-config>>.
	+Install from package:editors/vim[], then follow the configuration instructions in crossref:editor-config[editor-config-vim-config].
	More advanced users can use a proper linter like link:https://github.com/dense-analysis/ale[Ale] which can also act as a Vim link:https://langserver.org/[Language Server Protocol] client.

	[[editor-config-vim-use]]
	diff --git a/documentation/content/en/books/handbook/advanced-networking/_index.adoc b/documentation/content/en/books/handbook/advanced-networking/_index.adoc
	--- a/documentation/content/en/books/handbook/advanced-networking/_index.adoc
	+++ b/documentation/content/en/books/handbook/advanced-networking/_index.adoc
	@@ -154,7 +154,7 @@
	The final line (destination subnet `224`) deals with multicasting.

	Various attributes of each route can be seen in the `Flags` column.
	-<<routeflags>> summarizes some of these flags and their meanings:
	+crossref:advanced-networking[routeflags] summarizes some of these flags and their meanings:

	[[routeflags]]
	.Commonly Seen Routing Table Flags
	@@ -656,7 +656,7 @@
	==== Basic Settings

	Before configuring a FreeBSD machine as an AP, the kernel must be configured with the appropriate networking support for the wireless card as well as the security protocols being used.
	-For more details, see <<network-wireless-basic>>.
	+For more details, see crossref:advanced-networking[network-wireless-basic].

	[NOTE]
	====
	@@ -756,7 +756,8 @@
	==== WPA2 Host-based Access Point

	This section focuses on setting up a FreeBSD access point using the WPA2 security protocol.
	-More details regarding WPA and the configuration of WPA-based wireless clients can be found in <<network-wireless-wpa>>.
	+More details regarding WPA and the configuration of WPA-based wireless clients
	+can be found in crossref:advanced-networking[network-wireless-wpa].

	The man:hostapd[8] daemon is used to deal with client authentication and key management on the WPA2-enabled AP.

	@@ -768,7 +769,8 @@
	hostapd_enable="YES"
	....

	-Before trying to configure man:hostapd[8], first configure the basic settings introduced in <<network-wireless-ap-basic>>.
	+Before trying to configure man:hostapd[8], first configure the basic settings
	+introduced in crossref:advanced-networking[network-wireless-ap-basic].

	===== WPA2-PSK

	@@ -824,7 +826,7 @@
	....

	Once the AP is running, the clients can associate with it.
	-See <<network-wireless-wpa>> for more details.
	+See crossref:advanced-networking[network-wireless-wpa] for more details.
	It is possible to see the stations associated with the AP using `ifconfig _wlan0_ list sta`.

	[[network-usb-tethering]]
	diff --git a/documentation/content/en/books/handbook/audit/_index.adoc b/documentation/content/en/books/handbook/audit/_index.adoc
	--- a/documentation/content/en/books/handbook/audit/_index.adoc
	+++ b/documentation/content/en/books/handbook/audit/_index.adoc
	@@ -126,7 +126,7 @@
	Expressions contain a list of event classes to match.
	Selection expressions are evaluated from left to right, and two expressions are combined by appending one onto the other.

	-<<event-selection>> summarizes the default audit event classes:
	+crossref:audit[event-selection] summarizes the default audit event classes:

	[[event-selection]]
	.Default Audit Event Classes
	@@ -220,7 +220,7 @@
	These audit event classes may be customized by modifying the [.filename]#audit_class# and [.filename]#audit_event# configuration files.

	Each audit event class may be combined with a prefix indicating whether successful/failed operations are matched, and whether the entry is adding or removing matching for the class and type.
	-<<event-prefixes>> summarizes the available prefixes:
	+crossref:audit[event-prefixes] summarizes the available prefixes:

	[[event-prefixes]]
	.Prefixes for Audit Event Classes
	@@ -435,7 +435,9 @@

	The change will take effect once [.filename]#/etc/crontab# is saved.

	-Automatic rotation of the audit trail file based on file size is possible using `filesz` in [.filename]#audit_control# as described in <<audit-auditcontrol>>.
	+Automatic rotation of the audit trail file based on file size is possible using
	+`filesz` in [.filename]#audit_control# as described in
	+crossref:audit[audit-auditcontrol].

	As audit trail files can become very large, it is often desirable to compress or otherwise archive trails once they have been closed by the audit daemon.
	The [.filename]#audit_warn# script can be used to perform customized operations for a variety of audit-related events, including the clean termination of audit trails when they are rotated.
	diff --git a/documentation/content/en/books/handbook/basics/_index.adoc b/documentation/content/en/books/handbook/basics/_index.adoc
	--- a/documentation/content/en/books/handbook/basics/_index.adoc
	+++ b/documentation/content/en/books/handbook/basics/_index.adoc
	@@ -344,7 +344,8 @@
	=== Managing Accounts

	FreeBSD provides a variety of different commands to manage user accounts.
	-The most common commands are summarized in <<users-modifying-utilities>>, followed by some examples of their usage.
	+The most common commands are summarized in
	+crossref:basics[users-modifying-utilities], followed by some examples of their usage.
	See the manual page for each utility for more details and usage examples.

	[[users-modifying-utilities]]
	@@ -382,7 +383,7 @@
	This utility must be run as the superuser.

	The man:adduser[8] utility is interactive and walks through the steps for creating a new user account.
	-As seen in <<users-modifying-adduser>>, either input the required information or press kbd:[Return] to accept the default value shown in square brackets.
	+As seen in crossref:basics[users-modifying-adduser], either input the required information or press kbd:[Return] to accept the default value shown in square brackets.
	In this example, the user has been invited into the `wheel` group, allowing them to become the superuser with man:su[1].
	When finished, the utility will prompt to either create another user or to exit.

	@@ -493,9 +494,9 @@
	This utility will prompt for the user's password when exiting the editor, unless the utility is run as the superuser.
	====

	-In <<users-modifying-chpass-su>>, the superuser has typed `chpass jru` and is now viewing the fields that can be changed for this user.
	+In crossref:basics[users-modifying-chpass-su], the superuser has typed `chpass jru` and is now viewing the fields that can be changed for this user.
	If `jru` runs this command instead, only the last six fields will be displayed and available for editing.
	-This is shown in <<users-modifying-chpass-ru>>.
	+This is shown in crossref:basics[users-modifying-chpass-ru].

	[[users-modifying-chpass-su]]
	.Using `chpass` as Superuser
	@@ -1073,12 +1074,12 @@
	The root directory also contains mount points for other file systems that are mounted during the transition to multi-user operation.

	A mount point is a directory where additional file systems can be grafted onto a parent file system (usually the root file system).
	-This is further described in <<disk-organization>>.
	+This is further described in crossref:basics[disk-organization].
	Standard mount points include `/usr/`, `/var/`, `/tmp/`, `/mnt/`, and `/cdrom/`.
	These directories are usually referenced to entries in `/etc/fstab`.
	This file is a table of various file systems and mount points and is read by the system.
	Most of the file systems in `/etc/fstab` are mounted automatically at boot time from the script man:rc[8] unless their entry includes `noauto`.
	-Details can be found in <<disks-fstab>>.
	+Details can be found in crossref:basics[disks-fstab].

	A complete description of the file system hierarchy is available in man:hier[7].
	The following table provides a brief overview of the most common directories.
	@@ -1270,7 +1271,7 @@

	File systems are contained in _partitions_.
	Disks are divided into partitions using one of several partitioning schemes;
	-see <<bsdinstall-part-manual>>.
	+see crossref:basics[bsdinstall-part-manual].
	The newer scheme is GPT; older BIOS-based computers use MBR.
	GPT supports division of a disk into partitions with a size, offset, and type.
	It supports a large number of partitions and partition types, and is recommended whenever its use is possible.
	@@ -1320,13 +1321,13 @@
	Finally, each disk on the system is identified.
	A disk name starts with a code that indicates the type of disk, and then a number, indicating which disk it is.
	Unlike partitions and slices, disk numbering starts at 0.
	-Common codes are listed in <<disks-naming>>.
	+Common codes are listed in crossref:basics[disks-naming].

	When referring to a partition in a slice, include the disk name, `s`, the slice number, and then the partition letter.
	-Examples are shown in <<basics-disk-slice-part>>.
	+Examples are shown in crossref:basics[basics-disk-slice-part].
	GPT partitions include the disk name, `p`, and then the partition number.

	-<<basics-concept-disk-model>> shows a conceptual model of a disk layout using MBR slices.
	+crossref:basics[basics-concept-disk-model] shows a conceptual model of a disk layout using MBR slices.

	When installing FreeBSD, configure the disk slices if using MBR, and create partitions within the slice to be used for FreeBSD.
	If using GPT, configure partitions for each file system.
	@@ -1422,7 +1423,7 @@
	....

	`device`::
	-An existing device name as explained in <<disks-naming>>.
	+An existing device name as explained in crossref:basics[disks-naming].

	`mount-point`::
	An existing directory on which to mount the file system.
	@@ -1683,7 +1684,7 @@
	Another feature of the shell is the use of environment variables.
	Environment variables are a variable/key pair stored in the shell's environment.
	This environment can be read by any program invoked by the shell, and thus contains a lot of program configuration.
	-<<shell-env-vars>> provides a list of common environment variables and their meanings.
	+crossref:basics[shell-env-vars] provides a list of common environment variables and their meanings.
	Note that the names of environment variables are always in uppercase.

	[[shell-env-vars]]
	@@ -1857,7 +1858,8 @@
	Learning a more powerful editor such as vim or Emacs can save more time in the long run.

	Many applications which modify files or require typed input will automatically open a text editor.
	-To change the default editor, set the `EDITOR` environment variable as described in <<shells>>.
	+To change the default editor, set the `EDITOR` environment variable as described
	+in crossref:basics[shells].

	[[basics-devices]]
	== Devices and Device Nodes
	diff --git a/documentation/content/en/books/handbook/boot/_index.adoc b/documentation/content/en/books/handbook/boot/_index.adoc
	--- a/documentation/content/en/books/handbook/boot/_index.adoc
	+++ b/documentation/content/en/books/handbook/boot/_index.adoc
	@@ -217,7 +217,7 @@

	Finally, by default, loader issues a 10 second wait for key presses, and boots the kernel if it is not interrupted.
	If interrupted, the user is presented with a prompt which understands the command set, where the user may adjust variables, unload all modules, load modules, and then finally boot or reboot.
	-<<boot-loader-commands>> lists the most commonly used loader commands.
	+crossref:boot[boot-loader-commands] lists the most commonly used loader commands.
	For a complete discussion of all available commands, refer to man:loader[8].

	[[boot-loader-commands]]
	@@ -306,7 +306,7 @@
	=== Last Stage

	Once the kernel is loaded by either loader or by boot2, which bypasses loader, it examines any boot flags and adjusts its behavior as necessary.
	-<<boot-kernel>> lists the commonly used boot flags.
	+crossref:boot[boot-kernel] lists the commonly used boot flags.
	Refer to man:boot[8] for more information on the other boot flags.

	[[boot-kernel]]
	@@ -397,7 +397,8 @@
	This file stores kernel boot information known as variables, sometimes referred to as "device hints".
	These "device hints" are used by device drivers for device configuration.

	-Device hints may also be specified at the Stage 3 boot loader prompt, as demonstrated in <<boot-loader>>.
	+Device hints may also be specified at the Stage 3 boot loader prompt, as
	+demonstrated in crossref:boot[boot-loader].
	Variables can be added using `set`, removed with `unset`, and viewed `show`.
	Variables set in [.filename]#/boot/device.hints# can also be overridden.
	Device hints entered at the boot loader are not permanent and will not be applied on the next reboot.
	diff --git a/documentation/content/en/books/handbook/bsdinstall/_index.adoc b/documentation/content/en/books/handbook/bsdinstall/_index.adoc
	--- a/documentation/content/en/books/handbook/bsdinstall/_index.adoc
	+++ b/documentation/content/en/books/handbook/bsdinstall/_index.adoc
	@@ -171,8 +171,13 @@
	* `-bootonly.iso`: This is the smallest installation file as it only contains the installer. A working Internet connection is required during installation as the installer will download the files it needs to complete the FreeBSD installation. This file should be burned to optical media.
	* `-disc1.iso`: This file contains all of the files needed to install FreeBSD, its source, and the Ports Collection. This file should be burned to optical media.
	* `-dvd1.iso`: This file contains all of the files needed to install FreeBSD, its source, and the Ports Collection. It also contains a set of popular binary packages for installing a window manager and some applications so that a complete system can be installed from media without requiring a connection to the Internet. This file should be burned to optical media.
	-* `-memstick.img`: This file contains all of the files needed to install FreeBSD, its source, and the Ports Collection. Write this file to a USB stick as shown in <<bsdinstall-usb>>.
	-* `-mini-memstick.img`: Like `-bootonly.iso`, does not include installation files, but downloads them as needed. A working internet connection is required during installation. It should be written to a USB stick as shown in <<bsdinstall-usb>>.
	+* `-memstick.img`: This file contains all of the files needed to install
	+ FreeBSD, its source, and the Ports Collection. Write this file to a USB stick
	+ as shown in crossref:bsdinstall[bsdinstall-usb].
	+* `-mini-memstick.img`: Like `-bootonly.iso`, does not include installation
	+ files, but downloads them as needed. A working internet connection is required
	+ during installation. It should be written to a USB stick as shown in
	+ crossref:bsdinstall[bsdinstall-usb].

	After downloading the image file, download at least one _checksum_ file from the same directory.
	There are two _checksum_ files available, named after the release number and the architecture name.
	@@ -277,7 +282,9 @@
	If there is a concern that something is incorrectly configured, just turn the computer off before this point and no changes will be made to the system's disks.
	====

	-This section describes how to boot the system from the installation media which was prepared using the instructions in <<bsdinstall-installation-media>>.
	+This section describes how to boot the system from the installation media which
	+was prepared using the instructions in
	+crossref:bsdinstall[bsdinstall-installation-media].
	When using a bootable USB stick, plug in the USB stick before turning on the computer.
	When booting from CD or DVD, turn on the computer and insert the media at the first opportunity.
	How to configure the system to boot from the inserted media depends upon the architecture.
	@@ -302,7 +309,8 @@
	* `Reboot`: Reboots the system.
	* `Cons`: Allow to continue the installation by `video`, `serial`, `Dual (serial primary)` or `Dual (Video primary)`
	* `Kernel`: Loads a different kernel.
	-* `Boot Options`: Opens the menu shown in, and described under, <<bsdinstall-boot-options-menu>>.
	+* `Boot Options`: Opens the menu shown in, and described under,
	+ crossref:bsdinstall[bsdinstall-boot-options-menu].

	[[bsdinstall-boot-options-menu]]
	.FreeBSD Boot Options Menu
	@@ -322,7 +330,8 @@

	After making the needed selections, press kbd:[1] or kbd:[Backspace] to return to the main boot menu, then press kbd:[Enter] to continue booting into FreeBSD.
	A series of boot messages will appear as FreeBSD carries out its hardware device probes and loads the installation program.
	-Once the boot is complete, the welcome menu shown in <<bsdinstall-choose-mode>> will be displayed.
	+Once the boot is complete, the welcome menu shown in
	+crossref:bsdinstall[bsdinstall-choose-mode] will be displayed.

	[[bsdinstall-choose-mode]]
	.Welcome Menu
	@@ -333,7 +342,7 @@
	Otherwise, use the right or left arrows or the colorized letter to select the desired menu item.
	The btn:[Shell] can be used to access a FreeBSD shell in order to use command line utilities to prepare the disks before installation.
	The btn:[Live CD] option can be used to try out FreeBSD before installing it.
	-The live version is described in <<using-live-cd>>.
	+The live version is described in crossref:bsdinstall[using-live-cd].

	[TIP]
	====
	@@ -352,13 +361,15 @@
	[[bsdinstall-keymap]]
	=== Selecting the Keymap Menu

	-Before starting the process, bsdinstall will load the keymap files as shown in <<bsdinstall-keymap-loading>>.
	+Before starting the process, bsdinstall will load the keymap files as shown in
	+crossref:bsdinstall[bsdinstall-keymap-loading].

	[[bsdinstall-keymap-loading]]
	.Keymap Loading
	image::bsdinstall-keymap-loading.png[Keymap loading]

	-After the keymaps have been loaded, bsdinstall displays the menu shown in <<bsdinstall-keymap-10>>.
	+After the keymaps have been loaded, bsdinstall displays the menu shown in
	+crossref:bsdinstall[bsdinstall-keymap-10].
	Use the up and down arrows to select the keymap that most closely represents the mapping of the keyboard attached to the system.
	Press kbd:[Enter] to save the selection.

	@@ -372,7 +383,9 @@
	If the choice of keymap is not clear, [.guimenuitem]#United States of America ISO-8859-1# is also a safe option.
	====

	-In addition, when selecting a different keymap, the user can try the keymap and ensure it is correct before proceeding, as shown in <<bsdinstall-keymap-testing>>.
	+In addition, when selecting a different keymap, the user can try the keymap and
	+ensure it is correct before proceeding, as shown in
	+crossref:bsdinstall[bsdinstall-keymap-testing].

	[[bsdinstall-keymap-testing]]
	.Keymap Testing Menu
	@@ -422,9 +435,10 @@
	[[bsdinstall-netinstall]]
	=== Installing from the Network

	-The menu shown in <<bsdinstall-netinstall-notify>> only appears when installing from a `-bootonly.iso` or `-mini-memstick.img`, as this installation media does not hold copies of the installation files.
	+The menu shown in crossref:bsdinstall[bsdinstall-netinstall-notify] only appears when installing from a `-bootonly.iso` or `-mini-memstick.img`, as this installation media does not hold copies of the installation files.
	Since the installation files must be retrieved over a network connection, this menu indicates that the network interface must be configured first.
	-If this menu is shown in any step of the process, remember to follow the instructions in <<bsdinstall-config-network-dev>>.
	+If this menu is shown in any step of the process, remember to follow the
	+instructions in crossref:bsdinstall[bsdinstall-config-network-dev].

	[[bsdinstall-netinstall-notify]]
	.Installing from the Network
	@@ -522,7 +536,7 @@
	GPT is usually the most appropriate choice for amd64 computers.
	Older computers that are not compatible with GPT should use MBR.
	The other partition schemes are generally used for uncommon or older computers.
	-More information is available in <<partition-schemes>>.
	+More information is available in crossref:bsdinstall[partition-schemes].

	[[bsdinstall-ufs-scheme]]
	.Select Partition Scheme
	@@ -546,7 +560,8 @@
	.Final Confirmation
	image::bsdinstall-final-confirmation.png[Menu indicating to the user that all changes will be written to disk and informing that if he decides to continue the existing data will be permanently deleted.]

	-To continue with the installation process, go to <<bsdinstall-fetching-distribution>>.
	+To continue with the installation process, go to
	+crossref:bsdinstall[bsdinstall-fetching-distribution].

	[[bsdinstall-part-manual]]
	=== Manual Partitioning
	@@ -610,7 +625,7 @@
	Note that `/tmp` can be added later as a memory-based file system (man:tmpfs[5]) on systems with sufficient memory.
	====

	-See <<bsdinstall-part-manual-splitfs>> for an example.
	+See crossref:bsdinstall[bsdinstall-part-manual-splitfs] for an example.

	The `Size` may be entered with common abbreviations: _K_ for kilobytes, _M_ for megabytes, or _G_ for gigabytes.

	@@ -688,7 +703,9 @@
	\|===
	====

	-After the custom partitions have been created, select btn:[Finish] to continue with the installation and go to <<bsdinstall-fetching-distribution>>.
	+After the custom partitions have been created, select btn:[Finish] to continue
	+with the installation and go to
	+crossref:bsdinstall[bsdinstall-fetching-distribution].

	[[bsdinstall-part-zfs]]
	=== Guided Partitioning Using Root-on-ZFS
	@@ -703,7 +720,11 @@
	Here is a summary of the options in this menu:

	* `Install` - Proceed with the installation with the selected options.
	-* `Pool Type/Disks` - Configure the `Pool Type` and the disk(s) that will constitute the pool. The automatic ZFS installer currently only supports the creation of a single top level vdev, except in stripe mode. To create more complex pools, use the instructions in <<bsdinstall-part-shell>> to create the pool.
	+* `Pool Type/Disks` - Configure the `Pool Type` and the disk(s) that will
	+ constitute the pool. The automatic ZFS installer currently only supports the
	+ creation of a single top level vdev, except in stripe mode. To create more
	+ complex pools, use the instructions in
	+ crossref:bsdinstall[bsdinstall-part-shell] to create the pool.
	* `Rescan Devices` - Repopulate the list of available disks.
	* `Disk Info` - This menu can be used to inspect each disk, including its partition table and various other information such as the device model number and serial number, if available.
	* `Pool Name` - Establish the name of the pool. The default name is _zroot_.
	@@ -786,7 +807,8 @@
	image::bsdinstall-zfs-init-encription.png[Menu showing that the encryption is initializing.]

	The installation then proceeds normally.
	-To continue with the installation, go to <<bsdinstall-fetching-distribution>>.
	+To continue with the installation, go to
	+crossref:bsdinstall[bsdinstall-fetching-distribution].

	[[bsdinstall-part-shell]]
	=== Shell Mode Partitioning
	@@ -847,7 +869,8 @@
	.Choose a Network Interface
	image::bsdinstall-configure-network-interface.png[Menu showing the different network interfaces to configure.]

	-If an Ethernet interface is selected, the installer will skip ahead to the menu shown in <<bsdinstall-configure-net-ipv4>>.
	+If an Ethernet interface is selected, the installer will skip ahead to the menu
	+shown in crossref:bsdinstall[bsdinstall-configure-net-ipv4].
	If a wireless network interface is chosen, the system will instead scan for wireless access points:

	[[bsdinstall-wireless-scan]]
	@@ -886,7 +909,8 @@
	[NOTE]
	====
	Do not enter random network information as it will not work.
	-If a DHCP server is not available, obtain the information listed in <<bsdinstall-collect-network-information, Required Network Information>> from the network administrator or Internet service provider.
	+If a DHCP server is not available, obtain the information listed in
	+crossref:bsdinstall[bsdinstall-collect-network-information, Required Network Information] from the network administrator or Internet service provider.
	====

	If a DHCP server is available, select btn:[Yes] in the next menu to automatically configure the network interface.
	@@ -1064,7 +1088,7 @@
	image::bsdinstall-adduser1.png[Menu requesting if a user want to be added to the system.]

	Follow the prompts and input the requested information for the user account.
	-The example shown in <<bsdinstall-add-user2>> creates the `asample` user account.
	+The example shown in crossref:bsdinstall[bsdinstall-add-user2] creates the `asample` user account.

	[[bsdinstall-add-user2]]
	.Enter User Information
	@@ -1112,13 +1136,13 @@

	Use this menu to make any changes or to do any additional configuration before completing the installation.

	-* `Add User` - Described in <<bsdinstall-addusers>>.
	-* `Root Password` - Described in <<bsdinstall-post-root>>.
	-* `Hostname` - Described in <<bsdinstall-hostname>>.
	-* `Network` - Described in <<bsdinstall-config-network-dev>>.
	-* `Services` - Described in <<bsdinstall-sysconf>>.
	-* `System Hardening` - Described in <<bsdinstall-hardening>>.
	-* `Time Zone` - Described in <<bsdinstall-timezone>>.
	+* `Add User` - Described in crossref:bsdinstall[bsdinstall-addusers].
	+* `Root Password` - Described in crossref:bsdinstall[bsdinstall-post-root].
	+* `Hostname` - Described in crossref:bsdinstall[bsdinstall-hostname].
	+* `Network` - Described in crossref:bsdinstall[bsdinstall-config-network-dev].
	+* `Services` - Described in crossref:bsdinstall[bsdinstall-sysconf].
	+* `System Hardening` - Described in crossref:bsdinstall[bsdinstall-hardening].
	+* `Time Zone` - Described in crossref:bsdinstall[bsdinstall-timezone].
	* `Handbook` - Download and install the FreeBSD Handbook.

	Once configuration is complete, select btn:[Exit].
	@@ -1151,7 +1175,7 @@
	To review these messages once the system has been up for some time, type `less /var/run/dmesg.boot` from a command prompt.
	Press kbd:[q] to return to the command line after viewing.

	-If sshd was enabled in <<bsdinstall-config-serv>>, the first boot might be a bit slower as the system generates SSH host keys.
	+If sshd was enabled in crossref:bsdinstall[bsdinstall-config-serv], the first boot might be a bit slower as the system generates SSH host keys.
	Subsequent boots will be faster.
	The fingerprints of the keys are then displayed as in the following example:

	@@ -1236,7 +1260,8 @@
	[[using-live-cd]]
	== Using the Live CD

	-The welcome menu of bsdinstall, shown in <<bsdinstall-choose-mode>>, provides a btn:[Live CD] option.
	+The welcome menu of bsdinstall, shown in
	+crossref:bsdinstall[bsdinstall-choose-mode], provides a btn:[Live CD] option.
	This is useful for those who are still wondering whether FreeBSD is the right operating system for them and want to test some of the features before installing.

	The following points should be noted before using the btn:[Live CD]:
	diff --git a/documentation/content/en/books/handbook/config/_index.adoc b/documentation/content/en/books/handbook/config/_index.adoc
	--- a/documentation/content/en/books/handbook/config/_index.adoc
	+++ b/documentation/content/en/books/handbook/config/_index.adoc
	@@ -74,7 +74,7 @@
	and the [.filename]#/usr/local/etc# directory contains all the configuration files of the applications installed on the system through the ports collection and packages.

	The kernel state configuration is located in [.filename]#/etc/sysctl.conf#.
	-In the section <<configtuning-sysctl>>, the operation of man:sysctl[8] will be explained in more detail.
	+In the section crossref:config[configtuning-sysctl], the operation of man:sysctl[8] will be explained in more detail.

	For more information about the FreeBSD file system structure refer to man:hier[7].

	@@ -124,7 +124,10 @@
	\|System and daemon startup/control scripts, see man:rc[8] for more information.

	\|[.filename]#/etc/rc.conf#
	-\|Contains descriptive information about the local host name, configuration details for any potential network interfaces and which services should be started up at system initial boot time. More information in <<configtuning-core-configuration>>
	+\|Contains descriptive information about the local host name, configuration
	+details for any potential network interfaces and which services should be
	+started up at system initial boot time. More information in
	+crossref:bsdinstall[configtuning-core-configuration]

	\|[.filename]#/etc/security#
	\|OpenBSM audit configuration files, see man:audit[8] for more information.
	@@ -139,7 +142,8 @@
	\|OpenSSL configuration files.

	\|[.filename]#/etc/sysctl.conf#
	-\|Contains settings for the kernel. More information in <<configtuning-sysctl>>
	+\|Contains settings for the kernel. More information in
	+crossref:bsdinstall[configtuning-sysctl]

	\|===

	diff --git a/documentation/content/en/books/handbook/cutting-edge/_index.adoc b/documentation/content/en/books/handbook/cutting-edge/_index.adoc
	--- a/documentation/content/en/books/handbook/cutting-edge/_index.adoc
	+++ b/documentation/content/en/books/handbook/cutting-edge/_index.adoc
	@@ -229,7 +229,7 @@
	====
	Always keep a copy of the [.filename]#GENERIC# kernel in [.filename]#/boot/GENERIC#.
	It will be helpful in diagnosing a variety of problems and in performing version upgrades.
	-Refer to <<freebsd-update-custom-kernel-9x>> for instructions on how to get a copy of the [.filename]#GENERIC# kernel.
	+Refer to crossref:cutting-edge[freebsd-update-custom-kernel-9x] for instructions on how to get a copy of the [.filename]#GENERIC# kernel.
	====

	Unless the default configuration in [.filename]#/etc/freebsd-update.conf# has been changed,
	@@ -277,7 +277,7 @@
	[NOTE]
	====
	If the system is running a custom kernel, make sure that a copy of the [.filename]#GENERIC# kernel exists in [.filename]#/boot/GENERIC# before starting the upgrade.
	-Refer to <<freebsd-update-custom-kernel-9x>> for instructions on how to get a copy of the [.filename]#GENERIC# kernel.
	+Refer to crossref:cutting-edge[freebsd-update-custom-kernel-9x] for instructions on how to get a copy of the [.filename]#GENERIC# kernel.
	====

	Before upgrading to a new version, ensure the existing FreeBSD installation is up to date with respect to security and errata patches:
	@@ -398,7 +398,8 @@
	====

	The upgrade is now complete.
	-If this was a major version upgrade, reinstall all ports and packages as described in <<freebsdupdate-portsrebuild>>.
	+If this was a major version upgrade, reinstall all ports and packages as
	+described in crossref:cutting-edge[freebsdupdate-portsrebuild].

	[[freebsd-update-custom-kernel-9x]]
	==== Custom Kernels with FreeBSD 9.X and Later
	@@ -604,7 +605,8 @@
	. Synchronize with the FreeBSD-CURRENT sources. Typically, `git` is used to check out the -CURRENT code from the `main` branch of the FreeBSD Git repository (see crossref:mirrors[git,“Using Git”] for details).
	. Due to the size of the repository, some users choose to only synchronize the sections of source that interest them or which they are contributing patches to. However, users that plan to compile the operating system from source must download _all_ of FreeBSD-CURRENT, not just selected portions.
	+
	-Before compiling FreeBSD-CURRENT, read [.filename]#/usr/src/Makefile# very carefully and follow the instructions in <<makeworld>>.
	+Before compiling FreeBSD-CURRENT, read [.filename]#/usr/src/Makefile# very
	+carefully and follow the instructions in crossref:cutting-edge[makeworld].
	Read the {freebsd-current} and [.filename]#/usr/src/UPDATING# to stay up-to-date on other bootstrapping procedures that sometimes become necessary on the road to the next release.
	. Be active! FreeBSD-CURRENT users are encouraged to submit their suggestions for enhancements or bug fixes. Suggestions with accompanying code are always welcome.

	@@ -638,7 +640,9 @@
	+
	To compile or upgrade an existing FreeBSD system to FreeBSD-STABLE, use `git` to check out the source for the desired branch.
	Branch names, such as `stable/13`, are listed at link:https://www.FreeBSD.org/releng/[www.freebsd.org/releng].
	-. Before compiling or upgrading to FreeBSD-STABLE , read [.filename]#/usr/src/Makefile# carefully and follow the instructions in <<makeworld>>. Read the {freebsd-stable} and [.filename]#/usr/src/UPDATING# to keep up-to-date on other bootstrapping procedures that sometimes become necessary on the road to the next release.
	+. Before compiling or upgrading to FreeBSD-STABLE , read
	+ [.filename]#/usr/src/Makefile# carefully and follow the instructions in
	+ crossref:cutting-edge[makeworld]. Read the {freebsd-stable} and [.filename]#/usr/src/UPDATING# to keep up-to-date on other bootstrapping procedures that sometimes become necessary on the road to the next release.

	[[translate-n-number]]
	=== The N-number
	@@ -734,7 +738,8 @@
	# shutdown -r now <.>
	....

	-<.> Get the latest version of the source. See <<updating-src-obtaining-src>> for more information on obtaining and updating source.
	+<.> Get the latest version of the source. See
	+crossref:cutting-edge[updating-src-obtaining-src] for more information on obtaining and updating source.

	<.> Check [.filename]#/usr/src/UPDATING# for any manual steps required before or after building from source.

	@@ -829,7 +834,7 @@
	13.2-RELEASE
	....

	-Based on <<updating-src-obtaining-src-repopath>>, the source used to update `13.2-RELEASE` has a repository path of `releng/13.2`.
	+Based on crossref:cutting-edge[updating-src-obtaining-src-repopath], the source used to update `13.2-RELEASE` has a repository path of `releng/13.2`.
	That path is used when checking out the source:

	[source,shell]
	@@ -840,7 +845,7 @@

	<.> Move the old directory out of the way. If there are no local modifications in this directory, it can be deleted.

	-<.> The path from <<updating-src-obtaining-src-repopath>> is added to the repository URL. The third parameter is the destination directory for the source code on the local system.
	+<.> The path from crossref:cutting-edge[updating-src-obtaining-src-repopath] is added to the repository URL. The third parameter is the destination directory for the source code on the local system.

	[[updating-src-building]]
	=== Building from Source
	@@ -1109,7 +1114,8 @@
	and the build machine should list them all in its `KERNCONF`, listing its own kernel first.
	The build machine must have the kernel configuration files for each machine in its [.filename]#/usr/src/sys/arch/conf#.

	-On the build machine, build the kernel and world as described in <<makeworld>>,
	+On the build machine, build the kernel and world as described in
	+crossref:cutting-edge[makeworld],
	but do not install anything on the build machine.
	Instead, install the built kernel on the test machine.
	On the test machine, mount [.filename]#/usr/src# and [.filename]#/usr/obj# via NFS.
	diff --git a/documentation/content/en/books/handbook/desktop/_index.adoc b/documentation/content/en/books/handbook/desktop/_index.adoc
	--- a/documentation/content/en/books/handbook/desktop/_index.adoc
	+++ b/documentation/content/en/books/handbook/desktop/_index.adoc
	@@ -899,7 +899,7 @@
	== Desktop office productivity

	When it comes to productivity, users often look for an office suite or an easy-to-use word processor.
	-While some desktop environments like <<kde-environment, KDE Plasma>> provide an office suite, there is no default productivity package.
	+While some desktop environments like crossref:desktop[kde-environment, KDE Plasma] provide an office suite, there is no default productivity package.
	Several office suites and graphical word processors are available for FreeBSD, regardless of the installed desktop environments.

	This section demonstrates how to install the following popular productivity software and indicates if the application is resource-heavy, takes time to compile from ports, or has any major dependencies.
	diff --git a/documentation/content/en/books/handbook/disks/_index.adoc b/documentation/content/en/books/handbook/disks/_index.adoc
	--- a/documentation/content/en/books/handbook/disks/_index.adoc
	+++ b/documentation/content/en/books/handbook/disks/_index.adoc
	@@ -353,7 +353,7 @@
	ugen0.3: <Simple Drive STECH> at usbus0, cfg=0 md=HOST spd=HIGH (480Mbps) pwr=ON (2mA)
	....

	-If the device has not been formatted, refer to <<disks-adding>> for instructions on how to format and create partitions on the USB drive.
	+If the device has not been formatted, refer to crossref:disks[disks-adding] for instructions on how to format and create partitions on the USB drive.
	If the drive comes with a file system, it can be mounted by `root` using the instructions in crossref:basics[mount-unmount,“Mounting and Unmounting File Systems”].

	[WARNING]
	@@ -703,7 +703,7 @@
	# dd if=/dev/cd0 of=file.iso bs=2048
	....

	-The resulting image file can be burned to CD as described in <<cdrecord>>.
	+The resulting image file can be burned to CD as described in crossref:disks[cdrecord].
	====

	[[mounting-cd]]
	@@ -773,8 +773,9 @@

	To duplicate an audio CD, extract the audio data from the CD to a series of files, then write these files to a blank CD.

	-<<using-cdrecord>> describes how to duplicate and burn an audio CD.
	-If the FreeBSD version is less than 10.0 and the device is ATAPI, the `atapicam` module must be first loaded using the instructions in <<atapicam>>.
	+crossref:disks[using-cdrecord] describes how to duplicate and burn an audio CD.
	+If the FreeBSD version is less than 10.0 and the device is ATAPI, the `atapicam`
	+module must be first loaded using the instructions in crossref:disks[atapicam].

	[[using-cdrecord]]
	[.procedure]
	@@ -795,7 +796,7 @@
	% cdrecord -v dev=2,0 -dao -useinfo *.wav
	....
	+
	-Make sure that _2,0_ is set appropriately, as described in <<cdrecord>>.
	+Make sure that _2,0_ is set appropriately, as described in crossref:disks[cdrecord].

	[[creating-dvds]]
	== Creating and Using DVD Media
	@@ -807,7 +808,10 @@

	* DVD-R: This was the first DVD recordable format available. The DVD-R standard is defined by the http://www.dvdforum.org/forum.shtml[DVD Forum]. This format is write once.
	* DVD-RW: This is the rewritable version of the DVD-R standard. A DVD-RW can be rewritten about 1000 times.
	-* DVD-RAM: This is a rewritable format which can be seen as a removable hard drive. However, this media is not compatible with most DVD-ROM drives and DVD-Video players as only a few DVD writers support the DVD-RAM format. Refer to <<creating-dvd-ram>> for more information on DVD-RAM use.
	+* DVD-RAM: This is a rewritable format which can be seen as a removable hard
	+ drive. However, this media is not compatible with most DVD-ROM drives and
	+ DVD-Video players as only a few DVD writers support the DVD-RAM format. Refer
	+ to crossref:disks[creating-dvd-ram] for more information on DVD-RAM use.
	* DVD+RW: This is a rewritable format defined by the https://en.wikipedia.org/wiki/DVD%2BRW_Alliance[DVD+RW Alliance]. A DVD+RW can be rewritten about 1000 times.
	* DVD+R: This format is the write once variation of the DVD+RW format.

	@@ -825,9 +829,10 @@
	To perform DVD recording, use man:growisofs[1].
	This command is part of the package:sysutils/dvd+rw-tools[] utilities which support all DVD media types.

	-These tools use the SCSI subsystem to access the devices, therefore <<atapicam,ATAPI/CAM support>> must be loaded or statically compiled into the kernel.
	+These tools use the SCSI subsystem to access the devices, therefore
	+crossref:disks[atapicam,ATAPI/CAM support] must be loaded or statically compiled into the kernel.
	This support is not needed if the burner uses the USB interface.
	-Refer to <<usb-disks>> for more details on USB device configuration.
	+Refer to crossref:disks[usb-disks] for more details on USB device configuration.

	DMA access must also be enabled for ATAPI devices, by adding the following line to [.filename]#/boot/loader.conf#:

	@@ -845,7 +850,7 @@

	=== Burning Data DVDs

	-Since man:growisofs[1] is a front-end to <<mkisofs,mkisofs>>, it will invoke man:mkisofs[8] to create the file system layout and perform the write on the DVD.
	+Since man:growisofs[1] is a front-end to crossref:disks[mkisofs,mkisofs], it will invoke man:mkisofs[8] to create the file system layout and perform the write on the DVD.
	This means that an image of the data does not need to be created before the burning process.

	To burn to a DVD+R or a DVD-R the data in [.filename]#/path/to/data#, use the following command:
	@@ -1838,7 +1843,7 @@
	.Procedure: Encrypting a Partition with gbde
	. Add the New Hard Drive
	+
	-Install the new drive to the system as explained in <<disks-adding>>.
	+Install the new drive to the system as explained in crossref:disks[disks-adding].
	For the purposes of this example, a new hard drive partition has been added as [.filename]#/dev/ad4s1c# and [.filename]#/dev/ad0s1*# represents the existing standard FreeBSD partitions.
	+
	[source,shell]
	diff --git a/documentation/content/en/books/handbook/firewalls/_index.adoc b/documentation/content/en/books/handbook/firewalls/_index.adoc
	--- a/documentation/content/en/books/handbook/firewalls/_index.adoc
	+++ b/documentation/content/en/books/handbook/firewalls/_index.adoc
	@@ -245,7 +245,7 @@
	Refer to the http://www.openbsd.org/faq/pf/[PF FAQ] for complete coverage of PF rulesets.

	To control PF, use `pfctl`.
	-<<pfctl>> summarizes some useful options to this command.
	+crossref:firewalls[pfctl] summarizes some useful options to this command.
	Refer to man:pfctl[8] for a description of all available options:
	[[pfctl]]
	.Useful `pfctl` Options
	@@ -1066,7 +1066,8 @@

	IPFW is included in the basic FreeBSD install as a kernel loadable module, meaning that a custom kernel is not needed in order to enable IPFW.

	-For those users who wish to statically compile IPFW support into a custom kernel, see <<firewalls-ipfw-kernelconfig>>.
	+For those users who wish to statically compile IPFW support into a custom
	+kernel, see crossref:firewalls[firewalls-ipfw-kernelconfig].

	To configure the system to enable IPFW at boot time, add `firewall_enable="YES"` to [.filename]#/etc/rc.conf#:

	diff --git a/documentation/content/en/books/handbook/geom/_index.adoc b/documentation/content/en/books/handbook/geom/_index.adoc
	--- a/documentation/content/en/books/handbook/geom/_index.adoc
	+++ b/documentation/content/en/books/handbook/geom/_index.adoc
	@@ -338,7 +338,7 @@
	The BIOS will see the mirror as two individual drives rather than a mirror.
	Since the drives are identical, it does not matter which is selected to boot.

	-See <<gmirror-troubleshooting>> if there are problems booting.
	+See crossref:geom[gmirror-troubleshooting] if there are problems booting.
	Powering down and disconnecting the original [.filename]#ada0# disk will allow it to be kept as an offline backup.

	In use, the mirror will behave just like the original single drive.
	@@ -556,7 +556,7 @@

	Restart the system, booting from [.filename]#ada1#.
	If everything is working, the system will boot from [.filename]#mirror/gm0#, which now contains the same data as [.filename]#ada0# had previously.
	-See <<gmirror-troubleshooting>> if there are problems booting.
	+See crossref:geom[gmirror-troubleshooting] if there are problems booting.

	At this point, the mirror still consists of only the single [.filename]#ada1# disk.

	@@ -682,7 +682,8 @@
	# gmirror forget gm0
	....

	-Any old metadata should be cleared from the replacement disk using the instructions in <<geom-mirror-metadata>>.
	+Any old metadata should be cleared from the replacement disk using the
	+instructions in crossref:geom[geom-mirror-metadata].
	Then the replacement disk, [.filename]#ada4# for this example, is inserted into the mirror:

	[source,shell]
	diff --git a/documentation/content/en/books/handbook/glossary.adoc b/documentation/content/en/books/handbook/glossary.adoc
	--- a/documentation/content/en/books/handbook/glossary.adoc
	+++ b/documentation/content/en/books/handbook/glossary.adoc
	@@ -51,37 +51,37 @@
	== A

	ACL::
	-See <<acl-glossary,Access Control List>>.
	+See crossref:glossary[acl-glossary,Access Control List].

	ACPI::
	-See <<acpi-glossary,Advanced Configuration and Power Interface>>.
	+See crossref:glossary[acpi-glossary,Advanced Configuration and Power Interface].

	AMD::
	-See <<amd-glossary,Automatic Mount Daemon>>.
	+See crossref:glossary[amd-glossary,Automatic Mount Daemon].

	AML::
	-See <<aml-glossary,ACPI Machine Language>>.
	+See crossref:glossary[aml-glossary,ACPI Machine Language].

	API::
	-See <<api-glossary,Application Programming Interface>>.
	+See crossref:glossary[api-glossary,Application Programming Interface].

	APIC::
	-See <<apic-glossary,Advanced Programmable Interrupt Controller>>.
	+See crossref:glossary[apic-glossary,Advanced Programmable Interrupt Controller].

	APM::
	-See <<apm-glossary,Advanced Power Management>>.
	+See crossref:glossary[apm-glossary,Advanced Power Management].

	APOP::
	-See <<apop-glossary,Authenticated Post Office Protocol>>.
	+See crossref:glossary[apop-glossary,Authenticated Post Office Protocol].

	ASL::
	-See <<asl-glossary,ACPI Source Language>>.
	+See crossref:glossary[asl-glossary,ACPI Source Language].

	ATA::
	-See <<ata-glossary,Advanced Technology Attachment>>.
	+See crossref:glossary[ata-glossary,Advanced Technology Attachment].

	ATM::
	-See <<atm-glossary,Asynchronous Transfer Mode>>.
	+See crossref:glossary[atm-glossary,Asynchronous Transfer Mode].

	[[aml-glossary]]
	ACPI Machine Language::
	@@ -134,16 +134,16 @@
	== B

	BAR::
	-See <<bar-glossary,Base Address Register>>.
	+See crossref:glossary[bar-glossary,Base Address Register].

	BIND::
	-See <<bind-glossary,Berkeley Internet Name Domain>>.
	+See crossref:glossary[bind-glossary,Berkeley Internet Name Domain].

	BIOS::
	-See <<bios-glossary,Basic Input/Output System>>.
	+See crossref:glossary[bios-glossary,Basic Input/Output System].

	BSD::
	-See <<bsd-glossary,Berkeley Software Distribution>>.
	+See crossref:glossary[bsd-glossary,Berkeley Software Distribution].

	[[bar-glossary]]
	Base Address Register::
	@@ -175,22 +175,22 @@
	== C

	CD::
	-See <<cd-glossary,Carrier Detect>>.
	+See crossref:glossary[cd-glossary,Carrier Detect].

	CHAP::
	-See <<chap-glossary,Challenge Handshake Authentication Protocol>>.
	+See crossref:glossary[chap-glossary,Challenge Handshake Authentication Protocol].

	CLIP::
	-See <<clip-glossary,Classical IP over ATM>>.
	+See crossref:glossary[clip-glossary,Classical IP over ATM].

	COFF::
	-See <<coff-glossary,Common Object File Format>>.
	+See crossref:glossary[coff-glossary,Common Object File Format].

	CPU::
	-See <<cpu-glossary,Central Processing Unit>>.
	+See crossref:glossary[cpu-glossary,Central Processing Unit].

	CTS::
	-See <<cts-glossary,Clear To Send>>.
	+See crossref:glossary[cts-glossary,Clear To Send].

	[[cd-glossary]]
	Carrier Detect::
	@@ -215,7 +215,7 @@
	Clear To Send::
	An RS232C signal giving the remote system permission to send data.
	+
	-See <<rts-glossary,Also Request To Send>>.
	+See crossref:glossary[rts-glossary,Also Request To Send].

	[[coff-glossary]]
	Common Object File Format::
	@@ -225,31 +225,31 @@
	== D

	DAC::
	-See <<dac-glossary,Discretionary Access Control>>.
	+See crossref:glossary[dac-glossary,Discretionary Access Control].

	DDB::
	-See <<ddb-glossary,Debugger>>.
	+See crossref:glossary[ddb-glossary,Debugger].

	DES::
	-See <<des-glossary,Data Encryption Standard>>.
	+See crossref:glossary[des-glossary,Data Encryption Standard].

	DHCP::
	-See <<dhcp-glossary,Dynamic Host Configuration Protocol>>.
	+See crossref:glossary[dhcp-glossary,Dynamic Host Configuration Protocol].

	DNS::
	-See <<dns-glossary,Domain Name System>>.
	+See crossref:glossary[dns-glossary,Domain Name System].

	DSDT::
	-See <<dsdt-glossary,Differentiated System Description Table>>.
	+See crossref:glossary[dsdt-glossary,Differentiated System Description Table].

	DSR::
	-See <<dsr-glossary,Data Set Ready>>.
	+See crossref:glossary[dsr-glossary,Data Set Ready].

	DTR::
	-See <<dtr-glossary,Data Terminal Ready>>.
	+See crossref:glossary[dtr-glossary,Data Terminal Ready].

	DVMRP::
	-See <<dvmrp-glossary,Distance-Vector Multicast Routing Protocol>>.
	+See crossref:glossary[dvmrp-glossary,Distance-Vector Multicast Routing Protocol].

	[[dac-glossary]]
	Discretionary Access Control::
	@@ -263,7 +263,7 @@
	Data Set Ready::
	An RS232C signal sent from the modem to the computer or terminal indicating a readiness to send and receive data.
	+
	-See <<dtr-glossary,Also Data Terminal Ready>>.
	+See crossref:glossary[dtr-glossary,Also Data Terminal Ready].

	[[dtr-glossary]]
	Data Terminal Ready::
	@@ -294,13 +294,13 @@
	== E

	ECOFF::
	-See <<ecoff-glossary,Extended COFF>>.
	+See crossref:glossary[ecoff-glossary,Extended COFF].

	ELF::
	-See <<elf-glossary,Executable and Linking Format>>.
	+See crossref:glossary[elf-glossary,Executable and Linking Format].

	ESP::
	-See <<esp-glossary,Encapsulated Security Payload>>.
	+See crossref:glossary[esp-glossary,Encapsulated Security Payload].

	Encapsulated Security Payload::
	{empty}
	@@ -317,16 +317,16 @@
	== F

	FADT::
	-See <<fadt-glossary,Fixed ACPI Description Table>>.
	+See crossref:glossary[fadt-glossary,Fixed ACPI Description Table].

	FAT::
	-See <<fat-glossary,File Allocation Table>>.
	+See crossref:glossary[fat-glossary,File Allocation Table].

	FAT16::
	-See <<fat16-glossary,File Allocation Table (16-bit)>>.
	+See crossref:glossary[fat16-glossary,File Allocation Table (16-bit)].

	FTP::
	-See <<ftp-glossary,File Transfer Protocol>>.
	+See crossref:glossary[ftp-glossary,File Transfer Protocol].

	[[fat-glossary]]
	File Allocation Table::
	@@ -348,7 +348,7 @@
	== G

	GUI::
	-See <<gui-glossary,Graphical User Interface>>.
	+See crossref:glossary[gui-glossary,Graphical User Interface].

	[[giant-glossary]]
	Giant::
	@@ -364,10 +364,10 @@
	== H

	HTML::
	-See <<html-glossary,HyperText Markup Language>>.
	+See crossref:glossary[html-glossary,HyperText Markup Language].

	HUP::
	-See <<hup-glossary,HangUp>>.
	+See crossref:glossary[hup-glossary,HangUp].

	[[hup-glossary]]
	HangUp::
	@@ -381,31 +381,31 @@
	== I

	I/O::
	-See <<io-glossary,Input/Output>>.
	+See crossref:glossary[io-glossary,Input/Output].

	IASL::
	-See <<iasl-glossary,Intel’s ASL compiler>>.
	+See crossref:glossary[iasl-glossary,Intel’s ASL compiler].

	IMAP::
	-See <<imap-glossary,Internet Message Access Protocol>>.
	+See crossref:glossary[imap-glossary,Internet Message Access Protocol].

	IP::
	-See <<ip-glossary,Internet Protocol>>.
	+See crossref:glossary[ip-glossary,Internet Protocol].

	IPFW::
	-See <<ipfw-glossary,IP Firewall>>.
	+See crossref:glossary[ipfw-glossary,IP Firewall].

	IPP::
	-See <<ipp-glossary,Internet Printing Protocol>>.
	+See crossref:glossary[ipp-glossary,Internet Printing Protocol].

	IPv4::
	-See <<ipv4-glossary,IP Version 4>>.
	+See crossref:glossary[ipv4-glossary,IP Version 4].

	IPv6::
	-See <<ipv6-glossary,IP Version 6>>.
	+See crossref:glossary[ipv6-glossary,IP Version 6].

	ISP::
	-See <<isp-glossary,Internet Service Provider>>.
	+See crossref:glossary[isp-glossary,Internet Service Provider].

	[[ipfw-glossary]]
	IP Firewall::
	@@ -416,7 +416,7 @@
	The IP protocol version 4, which uses 32 bits for addressing.
	This version is still the most widely used, but it is slowly being replaced with IPv6.
	+
	-See <<ipv6-glossary,Also IP Version 6>>.
	+See crossref:glossary[ipv6-glossary,Also IP Version 6].

	[[ipv6-glossary]]
	IP Version 6::
	@@ -461,19 +461,19 @@
	Japanese for “turtle”, the term KAME is used in computing circles to refer to the link:http://www.kame.net/[KAME Project], who work on an implementation of IPv6.

	KDC::
	-See <<kdc-glossary,Key Distribution Center>>.
	+See crossref:glossary[kdc-glossary,Key Distribution Center].

	KLD::
	-See <<kld-glossary,Kernel ld(1)>>.
	+See crossref:glossary[kld-glossary,Kernel ld(1)].

	KSE::
	-See <<kse-glossary,Kernel Scheduler Entities>>.
	+See crossref:glossary[kse-glossary,Kernel Scheduler Entities].

	KVA::
	-See <<kva-glossary,Kernel Virtual Address>>.
	+See crossref:glossary[kva-glossary,Kernel Virtual Address].

	Kbps::
	-See <<kbps-glossary,Kilo Bits Per Second>>.
	+See crossref:glossary[kbps-glossary,Kilo Bits Per Second].

	[[kld-glossary]]
	Kernel man:ld[1]::
	@@ -501,13 +501,13 @@
	== L

	LAN::
	-See <<lan-glossary,Local Area Network>>.
	+See crossref:glossary[lan-glossary,Local Area Network].

	LOR::
	-See <<lor-glossary,Lock Order Reversal>>.
	+See crossref:glossary[lor-glossary,Lock Order Reversal].

	LPD::
	-See <<lpd-glossary,Line Printer Daemon>>.
	+See crossref:glossary[lpd-glossary,Line Printer Daemon].

	[[lpd-glossary]]
	Line Printer Daemon::
	@@ -530,37 +530,37 @@
	== M

	MAC::
	-See <<mac-glossary,Mandatory Access Control>>.
	+See crossref:glossary[mac-glossary,Mandatory Access Control].

	MADT::
	-See <<madt-glossary,Multiple APIC Description Table>>.
	+See crossref:glossary[madt-glossary,Multiple APIC Description Table].

	MFC::
	-See <<mfc-glossary,Merge From Current>>.
	+See crossref:glossary[mfc-glossary,Merge From Current].

	MFH::
	-See <<mfh-glossary,Merge From Head>>.
	+See crossref:glossary[mfh-glossary,Merge From Head].

	MFS::
	-See <<mfs-glossary,Merge From Stable>>.
	+See crossref:glossary[mfs-glossary,Merge From Stable].

	MFV::
	-See <<mfv-glossary,Merge From Vendor>>.
	+See crossref:glossary[mfv-glossary,Merge From Vendor].

	MIT::
	-See <<mit-glossary,Massachusetts Institute of Technology>>.
	+See crossref:glossary[mit-glossary,Massachusetts Institute of Technology].

	MLS::
	-See <<mls-glossary,Multi-Level Security>>.
	+See crossref:glossary[mls-glossary,Multi-Level Security].

	MOTD::
	-See <<motd-glossary,Message Of The Day>>.
	+See crossref:glossary[motd-glossary,Message Of The Day].

	MTA::
	-See <<mta-glossary,Mail Transfer Agent>>.
	+See crossref:glossary[mta-glossary,Mail Transfer Agent].

	MUA::
	-See <<mua-glossary,Mail User Agent>>.
	+See crossref:glossary[mua-glossary,Mail User Agent].

	[[mta-glossary]]
	Mail Transfer Agent::
	@@ -595,7 +595,7 @@
	+
	This term is also used when a patch is merged from -STABLE to a security branch.
	+
	-See <<mfc-glossary,Also Merge From Current>>.
	+See crossref:glossary[mfc-glossary,Also Merge From Current].

	[[mfv-glossary]]
	Merge From Vendor::
	@@ -617,19 +617,19 @@
	== N

	NAT::
	-See <<nat-glossary,Network Address Translation>>.
	+See crossref:glossary[nat-glossary,Network Address Translation].

	NDISulator::
	-See <<projectevil-glossary,Project Evil>>.
	+See crossref:glossary[projectevil-glossary,Project Evil].

	NFS::
	-See <<nfs-glossary,Network File System>>.
	+See crossref:glossary[nfs-glossary,Network File System].

	NTFS::
	-See <<ntfs-glossary,New Technology File System>>.
	+See crossref:glossary[ntfs-glossary,New Technology File System].

	NTP::
	-See <<ntp-glossary,Network Time Protocol>>.
	+See crossref:glossary[ntp-glossary,Network Time Protocol].

	[[nat-glossary]]
	Network Address Translation::
	@@ -651,13 +651,13 @@
	== O

	OBE::
	-See <<obe-glossary,Overtaken By Events>>.
	+See crossref:glossary[obe-glossary,Overtaken By Events].

	ODMR::
	-See <<odmr-glossary,On-Demand Mail Relay>>.
	+See crossref:glossary[odmr-glossary,On-Demand Mail Relay].

	OS::
	-See <<os-glossary,Operating System>>.
	+See crossref:glossary[os-glossary,Operating System].

	[[odmr-glossary]]
	On-Demand Mail Relay::
	@@ -676,46 +676,47 @@
	== P

	PAE::
	-See <<pae-glossary,Physical Address Extensions>>.
	+See crossref:glossary[pae-glossary,Physical Address Extensions].

	PAM::
	-See <<pam-glossary,Pluggable Authentication Modules>>.
	+See crossref:glossary[pam-glossary,Pluggable Authentication Modules].

	PAP::
	-See <<pap-glossary,Password Authentication Protocol>>.
	+See crossref:glossary[pap-glossary,Password Authentication Protocol].

	PC::
	-See <<pc-glossary,Personal Computer>>.
	+See crossref:glossary[pc-glossary,Personal Computer].

	PCNSFD::
	-See <<pcnfsd-glossary,Personal Computer Network File System Daemon>>.
	+See crossref:glossary[pcnfsd-glossary,Personal Computer Network File System
	+Daemon].

	PDF::
	-See <<pdf-glossary,Portable Document Format>>.
	+See crossref:glossary[pdf-glossary,Portable Document Format].

	PID::
	-See <<pid-glossary,Process ID>>.
	+See crossref:glossary[pid-glossary,Process ID].

	POLA::
	-See <<pola-glossary,Principle Of Least Astonishment>>.
	+See crossref:glossary[pola-glossary,Principle Of Least Astonishment].

	POP::
	-See <<pop-glossary,Post Office Protocol>>.
	+See crossref:glossary[pop-glossary,Post Office Protocol].

	POP3::
	-See <<pop3-glossary,Post Office Protocol Version 3>>.
	+See crossref:glossary[pop3-glossary,Post Office Protocol Version 3].

	PPD::
	-See <<ppd-glossary,PostScript Printer Description>>.
	+See crossref:glossary[ppd-glossary,PostScript Printer Description].

	PPP::
	-See <<ppp-glossary,Point-to-Point Protocol>>.
	+See crossref:glossary[ppp-glossary,Point-to-Point Protocol].

	PPPoA::
	-See <<pppoa-glossary,PPP over ATM>>.
	+See crossref:glossary[pppoa-glossary,PPP over ATM].

	PPPoE::
	-See <<pppoe-glossary,PPP over Ethernet>>.
	+See crossref:glossary[pppoe-glossary,PPP over Ethernet].

	[[pppoa-glossary]]
	PPP over ATM::
	@@ -726,10 +727,10 @@
	{empty}

	PR::
	-See <<pr-glossary,Problem Report>>.
	+See crossref:glossary[pr-glossary,Problem Report].

	PXE::
	-See <<pxe-glossary,Preboot eXecution Environment>>.
	+See crossref:glossary[pxe-glossary,Preboot eXecution Environment].

	[[pap-glossary]]
	Password Authentication Protocol::
	@@ -773,7 +774,7 @@
	Post Office Protocol Version 3::
	A protocol for accessing email messages on a mail server, characterised by the messages usually being downloaded from the server to the client, as opposed to remaining on the server.
	+
	-See <<imap-glossary,Also Internet Message Access Protocol>>.
	+See crossref:glossary[imap-glossary,Also Internet Message Access Protocol].

	[[ppd-glossary]]
	PostScript Printer Description::
	@@ -809,31 +810,31 @@
	== R

	RA::
	-See <<ra-glossary,Router Advertisement>>.
	+See crossref:glossary[ra-glossary,Router Advertisement].

	RAID::
	-See <<raid-glossary,Redundant Array of Inexpensive Disks>>.
	+See crossref:glossary[raid-glossary,Redundant Array of Inexpensive Disks].

	RAM::
	-See <<ram-glossary,Random Access Memory>>.
	+See crossref:glossary[ram-glossary,Random Access Memory].

	RD::
	-See <<rd-glossary,Received Data>>.
	+See crossref:glossary[rd-glossary,Received Data].

	RFC::
	-See <<rfc-glossary,Request For Comments>>.
	+See crossref:glossary[rfc-glossary,Request For Comments].

	RISC::
	-See <<risc-glossary,Reduced Instruction Set Computer>>.
	+See crossref:glossary[risc-glossary,Reduced Instruction Set Computer].

	RPC::
	-See <<rpc-glossary,Remote Procedure Call>>.
	+See crossref:glossary[rpc-glossary,Remote Procedure Call].

	RS232C::
	-See <<rs232c-glossary,Recommended Standard 232C>>.
	+See crossref:glossary[rs232c-glossary,Recommended Standard 232C].

	RTS::
	-See <<rts-glossary,Request To Send>>.
	+See crossref:glossary[rts-glossary,Request To Send].

	[[ram-glossary]]
	Random Access Memory::
	@@ -846,13 +847,13 @@
	RCS consists of many small tools that work together.
	It lacks some of the features found in more modern revision control systems, like Git, but it is very simple to install, configure, and start using for a small set of files.
	+
	-See <<svn-glossary,Also Subversion>>.
	+See crossref:glossary[svn-glossary,Also Subversion].

	[[rd-glossary]]
	Received Data::
	An RS232C pin or wire that data is received on.
	+
	-See <<td-glossary,Also Transmitted Data>>.
	+See crossref:glossary[td-glossary,Also Transmitted Data].

	[[rs232c-glossary]]
	Recommended Standard 232C::
	@@ -883,7 +884,7 @@
	Request To Send::
	An RS232C signal requesting that the remote system commences transmission of data.
	+
	-See <<cts-glossary,Also Clear To Send>>.
	+See crossref:glossary[cts-glossary,Also Clear To Send].

	[[ra-glossary]]
	Router Advertisement::
	@@ -893,34 +894,34 @@
	== S

	SCI::
	-See <<sci-glossary,System Control Interrupt>>.
	+See crossref:glossary[sci-glossary,System Control Interrupt].

	SCSI::
	-See <<scsi-glossary,Small Computer System Interface>>.
	+See crossref:glossary[scsi-glossary,Small Computer System Interface].

	SG::
	-See <<sg-glossary,Signal Ground>>.
	+See crossref:glossary[sg-glossary,Signal Ground].

	SMB::
	-See <<smb-glossary,Server Message Block>>.
	+See crossref:glossary[smb-glossary,Server Message Block].

	SMP::
	-See <<smp-glossary,Symmetric MultiProcessor>>.
	+See crossref:glossary[smp-glossary,Symmetric MultiProcessor].

	SMTP::
	-See <<smtp-glossary,Simple Mail Transfer Protocol>>.
	+See crossref:glossary[smtp-glossary,Simple Mail Transfer Protocol].

	SMTP AUTH::
	-See <<smtpauth-glossary,SMTP Authentication>>.
	+See crossref:glossary[smtpauth-glossary,SMTP Authentication].

	SSH::
	-See <<ssh-glossary,Secure Shell>>.
	+See crossref:glossary[ssh-glossary,Secure Shell].

	STR::
	-See <<str-glossary,Suspend To RAM>>.
	+See crossref:glossary[str-glossary,Suspend To RAM].

	SVN::
	-See <<svn-glossary,Subversion>>.
	+See crossref:glossary[svn-glossary,Subversion].

	[[smtpauth-glossary]]
	SMTP Authentication::
	@@ -966,22 +967,23 @@
	== T

	TCP::
	-See <<tcp-glossary,Transmission Control Protocol>>.
	+See crossref:glossary[tcp-glossary,Transmission Control Protocol].

	TCP/IP::
	-See <<tcpip-glossary,Transmission Control Protocol/Internet Protocol>>.
	+See crossref:glossary[tcpip-glossary,Transmission Control Protocol/Internet
	+Protocol].

	TD::
	-See <<td-glossary,Transmitted Data>>.
	+See crossref:glossary[td-glossary,Transmitted Data].

	TFTP::
	-See <<tftp-glossary,Trivial FTP>>.
	+See crossref:glossary[tftp-glossary,Trivial FTP].

	TGT::
	-See <<tgt-glossary,Ticket-Granting Ticket>>.
	+See crossref:glossary[tgt-glossary,Ticket-Granting Ticket].

	TSC::
	-See <<tsc-glossary,Time Stamp Counter>>.
	+See crossref:glossary[tsc-glossary,Time Stamp Counter].

	[[tgt-glossary]]
	Ticket-Granting Ticket::
	@@ -1004,7 +1006,7 @@
	Transmitted Data::
	An RS232C pin or wire that data is transmitted on.
	+
	-See <<rd-glossary,Also Received Data>>.
	+See crossref:glossary[rd-glossary,Also Received Data].

	[[tftp-glossary]]
	Trivial FTP::
	@@ -1014,22 +1016,22 @@
	== U

	UDP::
	-See <<udp-glossary,User Datagram Protocol>>.
	+See crossref:glossary[udp-glossary,User Datagram Protocol].

	UFS1::
	-See <<ufs1-glossary,Unix File System Version 1>>.
	+See crossref:glossary[ufs1-glossary,Unix File System Version 1].

	UFS2::
	-See <<ufs2-glossary,Unix File System Version 2>>.
	+See crossref:glossary[ufs2-glossary,Unix File System Version 2].

	UID::
	-See <<uid-glossary,User ID>>.
	+See crossref:glossary[uid-glossary,User ID].

	URL::
	-See <<url-glossary,Uniform Resource Locator>>.
	+See crossref:glossary[url-glossary,Uniform Resource Locator].

	USB::
	-See <<usb-glossary,Universal Serial Bus>>.
	+See crossref:glossary[usb-glossary,Universal Serial Bus].

	[[url-glossary]]
	Uniform Resource Locator::
	@@ -1061,7 +1063,7 @@
	== V

	VPN::
	-See <<vpn-glossary,Virtual Private Network>>.
	+See crossref:glossary[vpn-glossary,Virtual Private Network].

	[[vpn-glossary]]
	Virtual Private Network::
	diff --git a/documentation/content/en/books/handbook/jails/_index.adoc b/documentation/content/en/books/handbook/jails/_index.adoc
	--- a/documentation/content/en/books/handbook/jails/_index.adoc
	+++ b/documentation/content/en/books/handbook/jails/_index.adoc
	@@ -405,7 +405,7 @@
	# service jail start classic
	....

	-More information on how to manage jails can be found in the section <<jail-management>>.
	+More information on how to manage jails can be found in the section crossref:jails[jail-management].

	[[thin-jail]]
	== Thin Jails
	@@ -514,7 +514,8 @@
	# service jail start thinjail
	....

	-More information on how to manage jails can be found in the section <<jail-management>>.
	+More information on how to manage jails can be found in the section
	+crossref:jails[jail-management].

	[[creating-thin-jail-nullfs]]
	=== Creating a Thin Jail Using NullFS
	@@ -715,7 +716,8 @@

	The next step is to create the jail as indicated above.

	-Either the <<classic-jail>> procedure and the <<thin-jail>> procedure can be used.
	+Either the crossref:jails[classic-jail] procedure and the
	+crossref:jails[thin-jail] procedure can be used.
	The only thing that will change is the configuration in the [.filename]#/etc/jail.conf# file.

	The path [.filename]#/usr/local/jails/containers/vnet# will be used as an example for the created jail.
	@@ -787,7 +789,8 @@
	# service linux start
	....

	-The next step will be to create a jail as indicated above, for example in <<creating-thin-jail-openzfs-snapshots>>, but without performing the configuration.
	+The next step will be to create a jail as indicated above, for example in
	+crossref:jails[creating-thin-jail-openzfs-snapshots], but without performing the configuration.
	FreeBSD Linux jails require a specific configuration that will be detailed below.

	Once the jail has been created as explained above, execute the following command to perform required configuration for the jail and start it:
	diff --git a/documentation/content/en/books/handbook/kernelconfig/_index.adoc b/documentation/content/en/books/handbook/kernelconfig/_index.adoc
	--- a/documentation/content/en/books/handbook/kernelconfig/_index.adoc
	+++ b/documentation/content/en/books/handbook/kernelconfig/_index.adoc
	@@ -284,7 +284,8 @@
	# make installkernel KERNCONF=MYKERNEL
	....
	+
	-. Shutdown the system and reboot into the new kernel. If something goes wrong, refer to <<kernelconfig-noboot, The kernel does not boot>>.
	+. Shutdown the system and reboot into the new kernel. If something goes wrong,
	+ refer to crossref:kernelconfig[kernelconfig-noboot, The kernel does not boot].
	====

	By default, when a custom kernel is compiled, all kernel modules are rebuilt.
	diff --git a/documentation/content/en/books/handbook/l10n/_index.adoc b/documentation/content/en/books/handbook/l10n/_index.adoc
	--- a/documentation/content/en/books/handbook/l10n/_index.adoc
	+++ b/documentation/content/en/books/handbook/l10n/_index.adoc
	@@ -85,7 +85,7 @@
	....

	The _LanguageCode_ and _CountryCode_ are used to determine the country and the specific language variation.
	-<<locale-lang-country>> provides some examples of __LanguageCode_CountryCode__:
	+crossref:l10n[locale-lang-country] provides some examples of __LanguageCode_CountryCode__:

	[[locale-lang-country]]
	.Common Language and Country Codes
	@@ -146,7 +146,9 @@

	In addition to the user's shell configuration, these variables should also be set for specific application configuration and Xorg configuration.

	-Two methods are available for making the needed variable assignments: the <<login-class,login class>> method, which is the recommended method, and the <<startup-file,startup file>> method.
	+Two methods are available for making the needed variable assignments: the
	+crossref:l10n[login-class,login class] method, which is the recommended method,
	+and the crossref:l10n[startup-file,startup file] method.
	The next two sections demonstrate how to use both methods.

	[[login-class]]
	@@ -330,7 +332,7 @@
	The `keychange` entry is usually needed to program function keys to match the selected terminal type because function key sequences cannot be defined in the keymap.

	Next, set the correct console terminal type in [.filename]#/etc/ttys# for all virtual terminal entries.
	-<<locale-charset>> summarizes the available terminal types.:
	+crossref:l10n[locale-charset] summarizes the available terminal types.:

	[[locale-charset]]
	.Defined Terminal Types for Character Sets
	@@ -362,7 +364,7 @@
	\|===

	For languages with wide or multibyte characters, install a console for that language from the FreeBSD Ports Collection.
	-The available ports are summarized in <<locale-console>>.
	+The available ports are summarized in crossref:l10n[locale-console].
	Once installed, refer to the port's [.filename]#pkg-message# or man pages for configuration and usage instructions.

	[[locale-console]]
	@@ -407,7 +409,7 @@
	Application specific i18n settings such as fonts and menus can be tuned in [.filename]#~/.Xresources# and should allow users to view their selected language in graphical application menus.

	The X Input Method (XIM) protocol is an Xorg standard for inputting non-English characters.
	-<<locale-xim>> summarizes the input method applications which are available in the FreeBSD Ports Collection.
	+crossref:l10n[locale-xim] summarizes the input method applications which are available in the FreeBSD Ports Collection.
	Additional Fcitx and Uim applications are also available.

	[[locale-xim]]
	@@ -538,7 +540,7 @@
	=== Russian Language (KOI8-R Encoding)

	This section shows the specific settings needed to localize a FreeBSD system for the Russian language.
	-Refer to <<using-localization,Using Localization>> for a complete description of each type of setting.
	+Refer to crossref:l10n[using-localization,Using Localization] for a complete description of each type of setting.

	To set this locale for the login shell, add the following lines to each user's [.filename]#~/.login_conf#:

	diff --git a/documentation/content/en/books/handbook/mac/_index.adoc b/documentation/content/en/books/handbook/mac/_index.adoc
	--- a/documentation/content/en/books/handbook/mac/_index.adoc
	+++ b/documentation/content/en/books/handbook/mac/_index.adoc
	@@ -150,7 +150,7 @@
	[NOTE]
	====
	Some users have experienced problems with setting the `multilabel` flag on the root partition.
	-If this is the case, please review <<mac-troubleshoot>>.
	+If this is the case, please review crossref:mac[mac-troubleshoot].
	====

	Since the multi label policy is set on a per-file system basis, a multi label policy may not be needed if the file system layout is well designed.
	diff --git a/documentation/content/en/books/handbook/mail/_index.adoc b/documentation/content/en/books/handbook/mail/_index.adoc
	--- a/documentation/content/en/books/handbook/mail/_index.adoc
	+++ b/documentation/content/en/books/handbook/mail/_index.adoc
	@@ -80,7 +80,8 @@
	This application can be a command line program, such as the built-in `mail` utility or a third-party application from the Ports Collection, such as alpine, elm, or mutt.
	Dozens of graphical programs are also available in the Ports Collection, including Claws Mail, Evolution, and Thunderbird.
	Some organizations provide a web mail program which can be accessed through a web browser.
	-More information about installing and using a MUA on FreeBSD can be found in <<mail-agents>>.
	+More information about installing and using a MUA on FreeBSD can be found in
	+crossref:mail[mail-agents].

	Mail Transfer Agent (MTA)::
	The Mail Transfer Agent (MTA) is responsible for receiving incoming mail and delivering outgoing mail.
	@@ -383,7 +384,7 @@
	# pkg install dma
	....

	-Perform the configuration as indicated in <<configuring-dragonfly-mail-agent>>.
	+Perform the configuration as indicated in crossref:mail[configuring-dragonfly-mail-agent].

	Then change all the entries in the file [.filename]#/etc/mail/mailer.conf# to man:dma[8]:

	@@ -843,7 +844,8 @@

	Additionally, a typical Internet access service agreement may forbid one from running a "mail server".

	-The easiest way to fulfill those needs is to use the man:dma[8] MTA included in the <<configuring-dragonfly-mail-agent, base system>>.
	+The easiest way to fulfill those needs is to use the man:dma[8] MTA included in
	+the crossref:mail[configuring-dragonfly-mail-agent, base system].
	For systems up to 13.2, need be to installed from ports.

	In addition to man:dma[8], third-party software can be used to achieve the same, like package:mail/ssmtp[].
	@@ -869,7 +871,7 @@
	Some ISPs call this the "outgoing mail server" or "SMTP server".

	Make sure to disable Sendmail, including the outgoing mail service.
	-See <<mail-disable-sendmail>> for details.
	+See crossref:mail[mail-disable-sendmail] for details.

	package:mail/ssmtp[] has some other options available. Refer to the examples in [.filename]#/usr/local/etc/ssmtp# or the manual page of ssmtp for more information.

	diff --git a/documentation/content/en/books/handbook/mirrors/_index.adoc b/documentation/content/en/books/handbook/mirrors/_index.adoc
	--- a/documentation/content/en/books/handbook/mirrors/_index.adoc
	+++ b/documentation/content/en/books/handbook/mirrors/_index.adoc
	@@ -355,7 +355,8 @@
	\| Read-only ports repo via anon-ssh \| `ssh://anongit@git.FreeBSD.org/ports.git`
	\|=======================================================

	-External mirrors maintained by project members are also available; please refer to the <<external-mirrors>> section.
	+External mirrors maintained by project members are also available; please refer
	+to the crossref:mirrors[external-mirrors] section.

	To clone a copy of the FreeBSD system source code repository:

	diff --git a/documentation/content/en/books/handbook/network-servers/_index.adoc b/documentation/content/en/books/handbook/network-servers/_index.adoc
	--- a/documentation/content/en/books/handbook/network-servers/_index.adoc
	+++ b/documentation/content/en/books/handbook/network-servers/_index.adoc
	@@ -895,7 +895,7 @@
	+
	This line configures the client to provide anyone with a valid account in the NIS server's password maps an account on the client.
	There are many ways to configure the NIS client by modifying this line.
	-One method is described in <<network-netgroups>>.
	+One method is described in crossref:network-servers[network-netgroups].
	For more detailed reading, refer to the book `Managing NFS and NIS`, published by O'Reilly Media.
	. To import all possible group entries from the NIS server, add this line to [.filename]#/etc/group#:
	+
	diff --git a/documentation/content/en/books/handbook/network/_index.adoc b/documentation/content/en/books/handbook/network/_index.adoc
	--- a/documentation/content/en/books/handbook/network/_index.adoc
	+++ b/documentation/content/en/books/handbook/network/_index.adoc
	@@ -615,7 +615,8 @@
	=== Basic Wireless Configuration

	The first step will be to configure the wireless network card to an interface.
	-To find out what wireless network cards are in the system check the section <<config-identify-network-adapter>>.
	+To find out what wireless network cards are in the system check the section
	+crossref:network[config-identify-network-adapter].

	[source,shell]
	....
	diff --git a/documentation/content/en/books/handbook/ports/_index.adoc b/documentation/content/en/books/handbook/ports/_index.adoc
	--- a/documentation/content/en/books/handbook/ports/_index.adoc
	+++ b/documentation/content/en/books/handbook/ports/_index.adoc
	@@ -130,7 +130,8 @@

	For sites wishing to only use prebuilt binary packages from the FreeBSD mirrors, managing packages with man:pkg[8] can be sufficient.

	-However, for those sites building from source a separate <<ports-upgrading-tools, port management tool>> will be needed.
	+However, for those sites building from source a separate
	+crossref:ports[ports-upgrading-tools, port management tool] will be needed.

	Since man:pkg[8] only works with binary packages, it is not a replacement for such tools.
	Those tools can be used to install software from both binary packages and the Ports Collection, while man:pkg[8] installs only binary packages.
	@@ -906,7 +907,7 @@
	This section describes how to determine which software can be upgraded and how to perform the upgrade.

	To determine if newer versions of installed ports are available, ensure that the latest version of the ports tree is installed,
	-using the updating command described in <<ports-using-git-method, "Git Method">>.
	+using the updating command described in crossref:ports[ports-using-git-method, "Git Method"].
	The following command will list the installed ports which are out of date:

	[source,shell]
	@@ -1306,4 +1307,4 @@
	+
	If there is no response to the email, use Bugzilla to submit a bug report using the instructions in extref:{problem-reports}[Writing FreeBSD Problem Reports].
	. Fix it! The extref:{porters-handbook}[Porter's Handbook] includes detailed information on the ports infrastructure so that you can fix the occasional broken port or even submit your own!
	-. Install the package instead of the port using the instructions in <<pkgng-intro>>.
	+. Install the package instead of the port using the instructions in crossref:ports[pkgng-intro].
	diff --git a/documentation/content/en/books/handbook/printing/_index.adoc b/documentation/content/en/books/handbook/printing/_index.adoc
	--- a/documentation/content/en/books/handbook/printing/_index.adoc
	+++ b/documentation/content/en/books/handbook/printing/_index.adoc
	@@ -57,7 +57,7 @@

	Basic printing can be set up quickly.
	The printer must be capable of printing plain `ASCII` text.
	-For printing to other types of files, see <<printing-lpd-filters>>.
	+For printing to other types of files, see crossref:printing[printing-lpd-filters].

	[.procedure]
	****
	@@ -124,7 +124,8 @@
	+
	[TIP]
	====
	-If both lines do not start at the left border, but "stairstep" instead, see <<printing-lpd-filters-stairstep>>.
	+If both lines do not start at the left border, but "stairstep" instead, see
	+crossref:printing[printing-lpd-filters-stairstep].
	====
	+
	Text files can now be printed with `lpr`.
	diff --git a/documentation/content/en/books/handbook/security/_index.adoc b/documentation/content/en/books/handbook/security/_index.adoc
	--- a/documentation/content/en/books/handbook/security/_index.adoc
	+++ b/documentation/content/en/books/handbook/security/_index.adoc
	@@ -870,7 +870,7 @@
	....

	Once the configuration is done, the users will have to send the system administrator their public key and these keys will be added in [.filename]#.ssh/authorized_keys#.
	-The process for generating the keys is described in <<Key-based Authentication>>.
	+The process for generating the keys is described in crossref:security[Key-based Authentication].

	Then restart the server executing the following command:

	@@ -879,7 +879,8 @@
	# service sshd reload
	....

	-It is strongly recommended to follow the security improvements indicated in <<security-sshd-security-options>>.
	+It is strongly recommended to follow the security improvements indicated in
	+crossref:security[security-sshd-security-options].

	[[security-sshd-security-options]]
	=== SSH Server Security Options
	diff --git a/documentation/content/en/books/handbook/serialcomms/_index.adoc b/documentation/content/en/books/handbook/serialcomms/_index.adoc
	--- a/documentation/content/en/books/handbook/serialcomms/_index.adoc
	+++ b/documentation/content/en/books/handbook/serialcomms/_index.adoc
	@@ -102,7 +102,8 @@
	The documentation for the hardware should describe the type of cable required.

	These two types of cables differ in how the wires are connected to the connector.
	-Each wire represents a signal, with the defined signals summarized in <<serialcomms-signal-names>>.
	+Each wire represents a signal, with the defined signals summarized in
	+crossref:serialcomms[serialcomms-signal-names].
	A standard serial cable passes all of the RS-232C signals straight through.
	For example, the "Transmitted Data" pin on one end of the cable goes to the "Transmitted Data" pin on the other end.
	This is the type of cable used to connect a modem to the FreeBSD system, and is also appropriate for some terminals.
	@@ -110,7 +111,9 @@
	A null-modem cable switches the "Transmitted Data" pin of the connector on one end with the "Received Data" pin on the other end.
	The connector can be either a DB-25 or a DB-9.

	-A null-modem cable can be constructed using the pin connections summarized in <<nullmodem-db25>>, <<nullmodem-db9>>, and <<nullmodem-db9-25>>.
	+A null-modem cable can be constructed using the pin connections summarized in
	+crossref:serialcomms[nullmodem-db25], crossref:serialcomms[nullmodem-db9], and
	+crossref:serialcomms[nullmodem-db9-25].
	While the standard calls for a straight-through pin 1 to pin 1 "Protective Ground" line, it is often omitted.
	Some terminals work using only pins 2, 3, and 7, while others require different configurations.
	When in doubt, refer to the documentation for the hardware.
	@@ -499,7 +502,7 @@
	When attaching a terminal to one of those ports, modify the default entry to set the required speed and terminal type, to turn the device `on` and, if needed, to change the port's `secure` setting.
	If the terminal is connected to another port, add an entry for the port.

	-<<ex-etc-ttys>> configures two terminals in [.filename]#/etc/ttys#.
	+crossref:serialcomms[ex-etc-ttys] configures two terminals in [.filename]#/etc/ttys#.
	The first entry configures a Wyse-50 connected to [.filename]#COM2#.
	The second entry configures an old computer running Procomm terminal software emulating a VT-100 terminal.
	The computer is connected to the sixth serial port on a multi-port serial card.
	@@ -608,7 +611,7 @@

	FreeBSD needs the RTS and CTS signals for flow control at speeds above 2400 bps, the CD signal to detect when a call has been answered or the line has been hung up, and the DTR signal to reset the modem after a session is complete.
	Some cables are wired without all of the needed signals, so if a login session does not go away when the line hangs up, there may be a problem with the cable.
	-Refer to <<term-cables-null>> for more information about these signals.
	+Refer to crossref:serialcomms[term-cables-null] for more information about these signals.

	Like other UNIX(R)-like operating systems, FreeBSD uses the hardware signals to find out when a call has been answered or a line has been hung up and to hangup and reset the modem after a call.
	FreeBSD avoids sending commands to the modem or watching for status reports from the modem.
	@@ -689,7 +692,8 @@

	For a slow CPU or a heavily loaded system without 16550A-based serial ports, this configuration may produce `uart` "silo" errors at 57.6 Kbps.

	-The configuration of [.filename]#/etc/ttys# is similar to <<ex-etc-ttys>>, but a different argument is passed to `getty` and `dialup` is used for the terminal type.
	+The configuration of [.filename]#/etc/ttys# is similar to
	+crossref:serialcomms[ex-etc-ttys], but a different argument is passed to `getty` and `dialup` is used for the terminal type.
	Replace _xxx_ with the process `init` will run on the device:

	[.programlisting]
	@@ -1012,7 +1016,7 @@
	. Prepare a serial cable.
	+
	Use either a null-modem cable or a standard serial cable and a null-modem adapter.
	-See <<term-cables-null>> for a discussion on serial cables.
	+See crossref:serialcomms[term-cables-null] for a discussion on serial cables.
	. Unplug the keyboard.
	+
	Many systems probe for the keyboard during the Power-On Self-Test (POST) and will generate an error if the keyboard is not detected.
	@@ -1162,7 +1166,8 @@
	[TIP]
	====
	While it is not required, it is possible to provide a `login` prompt over the serial line.
	-To configure this, edit the entry for the serial port in [.filename]#/etc/ttys# using the instructions in <<term-config>>.
	+To configure this, edit the entry for the serial port in [.filename]#/etc/ttys#
	+using the instructions in crossref:serialcomms[term-config].
	If the speed of the serial port has been changed, change `std.115200` to match the new setting.
	====

	diff --git a/documentation/content/en/books/handbook/wine/_index.adoc b/documentation/content/en/books/handbook/wine/_index.adoc
	--- a/documentation/content/en/books/handbook/wine/_index.adoc
	+++ b/documentation/content/en/books/handbook/wine/_index.adoc
	@@ -98,7 +98,7 @@
	[[what-is-wine]]
	=== What is WINE?

	-As mentioned in the <<wine-synopsis,Synopsis>> for this chapter, WINE is a compatibility layer that allows Windows(R) applications to run on other operating systems.
	+As mentioned in the crossref:wine[wine-synopsis,Synopsis] for this chapter, WINE is a compatibility layer that allows Windows(R) applications to run on other operating systems.
	In theory, it means these programs should run on systems like FreeBSD, macOS, and Android.

	When WINE runs a Windows(R) executable, two things occur:
	@@ -162,7 +162,8 @@
	In addition to proprietary offerings, other projects have released applications designed to work in tandem with the standard, open source version of WINE.
	The goals for these can range from making installation easier to offering easy ways to get popular software installed.

	-These solutions are covered in greater detail in the later section on <<wine-management-guis,GUI frontends>>, and include the following:
	+These solutions are covered in greater detail in the later section on
	+crossref:wine[wine-management-guis,GUI frontends], and include the following:

	* winetricks
	* Mizutamari
	@@ -173,7 +174,15 @@
	For FreeBSD users, some alternatives to using WINE are as follows:

	* Dual-Booting: A straightforward option is to run desired Windows(R) applications natively on that OS. This of course means exiting FreeBSD in order to boot Windows(R), so this method is not feasible if access to programs in both systems is required simultaneously.
	-* Virtual Machines: Virtual Machines (VMs), as mentioned earlier in this chapter, are software processes that emulate full sets of hardware, on which additional operating systems (including Windows(R)) can be installed and run. Modern tools make VMs easy to create and manage, but this method comes at a cost. A good portion of the host systems resources must be allocated to each VM, and those resources cannot be reclaimed by the host as long as the VM is running. A few examples of VM managers include the open source solutions qemu, bhyve, and VirtualBox. See the chapter on <<virtualization,Virtualization>> for more detail.
	+* Virtual Machines: Virtual Machines (VMs), as mentioned earlier in this
	+ chapter, are software processes that emulate full sets of hardware, on which
	+ additional operating systems (including Windows(R)) can be installed and run.
	+ Modern tools make VMs easy to create and manage, but this method comes at a
	+ cost. A good portion of the host systems resources must be allocated to each
	+ VM, and those resources cannot be reclaimed by the host as long as the VM is
	+ running. A few examples of VM managers include the open source solutions qemu,
	+ bhyve, and VirtualBox. See the chapter on
	+ crossref:virtualization[virtualization,Virtualization] for more detail.
	* Remote Access: Like many other UNIX(R)-like systems, FreeBSD can run a variety of applications enabling users to remotely access Windows(R) computers and use their programs or data. In addition to clients such as xrdp that connect to the standard Windows(R) Remote Desktop Protocol, other open source standards such as vnc can also be used (provided a compatible server is present on the other side).

	[[installing-wine-on-freebsd]]
	diff --git a/documentation/content/en/books/handbook/x11/_index.adoc b/documentation/content/en/books/handbook/x11/_index.adoc
	--- a/documentation/content/en/books/handbook/x11/_index.adoc
	+++ b/documentation/content/en/books/handbook/x11/_index.adoc
	@@ -608,7 +608,7 @@
	The URW font collection (package:x11-fonts/urwfonts[]) includes high quality versions of standard type1 fonts (Times Roman(TM), Helvetica(TM), Palatino(TM) and others).
	The Freefonts collection (package:x11-fonts/freefonts[]) includes many more fonts, but most of them are intended for use in graphics software such as the Gimp, and are not complete enough to serve as screen fonts.
	In addition, Xorg can be configured to use TrueType(R) fonts with a minimum of effort.
	-For more details on this, see the man:X[7] manual page or <<truetype>>.
	+For more details on this, see the man:X[7] manual page or crossref:x11[truetype].

	To install the above Type1 font collections from binary packages, run the following commands:

	@@ -636,7 +636,8 @@
	....

	This will work but will be lost when the X session is closed, unless it is added to the startup file ([.filename]#~/.xinitrc# for a normal `startx` session, or [.filename]#~/.xsession# when logging in through a graphical login manager like XDM).
	-A third way is to use the new [.filename]#/usr/local/etc/fonts/local.conf# as demonstrated in <<antialias>>.
	+A third way is to use the new [.filename]#/usr/local/etc/fonts/local.conf# as
	+demonstrated in crossref:x11[antialias].

	[[truetype]]
	=== TrueType(R) Fonts
	@@ -670,7 +671,7 @@
	....

	Now add the TrueType(R) directory to the font path.
	-This is just the same as described in <<type1>>:
	+This is just the same as described in crossref:x11[type1]:

	[source,shell]
	....
	diff --git a/documentation/content/en/books/handbook/zfs/_index.adoc b/documentation/content/en/books/handbook/zfs/_index.adoc
	--- a/documentation/content/en/books/handbook/zfs/_index.adoc
	+++ b/documentation/content/en/books/handbook/zfs/_index.adoc
	@@ -54,11 +54,15 @@

	ZFS has three major design goals:

	-* Data integrity: All data includes a <<zfs-term-checksum,checksum>> of the data. ZFS calculates checksums and writes them along with the data. When reading that data later, ZFS recalculates the checksums. If the checksums do not match, meaning detecting one or more data errors, ZFS will attempt to automatically correct errors when ditto-, mirror-, or parity-blocks are available.
	+* Data integrity: All data includes a crossref:zfs[zfs-term-checksum,checksum] of the data. ZFS calculates checksums and writes them along with the data. When reading that data later, ZFS recalculates the checksums. If the checksums do not match, meaning detecting one or more data errors, ZFS will attempt to automatically correct errors when ditto-, mirror-, or parity-blocks are available.
	* Pooled storage: adding physical storage devices to a pool, and allocating storage space from that shared pool. Space is available to all file systems and volumes, and increases by adding new storage devices to the pool.
	-* Performance: caching mechanisms provide increased performance. <<zfs-term-arc,ARC>> is an advanced memory-based read cache. ZFS provides a second level disk-based read cache with <<zfs-term-l2arc,L2ARC>>, and a disk-based synchronous write cache named <<zfs-term-zil,ZIL>>.
	+* Performance: caching mechanisms provide increased performance.
	+ crossref:zfs[zfs-term-arc,ARC] is an advanced memory-based read cache. ZFS
	+ provides a second level disk-based read cache with
	+ crossref:zfs[zfs-term-l2arc,L2ARC], and a disk-based synchronous write cache
	+ named crossref:zfs[zfs-term-zil,ZIL].

	-A complete list of features and terminology is in <<zfs-term>>.
	+A complete list of features and terminology is in crossref:zfs[zfs-term].

	[[zfs-differences]]
	== What Makes ZFS Different
	@@ -361,14 +365,15 @@
	# zpool status -x
	....

	-If all pools are <<zfs-term-online,Online>> and everything is normal, the message shows:
	+If all pools are crossref:zfs[zfs-term-online,Online] and everything is normal, the message shows:

	[source,shell]
	....
	all pools are healthy
	....

	-If there is a problem, perhaps a disk being in the <<zfs-term-offline,Offline>> state, the pool state will look like this:
	+If there is a problem, perhaps a disk being in the
	+crossref:zfs[zfs-term-offline,Offline] state, the pool state will look like this:

	[source,shell]
	....
	@@ -483,14 +488,16 @@

	ZFS administration uses two main utilities.
	The `zpool` utility controls the operation of the pool and allows adding, removing, replacing, and managing disks.
	-The <<zfs-zfs,`zfs`>> utility allows creating, destroying, and managing datasets, both <<zfs-term-filesystem,file systems>> and <<zfs-term-volume,volumes>>.
	+The crossref:zfs[zfs-zfs,`zfs`] utility allows creating, destroying, and
	+managing datasets, both crossref:zfs[zfs-term-filesystem,file systems] and
	+crossref:zfs[zfs-term-volume,volumes].

	[[zfs-zpool-create]]
	=== Creating and Destroying Storage Pools

	Creating a ZFS storage pool requires permanent decisions, as the pool structure cannot change after creation.
	The most important decision is which types of vdevs to group the physical disks into.
	-See the list of <<zfs-term-vdev,vdev types>> for details about the possible options.
	+See the list of crossref:zfs[zfs-term-vdev,vdev types] for details about the possible options.
	After creating the pool, most vdev types do not allow adding disks to the vdev.
	The exceptions are mirrors, which allow adding new disks to the vdev, and stripes, which upgrade to mirrors by attaching a new disk to the vdev.
	Although adding new vdevs expands a pool, the pool layout cannot change after pool creation.
	@@ -547,7 +554,7 @@
	Using partitions also allows the administrator to _under-provision_ the disks, using less than the full capacity.
	If a future replacement disk of the same nominal size as the original actually has a slightly smaller capacity, the smaller partition will still fit, using the replacement disk.

	-Create a <<zfs-term-vdev-raidz,RAID-Z2>> pool using partitions:
	+Create a crossref:zfs[zfs-term-vdev-raidz,RAID-Z2] pool using partitions:

	[source,shell]
	....
	@@ -581,11 +588,11 @@
	=== Adding and Removing Devices

	Two ways exist for adding disks to a pool: attaching a disk to an existing vdev with `zpool attach`, or adding vdevs to the pool with `zpool add`.
	-Some <<zfs-term-vdev,vdev types>> allow adding disks to the vdev after creation.
	+Some crossref:zfs[zfs-term-vdev,vdev types] allow adding disks to the vdev after creation.

	A pool created with a single disk lacks redundancy.
	It can detect corruption but can not repair it, because there is no other copy of the data.
	-The <<zfs-term-copies,copies>> property may be able to recover from a small failure such as a bad sector,
	+The crossref:zfs[zfs-term-copies,copies] property may be able to recover from a small failure such as a bad sector,
	but does not provide the same level of protection as mirroring or RAID-Z.
	Starting with a pool consisting of a single disk vdev, use `zpool attach` to add a new disk to the vdev, creating a mirror.
	Also use `zpool attach` to add new disks to a mirror group, increasing redundancy and read performance.
	@@ -747,7 +754,7 @@
	Pool status is important.
	If a drive goes offline or ZFS detects a read, write, or checksum error, the corresponding error count increases.
	The `status` output shows the configuration and status of each device in the pool and the status of the entire pool.
	-Actions to take and details about the last <<zfs-zpool-scrub,`scrub`>> are also shown.
	+Actions to take and details about the last crossref:zfs[zfs-zpool-scrub,`scrub`] are also shown.

	[source,shell]
	....
	@@ -783,11 +790,11 @@

	It may be desirable to replace one disk with a different disk.
	When replacing a working disk, the process keeps the old disk online during the replacement.
	-The pool never enters a <<zfs-term-degraded,degraded>> state, reducing the risk of data loss.
	+The pool never enters a crossref:zfs[zfs-term-degraded,degraded] state, reducing the risk of data loss.
	Running `zpool replace` copies the data from the old disk to the new one.
	After the operation completes, ZFS disconnects the old disk from the vdev.
	If the new disk is larger than the old disk, it may be possible to grow the zpool, using the new space.
	-See <<zfs-zpool-online,Growing a Pool>>.
	+See crossref:zfs[zfs-zpool-online,Growing a Pool].

	Replace a functioning device in the pool:

	@@ -853,14 +860,17 @@
	[[zfs-zpool-resilver]]
	=== Dealing with Failed Devices

	-When a disk in a pool fails, the vdev to which the disk belongs enters the <<zfs-term-degraded,degraded>> state.
	+When a disk in a pool fails, the vdev to which the disk belongs enters the
	+crossref:zfs[zfs-term-degraded,degraded] state.
	The data is still available, but with reduced performance because ZFS computes missing data from the available redundancy.
	To restore the vdev to a fully functional state, replace the failed physical device.
	-ZFS is then instructed to begin the <<zfs-term-resilver,resilver>> operation.
	+ZFS is then instructed to begin the crossref:zfs[zfs-term-resilver,resilver] operation.
	ZFS recomputes data on the failed device from available redundancy and writes it to the replacement device.
	-After completion, the vdev returns to <<zfs-term-online,online>> status.
	+After completion, the vdev returns to crossref:zfs[zfs-term-online,online] status.

	-If the vdev does not have any redundancy, or if devices have failed and there is not enough redundancy to compensate, the pool enters the <<zfs-term-faulted,faulted>> state.
	+If the vdev does not have any redundancy, or if devices have failed and there is
	+not enough redundancy to compensate, the pool enters the
	+crossref:zfs[zfs-term-faulted,faulted] state.
	Unless enough devices can reconnect the pool becomes inoperative requiring a data restore from backups.

	When replacing a failed disk, the name of the failed disk changes to the GUID of the new disk.
	@@ -926,9 +936,10 @@
	[[zfs-zpool-scrub]]
	=== Scrubbing a Pool

	-Routinely <<zfs-term-scrub,scrub>> pools, ideally at least once every month.
	+Routinely crossref:zfs[zfs-term-scrub,scrub] pools, ideally at least once every month.
	The `scrub` operation is disk-intensive and will reduce performance while running.
	-Avoid high-demand periods when scheduling `scrub` or use <<zfs-advanced-tuning-scrub_delay,`vfs.zfs.scrub_delay`>> to adjust the relative priority of the `scrub` to keep it from slowing down other workloads.
	+Avoid high-demand periods when scheduling `scrub` or use
	+crossref:zfs[zfs-advanced-tuning-scrub_delay,`vfs.zfs.scrub_delay`] to adjust the relative priority of the `scrub` to keep it from slowing down other workloads.

	[source,shell]
	....
	@@ -1123,7 +1134,8 @@
	errors: No known data errors
	....

	-After the scrubbing operation completes with all the data synchronized from [.filename]#ada0# to [.filename]#ada1#, <<zfs-zpool-clear,clear>> the error messages from the pool status by running `zpool clear`.
	+After the scrubbing operation completes with all the data synchronized from
	+[.filename]#ada0# to [.filename]#ada1#, crossref:zfs[zfs-zpool-clear,clear] the error messages from the pool status by running `zpool clear`.

	[source,shell]
	....
	@@ -1150,7 +1162,8 @@

	The smallest device in each vdev limits the usable size of a redundant pool.
	Replace the smallest device with a larger device.
	-After completing a <<zfs-zpool-replace,replace>> or <<zfs-term-resilver,resilver>> operation, the pool can grow to use the capacity of the new device.
	+After completing a crossref:zfs[zfs-zpool-replace,replace] or
	+crossref:zfs[zfs-term-resilver,resilver] operation, the pool can grow to use the capacity of the new device.
	For example, consider a mirror of a 1 TB drive and a 2 TB drive.
	The usable space is 1 TB.
	When replacing the 1 TB drive with another 2 TB drive, the resilvering process copies the existing data onto the new drive.
	@@ -1455,7 +1468,7 @@
	== `zfs` Administration

	The `zfs` utility can create, destroy, and manage all existing ZFS datasets within a pool.
	-To manage the pool itself, use <<zfs-zpool,`zpool`>>.
	+To manage the pool itself, use crossref:zfs[zfs-zpool,`zpool`].

	[[zfs-zfs-create]]
	=== Creating and Destroying Datasets
	@@ -1463,13 +1476,14 @@
	Unlike traditional disks and volume managers, space in ZFS is _not_ preallocated.
	With traditional file systems, after partitioning and assigning the space, there is no way to add a new file system without adding a new disk.
	With ZFS, creating new file systems is possible at any time.
	-Each <<zfs-term-dataset,_dataset_>> has properties including features like compression, deduplication, caching, and quotas, as well as other useful properties like readonly, case sensitivity, network file sharing, and a mount point.
	+Each crossref:zfs[zfs-term-dataset,_dataset_] has properties including features like compression, deduplication, caching, and quotas, as well as other useful properties like readonly, case sensitivity, network file sharing, and a mount point.
	Nesting datasets within each other is possible and child datasets will inherit properties from their ancestors.
	-<<zfs-zfs-allow,Delegate>>, <<zfs-zfs-send,replicate>>, <<zfs-zfs-snapshot,snapshot>>, <<zfs-zfs-jail,jail>> allows administering and destroying each dataset as a unit.
	+crossref:zfs[zfs-zfs-allow,Delegate], crossref:zfs[zfs-zfs-send,replicate],
	+crossref:zfs[zfs-zfs-snapshot,snapshot], crossref:zfs[zfs-zfs-jail,jail] allows administering and destroying each dataset as a unit.
	Creating a separate dataset for each different type or set of files has advantages.
	The drawbacks to having a large number of datasets are that some commands like `zfs list` will be slower, and that mounting of hundreds or even thousands of datasets will slow the FreeBSD boot process.

	-Create a new dataset and enable <<zfs-term-compression-lz4,LZ4 compression>> on it:
	+Create a new dataset and enable crossref:zfs[zfs-term-compression-lz4,LZ4 compression] on it:

	[source,shell]
	....
	@@ -1549,7 +1563,7 @@

	In modern versions of ZFS, `zfs destroy` is asynchronous, and the free space might take minutes to appear in the pool.
	Use `zpool get freeing _poolname_` to see the `freeing` property, that shows which datasets are having their blocks freed in the background.
	-If there are child datasets, like <<zfs-term-snapshot,snapshots>> or other datasets, destroying the parent is impossible.
	+If there are child datasets, like crossref:zfs[zfs-term-snapshot,snapshots] or other datasets, destroying the parent is impossible.
	To destroy a dataset and its children, use `-r` to recursively destroy the dataset and its children.
	Use `-n -v` to list datasets and snapshots destroyed by this operation, without actually destroy anything.
	Space reclaimed by destroying snapshots is also shown.
	@@ -1716,7 +1730,7 @@
	[[zfs-zfs-snapshot]]
	=== Managing Snapshots

	-<<zfs-term-snapshot,Snapshots>> are one of the most powerful features of ZFS.
	+crossref:zfs[zfs-term-snapshot,Snapshots] are one of the most powerful features of ZFS.
	A snapshot provides a read-only, point-in-time copy of the dataset.
	With Copy-On-Write (COW), ZFS creates snapshots fast by preserving older versions of the data on disk.
	If no snapshots exist, ZFS reclaims space for future use when data is rewritten or deleted.
	@@ -1801,7 +1815,8 @@
	mypool/usr/home@my_recursive_snapshot 0 - 184K -
	....

	-Displaying both the dataset and the snapshot together reveals how snapshots work in <<zfs-term-cow,COW>> fashion.
	+Displaying both the dataset and the snapshot together reveals how snapshots work
	+in crossref:zfs[zfs-term-cow,COW] fashion.
	They save the changes (_delta_) made and not the complete file system contents all over again.
	This means that snapshots take little space when making changes.
	Observe space usage even more by copying a file to the dataset, then creating a second snapshot:
	@@ -1883,7 +1898,7 @@
	....

	A backup administrator can compare two snapshots received from the sending host and determine the actual changes in the dataset.
	-See the <<zfs-zfs-send,Replication>> section for more information.
	+See the crossref:zfs[zfs-zfs-send,Replication] section for more information.

	[[zfs-zfs-snapshot-rollback]]
	==== Snapshot Rollback
	@@ -2115,7 +2130,8 @@
	Making regular backups of the entire pool is vital.
	ZFS provides a built-in serialization feature that can send a stream representation of the data to standard output.
	Using this feature, storing this data on another pool connected to the local system is possible, as is sending it over a network to another system.
	-Snapshots are the basis for this replication (see the section on <<zfs-zfs-snapshot,ZFS snapshots>>).
	+Snapshots are the basis for this replication (see the section on
	+crossref:zfs[zfs-zfs-snapshot,ZFS snapshots]).
	The commands used for replicating data are `zfs send` and `zfs receive`.

	These examples show ZFS replication with these two pools:
	@@ -2267,7 +2283,7 @@
	* Passwordless SSH access between sending and receiving host using SSH keys
	* ZFS requires the privileges of the `root` user to send and receive streams. This requires logging in to the receiving system as `root`.
	* Security reasons prevent `root` from logging in by default.
	-* Use the <<zfs-zfs-allow,ZFS Delegation>> system to allow a non-`root` user on each system to perform the respective send and receive operations.
	+* Use the crossref:zfs[zfs-zfs-allow,ZFS Delegation] system to allow a non-`root` user on each system to perform the respective send and receive operations.
	On the sending system:
	+
	[source,shell]
	@@ -2309,9 +2325,10 @@
	[[zfs-zfs-quota]]
	=== Dataset, User, and Group Quotas

	-Use <<zfs-term-quota,Dataset quotas>> to restrict the amount of space consumed by a particular dataset.
	-<<zfs-term-refquota,Reference Quotas>> work in much the same way, but count the space used by the dataset itself, excluding snapshots and child datasets.
	-Similarly, use <<zfs-term-userquota,user>> and <<zfs-term-groupquota,group>> quotas to prevent users or groups from using up all the space in the pool or dataset.
	+Use crossref:zfs[zfs-term-quota,Dataset quotas] to restrict the amount of space consumed by a particular dataset.
	+crossref:zfs[zfs-term-refquota,Reference Quotas] work in much the same way, but count the space used by the dataset itself, excluding snapshots and child datasets.
	+Similarly, use crossref:zfs[zfs-term-userquota,user] and
	+crossref:zfs[zfs-term-groupquota,group] quotas to prevent users or groups from using up all the space in the pool or dataset.

	The following examples assume that the users already exist in the system.
	Before adding a user to the system, make sure to create their home dataset first and set the `mountpoint` to `/home/_bob_`.
	@@ -2400,7 +2417,7 @@
	[[zfs-zfs-reservation]]
	=== Reservations

	-<<zfs-term-reservation,Reservations>> guarantee an always-available amount of space on a dataset.
	+crossref:zfs[zfs-term-reservation,Reservations] guarantee an always-available amount of space on a dataset.
	The reserved space will not be available to any other dataset.
	This useful feature ensures that free space is available for an important dataset or log files.

	@@ -2418,7 +2435,8 @@
	# zfs set reservation=none storage/home/bob
	....

	-The same principle applies to the `refreservation` property for setting a <<zfs-term-refreservation,Reference Reservation>>, with the general format `refreservation=_size_`.
	+The same principle applies to the `refreservation` property for setting a
	+crossref:zfs[zfs-term-refreservation,Reference Reservation], with the general format `refreservation=_size_`.

	This command shows any reservations or refreservations that exist on [.filename]#storage/home/bob#:

	@@ -2434,13 +2452,15 @@
	ZFS provides transparent compression.
	Compressing data written at the block level saves space and also increases disk throughput.
	If data compresses by 25% the compressed data writes to the disk at the same rate as the uncompressed version, resulting in an effective write speed of 125%.
	-Compression can also be a great alternative to <<zfs-zfs-deduplication,Deduplication>> because it does not require extra memory.
	+Compression can also be a great alternative to
	+crossref:zfs[zfs-zfs-deduplication,Deduplication] because it does not require extra memory.

	ZFS offers different compression algorithms, each with different trade-offs.
	The introduction of LZ4 compression in ZFS v5000 enables compressing the entire pool without the large performance trade-off of other algorithms.
	The biggest advantage to LZ4 is the _early abort_ feature.
	If LZ4 does not achieve at least 12.5% compression in the header part of the data, ZFS writes the block uncompressed to avoid wasting CPU cycles trying to compress data that is either already compressed or uncompressible.
	-For details about the different compression algorithms available in ZFS, see the <<zfs-term-compression,Compression>> entry in the terminology section.
	+For details about the different compression algorithms available in ZFS, see the
	+crossref:zfs[zfs-term-compression,Compression] entry in the terminology section.

	The administrator can see the effectiveness of compression using dataset properties.

	@@ -2458,7 +2478,8 @@
	Without compression, it would have taken 496 GB of space (the `logicalused` property).
	This results in a 1.11:1 compression ratio.

	-Compression can have an unexpected side effect when combined with <<zfs-term-userquota,User Quotas>>.
	+Compression can have an unexpected side effect when combined with
	+crossref:zfs[zfs-term-userquota,User Quotas].
	User quotas restrict how much actual space a user consumes on a dataset _after compression_.
	If a user has a quota of 10 GB, and writes 10 GB of compressible data, they will still be able to store more data.
	If they later update a file, say a database, with more or less compressible data, the amount of space available to them will change.
	@@ -2496,7 +2517,7 @@
	[[zfs-zfs-deduplication]]
	=== Deduplication

	-When enabled, <<zfs-term-deduplication,deduplication>> uses the checksum of each block to detect duplicate blocks.
	+When enabled, crossref:zfs[zfs-term-deduplication,deduplication] uses the checksum of each block to detect duplicate blocks.
	When a new block is a duplicate of an existing block, ZFS writes a new reference to the existing data instead of the whole duplicate block.
	Tremendous space savings are possible if the data contains a lot of duplicated files or repeated information.
	Warning: deduplication requires a large amount of memory, and enabling compression instead provides most of the space savings without the extra cost.
	@@ -2576,7 +2597,8 @@
	Using the formula _ratio = dedup * compress / copies_, system administrators can plan the storage allocation, deciding whether the workload will contain enough duplicate blocks to justify the memory requirements.
	If the data is reasonably compressible, the space savings may be good.
	Good practice is to enable compression first as compression also provides greatly increased performance.
	-Enable deduplication in cases where savings are considerable and with enough available memory for the <<zfs-term-deduplication,DDT>>.
	+Enable deduplication in cases where savings are considerable and with enough
	+available memory for the crossref:zfs[zfs-term-deduplication,DDT].

	[[zfs-zfs-jail]]
	=== ZFS and Jails
	@@ -2618,9 +2640,21 @@

	Adjust tunables to make ZFS perform best for different workloads.

	-* [[zfs-advanced-tuning-arc_max]] `_vfs.zfs.arc.max_` starting with 13.x (`vfs.zfs.arc_max` for 12.x) - Upper size of the <<zfs-term-arc,ARC>>. The default is all RAM but 1 GB, or 5/8 of all RAM, whichever is more. Use a lower value if the system runs any other daemons or processes that may require memory. Adjust this value at runtime with man:sysctl[8] and set it in [.filename]#/boot/loader.conf# or [.filename]#/etc/sysctl.conf#.
	-* [[zfs-advanced-tuning-arc_meta_limit]] `_vfs.zfs.arc.meta_limit_` starting with 13.x (`vfs.zfs.arc_meta_limit` for 12.x) - Limit the amount of the <<zfs-term-arc,ARC>> used to store metadata. The default is one fourth of `vfs.zfs.arc.max`. Increasing this value will improve performance if the workload involves operations on a large number of files and directories, or frequent metadata operations, at the cost of less file data fitting in the <<zfs-term-arc,ARC>>. Adjust this value at runtime with man:sysctl[8] in [.filename]#/boot/loader.conf# or [.filename]#/etc/sysctl.conf#.
	-* [[zfs-advanced-tuning-arc_min]] `_vfs.zfs.arc.min_` starting with 13.x (`vfs.zfs.arc_min` for 12.x) - Lower size of the <<zfs-term-arc,ARC>>. The default is one half of `vfs.zfs.arc.meta_limit`. Adjust this value to prevent other applications from pressuring out the entire <<zfs-term-arc,ARC>>. Adjust this value at runtime with man:sysctl[8] and in [.filename]#/boot/loader.conf# or [.filename]#/etc/sysctl.conf#.
	+* [[zfs-advanced-tuning-arc_max]] `_vfs.zfs.arc.max_` starting with 13.x
	+ (`vfs.zfs.arc_max` for 12.x) - Upper size of the
	+ crossref:zfs[zfs-term-arc,ARC]. The default is all RAM but 1 GB, or 5/8 of all RAM, whichever is more. Use a lower value if the system runs any other daemons or processes that may require memory. Adjust this value at runtime with man:sysctl[8] and set it in [.filename]#/boot/loader.conf# or [.filename]#/etc/sysctl.conf#.
	+* [[zfs-advanced-tuning-arc_meta_limit]] `_vfs.zfs.arc.meta_limit_` starting
	+ with 13.x (`vfs.zfs.arc_meta_limit` for 12.x) - Limit the amount of the
	+ crossref:zfs[zfs-term-arc,ARC] used to store metadata. The default is one
	+ fourth of `vfs.zfs.arc.max`. Increasing this value will improve performance if
	+ the workload involves operations on a large number of files and directories,
	+ or frequent metadata operations, at the cost of less file data fitting in the
	+ crossref:zfs[zfs-term-arc,ARC]. Adjust this value at runtime with man:sysctl[8] in [.filename]#/boot/loader.conf# or [.filename]#/etc/sysctl.conf#.
	+* [[zfs-advanced-tuning-arc_min]] `_vfs.zfs.arc.min_` starting with 13.x
	+ (`vfs.zfs.arc_min` for 12.x) - Lower size of the
	+ crossref:zfs[zfs-term-arc,ARC]. The default is one half of
	+ `vfs.zfs.arc.meta_limit`. Adjust this value to prevent other applications from
	+ pressuring out the entire crossref:zfs[zfs-term-arc,ARC]. Adjust this value at runtime with man:sysctl[8] and in [.filename]#/boot/loader.conf# or [.filename]#/etc/sysctl.conf#.
	* [[zfs-advanced-tuning-vdev-cache-size]] `_vfs.zfs.vdev.cache.size_` - A preallocated amount of memory reserved as a cache for each device in the pool. The total amount of memory used will be this value multiplied by the number of devices. Set this value at boot time and in [.filename]#/boot/loader.conf#.
	* [[zfs-advanced-tuning-min-auto-ashift]] `_vfs.zfs.min_auto_ashift_` - Lower `ashift` (sector size) used automatically at pool creation time. The value is a power of two. The default value of `9` represents `2^9 = 512`, a sector size of 512 bytes. To avoid _write amplification_ and get the best performance, set this value to the largest sector size used by a device in the pool.
	+
	@@ -2636,16 +2670,61 @@
	In some specific cases, the smaller 512-byte block size might be preferable.
	When used with 512-byte disks for databases or as storage for virtual machines, less data transfers during small random reads.
	This can provide better performance when using a smaller ZFS record size.
	-* [[zfs-advanced-tuning-prefetch_disable]] `_vfs.zfs.prefetch_disable_` - Disable prefetch. A value of `0` enables and `1` disables it. The default is `0`, unless the system has less than 4 GB of RAM. Prefetch works by reading larger blocks than requested into the <<zfs-term-arc,ARC>> in hopes to soon need the data. If the workload has a large number of random reads, disabling prefetch may actually improve performance by reducing unnecessary reads. Adjust this value at any time with man:sysctl[8].
	+* [[zfs-advanced-tuning-prefetch_disable]] `_vfs.zfs.prefetch_disable_` -
	+ Disable prefetch. A value of `0` enables and `1` disables it. The default is
	+ `0`, unless the system has less than 4 GB of RAM. Prefetch works by reading
	+ larger blocks than requested into the crossref:zfs[zfs-term-arc,ARC] in hopes to soon need the data. If the workload has a large number of random reads, disabling prefetch may actually improve performance by reducing unnecessary reads. Adjust this value at any time with man:sysctl[8].
	* [[zfs-advanced-tuning-vdev-trim_on_init]] `_vfs.zfs.vdev.trim_on_init_` - Control whether new devices added to the pool have the `TRIM` command run on them. This ensures the best performance and longevity for SSDs, but takes extra time. If the device has already been secure erased, disabling this setting will make the addition of the new device faster. Adjust this value at any time with man:sysctl[8].
	* [[zfs-advanced-tuning-vdev-max_pending]] `_vfs.zfs.vdev.max_pending_` - Limit the number of pending I/O requests per device. A higher value will keep the device command queue full and may give higher throughput. A lower value will reduce latency. Adjust this value at any time with man:sysctl[8].
	-* [[zfs-advanced-tuning-top_maxinflight]] `_vfs.zfs.top_maxinflight_` - Upper number of outstanding I/Os per top-level <<zfs-term-vdev,vdev>>. Limits the depth of the command queue to prevent high latency. The limit is per top-level vdev, meaning the limit applies to each <<zfs-term-vdev-mirror,mirror>>, <<zfs-term-vdev-raidz,RAID-Z>>, or other vdev independently. Adjust this value at any time with man:sysctl[8].
	-* [[zfs-advanced-tuning-l2arc_write_max]] `_vfs.zfs.l2arc_write_max_` - Limit the amount of data written to the <<zfs-term-l2arc,L2ARC>> per second. This tunable extends the longevity of SSDs by limiting the amount of data written to the device. Adjust this value at any time with man:sysctl[8].
	-* [[zfs-advanced-tuning-l2arc_write_boost]] `_vfs.zfs.l2arc_write_boost_` - Adds the value of this tunable to <<zfs-advanced-tuning-l2arc_write_max,`vfs.zfs.l2arc_write_max`>> and increases the write speed to the SSD until evicting the first block from the <<zfs-term-l2arc,L2ARC>>. This "Turbo Warmup Phase" reduces the performance loss from an empty <<zfs-term-l2arc,L2ARC>> after a reboot. Adjust this value at any time with man:sysctl[8].
	-* [[zfs-advanced-tuning-scrub_delay]]`_vfs.zfs.scrub_delay_` - Number of ticks to delay between each I/O during a <<zfs-term-scrub,`scrub`>>. To ensure that a `scrub` does not interfere with the normal operation of the pool, if any other I/O is happening the `scrub` will delay between each command. This value controls the limit on the total IOPS (I/Os Per Second) generated by the `scrub`. The granularity of the setting is determined by the value of `kern.hz` which defaults to 1000 ticks per second. Changing this setting results in a different effective IOPS limit. The default value is `4`, resulting in a limit of: 1000 ticks/sec / 4 = 250 IOPS. Using a value of _20_ would give a limit of: 1000 ticks/sec / 20 = 50 IOPS. Recent activity on the pool limits the speed of `scrub`, as determined by <<zfs-advanced-tuning-scan_idle,`vfs.zfs.scan_idle`>>. Adjust this value at any time with man:sysctl[8].
	-* [[zfs-advanced-tuning-resilver_delay]] `_vfs.zfs.resilver_delay_` - Number of milliseconds of delay inserted between each I/O during a <<zfs-term-resilver,resilver>>. To ensure that a resilver does not interfere with the normal operation of the pool, if any other I/O is happening the resilver will delay between each command. This value controls the limit of total IOPS (I/Os Per Second) generated by the resilver. ZFS determins the granularity of the setting by the value of `kern.hz` which defaults to 1000 ticks per second. Changing this setting results in a different effective IOPS limit. The default value is 2, resulting in a limit of: 1000 ticks/sec / 2 = 500 IOPS. Returning the pool to an <<zfs-term-online,Online>> state may be more important if another device failing could <<zfs-term-faulted,Fault>> the pool, causing data loss. A value of 0 will give the resilver operation the same priority as other operations, speeding the healing process. Other recent activity on the pool limits the speed of resilver, as determined by <<zfs-advanced-tuning-scan_idle,`vfs.zfs.scan_idle`>>. Adjust this value at any time with man:sysctl[8].
	-* [[zfs-advanced-tuning-scan_idle]] `_vfs.zfs.scan_idle_` - Number of milliseconds since the last operation before considering the pool is idle. ZFS disables the rate limiting for <<zfs-term-scrub,`scrub`>> and <<zfs-term-resilver,resilver>> when the pool is idle. Adjust this value at any time with man:sysctl[8].
	-* [[zfs-advanced-tuning-txg-timeout]] `_vfs.zfs.txg.timeout_` - Upper number of seconds between <<zfs-term-txg,transaction group>>s. The current transaction group writes to the pool and a fresh transaction group starts if this amount of time elapsed since the previous transaction group. A transaction group may trigger earlier if writing enough data. The default value is 5 seconds. A larger value may improve read performance by delaying asynchronous writes, but this may cause uneven performance when writing the transaction group. Adjust this value at any time with man:sysctl[8].
	+* [[zfs-advanced-tuning-top_maxinflight]] `_vfs.zfs.top_maxinflight_` - Upper
	+ number of outstanding I/Os per top-level crossref:zfs[zfs-term-vdev,vdev].
	+ Limits the depth of the command queue to prevent high latency. The limit is
	+ per top-level vdev, meaning the limit applies to each
	+ crossref:zfs[zfs-term-vdev-mirror,mirror],
	+ crossref:zfs[zfs-term-vdev-raidz,RAID-Z], or other vdev independently. Adjust this value at any time with man:sysctl[8].
	+* [[zfs-advanced-tuning-l2arc_write_max]] `_vfs.zfs.l2arc_write_max_` - Limit
	+ the amount of data written to the crossref:zfs[zfs-term-l2arc,L2ARC] per second. This tunable extends the longevity of SSDs by limiting the amount of data written to the device. Adjust this value at any time with man:sysctl[8].
	+* [[zfs-advanced-tuning-l2arc_write_boost]] `_vfs.zfs.l2arc_write_boost_` - Adds
	+ the value of this tunable to
	+ crossref:zfs[zfs-advanced-tuning-l2arc_write_max,`vfs.zfs.l2arc_write_max`]
	+ and increases the write speed to the SSD until evicting the first block from
	+ the crossref:zfs[zfs-term-l2arc,L2ARC]. This "Turbo Warmup Phase" reduces the
	+ performance loss from an empty crossref:zfs[zfs-term-l2arc,L2ARC] after a reboot. Adjust this value at any time with man:sysctl[8].
	+* [[zfs-advanced-tuning-scrub_delay]]`_vfs.zfs.scrub_delay_` - Number of ticks
	+ to delay between each I/O during a crossref:zfs[zfs-term-scrub,`scrub`]. To
	+ ensure that a `scrub` does not interfere with the normal operation of the
	+ pool, if any other I/O is happening the `scrub` will delay between each
	+ command. This value controls the limit on the total IOPS (I/Os Per Second)
	+ generated by the `scrub`. The granularity of the setting is determined
	+ by the value of `kern.hz` which defaults to 1000 ticks per second.
	+ Changing this setting results in a different effective IOPS limit. The
	+ default value is `4`, resulting in a limit of: 1000 ticks/sec / 4 = 250
	+ IOPS. Using a value of _20_ would give a limit of: 1000 ticks/sec / 20 =
	+ 50 IOPS. Recent activity on the pool limits the speed of `scrub`, as
	+ determined by
	+ crossref:zfs[zfs-advanced-tuning-scan_idle,`vfs.zfs.scan_idle`]. Adjust this value at any time with man:sysctl[8].
	+* [[zfs-advanced-tuning-resilver_delay]] `_vfs.zfs.resilver_delay_` - Number of
	+ milliseconds of delay inserted between each I/O during a
	+ crossref:zfs[zfs-term-resilver,resilver]. To ensure that a resilver does not
	+ interfere with the normal operation of the pool, if any other I/O is happening
	+ the resilver will delay between each command. This value controls the limit of
	+ total IOPS (I/Os Per Second) generated by the resilver. ZFS determins the
	+ granularity of the setting by the value of `kern.hz` which defaults to 1000
	+ ticks per second. Changing this setting results in a different effective IOPS
	+ limit. The default value is 2, resulting in a limit of: 1000 ticks/sec / 2 =
	+ 500 IOPS. Returning the pool to an crossref:zfs[zfs-term-online,Online] state
	+ may be more important if another device failing could
	+ crossref:zfs[zfs-term-faulted,Fault] the pool, causing data loss. A value of 0
	+ will give the resilver operation the same priority as other operations,
	+ speeding the healing process. Other recent activity on the pool limits the
	+ speed of resilver, as determined by
	+ crossref:zfs[zfs-advanced-tuning-scan_idle,`vfs.zfs.scan_idle`]. Adjust this value at any time with man:sysctl[8].
	+* [[zfs-advanced-tuning-scan_idle]] `_vfs.zfs.scan_idle_` - Number of
	+ milliseconds since the last operation before considering the pool is idle. ZFS
	+ disables the rate limiting for crossref:zfs[zfs-term-scrub,`scrub`] and
	+ crossref:zfs[zfs-term-resilver,resilver] when the pool is idle. Adjust this value at any time with man:sysctl[8].
	+* [[zfs-advanced-tuning-txg-timeout]] `_vfs.zfs.txg.timeout_` - Upper number of
	+ seconds between crossref:zfs[zfs-term-txg,transaction group]s. The current transaction group writes to the pool and a fresh transaction group starts if this amount of time elapsed since the previous transaction group. A transaction group may trigger earlier if writing enough data. The default value is 5 seconds. A larger value may improve read performance by delaying asynchronous writes, but this may cause uneven performance when writing the transaction group. Adjust this value at any time with man:sysctl[8].

	[[zfs-advanced-i386]]
	=== ZFS on i386
	@@ -2732,7 +2811,8 @@
	+
	[NOTE]
	====
	-To upgrade a regular single disk vdev to a mirror vdev at any time, use `zpool <<zfs-zpool-attach,attach>>`.
	+To upgrade a regular single disk vdev to a mirror vdev at any time, use `zpool
	+crossref:zfs[zfs-zpool-attach,attach]`.
	====

	* [[zfs-term-vdev-raidz]] _RAID-Z_ - ZFS uses RAID-Z, a variation on standard RAID-5 that offers better distribution of parity and eliminates the "RAID-5 write hole" in which the data and parity information become inconsistent after an unexpected restart. ZFS supports three levels of RAID-Z which provide varying levels of redundancy in exchange for decreasing levels of usable storage. ZFS uses RAID-Z1 through RAID-Z3 based on the number of parity devices in the array and the number of disks which can fail before the pool stops being operational.
	@@ -2743,21 +2823,54 @@
	+
	A configuration of two RAID-Z2 vdevs consisting of 8 disks each would create something like a RAID-60 array. A RAID-Z group's storage capacity is about the size of the smallest disk multiplied by the number of non-parity disks. Four 1 TB disks in RAID-Z1 has an effective size of about 3 TB, and an array of eight 1 TB disks in RAID-Z3 will yield 5 TB of usable space.
	* [[zfs-term-vdev-spare]] _Spare_ - ZFS has a special pseudo-vdev type for keeping track of available hot spares. Note that installed hot spares are not deployed automatically; manually configure them to replace the failed device using `zfs replace`.
	-* [[zfs-term-vdev-log]] _Log_ - ZFS Log Devices, also known as ZFS Intent Log (<<zfs-term-zil,ZIL>>) move the intent log from the regular pool devices to a dedicated device, typically an SSD. Having a dedicated log device improves the performance of applications with a high volume of synchronous writes like databases. Mirroring of log devices is possible, but RAID-Z is not supported. If using a lot of log devices, writes will be load-balanced across them.
	-* [[zfs-term-vdev-cache]] _Cache_ - Adding a cache vdev to a pool will add the storage of the cache to the <<zfs-term-l2arc,L2ARC>>. Mirroring cache devices is impossible. Since a cache device stores only new copies of existing data, there is no risk of data loss.
	+* [[zfs-term-vdev-log]] _Log_ - ZFS Log Devices, also known as ZFS Intent Log
	+ (crossref:zfs[zfs-term-zil,ZIL]) move the intent log from the regular pool devices to a dedicated device, typically an SSD. Having a dedicated log device improves the performance of applications with a high volume of synchronous writes like databases. Mirroring of log devices is possible, but RAID-Z is not supported. If using a lot of log devices, writes will be load-balanced across them.
	+* [[zfs-term-vdev-cache]] _Cache_ - Adding a cache vdev to a pool will add the
	+ storage of the cache to the crossref:zfs[zfs-term-l2arc,L2ARC]. Mirroring cache devices is impossible. Since a cache device stores only new copies of existing data, there is no risk of data loss.

	\|[[zfs-term-txg]] Transaction Group (TXG)
	\|Transaction Groups are the way ZFS groups blocks changes together and writes them to the pool. Transaction groups are the atomic unit that ZFS uses to ensure consistency. ZFS assigns each transaction group a unique 64-bit consecutive identifier. There can be up to three active transaction groups at a time, one in each of these three states:

	-* _Open_ - A new transaction group begins in the open state and accepts new writes. There is always a transaction group in the open state, but the transaction group may refuse new writes if it has reached a limit. Once the open transaction group has reached a limit, or reaching the <<zfs-advanced-tuning-txg-timeout,`vfs.zfs.txg.timeout`>>, the transaction group advances to the next state.
	+* _Open_ - A new transaction group begins in the open state and accepts new
	+ writes. There is always a transaction group in the open state, but the
	+ transaction group may refuse new writes if it has reached a limit. Once the
	+ open transaction group has reached a limit, or reaching the
	+ crossref:zfs[zfs-advanced-tuning-txg-timeout,`vfs.zfs.txg.timeout`], the transaction group advances to the next state.
	* _Quiescing_ - A short state that allows any pending operations to finish without blocking the creation of a new open transaction group. Once all the transactions in the group have completed, the transaction group advances to the final state.
	-* _Syncing_ - Write all the data in the transaction group to stable storage. This process will in turn change other data, such as metadata and space maps, that ZFS will also write to stable storage. The process of syncing involves several passes. On the first and biggest, all the changed data blocks; next come the metadata, which may take several passes to complete. Since allocating space for the data blocks generates new metadata, the syncing state cannot finish until a pass completes that does not use any new space. The syncing state is also where _synctasks_ complete. Synctasks are administrative operations such as creating or destroying snapshots and datasets that complete the uberblock change. Once the sync state completes the transaction group in the quiescing state advances to the syncing state. All administrative functions, such as <<zfs-term-snapshot,`snapshot`>> write as part of the transaction group. ZFS adds a created synctask to the open transaction group, and that group advances as fast as possible to the syncing state to reduce the latency of administrative commands.
	+* _Syncing_ - Write all the data in the transaction group to stable storage.
	+ This process will in turn change other data, such as metadata and space maps,
	+ that ZFS will also write to stable storage. The process of syncing involves
	+ several passes. On the first and biggest, all the changed data blocks; next
	+ come the metadata, which may take several passes to complete. Since allocating
	+ space for the data blocks generates new metadata, the syncing state cannot
	+ finish until a pass completes that does not use any new space. The syncing
	+ state is also where _synctasks_ complete. Synctasks are administrative
	+ operations such as creating or destroying snapshots and datasets that complete
	+ the uberblock change. Once the sync state completes the transaction group in
	+ the quiescing state advances to the syncing state. All administrative
	+ functions, such as crossref:zfs[zfs-term-snapshot,`snapshot`] write as part of the transaction group. ZFS adds a created synctask to the open transaction group, and that group advances as fast as possible to the syncing state to reduce the latency of administrative commands.

	\|[[zfs-term-arc]]Adaptive Replacement Cache (ARC)
	\|ZFS uses an Adaptive Replacement Cache (ARC), rather than a more traditional Least Recently Used (LRU) cache. An LRU cache is a simple list of items in the cache, sorted by how recently object was used, adding new items to the head of the list. When the cache is full, evicting items from the tail of the list makes room for more active objects. An ARC consists of four lists; the Most Recently Used (MRU) and Most Frequently Used (MFU) objects, plus a ghost list for each. These ghost lists track evicted objects to prevent adding them back to the cache. This increases the cache hit ratio by avoiding objects that have a history of occasional use. Another advantage of using both an MRU and MFU is that scanning an entire file system would evict all data from an MRU or LRU cache in favor of this freshly accessed content. With ZFS, there is also an MFU that tracks the most frequently used objects, and the cache of the most commonly accessed blocks remains.

	\|[[zfs-term-l2arc]]L2ARC
	-\|L2ARC is the second level of the ZFS caching system. RAM stores the primary ARC. Since the amount of available RAM is often limited, ZFS can also use <<zfs-term-vdev-cache,cache vdevs>>. Solid State Disks (SSDs) are often used as these cache devices due to their higher speed and lower latency compared to traditional spinning disks. L2ARC is entirely optional, but having one will increase read speeds for cached files on the SSD instead of having to read from the regular disks. L2ARC can also speed up <<zfs-term-deduplication,deduplication>> because a deduplication table (DDT) that does not fit in RAM but does fit in the L2ARC will be much faster than a DDT that must read from disk. Limits on the data rate added to the cache devices prevents prematurely wearing out SSDs with extra writes. Until the cache is full (the first block evicted to make room), writes to the L2ARC limit to the sum of the write limit and the boost limit, and afterwards limit to the write limit. A pair of man:sysctl[8] values control these rate limits. <<zfs-advanced-tuning-l2arc_write_max,`vfs.zfs.l2arc_write_max`>> controls the number of bytes written to the cache per second, while <<zfs-advanced-tuning-l2arc_write_boost,`vfs.zfs.l2arc_write_boost`>> adds to this limit during the "Turbo Warmup Phase" (Write Boost).
	+\|L2ARC is the second level of the ZFS caching system. RAM stores the primary
	+ARC. Since the amount of available RAM is often limited, ZFS can also use
	+crossref:zfs[zfs-term-vdev-cache,cache vdevs]. Solid State Disks (SSDs) are
	+often used as these cache devices due to their higher speed and lower latency
	+compared to traditional spinning disks. L2ARC is entirely optional, but having
	+one will increase read speeds for cached files on the SSD instead of having to
	+read from the regular disks. L2ARC can also speed up
	+crossref:zfs[zfs-term-deduplication,deduplication] because a deduplication table
	+(DDT) that does not fit in RAM but does fit in the L2ARC will be much faster
	+than a DDT that must read from disk. Limits on the data rate added to the cache
	+devices prevents prematurely wearing out SSDs with extra writes. Until the cache
	+is full (the first block evicted to make room), writes to the L2ARC limit to the
	+sum of the write limit and the boost limit, and afterwards limit to the write
	+limit. A pair of man:sysctl[8] values control these rate limits.
	+crossref:zfs[zfs-advanced-tuning-l2arc_write_max,`vfs.zfs.l2arc_write_max`]
	+controls the number of bytes written to the cache per second, while
	+crossref:zfs[zfs-advanced-tuning-l2arc_write_boost,`vfs.zfs.l2arc_write_boost`] adds to this limit during the "Turbo Warmup Phase" (Write Boost).

	\|[[zfs-term-zil]]ZIL
	\|ZIL accelerates synchronous transactions by using storage devices like SSDs that are faster than those used in the main storage pool. When an application requests a synchronous write (a guarantee that the data is stored to disk rather than merely cached for later writes), writing the data to the faster ZIL storage then later flushing it out to the regular disks greatly reduces latency and improves performance. Synchronous workloads like databases will profit from a ZIL alone. Regular asynchronous writes such as copying files will not use the ZIL at all.
	@@ -2766,7 +2879,15 @@
	\|Unlike a traditional file system, ZFS writes a different block rather than overwriting the old data in place. When completing this write the metadata updates to point to the new location. When a shorn write (a system crash or power loss in the middle of writing a file) occurs, the entire original contents of the file are still available and ZFS discards the incomplete write. This also means that ZFS does not require a man:fsck[8] after an unexpected shutdown.

	\|[[zfs-term-dataset]]Dataset
	-\|_Dataset_ is the generic term for a ZFS file system, volume, snapshot or clone. Each dataset has a unique name in the format _poolname/path@snapshot_. The root of the pool is a dataset as well. Child datasets have hierarchical names like directories. For example, _mypool/home_, the home dataset, is a child of _mypool_ and inherits properties from it. Expand this further by creating _mypool/home/user_. This grandchild dataset will inherit properties from the parent and grandparent. Set properties on a child to override the defaults inherited from the parent and grandparent. Administration of datasets and their children can be <<zfs-zfs-allow,delegated>>.
	+\|_Dataset_ is the generic term for a ZFS file system, volume, snapshot or clone.
	+Each dataset has a unique name in the format _poolname/path@snapshot_. The root
	+of the pool is a dataset as well. Child datasets have hierarchical names like
	+directories. For example, _mypool/home_, the home dataset, is a child of
	+_mypool_ and inherits properties from it. Expand this further by creating
	+_mypool/home/user_. This grandchild dataset will inherit properties from the
	+parent and grandparent. Set properties on a child to override the defaults
	+inherited from the parent and grandparent. Administration of datasets and their
	+children can be crossref:zfs[zfs-zfs-allow,delegated].

	\|[[zfs-term-filesystem]]File system
	\|A ZFS dataset is most often used as a file system. Like most other file systems, a ZFS file system mounts somewhere in the systems directory hierarchy and contains files and directories of its own with permissions, flags, and other metadata.
	@@ -2775,13 +2896,36 @@
	\|ZFS can also create volumes, which appear as disk devices. Volumes have a lot of the same features as datasets, including copy-on-write, snapshots, clones, and checksumming. Volumes can be useful for running other file system formats on top of ZFS, such as UFS virtualization, or exporting iSCSI extents.

	\|[[zfs-term-snapshot]]Snapshot
	-\|The <<zfs-term-cow,copy-on-write>> (COW) design of ZFS allows for nearly instantaneous, consistent snapshots with arbitrary names. After taking a snapshot of a dataset, or a recursive snapshot of a parent dataset that will include all child datasets, new data goes to new blocks, but without reclaiming the old blocks as free space. The snapshot contains the original file system version and the live file system contains any changes made since taking the snapshot using no other space. New data written to the live file system uses new blocks to store this data. The snapshot will grow as the blocks are no longer used in the live file system, but in the snapshot alone. Mount these snapshots read-only allows recovering of previous file versions. A <<zfs-zfs-snapshot,rollback>> of a live file system to a specific snapshot is possible, undoing any changes that took place after taking the snapshot. Each block in the pool has a reference counter which keeps track of the snapshots, clones, datasets, or volumes use that block. As files and snapshots get deleted, the reference count decreases, reclaiming the free space when no longer referencing a block. Marking snapshots with a <<zfs-zfs-snapshot,hold>> results in any attempt to destroy it will returns an `EBUSY` error. Each snapshot can have holds with a unique name each. The <<zfs-zfs-snapshot,release>> command removes the hold so the snapshot can deleted. Snapshots, cloning, and rolling back works on volumes, but independently mounting does not.
	+\|The crossref:zfs[zfs-term-cow,copy-on-write] (COW) design of ZFS allows for
	+nearly instantaneous, consistent snapshots with arbitrary names. After taking a
	+snapshot of a dataset, or a recursive snapshot of a parent dataset that will
	+include all child datasets, new data goes to new blocks, but without reclaiming
	+the old blocks as free space. The snapshot contains the original file system
	+version and the live file system contains any changes made since taking the
	+snapshot using no other space. New data written to the live file system uses new
	+blocks to store this data. The snapshot will grow as the blocks are no longer
	+used in the live file system, but in the snapshot alone. Mount these snapshots
	+read-only allows recovering of previous file versions. A
	+crossref:zfs[zfs-zfs-snapshot,rollback] of a live file system to a specific
	+snapshot is possible, undoing any changes that took place after taking the
	+snapshot. Each block in the pool has a reference counter which keeps track of
	+the snapshots, clones, datasets, or volumes use that block. As files and
	+snapshots get deleted, the reference count decreases, reclaiming the free space
	+when no longer referencing a block. Marking snapshots with a
	+crossref:zfs[zfs-zfs-snapshot,hold] results in any attempt to destroy it will
	+returns an `EBUSY` error. Each snapshot can have holds with a unique name each.
	+The crossref:zfs[zfs-zfs-snapshot,release] command removes the hold so the snapshot can deleted. Snapshots, cloning, and rolling back works on volumes, but independently mounting does not.

	\|[[zfs-term-clone]]Clone
	\|Cloning a snapshot is also possible. A clone is a writable version of a snapshot, allowing the file system to fork as a new dataset. As with a snapshot, a clone initially consumes no new space. As new data written to a clone uses new blocks, the size of the clone grows. When blocks are overwritten in the cloned file system or volume, the reference count on the previous block decreases. Removing the snapshot upon which a clone bases is impossible because the clone depends on it. The snapshot is the parent, and the clone is the child. Clones can be _promoted_, reversing this dependency and making the clone the parent and the previous parent the child. This operation requires no new space. Since the amount of space used by the parent and child reverses, it may affect existing quotas and reservations.

	\|[[zfs-term-checksum]]Checksum
	-\|Every block is also checksummed. The checksum algorithm used is a per-dataset property, see <<zfs-zfs-set,`set`>>. The checksum of each block is transparently validated when read, allowing ZFS to detect silent corruption. If the data read does not match the expected checksum, ZFS will attempt to recover the data from any available redundancy, like mirrors or RAID-Z. Triggering a validation of all checksums with <<zfs-term-scrub,`scrub`>>. Checksum algorithms include:
	+\|Every block is also checksummed. The checksum algorithm used is a per-dataset
	+property, see crossref:zfs[zfs-zfs-set,`set`]. The checksum of each block is
	+transparently validated when read, allowing ZFS to detect silent corruption. If
	+the data read does not match the expected checksum, ZFS will attempt to recover
	+the data from any available redundancy, like mirrors or RAID-Z. Triggering a
	+validation of all checksums with crossref:zfs[zfs-term-scrub,`scrub`]. Checksum algorithms include:

	* `fletcher2`
	* `fletcher4`
	@@ -2804,18 +2948,31 @@
	* _ZLE_ - Zero Length Encoding is a special compression algorithm that compresses continuous runs of zeros alone. This compression algorithm is useful when the dataset contains large blocks of zeros.

	\|[[zfs-term-copies]]Copies
	-\|When set to a value greater than 1, the `copies` property instructs ZFS to maintain copies of each block in the <<zfs-term-filesystem,file system>> or <<zfs-term-volume,volume>>. Setting this property on important datasets provides added redundancy from which to recover a block that does not match its checksum. In pools without redundancy, the copies feature is the single form of redundancy. The copies feature can recover from a single bad sector or other forms of minor corruption, but it does not protect the pool from the loss of an entire disk.
	-
	+\|When set to a value greater than 1, the `copies` property instructs ZFS to
	+maintain copies of each block in the crossref:zfs[zfs-term-filesystem,file
	+system] or crossref:zfs[zfs-term-volume,volume]. Setting this property on important datasets provides added redundancy from which to recover a block that does not match its checksum. In pools without redundancy, the copies feature is the single form of redundancy. The copies feature can recover from a single bad sector or other forms of minor corruption, but it does not protect the pool from the loss of an entire disk.
	\|[[zfs-term-deduplication]]Deduplication
	\|Checksums make it possible to detect duplicate blocks when writing data. With deduplication, the reference count of an existing, identical block increases, saving storage space. ZFS keeps a deduplication table (DDT) in memory to detect duplicate blocks. The table contains a list of unique checksums, the location of those blocks, and a reference count. When writing new data, ZFS calculates checksums and compares them to the list. When finding a match it uses the existing block. Using the SHA256 checksum algorithm with deduplication provides a secure cryptographic hash. Deduplication is tunable. If `dedup` is `on`, then a matching checksum means that the data is identical. Setting `dedup` to `verify`, ZFS performs a byte-for-byte check on the data ensuring they are actually identical. If the data is not identical, ZFS will note the hash collision and store the two blocks separately. As the DDT must store the hash of each unique block, it consumes a large amount of memory. A general rule of thumb is 5-6 GB of ram per 1 TB of deduplicated data). In situations not practical to have enough RAM to keep the entire DDT in memory, performance will suffer greatly as the DDT must read from disk before writing each new block. Deduplication can use L2ARC to store the DDT, providing a middle ground between fast system memory and slower disks. Consider using compression instead, which often provides nearly as much space savings without the increased memory.

	\|[[zfs-term-scrub]]Scrub
	-\|Instead of a consistency check like man:fsck[8], ZFS has `scrub`. `scrub` reads all data blocks stored on the pool and verifies their checksums against the known good checksums stored in the metadata. A periodic check of all the data stored on the pool ensures the recovery of any corrupted blocks before needing them. A scrub is not required after an unclean shutdown, but good practice is at least once every three months. ZFS verifies the checksum of each block during normal use, but a scrub makes certain to check even infrequently used blocks for silent corruption. ZFS improves data security in archival storage situations. Adjust the relative priority of `scrub` with <<zfs-advanced-tuning-scrub_delay,`vfs.zfs.scrub_delay`>> to prevent the scrub from degrading the performance of other workloads on the pool.
	+\|Instead of a consistency check like man:fsck[8], ZFS has `scrub`. `scrub` reads
	+all data blocks stored on the pool and verifies their checksums against the
	+known good checksums stored in the metadata. A periodic check of all the data
	+stored on the pool ensures the recovery of any corrupted blocks before needing
	+them. A scrub is not required after an unclean shutdown, but good practice is at
	+least once every three months. ZFS verifies the checksum of each block during
	+normal use, but a scrub makes certain to check even infrequently used blocks for
	+silent corruption. ZFS improves data security in archival storage situations.
	+Adjust the relative priority of `scrub` with
	+crossref:zfs[zfs-advanced-tuning-scrub_delay,`vfs.zfs.scrub_delay`] to prevent the scrub from degrading the performance of other workloads on the pool.

	\|[[zfs-term-quota]]Dataset Quota
	a\|ZFS provides fast and accurate dataset, user, and group space accounting as well as quotas and space reservations. This gives the administrator fine grained control over space allocation and allows reserving space for critical file systems.

	-ZFS supports different types of quotas: the dataset quota, the <<zfs-term-refquota,reference quota (refquota)>>, the <<zfs-term-userquota,user quota>>, and the <<zfs-term-groupquota,group quota>>.
	+ZFS supports different types of quotas: the dataset quota, the
	+crossref:zfs[zfs-term-refquota,reference quota (refquota)], the
	+crossref:zfs[zfs-term-userquota,user quota], and the
	+crossref:zfs[zfs-term-groupquota,group quota].

	Quotas limit the total size of a dataset and its descendants, including snapshots of the dataset, child datasets, and the snapshots of those datasets.

	@@ -2834,12 +2991,20 @@
	\|The group quota limits the amount of space that a specified group can consume.

	\|[[zfs-term-reservation]]Dataset Reservation
	-\|The `reservation` property makes it possible to guarantee an amount of space for a specific dataset and its descendants. This means that setting a 10 GB reservation on [.filename]#storage/home/bob# prevents other datasets from using up all free space, reserving at least 10 GB of space for this dataset. Unlike a regular <<zfs-term-refreservation,`refreservation`>>, space used by snapshots and descendants is not counted against the reservation. For example, if taking a snapshot of [.filename]#storage/home/bob#, enough disk space other than the `refreservation` amount must exist for the operation to succeed. Descendants of the main data set are not counted in the `refreservation` amount and so do not encroach on the space set.
	+\|The `reservation` property makes it possible to guarantee an amount of space
	+for a specific dataset and its descendants. This means that setting a 10 GB
	+reservation on [.filename]#storage/home/bob# prevents other datasets from using
	+up all free space, reserving at least 10 GB of space for this dataset. Unlike a
	+regular crossref:zfs[zfs-term-refreservation,`refreservation`], space used by snapshots and descendants is not counted against the reservation. For example, if taking a snapshot of [.filename]#storage/home/bob#, enough disk space other than the `refreservation` amount must exist for the operation to succeed. Descendants of the main data set are not counted in the `refreservation` amount and so do not encroach on the space set.

	Reservations of any sort are useful in situations such as planning and testing the suitability of disk space allocation in a new system, or ensuring that enough space is available on file systems for audio logs or system recovery procedures and files.

	\|[[zfs-term-refreservation]]Reference Reservation
	-\|The `refreservation` property makes it possible to guarantee an amount of space for the use of a specific dataset _excluding_ its descendants. This means that setting a 10 GB reservation on [.filename]#storage/home/bob#, and another dataset tries to use the free space, reserving at least 10 GB of space for this dataset. In contrast to a regular <<zfs-term-reservation,reservation>>, space used by snapshots and descendant datasets is not counted against the reservation. For example, if taking a snapshot of [.filename]#storage/home/bob#, enough disk space other than the `refreservation` amount must exist for the operation to succeed. Descendants of the main data set are not counted in the `refreservation` amount and so do not encroach on the space set.
	+\|The `refreservation` property makes it possible to guarantee an amount of space
	+for the use of a specific dataset _excluding_ its descendants. This means that
	+setting a 10 GB reservation on [.filename]#storage/home/bob#, and another
	+dataset tries to use the free space, reserving at least 10 GB of space for this
	+dataset. In contrast to a regular crossref:zfs[zfs-term-reservation,reservation], space used by snapshots and descendant datasets is not counted against the reservation. For example, if taking a snapshot of [.filename]#storage/home/bob#, enough disk space other than the `refreservation` amount must exist for the operation to succeed. Descendants of the main data set are not counted in the `refreservation` amount and so do not encroach on the space set.

	\|[[zfs-term-resilver]]Resilver
	\|When replacing a failed disk, ZFS must fill the new disk with the lost data. _Resilvering_ is the process of using the parity information distributed across the remaining drives to calculate and write the missing data to the new drive.
	@@ -2847,11 +3012,22 @@
	\|A pool or vdev in the `Online` state has its member devices connected and fully operational. Individual devices in the `Online` state are functioning.

	\|[[zfs-term-offline]]Offline
	-\|The administrator puts individual devices in an `Offline` state if enough redundancy exists to avoid putting the pool or vdev into a <<zfs-term-faulted,Faulted>> state. An administrator may choose to offline a disk in preparation for replacing it, or to make it easier to identify.
	+\|The administrator puts individual devices in an `Offline` state if enough
	+redundancy exists to avoid putting the pool or vdev into a
	+crossref:zfs[zfs-term-faulted,Faulted] state. An administrator may choose to offline a disk in preparation for replacing it, or to make it easier to identify.

	\|[[zfs-term-degraded]]Degraded
	-\|A pool or vdev in the `Degraded` state has one or more disks that disappeared or failed. The pool is still usable, but if other devices fail, the pool may become unrecoverable. Reconnecting the missing devices or replacing the failed disks will return the pool to an <<zfs-term-online,Online>> state after the reconnected or new device has completed the <<zfs-term-resilver,Resilver>> process.
	+\|A pool or vdev in the `Degraded` state has one or more disks that disappeared
	+or failed. The pool is still usable, but if other devices fail, the pool may
	+become unrecoverable. Reconnecting the missing devices or replacing the failed
	+disks will return the pool to an crossref:zfs[zfs-term-online,Online] state
	+after the reconnected or new device has completed the
	+crossref:zfs[zfs-term-resilver,Resilver] process.

	\|[[zfs-term-faulted]]Faulted
	-\|A pool or vdev in the `Faulted` state is no longer operational. Accessing the data is no longer possible. A pool or vdev enters the `Faulted` state when the number of missing or failed devices exceeds the level of redundancy in the vdev. If reconnecting missing devices the pool will return to an <<zfs-term-online,Online>> state. Insufficient redundancy to compensate for the number of failed disks loses the pool contents and requires restoring from backups.
	+\|A pool or vdev in the `Faulted` state is no longer operational. Accessing the
	+data is no longer possible. A pool or vdev enters the `Faulted` state when the
	+number of missing or failed devices exceeds the level of redundancy in the vdev.
	+If reconnecting missing devices the pool will return to an
	+crossref:zfs[zfs-term-online,Online] state. Insufficient redundancy to compensate for the number of failed disks loses the pool contents and requires restoring from backups.
	\|===
	diff --git a/documentation/content/en/books/porters-handbook/flavors/_index.adoc b/documentation/content/en/books/porters-handbook/flavors/_index.adoc
	--- a/documentation/content/en/books/porters-handbook/flavors/_index.adoc
	+++ b/documentation/content/en/books/porters-handbook/flavors/_index.adoc
	@@ -119,7 +119,8 @@
	.More Complex Flavors Usage
	[example]
	====
	-Here is a slightly edited excerpt of what is present in package:devel/libpeas[], a port that uses the <<flavors-auto-python,Python flavors>>.
	+Here is a slightly edited excerpt of what is present in package:devel/libpeas[],
	+a port that uses the crosref:flavors[flavors-auto-python,Python flavors].
	With the default Python 2 and 3 versions being 2.7 and 3.6, it will automatically get `FLAVORS=py27 py36`

	[.programlisting]
	@@ -154,7 +155,9 @@
	The Gnome Python gobject3 bindings have two different names, one for Python 2, pygobject3 and one for Python 3, py3gobject3.
	The `configure` script has to run in [.filename]#${WRKSRC}#, but we are only interested in building and installing the Python 2 or Python 3 parts of the software, so set the build and install base directories appropriately.
	Hint about the correct Python 3 config script path name.
	-The packing list is different when the built with Python 3. As there are three possible Python 3 versions, set `PLIST` for all three using the <<flavors-using-helpers,helper>>.
	+The packing list is different when the built with Python 3. As there are three
	+possible Python 3 versions, set `PLIST` for all three using the
	+crosref:flavors[flavors-using-helpers,helper].
	====

	[[flavors-using-helpers]]
	diff --git a/documentation/content/en/books/porters-handbook/makefiles/_index.adoc b/documentation/content/en/books/porters-handbook/makefiles/_index.adoc
	--- a/documentation/content/en/books/porters-handbook/makefiles/_index.adoc
	+++ b/documentation/content/en/books/porters-handbook/makefiles/_index.adoc
	@@ -72,13 +72,14 @@
	=== `PORTNAME`

	Set `PORTNAME` to the base name of the software.
	-It is used as the base for the FreeBSD package, and for <<makefile-distname,`DISTNAME`>>.
	+It is used as the base for the FreeBSD package, and for crossref:makefiles[makefile-distname,`DISTNAME`].

	[IMPORTANT]
	====
	The package name must be unique across the entire ports tree.
	Make sure that the `PORTNAME` is not already in use by an existing port, and that no other port already has the same `PKGBASE`.
	-If the name has already been used, add either <<porting-pkgnameprefix-suffix,`PKGNAMEPREFIX` or `PKGNAMESUFFIX`>>.
	+If the name has already been used, add either
	+crossref:makefiles[porting-pkgnameprefix-suffix,`PKGNAMEPREFIX` or `PKGNAMESUFFIX`].
	====

	[[makefile-versions]]
	@@ -100,7 +101,7 @@
	[TIP]
	====
	When updating a port, it is possible to use man:pkg-version[8]'s `-t` argument to check if the new version is greater or lesser than before.
	-See <<makefile-versions-ex-pkg-version>>.
	+See crossref:makefiles[makefile-versions-ex-pkg-version].
	====

	[[makefile-versions-ex-pkg-version]]
	@@ -278,7 +279,10 @@
	<.> `1.2` is before `1.2p4`, which is what was needed.
	====

	-For some more advanced examples of setting `PORTVERSION`, when the software's versioning is really not compatible with FreeBSD's, or `DISTNAME` when the distribution file does not contain the version itself, see <<makefile-distname>>.
	+For some more advanced examples of setting `PORTVERSION`, when the software's
	+versioning is really not compatible with FreeBSD's, or `DISTNAME` when the
	+distribution file does not contain the version itself, see
	+crossref:makefiles[makefile-distname].

	[[makefile-naming-revepoch]]
	=== `PORTREVISION` and `PORTEPOCH`
	@@ -290,7 +294,8 @@
	Changes to `PORTREVISION` are used by automated tools like man:pkg-version[8] to determine that a new package is available.

	`PORTREVISION` must be increased each time a change is made to the port that changes the generated package in any way.
	-That includes changes that only affect a package built with non-default <<makefile-options,options>>.
	+That includes changes that only affect a package built with non-default
	+crossref:makefiles[makefile-options,options].

	Examples of when `PORTREVISION` must be bumped:

	@@ -416,7 +421,7 @@
	=== `PKGNAMEPREFIX` and `PKGNAMESUFFIX`

	Two optional variables, `PKGNAMEPREFIX` and `PKGNAMESUFFIX`, are combined with `PORTNAME` and `PORTVERSION` to form `PKGNAME` as `${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}`.
	-Make sure this conforms to our <<porting-pkgname,guidelines for a good package name>>.
	+Make sure this conforms to our crossref:makefiles[porting-pkgname,guidelines for a good package name].
	In particular, the use of a hyphen (`-`) in `PORTVERSION` is _not_ allowed.
	Also, if the package name has the _language-_ or the _-compiled.specifics_ part (see below), use `PKGNAMEPREFIX` and `PKGNAMESUFFIX`, respectively.
	Do not make them part of `PORTNAME`.
	@@ -454,7 +459,8 @@
	For example, the `Data::Dumper` module becomes `p5-Data-Dumper`.
	[[porting-pkgname-compiled-specifics]]
	[.filename]#-compiled.specifics#::
	-If the port can be built with different <<makefile-masterdir,hardcoded defaults>> (usually part of the directory name in a family of ports), the _-compiled.specifics_ part states the compiled-in defaults.
	+If the port can be built with different
	+crossref:makefiles[makefile-masterdir,hardcoded defaults] (usually part of the directory name in a family of ports), the _-compiled.specifics_ part states the compiled-in defaults.
	The hyphen is optional.
	Examples are paper size and font units.
	+
	@@ -474,7 +480,9 @@

	[IMPORTANT]
	====
	-Package name must be unique among all of the ports tree, check that there is not already a port with the same `PORTNAME` and if there is add one of <<porting-pkgnameprefix-suffix,`PKGNAMEPREFIX` or `PKGNAMESUFFIX`>>.
	+Package name must be unique among all of the ports tree, check that there is not
	+already a port with the same `PORTNAME` and if there is add one of
	+crossref:makefiles[porting-pkgnameprefix-suffix,`PKGNAMEPREFIX` or `PKGNAMESUFFIX`].
	====

	Here are some (real) examples on how to convert the name as called by the software authors to a suitable package name, for each line, only one of `DISTVERSION` or `PORTVERSION` is set in, depending on which would be used in the port's [.filename]#Makefile#:
	@@ -613,11 +621,11 @@
	When a package is created, it is put under [.filename]#/usr/ports/packages/All# and links are made from one or more subdirectories of [.filename]#/usr/ports/packages#.
	The names of these subdirectories are specified by the variable `CATEGORIES`.
	It is intended to make life easier for the user when he is wading through the pile of packages on the FTP site or the CDROM.
	-Please take a look at the <<porting-categories,current list of categories>> and pick the ones that are suitable for the port.
	+Please take a look at the crossref:makefiles[porting-categories,current list of categories] and pick the ones that are suitable for the port.

	This list also determines where in the ports tree the port is imported.
	If there is more than one category here, the port files must be put in the subdirectory with the name of the first category.
	-See <<choosing-categories,below>> for more discussion about how to pick the right categories.
	+See crossref:makefiles[choosing-categories,below] for more discussion about how to pick the right categories.

	[[porting-categories]]
	=== Current List of Categories
	@@ -1030,7 +1038,8 @@
	There are several rules that govern this issue.
	Here is the list of priorities, in decreasing order of precedence:

	-* The first category must be a physical category (see <<porting-categories,above>>). This is necessary to make the packaging work. Virtual categories and physical categories may be intermixed after that.
	+* The first category must be a physical category (see
	+ crossref:makefiles[porting-categories,above]). This is necessary to make the packaging work. Virtual categories and physical categories may be intermixed after that.
	* Language specific categories always come first. For example, if the port installs Japanese X11 fonts, then the `CATEGORIES` line would read [.filename]#japanese x11-fonts#.
	* Specific categories are listed before less-specific ones. For instance, an HTML editor is listed as [.filename]#www editors#, not the other way around. Also, do not list [.filename]#net# when the port belongs to any of [.filename]#irc#, [.filename]#mail#, [.filename]#news#, [.filename]#security#, or [.filename]#www#, as [.filename]#net# is included implicitly.
	* [.filename]#x11# is used as a secondary category only when the primary category is a natural language. In particular, do not put [.filename]#x11# in the category line for X applications.
	@@ -1203,7 +1212,8 @@
	.Exotic Case 2
	[example]
	====
	-In package:comms/librs232[], the distribution file is not versioned, so using <<makefile-dist_subdir,`DIST_SUBDIR`>> is needed:
	+In package:comms/librs232[], the distribution file is not versioned, so using
	+crossref:makefiles[makefile-dist_subdir,`DIST_SUBDIR`] is needed:

	[.programlisting]
	....
	@@ -1470,7 +1480,9 @@
	\|`${DISTVERSIONPREFIX}${DISTVERSION}${DISTVERSIONSUFFIX}`

	\|`GH_SUBDIR`
	-\|When the software needs an additional distribution file to be extracted within `${WRKSRC}`, this variable can be used. See the examples in <<makefile-master_sites-github-multiple>> for more information.
	+\|When the software needs an additional distribution file to be extracted within
	+`${WRKSRC}`, this variable can be used. See the examples in
	+crossref:makefiles[makefile-master_sites-github-multiple] for more information.
	\|(none)

	\|`GH_TUPLE`
	@@ -1564,7 +1576,8 @@
	GH_TAGNAME= c472d66b
	....

	-This creates a versioning scheme that increases over time, and that is still before version `0` (see <<makefile-versions-ex-pkg-version>> for details on man:pkg-version[8]):
	+This creates a versioning scheme that increases over time, and that is still
	+before version `0` (see crossref:makefiles[makefile-versions-ex-pkg-version] for details on man:pkg-version[8]):

	[source,shell]
	....
	@@ -1609,7 +1622,7 @@
	....

	This creates a versioning scheme that increases over time (well, over commits), and does not conflict with the creation of a `0.7.4` version.
	-(See <<makefile-versions-ex-pkg-version>> for details on man:pkg-version[8]):
	+(See crossref:makefiles[makefile-versions-ex-pkg-version] for details on man:pkg-version[8]):

	[source,shell]
	....
	@@ -1641,12 +1654,13 @@
	==== Fetching Multiple Files from GitHub

	The `USE_GITHUB` framework also supports fetching multiple distribution files from different places in GitHub.
	-It works in a way very similar to <<porting-master-sites-n>>.
	+It works in a way very similar to crossref:makefiles[porting-master-sites-n].

	Multiple values are added to `GH_ACCOUNT`, `GH_PROJECT`, and `GH_TAGNAME`.
	Each different value is assigned a group.
	The main value can either have no group, or the `:DEFAULT` group.
	-A value can be omitted if it is the same as the default as listed in <<makefile-master_sites-github-description>>.
	+A value can be omitted if it is the same as the default as listed in
	+crossref:makefiles[makefile-master_sites-github-description].

	`GH_TUPLE` can also be used when there are a lot of distribution files.
	It helps keep the account, project, tagname, and group information at the same place.
	@@ -1662,7 +1676,9 @@

	[NOTE]
	====
	-As this is only syntactic sugar above `DISTFILES` and `MASTER_SITES`, the group names must adhere to the restrictions on group names outlined in <<porting-master-sites-n>>
	+As this is only syntactic sugar above `DISTFILES` and `MASTER_SITES`, the group
	+names must adhere to the restrictions on group names outlined in
	+crossref:makefiles[porting-master-sites-n]
	====

	When fetching multiple files from GitHub, sometimes the default distribution file is not fetched from GitHub.
	@@ -1735,7 +1751,8 @@
	[example]
	====

	-This is functionally equivalent to <<makefile-master_sites-github-multi>>, but using `GH_TUPLE`:
	+This is functionally equivalent to
	+crossref:makefiles[makefile-master_sites-github-multi], but using `GH_TUPLE`:

	[.programlisting]
	....
	@@ -1876,7 +1893,9 @@
	\|`(none)`

	\|`GL_SUBDIR`
	-\|When the software needs an additional distribution file to be extracted within `${WRKSRC}`, this variable can be used. See the examples in <<makefile-master_sites-gitlab-multiple>> for more information.
	+\|When the software needs an additional distribution file to be extracted within
	+`${WRKSRC}`, this variable can be used. See the examples in
	+ crossref:makefiles[makefile-master_sites-gitlab-multiple] for more information.
	\|(none)

	\|`GL_TUPLE`
	@@ -1940,10 +1959,12 @@
	==== Fetching Multiple Files from GitLab

	The `USE_GITLAB` framework also supports fetching multiple distribution files from different places from GitLab and GitLab hosted sites.
	-It works in a way very similar to <<porting-master-sites-n>> and <<makefile-master_sites-gitlab-multiple>>.
	+It works in a way very similar to crossref:makefiles[porting-master-sites-n] and
	+crossref:makefiles[makefile-master_sites-gitlab-multiple].

	Multiple values are added to `GL_SITE`, `GL_ACCOUNT`, `GL_PROJECT` and `GL_COMMIT`.
	-Each different value is assigned a group. <<makefile-master_sites-gitlab-description>>.
	+Each different value is assigned a group.
	+crossref:makefiles[makefile-master_sites-gitlab-description].

	`GL_TUPLE` can also be used when there are a lot of distribution files.
	It helps keep the site, account, project, commit, and group information at the same place.
	@@ -1959,7 +1980,9 @@

	[NOTE]
	====
	-As this is only syntactic sugar above `DISTFILES` and `MASTER_SITES`, the group names must adhere to the restrictions on group names outlined in <<porting-master-sites-n>>
	+As this is only syntactic sugar above `DISTFILES` and `MASTER_SITES`, the group
	+names must adhere to the restrictions on group names outlined in
	+crossref:makefiles[porting-master-sites-n]
	====

	When fetching multiple files using GitLab, sometimes the default distribution file is not fetched from a GitLab site.
	@@ -1972,7 +1995,8 @@

	[IMPORTANT]
	====
	-When using `USE_GITLAB=nodefault`, the [.filename]#Makefile# must set `DISTFILES` in its <<porting-order-portname,top block>>.
	+When using `USE_GITLAB=nodefault`, the [.filename]#Makefile# must set
	+`DISTFILES` in its crossref:makefiles[porting-order-portname,top block].
	The definition should be:

	[.programlisting]
	@@ -2033,7 +2057,8 @@
	.Use of `USE_GITLAB` with Multiple Distribution Files Using `GL_TUPLE`
	[example]
	====
	-This is functionally equivalent to <<makefile-master_sites-gitlab-multi>>, but using `GL_TUPLE`:
	+This is functionally equivalent to
	+crossref:makefiles[makefile-master_sites-gitlab-multi], but using `GL_TUPLE`:

	[.programlisting]
	....
	@@ -2132,7 +2157,7 @@
	PATCHFILES= patch1 patch2:-p1
	....

	-This does not conflict with <<porting-master-sites-n,the master site grouping feature>>, adding a group also works:
	+This does not conflict with crossref:makefiles[porting-master-sites-n,the master site grouping feature], adding a group also works:

	[.programlisting]
	....
	@@ -2190,7 +2215,8 @@
	This section explains how to quickly prepare fine grained fetching of multiple distribution files and patches from different sites and subdirectories.
	We describe here a case of simplified `MASTER_SITES:n` usage.
	This will be sufficient for most scenarios.
	-More detailed information are available in <<ports-master-sites-n-detailed>>.
	+More detailed information are available in
	+crossref:makefiles[ports-master-sites-n-detailed].

	Some applications consist of multiple distribution files that must be downloaded from a number of different sites.
	For example, Ghostscript consists of the core of the program, and then a large number of driver files that are used depending on the user's printer.
	@@ -2200,7 +2226,8 @@
	Each site listed in `MASTER_SITES` is then followed by a colon, and the group that indicates which distribution files are downloaded from this site.

	For example, consider an application with the source split in two parts, [.filename]#source1.tar.gz# and [.filename]#source2.tar.gz#, which must be downloaded from two different sites.
	-The port's [.filename]#Makefile# would include lines like <<ports-master-sites-n-example-simple-use-one-file-per-site>>.
	+The port's [.filename]#Makefile# would include lines like
	+crossref:makefiles[ports-master-sites-n-example-simple-use-one-file-per-site].

	[[ports-master-sites-n-example-simple-use-one-file-per-site]]
	.Simplified Use of `MASTER_SITES:n` with One File Per Site
	@@ -2219,7 +2246,8 @@

	Multiple distribution files can have the same group.
	Continuing the previous example, suppose that there was a third distfile, [.filename]#source3.tar.gz#, that is downloaded from `ftp.example2.com`.
	-The [.filename]#Makefile# would then be written like <<ports-master-sites-n-example-simple-use-more-than-one-file-per-site>>.
	+The [.filename]#Makefile# would then be written like
	+crossref:makefiles[ports-master-sites-n-example-simple-use-more-than-one-file-per-site].

	[[ports-master-sites-n-example-simple-use-more-than-one-file-per-site]]
	.Simplified Use of `MASTER_SITES:n` with More Than One File Per Site
	@@ -2246,12 +2274,18 @@
	+
	Moreover, string matching is case sensitive; that is, `n` is different from `N`.
	+
	-However, these words cannot be used for postfixing purposes since they yield special meaning: `default`, `all` and `ALL` (they are used internally in item <<porting-master-sites-n-what-changes-in-port-targets, ii>>).
	-Furthermore, `DEFAULT` is a special purpose word (check item <<porting-master-sites-n-DEFAULT-group,3>>).
	+However, these words cannot be used for postfixing purposes since they yield
	+special meaning: `default`, `all` and `ALL` (they are used internally in item
	+crossref:makefiles[porting-master-sites-n-what-changes-in-port-targets, ii]).
	+Furthermore, `DEFAULT` is a special purpose word (check item
	+crossref:makefiles[porting-master-sites-n-DEFAULT-group,3]).
	. Elements postfixed with `:n` belong to the group `n`, `:m` belong to group `m` and so forth.
	+
	[[porting-master-sites-n-DEFAULT-group]]
	-. Elements without a postfix are groupless, they all belong to the special group `DEFAULT`. Any elements postfixed with `DEFAULT`, is just being redundant unless an element belongs to both `DEFAULT` and other groups at the same time (check item <<porting-master-sites-n-comma-operator,5>>).
	+. Elements without a postfix are groupless, they all belong to the special group
	+ `DEFAULT`. Any elements postfixed with `DEFAULT`, is just being redundant
	+ unless an element belongs to both `DEFAULT` and other groups at the same time
	+ (check item crossref:makefiles[porting-master-sites-n-comma-operator,5]).
	+
	These examples are equivalent but the first one is preferred:
	+
	@@ -2299,7 +2333,20 @@
	+
	[[porting-master-sites-n-group-semantics]]
	. Group semantics can be used in any of the variables `MASTER_SITES`, `PATCH_SITES`, `MASTER_SITE_SUBDIR`, `PATCH_SITE_SUBDIR`, `DISTFILES`, and `PATCHFILES` according to this syntax:
	-.. All `MASTER_SITES`, `PATCH_SITES`, `MASTER_SITE_SUBDIR` and `PATCH_SITE_SUBDIR` elements must be terminated with the forward slash `/` character. If any elements belong to any groups, the group postfix `:__n__` must come right after the terminator `/`. The `MASTER_SITES:n` mechanism relies on the existence of the terminator `/` to avoid confusing elements where a `:n` is a valid part of the element with occurrences where `:n` denotes group `n`. For compatibility purposes, since the `/` terminator was not required before in both `MASTER_SITE_SUBDIR` and `PATCH_SITE_SUBDIR` elements, if the postfix immediate preceding character is not a `/` then `:n` will be considered a valid part of the element instead of a group postfix even if an element is postfixed with `:n`. See both <<ports-master-sites-n-example-detailed-use-master-site-subdir>> and <<ports-master-sites-n-example-detailed-use-complete-example-master-sites>>.
	+.. All `MASTER_SITES`, `PATCH_SITES`, `MASTER_SITE_SUBDIR` and
	+ `PATCH_SITE_SUBDIR` elements must be terminated with the forward slash `/`
	+ character. If any elements belong to any groups, the group postfix `:__n__`
	+ must come right after the terminator `/`. The `MASTER_SITES:n` mechanism
	+ relies on the existence of the terminator `/` to avoid confusing elements
	+ where a `:n` is a valid part of the element with occurrences where `:n`
	+ denotes group `n`. For compatibility purposes, since the `/` terminator was
	+ not required before in both `MASTER_SITE_SUBDIR` and `PATCH_SITE_SUBDIR`
	+ elements, if the postfix immediate preceding character is not a `/` then `:n`
	+ will be considered a valid part of the element instead of a group postfix
	+ even if an element is postfixed with `:n`. See both
	+ crossref:makefiles[ports-master-sites-n-example-detailed-use-master-site-subdir]
	+ and
	+ crossref:makefiles[ports-master-sites-n-example-detailed-use-complete-example-master-sites].
	+
	[[ports-master-sites-n-example-detailed-use-master-site-subdir]]
	.Detailed Use of `MASTER_SITES:n` in `MASTER_SITE_SUBDIR`
	@@ -2392,7 +2439,8 @@
	. How do I group one of the special macros from [.filename]#bsd.sites.mk#, for example, SourceForge (`SF`)?
	+
	This has been simplified as much as possible.
	-See <<ports-master-sites-n-example-detailed-use-master-site-sourceforge>>.
	+See
	+crossref:makefiles[ports-master-sites-n-example-detailed-use-master-site-sourceforge].
	+
	[[ports-master-sites-n-example-detailed-use-master-site-sourceforge]]
	.Detailed Use of `MASTER_SITES:n` with SourceForge (`SF`)
	@@ -2409,7 +2457,9 @@
	====
	. How do I use this with `PATCH*`?
	+
	-All examples were done with `MASTER` but they work exactly the same for `PATCH` ones as can be seen in <<ports-master-sites-n-example-detailed-use-patch-sites>>.
	+All examples were done with `MASTER*` but they work exactly the same for
	+`PATCH*` ones as can be seen in
	+crossref:makefiles[ports-master-sites-n-example-detailed-use-patch-sites].
	+
	[[ports-master-sites-n-example-detailed-use-patch-sites]]
	.Simplified Use of `MASTER_SITES:n` with `PATCH_SITES`
	@@ -2428,18 +2478,26 @@
	==== What Does Change for Ports? What Does Not?

	[lowerroman]
	-. All current ports remain the same. The `MASTER_SITES:n` feature code is only activated if there are elements postfixed with `:__n__` like elements according to the aforementioned syntax rules, especially as shown in item <<porting-master-sites-n-group-semantics, 7>>.
	+. All current ports remain the same. The `MASTER_SITES:n` feature code is only
	+ activated if there are elements postfixed with `:__n__` like elements
	+ according to the aforementioned syntax rules, especially as shown in item
	+ crossref:makefiles[porting-master-sites-n-group-semantics, 7].
	+
	[[porting-master-sites-n-what-changes-in-port-targets]]
	. The port targets remain the same: `checksum`, `makesum`, `patch`, `configure`, `build`, etc. With the obvious exceptions of `do-fetch`, `fetch-list`, `master-sites` and `patch-sites`.

	-** `do-fetch`: deploys the new grouping postfixed `DISTFILES` and `PATCHFILES` with their matching group elements within both `MASTER_SITES` and `PATCH_SITES` which use matching group elements within both `MASTER_SITE_SUBDIR` and `PATCH_SITE_SUBDIR`. Check <<ports-master-sites-n-example-detailed-use-complete-example-master-sites>>.
	+** `do-fetch`: deploys the new grouping postfixed `DISTFILES` and `PATCHFILES`
	+ with their matching group elements within both `MASTER_SITES` and
	+ `PATCH_SITES` which use matching group elements within both
	+ `MASTER_SITE_SUBDIR` and `PATCH_SITE_SUBDIR`. Check
	+ crossref:makefiles[ports-master-sites-n-example-detailed-use-complete-example-master-sites].
	** `fetch-list`: works like old `fetch-list` with the exception that it groups just like `do-fetch`.
	** `master-sites` and `patch-sites`: (incompatible with older versions) only return the elements of group `DEFAULT`; in fact, they execute targets `master-sites-default` and `patch-sites-default` respectively.
	+
	Furthermore, using target either `master-sites-all` or `patch-sites-all` is preferred to directly checking either `MASTER_SITES` or `PATCH_SITES`.
	Also, directly checking is not guaranteed to work in any future versions.
	-Check item <<porting-master-sites-n-new-port-targets-master-sites-all, B>> for more information on these new port targets.
	+Check item
	+crossref:makefiles[porting-master-sites-n-new-port-targets-master-sites-all, B] for more information on these new port targets.

	. New port targets
	.. There are `master-sites-_n_` and `patch-sites-_n_` targets which will list the elements of the respective group _n_ within `MASTER_SITES` and `PATCH_SITES` respectively. For instance, both `master-sites-DEFAULT` and `patch-sites-DEFAULT` will return the elements of group `DEFAULT`, `master-sites-test` and `patch-sites-test` of group `test`, and thereon.
	@@ -2564,12 +2622,13 @@

	A short name for the license or licenses if more than one license apply.

	-If it is one of the licenses listed in <<licenses-license-list>>, only `LICENSE_FILE` and `LICENSE_DISTFILES` variables can be set.
	+If it is one of the licenses listed in crossref:makefiles[licenses-license-list], only `LICENSE_FILE` and `LICENSE_DISTFILES` variables can be set.

	-If this is a license that has not been defined in the ports framework (see <<licenses-license-list>>), the `LICENSE_PERMS` and `LICENSE_NAME` must be set, along with either `LICENSE_FILE` or `LICENSE_TEXT`.
	+If this is a license that has not been defined in the ports framework (see
	+crossref:makefiles[licenses-license-list]), the `LICENSE_PERMS` and `LICENSE_NAME` must be set, along with either `LICENSE_FILE` or `LICENSE_TEXT`.
	`LICENSE_DISTFILES` and `LICENSE_GROUPS` can also be set, but are not required.

	-The predefined licenses are shown in <<licenses-license-list>>.
	+The predefined licenses are shown in crossref:makefiles[licenses-license-list].
	The current list is always available in [.filename]#Mk/bsd.licenses.db.mk#.

	[[licenses-license-ex1]]
	@@ -3240,7 +3299,8 @@
	=== `LICENSE_FILE` and `LICENSE_FILE_NAME`

	Full path to the file containing the license text, usually [.filename]#${WRKSRC}/some/file#.
	-If the file is not in the distfile, and its content is too long to be put in <<licenses-license_text,`LICENSE_TEXT`>>, put it in a new file in [.filename]#${FILESDIR}#.
	+If the file is not in the distfile, and its content is too long to be put in
	+crossref:makefiles[licenses-license_text,`LICENSE_TEXT`], put it in a new file in [.filename]#${FILESDIR}#.

	[[licenses-license_file-ex1]]
	.`LICENSE_FILE`
	@@ -3705,7 +3765,8 @@
	[[makefile-automatic-dependencies]]
	=== Problems Caused by Automatic Dependencies

	-Dependencies must be declared either explicitly or by using the <<makefile-options,OPTIONS framework>>.
	+Dependencies must be declared either explicitly or by using the
	+crossref:makefiles[makefile-options,OPTIONS framework].
	Using other methods like automatic detection complicates indexing, which causes problems for port and package management.

	[[makefile-automatic-dependencies-bad]]
	@@ -3755,7 +3816,8 @@
	If the port needs to build slightly different versions of packages by having a variable (for instance, resolution, or paper size) take different values, create one subdirectory per package to make it easier for users to see what to do, but try to share as many files as possible between ports.
	Typically, by using variables cleverly, only a very short [.filename]#Makefile# is needed in all but one of the directories.
	In the sole [.filename]#Makefile#, use `MASTERDIR` to specify the directory where the rest of the files are.
	-Also, use a variable as part of <<porting-pkgname,`PKGNAMESUFFIX`>> so the packages will have different names.
	+Also, use a variable as part of
	+crossref:makefiles[porting-pkgname,`PKGNAMESUFFIX`] so the packages will have different names.

	This will be best demonstrated by an example.
	This is part of [.filename]#print/pkfonts300/Makefile#;
	@@ -4106,53 +4168,58 @@
	For easier access, a comprehensive list is provided:

	`PLIST_SUB`, `SUB_LIST`::
	-For automatic `%%_OPT_%%` and `%%NO__OPT__%%` generation, see <<options_sub>>.
	+For automatic `%%_OPT_%%` and `%%NO__OPT__%%` generation, see crossref:makefiles[options_sub].
	+
	-For more complex usage, see <<options-variables>>.
	+For more complex usage, see crossref:makefiles[options-variables].

	`CONFIGURE_ARGS`::
	-For `--enable-_x_` and `--disable-_x_`, see <<options-configure_enable>>.
	+For `--enable-_x_` and `--disable-_x_`, see crossref:makefiles[options-configure_enable].
	+
	-For `--with-_x_` and `--without-_x_`, see <<options-configure_with>>.
	+For `--with-_x_` and `--without-_x_`, see crossref:makefiles[options-configure_with].
	+
	-For all other cases, see <<options-configure_on>>.
	+For all other cases, see crossref:makefiles[options-configure_on].

	`CMAKE_ARGS`::
	-For arguments that are booleans (`on`, `off`, `true`, `false`, `0`, `1`) see <<options-cmake_bool>>.
	+For arguments that are booleans (`on`, `off`, `true`, `false`, `0`, `1`) see
	+crossref:makefiles[options-cmake_bool].
	+
	-For all other cases, see <<options-cmake_on>>.
	+For all other cases, see crossref:makefiles[options-cmake_on].

	`MESON_ARGS`::
	-For arguments that take `true` or `false`, see <<options-meson_true>>.
	+For arguments that take `true` or `false`, see crossref:makefiles[options-meson_true].
	+
	-For arguments that take `yes` or `no`, use <<options-meson_yes>>.
	+For arguments that take `yes` or `no`, use crossref:makefiles[options-meson_yes].
	+
	-For arguments that take `enabled` or `disabled`, see <<options-meson_enabled>>.
	+For arguments that take `enabled` or `disabled`, see crossref:makefiles[options-meson_enabled].
	+
	-For all other cases, use <<options-meson_on>>.
	+For all other cases, use crossref:makefiles[options-meson_on].

	`QMAKE_ARGS`::
	-See <<options-qmake_on>>.
	+See crossref:makefiles[options-qmake_on].

	`USE_*`::
	-See <<options-use>>.
	+See crossref:makefiles[options-use].

	`*_DEPENDS`::
	-See <<options-dependencies>>.
	+See crossref:makefiles[options-dependencies].

	`*` (Any variable)::
	-The most used variables have direct helpers, see <<options-variables>>.
	+The most used variables have direct helpers, see
	+crossref:makefiles[options-variables].
	+
	-For any variable without a specific helper, see <<options-vars>>.
	+For any variable without a specific helper, see crossref:makefiles[options-vars].

	Options dependencies::
	-When an option need another option to work, see <<options-implies>>.
	+When an option need another option to work, see
	+crossref:makefiles[options-implies].

	Options conflicts::
	-When an option cannot work if another is also enabled, see <<options-prevents>>.
	+When an option cannot work if another is also enabled, see
	+crossref:makefiles[options-prevents].

	Build targets::
	-When an option need some extra processing, see <<options-targets>>.
	+When an option need some extra processing, see
	+crossref:makefiles[options-targets].

	[[options_sub]]
	==== `OPTIONS_SUB`
	@@ -4329,7 +4396,8 @@

	[TIP]
	====
	-Most of the time, the helpers in <<options-configure_enable>> and <<options-configure_with>> provide a shorter and more comprehensive functionality.
	+Most of the time, the helpers in crossref:makefiles[options-configure_enable]
	+and crossref:makefiles[options-configure_with] provide a shorter and more comprehensive functionality.
	====

	[[options-cmake-helpers]]
	@@ -4366,7 +4434,7 @@
	[TIP]
	====

	-See <<options-cmake_bool>> for a shorter helper when the value is boolean.
	+See crossref:makefiles[options-cmake_bool] for a shorter helper when the value is boolean.
	====

	[[options-cmake_bool]]
	@@ -4562,7 +4630,7 @@
	Provides a way to add dependencies between options.

	When _OPT_ is selected, all the options listed in this variable will be selected too.
	-Using the <<options-configure_enable,`OPT_CONFIGURE_ENABLE`>> described earlier to illustrate:
	+Using the crossref:makefiles[options-configure_enable,`OPT_CONFIGURE_ENABLE`] described earlier to illustrate:

	[.programlisting]
	....
	@@ -4675,7 +4743,8 @@

	[WARNING]
	====
	-Before using `OPT_VARS` and `OPT_VARS_OFF`, see if there is already a more specific helper available in <<options-variables>>.
	+Before using `OPT_VARS` and `OPT_VARS_OFF`, see if there is already a more
	+specific helper available in crossref:makefiles[options-variables].
	====

	When option _OPT_ is selected, and `OPT_VARS` defined, `_key_=_value_` and `_key_+=_value_` pairs are evaluated from `OPT_VARS`.
	@@ -5235,7 +5304,8 @@

	These macros do not add the installed files to [.filename]#pkg-plist#.
	They must be added manually.
	-For optional documentation (`PORTDOCS`, see <<install-documentation>>) and examples (`PORTEXAMPLES`), the `%%PORTDOCS%%` or `%%PORTEXAMPLES%%` prefixes must be prepended in [.filename]#pkg-plist#.
	+For optional documentation (`PORTDOCS`, see
	+crossref:makefiles[install-documentation]) and examples (`PORTEXAMPLES`), the `%%PORTDOCS%%` or `%%PORTEXAMPLES%%` prefixes must be prepended in [.filename]#pkg-plist#.

	[[install-documentation]]
	=== Install Additional Documentation
	@@ -5259,7 +5329,7 @@
	....

	On the other hand, if there is a DOCS option in the port, install the documentation in a `post-install-DOCS-on` target.
	-These targets are described in <<options-targets>>.
	+These targets are described in crossref:makefiles[options-targets].

	Here are some handy variables and how they are expanded by default when used in the [.filename]#Makefile#:

	diff --git a/documentation/content/en/books/porters-handbook/new-port/_index.adoc b/documentation/content/en/books/porters-handbook/new-port/_index.adoc
	--- a/documentation/content/en/books/porters-handbook/new-port/_index.adoc
	+++ b/documentation/content/en/books/porters-handbook/new-port/_index.adoc
	@@ -50,7 +50,7 @@
	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 crossref:upgrading[preamble,Upgrading a Port].
	+To upgrade an existing port, read this, then read crossref: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.
	diff --git a/documentation/content/en/books/porters-handbook/order/_index.adoc b/documentation/content/en/books/porters-handbook/order/_index.adoc
	--- a/documentation/content/en/books/porters-handbook/order/_index.adoc
	+++ b/documentation/content/en/books/porters-handbook/order/_index.adoc
	@@ -71,9 +71,11 @@
	The variables must be in this order:

	* crossref:makefiles[makefile-portname,`PORTNAME`]
	-* crossref:makefiles[makefile-versions,`PORTVERSION`][<<portversion-footnote, 1>>]
	+*
	+crossref:makefiles[makefile-versions,`PORTVERSION`][crossref:order[portversion-footnote, 1]]
	* crossref:makefiles[makefile-versions,`DISTVERSIONPREFIX`]
	-* crossref:makefiles[makefile-versions,`DISTVERSION`][<<portversion-footnote, 1>>]
	+*
	+crossref:makefiles[makefile-versions,`DISTVERSION`][crossref:order[portversion-footnote, 1]]
	* crossref:makefiles[makefile-versions,`DISTVERSIONSUFFIX`]
	* crossref:makefiles[makefile-portrevision,`PORTREVISION`]
	* crossref:makefiles[makefile-portepoch,`PORTEPOCH`]
	@@ -151,10 +153,14 @@
	[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 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>>.
	+With the exception of variables that depend on a crossref:uses[uses,`USES`],
	+place those in crossref:order[porting-order-uses].
	+For instance, `IGNORE_WITH_PHP` only works if crossref:uses[uses-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
	+crossref:order[porting-order-rest].
	====

	[[porting-order-depends]]
	@@ -213,7 +219,7 @@
	The `FOO` and `BAR` options do not have a standard description, so one need to be written.
	The other options already have one in [.filename]#Mk/bsd.options.desc.mk# so writing one is not needed.
	The `DOCS` and `EXAMPLES` use target helpers to install their files, they are shown here for completeness,
	-though they belong in <<porting-order-targets>>, so other variables and targets could be inserted before them.
	+though they belong in crossref:order[porting-order-targets], so other variables and targets could be inserted before them.

	[.programlisting]
	....
	diff --git a/documentation/content/en/books/porters-handbook/pkg-files/_index.adoc b/documentation/content/en/books/porters-handbook/pkg-files/_index.adoc
	--- a/documentation/content/en/books/porters-handbook/pkg-files/_index.adoc
	+++ b/documentation/content/en/books/porters-handbook/pkg-files/_index.adoc
	@@ -149,7 +149,7 @@
	Multiline strings use the standard here document notation.
	The multiline delimiter _must_ start just after `<<` symbols without any whitespace and it _must_ consist of capital letters only.
	To finish a multiline string, add the delimiter string on a line of its own without any whitespace.
	-The message from <<porting-message-ucl-short-ex>> can be written as:
	+The message from crossref:pkg-files[porting-message-ucl-short-ex] can be written as:

	[.programlisting]
	....
	diff --git a/documentation/content/en/books/porters-handbook/plist/_index.adoc b/documentation/content/en/books/porters-handbook/plist/_index.adoc
	--- a/documentation/content/en/books/porters-handbook/plist/_index.adoc
	+++ b/documentation/content/en/books/porters-handbook/plist/_index.adoc
	@@ -159,7 +159,7 @@
	That will cause `pkg delete` to remove files that have been carefully edited by the user, and a re-installation will wipe them out.

	Instead, install sample files with a [.filename]#filename.sample# extension.
	-The `@sample` macro automates this, see <<plist-keywords-sample>> for what it does exactly.
	+The `@sample` macro automates this, see crossref:plist[plist-keywords-sample] for what it does exactly.
	For each sample file, add a line to [.filename]#pkg-plist#:

	[.programlisting]
	@@ -216,7 +216,8 @@
	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>>.
	+User configuration files should be installed as [.filename]#filename.sample#, as
	+it is described in crossref:plist[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.

	@@ -379,7 +380,7 @@
	This does three things. First, add the first file passed as argument, the sample file, to the plist.
	Then, on installation, if the actual file is not found, copy the sample file to the actual file.
	And finally, on deinstallation, remove the actual file if it has not been modified.
	-See <<plist-config>> for more information.
	+See crossref:plist[plist-config] for more information.

	[[plist-keywords-shared-mime-info]]
	=== `@shared-mime-info` _directory_
	@@ -502,7 +503,7 @@
	==== `@exec` _command_, `@unexec` _command_ (Deprecated)

	Execute _command_ as part of the installation or deinstallation process.
	-Please use <<plist-keywords-base-exec>> instead.
	+Please use crossref:plist[plist-keywords-base-exec] instead.

	[[plist-keywords-base-dirrm]]
	==== `@dirrm` _directory_ (Deprecated)
	@@ -600,7 +601,7 @@
	other.content
	....

	-It also affects how the <<plist-keywords-action,`action`>> entry works.
	+It also affects how the crossref:plist[plist-keywords-action,`action`] entry works.
	When there is more than one argument, the argument number must be specified.
	For example:

	@@ -613,7 +614,8 @@
	==== `pre-install`, `post-install`, `pre-deinstall`, `post-deinstall`, `pre-upgrade`, `post-upgrade`

	These keywords contains a man:sh[1] script to be executed before or after installation, deinstallation, or upgrade of the package.
	-In addition to the usual `@exec %_foo_` placeholders described in <<plist-keywords-base-exec>>, there is a new one, `%@`, which represents the argument of the keyword.
	+In addition to the usual `@exec %_foo_` placeholders described in
	+crossref:plist[plist-keywords-base-exec], there is a new one, `%@`, which represents the argument of the keyword.

	[[plist-keywords-examples]]
	==== Custom Keyword Examples
	diff --git a/documentation/content/en/books/porters-handbook/special/_index.adoc b/documentation/content/en/books/porters-handbook/special/_index.adoc
	--- a/documentation/content/en/books/porters-handbook/special/_index.adoc
	+++ b/documentation/content/en/books/porters-handbook/special/_index.adoc
	@@ -101,7 +101,7 @@

	[TIP]
	====
	-Metaports should use <<uses-metaport,`USES=metaport`>>.
	+Metaports should use crossref:special[uses-metaport,`USES=metaport`].
	It sets up defaults for ports that do not fetch, build, or install anything.
	====

	@@ -241,7 +241,7 @@

	When installing 32-bit libraries on a 64-bit system, use `USE_LDCONFIG32` instead.

	-If the software uses <<using-autotools,autotools>>, and specifically `libtool`, add crossref:uses[uses-libtool,`USES=libtool`].
	+If the software uses crossref:special[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.

	@@ -420,10 +420,12 @@
	\|Port specific CMake flags to be passed to the `cmake` binary.

	\|`CMAKE_ON`
	-\|For each entry in `CMAKE_ON`, an enabled boolean value is added to `CMAKE_ARGS`. See <<using-cmake-example2>>.
	+\|For each entry in `CMAKE_ON`, an enabled boolean value is added to
	+`CMAKE_ARGS`. See crossref:special[using-cmake-example2].

	\|`CMAKE_OFF`
	-\|For each entry in `CMAKE_OFF`, a disabled boolean value is added to `CMAKE_ARGS`. See <<using-cmake-example2>>.
	+\|For each entry in `CMAKE_OFF`, a disabled boolean value is added to
	+`CMAKE_ARGS`. See crossref:special[using-cmake-example2].

	\|`CMAKE_BUILD_TYPE`
	\|Type of build (CMake predefined build profiles). Default is `Release`, or `Debug` if `WITH_DEBUG` is set.
	@@ -1618,7 +1620,7 @@
	....

	`USE_GNOME` components automatically add the dependencies they need.
	-Please see <<gnome-components>> for an exhaustive list of all `USE_GNOME` components and which other components they imply and their dependencies.
	+Please see crossref:special[gnome-components] for an exhaustive list of all `USE_GNOME` components and which other components they imply and their dependencies.

	Here is an example [.filename]#Makefile# for a GNOME port that uses many of the techniques outlined in this document.
	Please use it as a guide for creating new ports.
	@@ -1654,7 +1656,7 @@

	This section explains which macros are available and how they are used.
	Like they are used in the above example.
	-The <<gnome-components>> has a more in-depth explanation.
	+The crossref:special[gnome-components] has a more in-depth explanation.
	`USE_GNOME` has to be set for these macros to be of use.

	`GLIB_SCHEMAS`::
	@@ -2433,8 +2435,10 @@

	If the application provides a qmake project file ([.filename]#*.pro#), define `USES= qmake` along with `USE_QT`.
	`USES= qmake` already implies a build dependency on qmake, therefore the qmake component can be omitted from `USE_QT`.
	-Similar to <<using-cmake,CMake>>, qmake supports out-of-source builds, which can be enabled by specifying the `outsource` argument (see <<using-qmake-example,`USES= qmake` example>>).
	-Also see <<using-qmake-arguments>>.
	+Similar to crossref:special[using-cmake,CMake], qmake supports out-of-source
	+builds, which can be enabled by specifying the `outsource` argument (see
	+crossref:special[using-qmake-example,`USES= qmake` example]).
	+Also see crossref:special[using-qmake-arguments].

	[[using-qmake-arguments]]
	.Possible Arguments for `USES= qmake`
	@@ -3091,7 +3095,8 @@
	[example]
	====
	This is a simple example for a KDE port.
	-`USES= cmake` instructs the port to utilize CMake, a configuration tool widely used by KDE projects (see <<using-cmake>> for detailed usage).
	+`USES= cmake` instructs the port to utilize CMake, a configuration tool widely
	+used by KDE projects (see crossref:special[using-cmake] for detailed usage).
	`USE_KDE` brings dependency on KDE libraries.
	Required KDE components and other dependencies can be determined through the configure log.
	`USE_KDE` does not imply `USE_QT`.
	@@ -3295,7 +3300,7 @@
	When the port is to be built using Apache Ant, it has to define `USE_ANT`.
	Ant is thus considered to be the sub-make command.
	When no `do-build` target is defined by the port, a default one will be set that runs Ant according to `MAKE_ENV`, `MAKE_ARGS` and `ALL_TARGET`.
	-This is similar to the `USES= gmake` mechanism, which is documented in <<building>>.
	+This is similar to the `USES= gmake` mechanism, which is documented in crossref:special[building].

	[[java-best-practices]]
	=== Best Practices
	@@ -3619,7 +3624,7 @@
	[IMPORTANT]
	====
	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>>.
	+See crossref:special[python-Makefile].
	====

	[[python-Makefile]]
	@@ -3803,7 +3808,7 @@
	\|package:x11-toolkits/wxgtk30[]
	\|===

	-The variables in <<wx-ver-sel-table>> can be set to one or more of these combinations separated by spaces:
	+The variables in crossref:special[wx-ver-sel-table] can be set to one or more of these combinations separated by spaces:

	[[wx-widgets-versions-specification]]
	.wxWidgets Version Specifications
	@@ -3869,7 +3874,7 @@
	\|===

	The dependency type can be selected for each component by adding a suffix separated by a semicolon.
	-If not present then a default type will be used (see <<wx-def-dep-types>>).
	+If not present then a default type will be used (see crossref:special[wx-def-dep-types]).
	These types are available:

	[[wx-widgets-dependency-table]]
	@@ -3974,7 +3979,7 @@
	[[wx-defined-variables]]
	=== Defined Variables

	-These variables are available in the port (after defining one from <<wx-ver-sel-table>>).
	+These variables are available in the port (after defining one from crossref:special[wx-ver-sel-table]).

	[[wx-widgets-variables]]
	.Variables Defined for Ports That Use wxWidgets
	@@ -4752,7 +4757,7 @@
	[[using-databases]]
	== Using Databases

	-Use one of the `USES` macros from <<using-databases-uses>> to add a dependency on a database.
	+Use one of the `USES` macros from crossref:special[using-databases-uses] to add a dependency on a database.

	[[using-databases-uses]]
	.Database `USES` Macros
	diff --git a/documentation/content/en/books/porters-handbook/testing/_index.adoc b/documentation/content/en/books/porters-handbook/testing/_index.adoc
	--- a/documentation/content/en/books/porters-handbook/testing/_index.adoc
	+++ b/documentation/content/en/books/porters-handbook/testing/_index.adoc
	@@ -122,7 +122,8 @@
	The package:ports-mgmt/porttools[] program is part of the Ports Collection.

	`port` is the front-end script, which can help simplify the testing job.
	-Whenever a new port or an update to an existing one needs testing, use `port test` to test the port, including the <<testing-portlint,`portlint`>> checking.
	+Whenever a new port or an update to an existing one needs testing, use `port
	+test` to test the port, including the crossref:testing[testing-portlint,`portlint`] checking.
	This command also detects and lists any files that are not listed in [.filename]#pkg-plist#.
	For example:

	@@ -191,7 +192,7 @@
	====
	All these tests are done automatically when running `poudriere testport` or `poudriere bulk -t`.
	It is highly recommended that every ports contributor install and test their ports with it.
	-See <<testing-poudriere>> for more information.
	+See crossref:testing[testing-poudriere] for more information.
	====

	[[testing-poudriere]]
	@@ -441,7 +442,8 @@

	[NOTE]
	====
	-Ports trees without a method, see <<testing-poudriere-ports-tree-manual>>, cannot be updated like this and must be updated manually by the porter.
	+Ports trees without a method, see
	+crossref:testing[testing-poudriere-ports-tree-manual], cannot be updated like this and must be updated manually by the porter.
	====

	[[testing-poudriere-testing-ports]]
	@@ -508,7 +510,8 @@

	Presents the port configuration dialog before the port is built.
	The ports given after `-o` in the format `_category_/_portname_` will use the specified options, all dependencies will use the default options.
	-Testing dependent ports with non-default options can be accomplished using sets, see <<testing-poudriere-sets>>.
	+Testing dependent ports with non-default options can be accomplished using sets,
	+see crossref:testing[testing-poudriere-sets].

	[TIP]
	====
	diff --git a/documentation/content/en/books/porters-handbook/upgrading/_index.adoc b/documentation/content/en/books/porters-handbook/upgrading/_index.adoc
	--- a/documentation/content/en/books/porters-handbook/upgrading/_index.adoc
	+++ b/documentation/content/en/books/porters-handbook/upgrading/_index.adoc
	@@ -72,7 +72,7 @@
	% diff -u something.orig something > something.diff
	....

	-Otherwise, either use the `git diff` method (<<git-diff>>) or copy the contents of the port to an entire different directory and use the result of the recursive man:diff[1] output of the new and old ports directories (for example, if the modified port directory is called [.filename]#superedit# and the original is in our tree as [.filename]#superedit.bak#, then save the result of `diff -ruN superedit.bak superedit`).
	+Otherwise, either use the `git diff` method (crossref:upgrading[git-diff]) or copy the contents of the port to an entire different directory and use the result of the recursive man:diff[1] output of the new and old ports directories (for example, if the modified port directory is called [.filename]#superedit# and the original is in our tree as [.filename]#superedit.bak#, then save the result of `diff -ruN superedit.bak superedit`).
	Either unified or context diff is fine, but port committers generally prefer unified diffs.
	Note the use of the `-N` option-this is the accepted way to force diff to properly deal with the case of new files being added or old files being deleted.
	Before sending us the diff, please examine the output to make sure all the changes make sense.
	diff --git a/documentation/content/en/books/porters-handbook/uses/_index.adoc b/documentation/content/en/books/porters-handbook/uses/_index.adoc
	--- a/documentation/content/en/books/porters-handbook/uses/_index.adoc
	+++ b/documentation/content/en/books/porters-handbook/uses/_index.adoc
	@@ -360,7 +360,7 @@

	Uses update-desktop-database from package:devel/desktop-file-utils[].
	An extra post-install step will be run without interfering with any post-install steps already in the port [.filename]#Makefile#.
	-A line with <<plist-keywords-desktop-file-utils,`@desktop-file-utils`>> will be added to the plist.
	+A line with crossref:plist[plist-keywords-desktop-file-utils,`@desktop-file-utils`] will be added to the plist.
	Only use this macro if the port provides a `.desktop` file which contains a
	`MimeType` entry.

	@@ -535,7 +535,8 @@
	Possible arguments: (none)

	Deprecated.
	-Will include both <<uses-gettext-runtime,`gettext-runtime`>> and <<uses-gettext-tools,`gettext-tools`>>.
	+Will include both crossref:uses[uses-gettext-runtime,`gettext-runtime`] and
	+crossref:uses[uses-gettext-tools,`gettext-tools`].

	[[uses-gettext-runtime]]
	== `gettext-runtime`
	@@ -1412,7 +1413,7 @@
	For example, it fixes the installation directory of `pkgconfig`'s [.filename]#.pc# files to [.filename]#${PREFIX}/libdata/pkgconfig#.
	If the port uses `USES=autoreconf`, [.filename]#Makefile.am# will be added to `PATHFIX_MAKEFILEIN` automatically.

	-If the port <<uses-cmake,`USES=cmake`>> it will look for [.filename]#CMakeLists.txt# in `PATHFIX_WRKSRC`.
	+If the port crossref:uses[uses-cmake,`USES=cmake`] it will look for [.filename]#CMakeLists.txt# in `PATHFIX_WRKSRC`.
	If needed, that default filename can be changed with `PATHFIX_CMAKELISTSTXT`.

	[[uses-pear]]
	@@ -1509,7 +1510,8 @@

	`flavors`::
	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`>>.
	+Flavors will be generated for all PHP versions, except the ones present in
	+crossref:uses[uses-php-ignore,`IGNORE_WITH_PHP`].

	`noflavors`::
	Disable automatic PHP flavors generation.
	@@ -1693,7 +1695,7 @@
	See crossref:special[using-python, Using Python] for more information.

	`USES=python:env` 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.
	+It can happen when using with crossref:uses[uses-shebangfix,`USES=shebangfix`], and the goal is only to fix the shebangs but not add a dependency on Python.

	[[uses-qmail]]
	== `qmail`
	@@ -1879,17 +1881,17 @@

	`SHEBANG_REGEX`::
	Contains _one_ extended regular expressions, and is used with the `-iregex` argument of man:find[1].
	-See <<uses-shebangfix-ex-regex>>.
	+See crossref:uses[uses-shebangfix-ex-regex].

	`SHEBANG_GLOB`::
	Contains a list of patterns used with the `-name` argument of man:find[1].
	-See <<uses-shebangfix-ex-glob>>.
	+See crossref:uses[uses-shebangfix-ex-glob].

	`SHEBANG_FILES`::
	Contains a list of files or man:sh[1] globs.
	The shebangfix macro is run from `${WRKSRC}`, so `SHEBANG_FILES` can contain paths that are relative to `${WRKSRC}`.
	It can also deal with absolute paths if files outside of `${WRKSRC}` require patching.
	-See <<uses-shebangfix-ex-files>>.
	+See crossref:uses[uses-shebangfix-ex-files].

	Currently Bash, Java, Ksh, Lua, Perl, PHP, Python, Ruby, Tcl, and Tk are supported by default.

	@@ -1916,7 +1918,7 @@
	====
	`_interp__OLD_CMD` contain multiple values.
	Any entry with spaces must be quoted.
	-See <<uses-shebangfix-ex-ksh>>.
	+See crossref:uses[uses-shebangfix-ex-ksh].
	====

	[IMPORTANT]
	@@ -1929,7 +1931,7 @@

	[TIP]
	====
	-When used with <<uses-python,`USES=python`>>, and the aim is only to fix the shebangs but a dependency on Python itself is not wanted, use `USES=python:env` instead.
	+When used with crossref:uses[uses-python,`USES=python`], and the aim is only to fix the shebangs but a dependency on Python itself is not wanted, use `USES=python:env` instead.
	====

	[[uses-shebangfix-ex-lua]]
	@@ -2167,7 +2169,7 @@
	Possible arguments: (none)

	Changes some default behavior (mostly variables) of the build system to allow installing this port as a normal user.
	-Try this in the port before using <<uses-fakeroot,USES=fakeroot>> or patching.
	+Try this in the port before using crossref:uses[uses-fakeroot,USES=fakeroot] or patching.

	[[uses-uniquefiles]]
	== `uniquefiles`
	diff --git a/shared/lib/CrossDocumentReferencesMacro/extension.rb b/shared/lib/CrossDocumentReferencesMacro/extension.rb
	--- a/shared/lib/CrossDocumentReferencesMacro/extension.rb
	+++ b/shared/lib/CrossDocumentReferencesMacro/extension.rb
	@@ -5,6 +5,7 @@
	class CrossDocumentReferencesMacro < Asciidoctor::Extensions::InlineMacroProcessor
	use_dsl

	+ # Macro to handle cross references to a different book.
	named :extref
	name_positional_attributes 'attributes'

	diff --git a/shared/lib/InterDocumentReferencesMacro/extension.rb b/shared/lib/InterDocumentReferencesMacro/extension.rb
	--- a/shared/lib/InterDocumentReferencesMacro/extension.rb
	+++ b/shared/lib/InterDocumentReferencesMacro/extension.rb
	@@ -5,30 +5,36 @@
	class InterDocumentReferencesMacro < Asciidoctor::Extensions::InlineMacroProcessor
	use_dsl

	+ # Macro to handle cross references to different files in the same book.
	named :crossref
	- name_positional_attributes 'attributes'

	def process parent, target, attrs
	- destination = target
	anchor = attrs[1]
	text = attrs[2]

	doc = parent.document

	- if doc.attributes['book'] == "true"
	- if doc.attributes['isonline'] == "1"
	- (create_anchor parent, text, type: :link, target: %(./##{anchor})).render
	+ if doc.backend == 'html5'
	+ if doc.attributes['book'] == "true"
	+ if doc.attributes['isonline'] == "1"
	+ (create_anchor parent, text, type: :link, target: %(./##{anchor})).render
	+ else
	+ (create_anchor parent, text, type: :link, target: %(./index.html##{anchor})).render
	+ end
	else
	- (create_anchor parent, text, type: :link, target: %(./index.html##{anchor})).render
	+ if doc.attributes['isonline'] == "1"
	+ (create_anchor parent, text, type: :link, target: %(../#{target}/##{anchor})).render
	+ else
	+ (create_anchor parent, text, type: :link, target: %(../#{target}/index.html##{anchor})).render
	+ end
	end
	else
	- if doc.attributes['isonline'] == "1"
	- (create_anchor parent, text, type: :link, target: %(../#{destination}/##{anchor})).render
	- else
	- (create_anchor parent, text, type: :link, target: %(../#{destination}/index.html##{anchor})).render
	- end
	+ xref_attrs = { 'refid' => anchor }
	+ xref_node = create_anchor parent, text, type: :xref, target: target, attributes: xref_attrs
	+ # Return the node
	+ xref_node
	end
	+ end # process

	- end
	-end
	+end # class

File Metadata

Mime Type: text/plain
Expires: Sat, Jan 31, 7:35 AM (11 h, 30 m)
Storage Engine: blob
Storage Format: Raw Data
Storage Handle: 28109804
Default Alt Text: D46480.diff (322 KB)

D46480.diffNo OneTemporaryActions

D46480.diffView Options

File Metadata

Event Timeline

D46480.diff
No OneTemporary
Actions

D46480.diff
View Options