git: 2d2f5d38cc - main - Fix links that use crossref without description
- Go to: [ bottom of page ] [ top of archives ] [ this month ]
Date: Sun, 22 Sep 2024 17:35:07 UTC
The branch main has been updated by fernape:
URL: https://cgit.FreeBSD.org/doc/commit/?id=2d2f5d38cc5fe0ddd71e4ad014111e253b95759a
commit 2d2f5d38cc5fe0ddd71e4ad014111e253b95759a
Author: Fernando Apesteguía <fernape@FreeBSD.org>
AuthorDate: 2024-09-20 17:35:23 +0000
Commit: Fernando Apesteguía <fernape@FreeBSD.org>
CommitDate: 2024-09-22 17:34:49 +0000
Fix links that use crossref without description
Summary: Add the anchor text to the crossref macro
Test Plan:
Apply patch and build the documentation
A follow-up change will make the crossref macro fail if no description
is used.
Subscribers: delphij
Differential Revision: https://reviews.freebsd.org/D46721
---
.../en/articles/building-products/_index.adoc | 8 +-
.../en/articles/committers-guide/_index.adoc | 30 +++----
.../content/en/articles/contributing/_index.adoc | 14 ++--
.../content/en/articles/freebsd-releng/_index.adoc | 20 ++---
.../en/articles/gjournal-desktop/_index.adoc | 2 +-
documentation/content/en/articles/hubs/_index.adoc | 12 +--
.../content/en/articles/ipsec-must/_index.adoc | 10 +--
.../content/en/articles/ldap-auth/_index.adoc | 4 +-
documentation/content/en/articles/pam/_index.adoc | 6 +-
.../content/en/articles/pr-guidelines/_index.adoc | 10 +--
.../content/en/articles/releng/_index.adoc | 10 +--
.../content/en/articles/remote-install/_index.adoc | 2 +-
.../content/en/articles/solid-state/_index.adoc | 8 +-
.../content/en/books/arch-handbook/mac/_index.adoc | 4 +-
.../content/en/books/arch-handbook/smp/_index.adoc | 2 +-
.../content/en/books/design-44bsd/_index.adoc | 2 +-
.../content/en/books/dev-model/_index.adoc | 78 +++++++++---------
.../en/books/developers-handbook/tools/_index.adoc | 4 +-
.../en/books/fdp-primer/editor-config/_index.adoc | 2 +-
.../books/handbook/advanced-networking/_index.adoc | 4 +-
.../content/en/books/handbook/audit/_index.adoc | 4 +-
.../content/en/books/handbook/basics/_index.adoc | 22 ++---
.../content/en/books/handbook/boot/_index.adoc | 6 +-
.../en/books/handbook/bsdinstall/_index.adoc | 56 ++++++-------
.../content/en/books/handbook/config/_index.adoc | 4 +-
.../en/books/handbook/cutting-edge/_index.adoc | 18 ++---
.../content/en/books/handbook/disks/_index.adoc | 14 ++--
.../en/books/handbook/firewalls/_index.adoc | 4 +-
.../content/en/books/handbook/geom/_index.adoc | 6 +-
.../content/en/books/handbook/jails/_index.adoc | 10 +--
.../content/en/books/handbook/l10n/_index.adoc | 8 +-
.../content/en/books/handbook/mac/_index.adoc | 2 +-
.../content/en/books/handbook/mail/_index.adoc | 4 +-
.../content/en/books/handbook/mirrors/_index.adoc | 2 +-
.../en/books/handbook/network-servers/_index.adoc | 2 +-
.../content/en/books/handbook/network/_index.adoc | 2 +-
.../content/en/books/handbook/ports/_index.adoc | 2 +-
.../content/en/books/handbook/printing/_index.adoc | 4 +-
.../content/en/books/handbook/security/_index.adoc | 2 +-
.../en/books/handbook/serialcomms/_index.adoc | 14 ++--
.../content/en/books/handbook/x11/_index.adoc | 6 +-
.../content/en/books/handbook/zfs/_index.adoc | 2 +-
.../books/porters-handbook/makefiles/_index.adoc | 94 +++++++++++-----------
.../en/books/porters-handbook/order/_index.adoc | 6 +-
.../books/porters-handbook/pkg-files/_index.adoc | 2 +-
.../en/books/porters-handbook/plist/_index.adoc | 8 +-
.../en/books/porters-handbook/special/_index.adoc | 24 +++---
.../en/books/porters-handbook/testing/_index.adoc | 6 +-
.../en/books/porters-handbook/uses/_index.adoc | 8 +-
49 files changed, 287 insertions(+), 287 deletions(-)
diff --git a/documentation/content/en/articles/building-products/_index.adoc b/documentation/content/en/articles/building-products/_index.adoc
index b444b4a41e..7f6007aa0a 100644
--- a/documentation/content/en/articles/building-products/_index.adoc
+++ b/documentation/content/en/articles/building-products/_index.adoc
@@ -63,7 +63,7 @@ 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 crossref:building-products[freebsd-intro]).
+(see crossref:building-products[freebsd-intro, FreeBSD as a set of building blocks]).
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.
@@ -96,9 +96,9 @@ After reading this article you should have:
The rest of the article is structured as follows:
-* 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.
+* crossref:building-products[freebsd-intro, FreeBSD as a set of building blocks] introduces the FreeBSD project, explores its organizational structure, key technologies and release engineering processes.
+* crossref:building-products[freebsd-collaboration, Collaborating with FreeBSD] 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, Conclusion] concludes.
[[freebsd-intro]]
== FreeBSD as a set of building blocks
diff --git a/documentation/content/en/articles/committers-guide/_index.adoc b/documentation/content/en/articles/committers-guide/_index.adoc
index 921a823a7d..ff2923c80c 100644
--- a/documentation/content/en/articles/committers-guide/_index.adoc
+++ b/documentation/content/en/articles/committers-guide/_index.adoc
@@ -49,7 +49,7 @@ All new committers should read this document before they start, and existing com
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 crossref:committers-guide[non-committers] for more information.
+Please see crossref:committers-guide[non-committers, Issues Specific to Developers Who Are Not 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 @@ toc::[]
|`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 crossref:committers-guide[smtp-setup]).
+|`smtp.FreeBSD.org:587` (see also crossref:committers-guide[smtp-setup, SMTP Access Setup]).
|`_src/_` Git Repository
|`ssh://git@gitrepo.FreeBSD.org/src.git`
@@ -99,7 +99,7 @@ toc::[]
|===
man:ssh[1] is required to connect to the project hosts. For more information,
- see crossref:committers-guide[ssh.guide].
+ see crossref:committers-guide[ssh.guide, SSH Quick-Start Guide].
Useful links:
@@ -1518,7 +1518,7 @@ Note: merging vendor branch commits will not work with this technique.
===== Finding the Subversion Revision
-You'll need to make sure that you've fetched the notes (see the crossref:committers-guide[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, Daily use]for details).
Once you have these, notes will show up in the git log command like so:
[source,shell]
@@ -2179,7 +2179,7 @@ It is very important to have a current PGP/GnuPG key in the repository. The key
Add an entry for each additional mentor/mentee relationship in the bottom section.
. Generate a Kerberos Password
+
-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).
+See crossref:committers-guide[kerberos-ldap, Kerberos and LDAP web Password for FreeBSD Cluster] 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.
@@ -2229,7 +2229,7 @@ For those willing to send e-mail messages through the FreeBSD.org infrastructure
. Enable STARTTLS.
. Ensure your `From:` address is set to `_yourusername_@FreeBSD.org`.
. 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.
+ (see crossref:committers-guide[kerberos-ldap, Kerberos and LDAP web Password for FreeBSD Cluster]). The `_yourusername_/mail` principal is preferred, as it is only valid for authenticating to mail resources.
+
[NOTE]
======
@@ -2380,7 +2380,7 @@ Document that approval with an `Approved by:` line in the commit message.
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
-crossref:committers-guide[admin-branch].
+crossref:committers-guide[admin-branch, "admin" branch].
[[pre-commit-review]]
== Pre-Commit Review
@@ -2931,7 +2931,7 @@ Committers with non-``FreeBSD.org`` Bugzilla accounts can have the old account m
. 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 crossref:committers-guide[kerberos-ldap] for more details on how to generate or set a password for your `FreeBSD.org` account.
+ confirm ownership. See crossref:committers-guide[kerberos-ldap, Kerberos and LDAP web Password for FreeBSD Cluster] 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.
====
@@ -2952,7 +2952,7 @@ Committers with non-``FreeBSD.org`` Phabricator accounts can have the old accoun
====
. Change your Phabricator account email to your `FreeBSD.org` email.
. 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/`
+ crossref:committers-guide[bugzilla, 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]
@@ -3578,7 +3578,7 @@ 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
-crossref:committers-guide[ports-qa-misc-request-mfh].
+crossref:committers-guide[ports-qa-misc-request-mfh, What is the procedure to request authorization for merging a commit to the quarterly branch?].
[[ports-qa-quarterly]]
=== Quarterly Branches
@@ -3727,16 +3727,16 @@ A few people who have access to the FreeBSD machines do not have commit bits.
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:
-* crossref:committers-guide[admin]
-* crossref:committers-guide[conventions-everyone]
+* crossref:committers-guide[admin, Administrative Details]
+* crossref:committers-guide[conventions-everyone, For 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.
====
-* crossref:committers-guide[developer.relations]
-* crossref:committers-guide[ssh.guide]
-* crossref:committers-guide[rules]
+* crossref:committers-guide[developer.relations, Developer Relations]
+* crossref:committers-guide[ssh.guide, SSH Quick-Start Guide]
+* crossref:committers-guide[rules, The FreeBSD Committers' Big List of 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
index 10bdcf03e5..a5b872383a 100644
--- a/documentation/content/en/articles/contributing/_index.adoc
+++ b/documentation/content/en/articles/contributing/_index.adoc
@@ -150,9 +150,9 @@ There are a number of easy ways you can contribute to keeping the ports tree up
* 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 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].
+Become a maintainer and crossref:contributing[adopt-port, Adopting an unmaintained port].
+* If you have created or adopted a port, be aware of crossref:contributing[maintain-port, The challenge for port maintainers].
+* When you are looking for a quick challenge you could crossref:contributing[fix-broken, Finding and fixing a broken port].
=== Pick one of the items from the Ideas page
@@ -197,7 +197,7 @@ Misdirected patches may be redirected to a more appropriate forum for the patch
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 crossref:contributing[ports-contributing].
+process crossref:contributing[ports-contributing, Contributing to ports].
The docs team also accepts pull requests via GitHub, but has not established any policy for them yet.
@@ -333,7 +333,7 @@ We expect you to be able to recognize such ports by looking through other ports'
==== How to adopt the port
-First make sure you understand your crossref:contributing[maintain-port].
+First make sure you understand your crossref:contributing[maintain-port, The challenge for port maintainers].
Also read the extref:{porters-handbook}[Porter's Handbook].
_Please do not commit yourself to more than you feel you can comfortably handle._
@@ -415,11 +415,11 @@ Thoroughly review and test your changes:
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 crossref:contributing[resources] for more information.
+See crossref:contributing[resources, Resources for ports maintainers and contributors] 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 crossref:contributing[resources] for important information about using portlint.
+See crossref:contributing[resources, Resources for ports maintainers and contributors] 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/freebsd-releng/_index.adoc b/documentation/content/en/articles/freebsd-releng/_index.adoc
index 27c467b1a0..60460d3c92 100644
--- a/documentation/content/en/articles/freebsd-releng/_index.adoc
+++ b/documentation/content/en/articles/freebsd-releng/_index.adoc
@@ -88,28 +88,28 @@ This article will highlight the workflow and responsibilities of the {teamRe} fo
The following sections of this article describe:
-crossref:freebsd-releng[releng-prep]::
+crossref:freebsd-releng[releng-prep, General Information and Preparation]::
General information and preparation before starting the release cycle.
-crossref:freebsd-releng[releng-website]::
+crossref:freebsd-releng[releng-website, Website Changes During the Release Cycle]::
Website Changes During the Release Cycle
-crossref:freebsd-releng[releng-terms]::
+crossref:freebsd-releng[releng-terms, Release Engineering Terminology]::
Terminology and general information, such as the "code slush" and "code freeze", used throughout this document.
-crossref:freebsd-releng[releng-head]::
+crossref:freebsd-releng[releng-head, Release from {branchHead}]::
The Release Engineering process for a "dot-zero" release.
-crossref:freebsd-releng[releng-stable]::
+crossref:freebsd-releng[releng-stable, Release from {branchStable}]::
The Release Engineering process for a "point" release.
-crossref:freebsd-releng[releng-building]::
+crossref:freebsd-releng[releng-building, Building FreeBSD Installation Media]::
Information related to the specific procedures to build installation medium.
-crossref:freebsd-releng[releng-mirrors]::
+crossref:freebsd-releng[releng-mirrors, Publishing FreeBSD Installation Media to Project Mirrors]::
Procedures to publish installation medium.
-crossref:freebsd-releng[releng-wrapup]::
+crossref:freebsd-releng[releng-wrapup, Wrapping up the Release Cycle]::
Wrapping up the release cycle.
[[releng-prep]]
@@ -361,7 +361,7 @@ FreeBSD `ALPHA` snapshots should be built approximately once a week.
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 crossref:freebsd-releng[releng-building] for information on building the `ALPHA` images.
+See crossref:freebsd-releng[releng-building, Building FreeBSD Installation Media] for information on building the `ALPHA` images.
[[releng-head-branching]]
=== Creating the {branchStablex} Branch
@@ -742,7 +742,7 @@ The completed Errata Notice template should be emailed together with either a pa
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 crossref:freebsd-releng[releng-wrapup-handoff], Errata Notice requests should be sent to the {teamSecteam}.
+described in crossref:freebsd-releng[releng-wrapup-handoff, Handoff to the {teamSecteam}], 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
index 774bcf29f3..1f8c15f843 100644
--- a/documentation/content/en/articles/gjournal-desktop/_index.adoc
+++ b/documentation/content/en/articles/gjournal-desktop/_index.adoc
@@ -385,7 +385,7 @@ The following section covers frequently asked questions regarding problems relat
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 crossref:gjournal-desktop[understanding-journaling] section.
+See the note in the crossref:gjournal-desktop[understanding-journaling, Understanding Journaling in FreeBSD] 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
index 3269322e7a..1ddbe3065a 100644
--- a/documentation/content/en/articles/hubs/_index.adoc
+++ b/documentation/content/en/articles/hubs/_index.adoc
@@ -191,7 +191,7 @@ All of course for various FreeBSD versions, and various architectures.
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 crossref:hubs[mirror-serv-rsync].
+rsync is already mentioned in crossref:hubs[mirror-serv-rsync, Rsync (optional for FTP Fileset)].
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.
@@ -310,7 +310,7 @@ 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
-crossref:hubs[mirror-requirements].
+crossref:hubs[mirror-requirements, Requirements for FreeBSD Mirrors].
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).
@@ -325,7 +325,7 @@ The short answer is: from the site that is closest to you in Internet terms, or
==== I Just Want to Mirror from Somewhere!
If you have no special intentions or requirements, the statement in
-crossref:hubs[mirror-where-where] applies.
+crossref:hubs[mirror-where-where, Ok, but Where Should I get the Stuff Now?] applies.
This means:
[.procedure]
@@ -338,10 +338,10 @@ This means:
[[mirror-where-official]]
==== I am an Official Mirror, What is the Right Site for Me?
-In general the description in crossref:hubs[mirror-where-simple] still applies.
+In general the description in crossref:hubs[mirror-where-simple, I Just Want to Mirror from Somewhere!] 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 crossref:hubs[mirror-official].
+in crossref:hubs[mirror-official, Official Mirrors].
[[mirror-where-master]]
==== I Want to Access the Master Sites!
@@ -363,7 +363,7 @@ There is one master site for the FTP fileset.
This is the master site for the FTP fileset.
`ftp-master.FreeBSD.org` provides rsync access, in addition to FTP.
-Refer to crossref:hubs[mirror-ftp-rsync].
+Refer to crossref:hubs[mirror-ftp-rsync, Mirroring the FTP Site].
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
index 025d16ca7f..361b6c007c 100644
--- a/documentation/content/en/articles/ipsec-must/_index.adoc
+++ b/documentation/content/en/articles/ipsec-must/_index.adoc
@@ -52,8 +52,8 @@ toc::[]
[[problem]]
== The Problem
-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.
+First, lets assume you have crossref::ipsec-must[ipsec-install, Installing IPsec].
+How do you know it is crossref::ipsec-must[caveat, 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,7 +73,7 @@ This would be true even if some of the data in "encrypted mode" was not encrypte
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.
-crossref::ipsec-must[code] for a variant which measures successive (~quarter megabyte) chunks of a file.
+crossref::ipsec-must[code, Maurer's Universal Statistical Test (for block size8 bits)] for a variant which measures successive (~quarter megabyte) chunks of a file.
[[tcpdump]]
=== Tcpdump
@@ -100,9 +100,9 @@ Here is the experiment:
[.procedure]
====
. Open a window to an IPsec host and another window to an insecure host.
-. Now start crossref::ipsec-must[tcpdump].
+. Now start crossref::ipsec-must[tcpdump, 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 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.
+. Now run crossref::ipsec-must[code, Maurer's Universal Statistical Test (for block size8 bits)] 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
index 37e46cb731..edffbd10ea 100644
--- a/documentation/content/en/articles/ldap-auth/_index.adoc
+++ b/documentation/content/en/articles/ldap-auth/_index.adoc
@@ -188,7 +188,7 @@ Getting Private key
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 crossref:ldap-auth[ssl-ca] to generate a CA key and use it to sign individual server certificates.
+will want to see crossref:ldap-auth[ssl-ca, OpenSSL Certificates for LDAP] 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#:
@@ -494,7 +494,7 @@ Unfortunately, as of the time this was written FreeBSD did not support changing
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 crossref:ldap-auth[security-passwd]
+issues you should be made aware of; see crossref:ldap-auth[security-passwd, Password Storage]
[[chpw-shell]]
.Shell Script for Changing Passwords
diff --git a/documentation/content/en/articles/pam/_index.adoc b/documentation/content/en/articles/pam/_index.adoc
index 23dbb861c4..307690be04 100644
--- a/documentation/content/en/articles/pam/_index.adoc
+++ b/documentation/content/en/articles/pam/_index.adoc
@@ -419,10 +419,10 @@ If you are unsure, refer to the individual application's documentation to determ
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
-crossref:pam[pam-facilities-primitives].
+crossref:pam[pam-facilities-primitives, Facilities and Primitives].
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.
+ crossref:pam[pam-chains-policies, Chains and 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.
@@ -624,7 +624,7 @@ The following is a minimal implementation of man:su[1] using PAM.
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 crossref:pam[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, Sample PAM Conversation Function] 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
index 85f3ab4546..b6729150cd 100644
--- a/documentation/content/en/articles/pr-guidelines/_index.adoc
+++ b/documentation/content/en/articles/pr-guidelines/_index.adoc
@@ -121,11 +121,11 @@ The "patched" state is directly related to feedback, so you may go directly to "
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.
-* 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]
+* crossref:pr-guidelines[pr-unassigned, Unassigned PRs]
+* crossref:pr-guidelines[pr-assigned, Assigned PRs]
+* crossref:pr-guidelines[pr-dups, Duplicate PRs]
+* crossref:pr-guidelines[pr-stale, Stale PRs]
+* crossref:pr-guidelines[pr-misfiled-notpr, Non-Bug PRs]
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/releng/_index.adoc b/documentation/content/en/articles/releng/_index.adoc
index b54952577c..f19ccb2bdd 100644
--- a/documentation/content/en/articles/releng/_index.adoc
+++ b/documentation/content/en/articles/releng/_index.adoc
@@ -105,19 +105,19 @@ In addition to source updates via Subversion, binary patchkits are available to
The following sections of this article describe:
-crossref:releng[release-proc]::
+crossref:releng[release-proc, Release Process]::
The different phases of the release engineering process leading up to the actual system build.
-crossref:releng[release-build]::
+crossref:releng[release-build, Release Building]::
The actual build process.
-crossref:releng[extensibility]::
+crossref:releng[extensibility, Extensibility]::
How the base release may be extended by third parties.
-crossref:releng[lessons-learned]::
+crossref:releng[lessons-learned, Lessons Learned from FreeBSD 4.4]::
Some of the lessons learned through the release of FreeBSD 4.4.
-crossref:releng[future]::
+crossref:releng[future, Future Directions]::
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
index 3883615121..ba9bf48256 100644
--- a/documentation/content/en/articles/remote-install/_index.adoc
+++ b/documentation/content/en/articles/remote-install/_index.adoc
@@ -70,7 +70,7 @@ The instructions included in this article will benefit those using services prov
[.procedure]
====
-. 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.
+. As we have mentioned in the crossref:remote-install[background, 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
index 40088623e3..3ea3224636 100644
--- a/documentation/content/en/articles/solid-state/_index.adoc
+++ b/documentation/content/en/articles/solid-state/_index.adoc
@@ -108,7 +108,7 @@ varsize=8192
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 crossref:solid-state[intro] we detailed the limitations of flash memory - specifically the limited write capability.
+Remember that in crossref:solid-state[intro, Solid State Disk Devices] 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.
@@ -124,7 +124,7 @@ A few applications in the average system will immediately begin to fail as a res
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
-crossref:solid-state[strategies].
+crossref:solid-state[strategies, System Strategies for Small and Read Only Environments].
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:
@@ -244,7 +244,7 @@ Assuming that you configured your filesystem correctly when it was built on the
[[strategies]]
== System Strategies for Small and Read Only Environments
-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 crossref:solid-state[ro-fs, The `rc` Subsystem and Read-Only Filesystems], 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
@@ -272,7 +272,7 @@ Therefore, somewhere in [.filename]#/etc/rc.d/var#, after the section that creat
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 crossref:solid-state[ro-fs].
+using the mount syntax shown in crossref:solid-state[ro-fs, The `rc` Subsystem and Read-Only Filesystems].
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/books/arch-handbook/mac/_index.adoc b/documentation/content/en/books/arch-handbook/mac/_index.adoc
index 73a27cdf0e..961774e323 100644
--- a/documentation/content/en/books/arch-handbook/mac/_index.adoc
+++ b/documentation/content/en/books/arch-handbook/mac/_index.adoc
@@ -1978,7 +1978,7 @@ void mpo_create_root_mount(struct ucred *cred, struct mount *mp,
| Description
| Locking
-3+|See crossref:mac[mac-mpo-create-mount].
+3+|See crossref:mac[mac-mpo-create-mount, `mpo_create_mount`].
|===
Fill out the labels on the mount point being created by the passed subject credential.
@@ -4314,7 +4314,7 @@ void mpo_check_vnode_mmap_downgrade(struct ucred *cred, struct vnode *vp,
| Locking
|`cred`
-|See crossref:mac[mac-mpo-check-vnode-mmap].
+|See crossref:mac[mac-mpo-check-vnode-mmap, `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
index 7d773ca258..9922f89eb1 100644
--- a/documentation/content/en/books/arch-handbook/smp/_index.adoc
+++ b/documentation/content/en/books/arch-handbook/smp/_index.adoc
@@ -58,7 +58,7 @@ 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.
+definitions of these and other SMP-related terms, please see the crossref:smp[smp-glossary, Glossary] section of this article.
[[smp-lock-fundamentals]]
== Basic Tools and Locking Fundamentals
diff --git a/documentation/content/en/books/design-44bsd/_index.adoc b/documentation/content/en/books/design-44bsd/_index.adoc
index af20245ea0..b3b86c58b7 100644
--- a/documentation/content/en/books/design-44bsd/_index.adoc
+++ b/documentation/content/en/books/design-44bsd/_index.adoc
@@ -230,7 +230,7 @@ Important components of the kernel state are described in Chapter 4.
image:fig1.png[Process lifecycle]
The process lifecycle is depicted in
-crossref:design-44bsd[fig-process-lifecycle].
+crossref:design-44bsd[fig-process-lifecycle,.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.
diff --git a/documentation/content/en/books/dev-model/_index.adoc b/documentation/content/en/books/dev-model/_index.adoc
index d30dbd7253..6d621f6a29 100644
--- a/documentation/content/en/books/dev-model/_index.adoc
+++ b/documentation/content/en/books/dev-model/_index.adoc
@@ -252,9 +252,9 @@ Multiple development efforts in the kernel also require a closer coordination th
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 crossref:dev-model[role-maintainer] section.
+Maintainership will be discussed in the crossref:dev-model[role-maintainer, Maintainership] section.
-Documentation is handled by crossref:dev-model[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, The FreeBSD Documentation Project] 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.
@@ -263,7 +263,7 @@ It contains information about where to fetch the source, what patches to apply a
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 crossref:dev-model[sub-project-ports].
+Ports will be discussed further in the section crossref:dev-model[sub-project-ports, The Ports Subproject].
[[methodology-model]]
== Methodology model
@@ -505,7 +505,7 @@ The following list shows the responsibility lines and gives a description of eac
[[role-doc-manager]]
==== Documentation project manager
-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.
+crossref:dev-model[sub-project-documentation, The FreeBSD Documentation Project] 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].
@@ -530,7 +530,7 @@ The responsibilities of the Release Engineering Team are
* 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
-crossref:dev-model[process-release-engineering] section.
+crossref:dev-model[process-release-engineering, Release engineering] section.
[[role-releng]]
Hat held by: the Release Engineering team mailto:re@FreeBSD.org[re@FreeBSD.org].
@@ -557,14 +557,14 @@ The Security Officer is also responsible for taking action when security problem
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.
+crossref:dev-model[role-core, Core Team] 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 crossref:dev-model[tool-git] tool.
+the repository without using the crossref:dev-model[tool-git, 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.
@@ -574,10 +574,10 @@ Hat held by: the Source Repository Manager mailto:clusteradm@FreeBSD.org[cluster
==== Election Manager
The Election Manager is responsible for the
-crossref:dev-model[process-core-election] process.
+crossref:dev-model[process-core-election, 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
-crossref:dev-model[role-core]
+crossref:dev-model[role-core, Core Team]
Hat held only during elections.
@@ -586,14 +586,14 @@ Hat held only during elections.
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
-crossref:dev-model[sub-project-documentation] and acts as maintainer for the "www" tree.
+crossref:dev-model[sub-project-documentation, The FreeBSD Documentation Project] 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 crossref:dev-model[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, The Ports Subproject] 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].
@@ -690,11 +690,11 @@ 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
-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
+crossref:dev-model[tool-pgp, Pretty Good Privacy]-signed email is sent from either
+crossref:dev-model[role-core-secretary], crossref:dev-model[role-ports-manager, 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, Secure Shell] public
key, and PGP key from the new committer and sends them to
-crossref:dev-model[role-admin].
+crossref:dev-model[role-admin, 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
@@ -724,11 +724,11 @@ In this case, it can also be restored at a later time by core, should the commit
Roles in this process:
-. 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]
+. crossref:dev-model[role-core, Core Team]
+. crossref:dev-model[role-contributor, Contributor]
+. crossref:dev-model[role-committer, Committer]
+. crossref:dev-model[role-maintainer, Maintainership]
+. crossref:dev-model[role-mentor, Mentor]
[crossref:dev-model[freebsd-bylaws, FreeBSD, 2000A]]
[crossref:dev-model[freebsd-expiration-policy, FreeBSD, 2002H]]
@@ -749,7 +749,7 @@ 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 crossref:dev-model[role-vendor], the maintainer should ensure that the patch is contributed back to the vendor.
+from an outside crossref:dev-model[role-vendor, 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.
@@ -778,10 +778,10 @@ This report is picked up by the maintainer who reviews the code and commits it.
Hats included in this process are:
-. crossref:dev-model[role-committer]
-. crossref:dev-model[role-contributor]
-. crossref:dev-model[role-vendor]
-. crossref:dev-model[role-reviewer]
+. crossref:dev-model[role-committer, Committer]
+. crossref:dev-model[role-contributor, Contributor]
+. crossref:dev-model[role-vendor, Vendor]
+. crossref:dev-model[role-reviewer, Reviewers]
[crossref:dev-model[freebsd-committer, FreeBSD, 2001]]
[crossref:dev-model[jorgensen2001, Jørgensen, 2001]]
@@ -821,9 +821,9 @@ After the vote is over, the election results are announced and the new core team
Hats in core elections are:
-* crossref:dev-model[role-core]
-* crossref:dev-model[role-committer]
-* crossref:dev-model[role-election-manager]
+* crossref:dev-model[role-core, Core Team]
+* crossref:dev-model[role-committer, Committer]
+* crossref:dev-model[role-election-manager, Election Manager]
[crossref:dev-model[freebsd-bylaws, FreeBSD, 2000A]]
[crossref:dev-model[bsd-election2002, FreeBSD, 2002B]]
@@ -844,7 +844,7 @@ The wishes that come within the responsibility of a developer are given to that
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
-crossref:dev-model[tool-bugzilla] tool.
+crossref:dev-model[tool-bugzilla, 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.
@@ -928,14 +928,14 @@ Problems include bug reports, feature requests, feature enhancements and notices
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 crossref:dev-model[role-bugbuster] classifies the problem and sends it to the correct group or maintainer within the project.
+A crossref:dev-model[role-bugbuster, 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
-crossref:dev-model[model-maintenance].
+crossref:dev-model[model-maintenance, 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.
@@ -949,9 +949,9 @@ This patch is then committed and the problem report is closed.
The roles included in this process are:
-. crossref:dev-model[role-problem-originator]
-. crossref:dev-model[role-maintainer]
-. crossref:dev-model[role-bugbuster]
+. crossref:dev-model[role-problem-originator, Report originator]
+. crossref:dev-model[role-maintainer, Maintainership]
+. crossref:dev-model[role-bugbuster, Bugbuster]
[crossref:dev-model[freebsd-handle-pr, FreeBSD, 2002C]].
[crossref:dev-model[freebsd-send-pr, FreeBSD, 2002D]]
@@ -981,8 +981,8 @@ All penalties come from breaking social etiquette.
Hats involved in this process:
-* crossref:dev-model[role-core]
-* crossref:dev-model[role-committer]
+* crossref:dev-model[role-core, Core Team]
+* crossref:dev-model[role-committer, Committer]
[[process-release-engineering]]
=== Release engineering
@@ -1013,7 +1013,7 @@ Updates are less likely to be allowed during this period, except for important b
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
-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.].
+crossref:dev-model[tool-pgp, Pretty Good Privacy]-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.
@@ -1107,13 +1107,13 @@ The amount of ports has grown at a tremendous rate, as shown by the following fi
.Number of ports added between 1995 and 2022 [[fig-ports]]
image::portsstatus.svg
-crossref:dev-model[fig-ports] shows the number of ports available to FreeBSD in the period 1995 to 2022.
+crossref:dev-model[fig-ports,image::portsstatus.svg] 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 crossref:dev-model[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, 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.
diff --git a/documentation/content/en/books/developers-handbook/tools/_index.adoc b/documentation/content/en/books/developers-handbook/tools/_index.adoc
index 15cf026c77..bb31426367 100644
--- a/documentation/content/en/books/developers-handbook/tools/_index.adoc
+++ b/documentation/content/en/books/developers-handbook/tools/_index.adoc
@@ -180,7 +180,7 @@ Moreover, distributing a program written for a compiler is usually more straight
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 crossref:tools[emacs].
+Using Emacs as an IDE is discussed in crossref:tools[emacs, Using Emacs as a Development Environment].
[[tools-compiling]]
== Compiling with `cc`
@@ -367,7 +367,7 @@ Basically, if the program failed under certain conditions, the system would writ
==== Fascinating stuff, but what I am supposed to do now?
-Use a debugger to analyze the core (see crossref:tools[debugging]).
+Use a debugger to analyze the core (see crossref:tools[debugging, Debugging]).
==== When my program dumped core, it said something about a segmentation fault. What is that?
diff --git a/documentation/content/en/books/fdp-primer/editor-config/_index.adoc b/documentation/content/en/books/fdp-primer/editor-config/_index.adoc
index 43411e6d6d..d7cf1b516e 100644
--- 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 @@ Adjusting your text editor configuration can make working on document files quic
[[editor-config-vim]]
== Vim
-Install from package:editors/vim[], then follow the configuration instructions in crossref:editor-config[editor-config-vim-config].
+Install from package:editors/vim[], then follow the configuration instructions in crossref:editor-config[editor-config-vim-config, Configuration].
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
index ab431aeab8..212b54a22d 100644
--- a/documentation/content/en/books/handbook/advanced-networking/_index.adoc
+++ b/documentation/content/en/books/handbook/advanced-networking/_index.adoc
@@ -154,7 +154,7 @@ Such routes only show up on the host that supports the alias and all other hosts
The final line (destination subnet `224`) deals with multicasting.
Various attributes of each route can be seen in the `Flags` column.
-crossref:advanced-networking[routeflags] summarizes some of these flags and their meanings:
+crossref:advanced-networking[routeflags,.Commonly Seen Routing Table Flags] summarizes some of these flags and their meanings:
[[routeflags]]
.Commonly Seen Routing Table Flags
@@ -770,7 +770,7 @@ hostapd_enable="YES"
....
Before trying to configure man:hostapd[8], first configure the basic settings
-introduced in crossref:advanced-networking[network-wireless-ap-basic].
+introduced in crossref:advanced-networking[network-wireless-ap-basic, Basic Settings].
===== WPA2-PSK
diff --git a/documentation/content/en/books/handbook/audit/_index.adoc b/documentation/content/en/books/handbook/audit/_index.adoc
index 4bf987fe02..9bd9c84cc5 100644
--- a/documentation/content/en/books/handbook/audit/_index.adoc
+++ b/documentation/content/en/books/handbook/audit/_index.adoc
@@ -126,7 +126,7 @@ Selection expressions are used in a number of places in the audit configuration
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.
-crossref:audit[event-selection] summarizes the default audit event classes:
+crossref:audit[event-selection,.Default Audit Event Classes] summarizes the default audit event classes:
[[event-selection]]
.Default Audit Event Classes
@@ -220,7 +220,7 @@ crossref:audit[event-selection] summarizes the default audit event classes:
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.
-crossref:audit[event-prefixes] summarizes the available prefixes:
+crossref:audit[event-prefixes,.Prefixes for Audit Event Classes] summarizes the available prefixes:
[[event-prefixes]]
.Prefixes for Audit Event Classes
diff --git a/documentation/content/en/books/handbook/basics/_index.adoc b/documentation/content/en/books/handbook/basics/_index.adoc
index b86f4cbf8a..4351d68819 100644
--- a/documentation/content/en/books/handbook/basics/_index.adoc
+++ b/documentation/content/en/books/handbook/basics/_index.adoc
@@ -345,7 +345,7 @@ This software provides activity logging and allows the administrator to configur
FreeBSD provides a variety of different commands to manage user accounts.
The most common commands are summarized in
-crossref:basics[users-modifying-utilities], followed by some examples of their usage.
+crossref:basics[users-modifying-utilities,.Utilities for Managing User Accounts], followed by some examples of their usage.
See the manual page for each utility for more details and usage examples.
[[users-modifying-utilities]]
@@ -494,9 +494,9 @@ When the user exits from the editor, the user database is updated with the new i
This utility will prompt for the user's password when exiting the editor, unless the utility is run as the superuser.
====
-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.
+In crossref:basics[users-modifying-chpass-su,.Using `chpass` as Superuser], 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 crossref:basics[users-modifying-chpass-ru].
+This is shown in crossref:basics[users-modifying-chpass-ru,.Using `chpass` as Regular User].
[[users-modifying-chpass-su]]
.Using `chpass` as Superuser
@@ -1074,12 +1074,12 @@ This directory is the first one mounted at boot time and it contains the base sy
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 crossref:basics[disk-organization].
+This is further described in crossref:basics[disk-organization, 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 crossref:basics[disks-fstab].
+Details can be found in crossref:basics[disks-fstab, The fstab File].
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.
@@ -1321,13 +1321,13 @@ This letter is appended to the device name, so "da0__a__" is the `a` partition o
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 crossref:basics[disks-naming].
+Common codes are listed in crossref:basics[disks-naming,.Disk Device Names].
*** 1364 LINES SKIPPED ***