git: 557464e66e - main - [documentation]: Fix links in all output formats
- Go to: [ bottom of page ] [ top of archives ] [ this month ]
Date: Sat, 07 Sep 2024 18:03:41 UTC
The branch main has been updated by fernape:
URL: https://cgit.FreeBSD.org/doc/commit/?id=557464e66e059e785c3d83036ed2168df224198f
commit 557464e66e059e785c3d83036ed2168df224198f
Author: Fernando Apesteguía <fernape@FreeBSD.org>
AuthorDate: 2024-08-11 16:52:22 +0000
Commit: Fernando Apesteguía <fernape@FreeBSD.org>
CommitDate: 2024-09-07 18:02:30 +0000
[documentation]: Fix links in all output formats
Use the crossref: macro for intra-file and intra-book links.
This will produce the correct link in Single HTML, Splitted HTML and PDF.
Rework the macro to include the PDF special render.
While here, briefly document macros.
PR: 266107
Reviewed by: bcr@, dbaio@, concussious.bugzilla_runbox.com
Differential Revision: https://reviews.freebsd.org/D46480
---
.../en/articles/building-products/_index.adoc | 58 ++--
.../en/articles/committers-guide/_index.adoc | 67 +++--
.../content/en/articles/contributing/_index.adoc | 15 +-
.../content/en/articles/contributors/_index.adoc | 3 +-
.../content/en/articles/freebsd-releng/_index.adoc | 21 +-
.../en/articles/gjournal-desktop/_index.adoc | 2 +-
documentation/content/en/articles/hubs/_index.adoc | 16 +-
.../content/en/articles/ipsec-must/_index.adoc | 13 +-
.../content/en/articles/ldap-auth/_index.adoc | 9 +-
.../content/en/articles/license-guide/_index.adoc | 4 +-
documentation/content/en/articles/pam/_index.adoc | 10 +-
.../content/en/articles/pr-guidelines/_index.adoc | 10 +-
.../content/en/articles/rc-scripting/_index.adoc | 11 +-
.../content/en/articles/releng/_index.adoc | 10 +-
.../content/en/articles/remote-install/_index.adoc | 2 +-
.../content/en/articles/solid-state/_index.adoc | 11 +-
.../content/en/articles/vinum/_index.adoc | 17 +-
.../content/en/books/arch-handbook/mac/_index.adoc | 4 +-
.../content/en/books/arch-handbook/smp/_index.adoc | 6 +-
.../en/books/arch-handbook/sound/_index.adoc | 17 +-
.../content/en/books/design-44bsd/_index.adoc | 40 ++-
.../content/en/books/dev-model/_index.adoc | 164 +++++++----
.../en/books/developers-handbook/ipv6/_index.adoc | 23 +-
.../en/books/developers-handbook/tools/_index.adoc | 6 +-
.../en/books/developers-handbook/x86/_index.adoc | 4 +-
.../en/books/fdp-primer/editor-config/_index.adoc | 2 +-
.../books/handbook/advanced-networking/_index.adoc | 12 +-
.../content/en/books/handbook/audit/_index.adoc | 8 +-
.../content/en/books/handbook/basics/_index.adoc | 28 +-
.../content/en/books/handbook/boot/_index.adoc | 7 +-
.../en/books/handbook/bsdinstall/_index.adoc | 83 ++++--
.../content/en/books/handbook/config/_index.adoc | 10 +-
.../en/books/handbook/cutting-edge/_index.adoc | 24 +-
.../content/en/books/handbook/desktop/_index.adoc | 2 +-
.../content/en/books/handbook/disks/_index.adoc | 25 +-
.../en/books/handbook/firewalls/_index.adoc | 5 +-
.../content/en/books/handbook/geom/_index.adoc | 7 +-
.../content/en/books/handbook/glossary.adoc | 268 ++++++++---------
.../content/en/books/handbook/jails/_index.adoc | 11 +-
.../en/books/handbook/kernelconfig/_index.adoc | 3 +-
.../content/en/books/handbook/l10n/_index.adoc | 14 +-
.../content/en/books/handbook/mac/_index.adoc | 2 +-
.../content/en/books/handbook/mail/_index.adoc | 10 +-
.../content/en/books/handbook/mirrors/_index.adoc | 3 +-
.../en/books/handbook/network-servers/_index.adoc | 2 +-
.../content/en/books/handbook/network/_index.adoc | 3 +-
.../content/en/books/handbook/ports/_index.adoc | 7 +-
.../content/en/books/handbook/printing/_index.adoc | 5 +-
.../content/en/books/handbook/security/_index.adoc | 5 +-
.../en/books/handbook/serialcomms/_index.adoc | 19 +-
.../content/en/books/handbook/wine/_index.adoc | 15 +-
.../content/en/books/handbook/x11/_index.adoc | 7 +-
.../content/en/books/handbook/zfs/_index.adoc | 316 ++++++++++++++++-----
.../en/books/porters-handbook/flavors/_index.adoc | 7 +-
.../books/porters-handbook/makefiles/_index.adoc | 208 +++++++++-----
.../en/books/porters-handbook/new-port/_index.adoc | 2 +-
.../en/books/porters-handbook/order/_index.adoc | 20 +-
.../books/porters-handbook/pkg-files/_index.adoc | 2 +-
.../en/books/porters-handbook/plist/_index.adoc | 14 +-
.../en/books/porters-handbook/special/_index.adoc | 35 ++-
.../en/books/porters-handbook/testing/_index.adoc | 11 +-
.../books/porters-handbook/upgrading/_index.adoc | 2 +-
.../en/books/porters-handbook/uses/_index.adoc | 24 +-
.../lib/CrossDocumentReferencesMacro/extension.rb | 1 +
.../lib/InterDocumentReferencesMacro/extension.rb | 32 ++-
65 files changed, 1137 insertions(+), 667 deletions(-)
diff --git a/documentation/content/en/articles/building-products/_index.adoc b/documentation/content/en/articles/building-products/_index.adoc
index 038feb9c07..b444b4a41e 100644
--- a/documentation/content/en/articles/building-products/_index.adoc
+++ b/documentation/content/en/articles/building-products/_index.adoc
@@ -62,7 +62,8 @@ toc::[]
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 @@ After reading this article you should have:
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 @@ A selection of these are listed below:
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 @@ Conflict resolution is performed by a nine member "Core Team" that is elected fr
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 list of extref:{committers-guide}[supported architectures, archs] is part of
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 @@ Using open-source code is best viewed not as a one-off activity, but as an __ong
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 @@ To be able to work effectively with the FreeBSD project, you need to understand
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 @@ For example:
+
*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 FreeBSD project maintains a link:https://www.FreeBSD.org/commercial/consult_
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
index 8eda3085f3..921a823a7d 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 <<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 @@ 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 <<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 @@ toc::[]
|`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 @@ Rather than suggest a single way, here are some links to sites that describe var
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 @@ Examples:
* 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 @@ At this point, you should have a pristine copy of glorbnitz ready to commit.
....
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 @@ Here 'good' means:
. 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 @@ 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 <<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 FreeBSD project's Git repositories do not, yet, allow user-created branches
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 @@ github git@github.com:gvnn3/freebsd-src.git (push)
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 @@ While this is not an official way to submit patches at this time, sometimes good
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 @@ It is worth noting that if your `github` origin uses `https://`, the only step y
[[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 @@ 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 <<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 @@ For those willing to send e-mail messages through the FreeBSD.org infrastructure
. 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 @@ 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 <<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 @@ 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 <<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 @@ Committers with non-``FreeBSD.org`` Phabricator accounts can have the old accoun
[.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 @@ Their contributions are as valid and as important as your own.
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 to the kernel, make sure you can still compile both GENERIC
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 @@ For a platform to be promoted to a higher tier, any missing support guarantees m
[[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 @@ Once the port and its category's Makefile are ready, the new port can be committ
....
[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 @@ It usually lasted a couple of weeks.
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 @@ 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:
-* <<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
index 53c9a450c7..10bdcf03e5 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 <<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 @@ Please avoid creating large, wide-ranging cleanup patches: they are too large an
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 @@ 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 <<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 @@ 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 <<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
index 41516b19fc..0937c40586 100644
--- a/documentation/content/en/articles/contributors/_index.adoc
+++ b/documentation/content/en/articles/contributors/_index.adoc
@@ -61,7 +61,8 @@ endif::[]
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
index db72238547..27c467b1a0 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:
-<<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 @@ 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 <<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 @@ To request an Errata Notice after a release cycle has completed, a developer sho
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
index 71ce2b3084..774bcf29f3 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 <<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
index 403cd84b9a..3269322e7a 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 <<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 @@ Lots of online documentation leads "interactive"users to `ftp.FreeBSD.org` so au
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 @@ The short answer is: from the site that is closest to you in Internet terms, or
[[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 @@ This means:
[[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 @@ 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 <<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
index d4de24e1a9..025d16ca7f 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 <<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 @@ 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.
-<<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 @@ Here is the experiment:
[.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
index 10bba18534..37e46cb731 100644
--- a/documentation/content/en/articles/ldap-auth/_index.adoc
+++ b/documentation/content/en/articles/ldap-auth/_index.adoc
@@ -187,7 +187,8 @@ 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 <<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 @@ If it does, your database is properly configured to be used as an LDAP authentic
[[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 @@ Congratulations! You should now have working LDAP authentication.
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
index c349ffd266..1533261697 100644
--- a/documentation/content/en/articles/license-guide/_index.adoc
+++ b/documentation/content/en/articles/license-guide/_index.adoc
@@ -248,13 +248,13 @@ In these cases, the license contained in the file governs.
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
index 36c4a77097..23dbb861c4 100644
--- a/documentation/content/en/articles/pam/_index.adoc
+++ b/documentation/content/en/articles/pam/_index.adoc
@@ -411,16 +411,18 @@ It is essential to understand that PAM's configuration system is centered on cha
[[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 @@ 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 <<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
index 0f5fbab15d..85f3ab4546 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.
-* <<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
index e9e5ef0389..14e0ad4bb4 100644
--- a/documentation/content/en/articles/rc-scripting/_index.adoc
+++ b/documentation/content/en/articles/rc-scripting/_index.adoc
@@ -91,7 +91,7 @@ Now a typical script can be just a few lines' worth of man:sh[1] code.
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 @@ That is, each [.filename]#rc.d# script _must_ set `name` before it calls man:rc.
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 @@ This is reflected in the list of processes, which can confuse man:rc.subr[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 @@ Since the final command line is passed to `eval` for its actual execution, input
_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 @@ Keep in mind that putting a service name in the `REQUIRE:` line does not guarant
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
index 34a81675b9..b54952577c 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:
-<<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
index 9efc5e4165..3883615121 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 <<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
index 1c019fb8a1..40088623e3 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 <<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 @@ Therefore, in addition to removing the `swap` entry from your [.filename]#/etc/f
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 @@ Assuming that you configured your filesystem correctly when it was built on the
[[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 @@ Therefore, somewhere in [.filename]#/etc/rc.d/var#, after the section that creat
=== 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
index 0583ae94a7..567d4b7e42 100644
--- a/documentation/content/en/articles/vinum/_index.adoc
+++ b/documentation/content/en/articles/vinum/_index.adoc
@@ -106,7 +106,7 @@ The most obvious method is to divide the virtual disk into groups of consecutive
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 @@ This mapping is called _striping_ or RAID-0.
`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 @@ As long as at least one plex can provide the data for the complete address range
* 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]]
*** 4407 LINES SKIPPED ***