diff --git a/documentation/content/en/articles/building-products/_index.adoc b/documentation/content/en/articles/building-products/_index.adoc --- a/documentation/content/en/articles/building-products/_index.adoc +++ b/documentation/content/en/articles/building-products/_index.adoc @@ -63,7 +63,7 @@ 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 @@ 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 --- a/documentation/content/en/articles/committers-guide/_index.adoc +++ b/documentation/content/en/articles/committers-guide/_index.adoc @@ -49,7 +49,7 @@ Almost all FreeBSD developers have commit rights to one or more repositories. However, a few developers do not, and some of the information here applies to them as well. (For instance, some people only have rights to work with the Problem Report database.) -Please see 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 @@ |`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 @@ |=== 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 @@ ===== 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 @@ 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 @@ . 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 @@ 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 @@ . 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 @@ ==== . 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 @@ 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 @@ 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 --- a/documentation/content/en/articles/contributing/_index.adoc +++ b/documentation/content/en/articles/contributing/_index.adoc @@ -150,9 +150,9 @@ * Find some cool or useful software and extref:{porters-handbook}[create a port] for it. * There are a large number of ports that have no maintainer. -Become a maintainer and 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 @@ 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 @@ ==== 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 @@ 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 --- a/documentation/content/en/articles/freebsd-releng/_index.adoc +++ b/documentation/content/en/articles/freebsd-releng/_index.adoc @@ -88,28 +88,28 @@ The following sections of this article describe: -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 @@ 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 @@ 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 --- a/documentation/content/en/articles/gjournal-desktop/_index.adoc +++ b/documentation/content/en/articles/gjournal-desktop/_index.adoc @@ -385,7 +385,7 @@ The journal probably fills up before it has a chance to get committed (flushed) to disk. Keep in mind the size of the journal depends on the usage load, and not the size of the data provider. If your disk activity is high, you need a larger partition for the journal. -See the note in the 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 --- a/documentation/content/en/articles/hubs/_index.adoc +++ b/documentation/content/en/articles/hubs/_index.adoc @@ -191,7 +191,7 @@ The best way to mirror the FTP area is rsync. You can install the port package:net/rsync[] and then use rsync to sync with your upstream host. -rsync is already mentioned in 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 @@ 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 @@ ==== 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 @@ [[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 @@ 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 --- a/documentation/content/en/articles/ipsec-must/_index.adoc +++ b/documentation/content/en/articles/ipsec-must/_index.adoc @@ -52,8 +52,8 @@ [[problem]] == The Problem -First, lets assume you have 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 @@ 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 @@ [.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 --- a/documentation/content/en/articles/ldap-auth/_index.adoc +++ b/documentation/content/en/articles/ldap-auth/_index.adoc @@ -188,7 +188,7 @@ 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 @@ 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 --- a/documentation/content/en/articles/pam/_index.adoc +++ b/documentation/content/en/articles/pam/_index.adoc @@ -419,10 +419,10 @@ 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 @@ 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 --- a/documentation/content/en/articles/pr-guidelines/_index.adoc +++ b/documentation/content/en/articles/pr-guidelines/_index.adoc @@ -121,11 +121,11 @@ While handling problem reports, either as a developer who has direct access to the Problem Reports database or as a contributor who browses the database and submits followups with patches, comments, suggestions or change requests, you will come across several different types of PRs. -* 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 --- a/documentation/content/en/articles/releng/_index.adoc +++ b/documentation/content/en/articles/releng/_index.adoc @@ -105,19 +105,19 @@ The following sections of this article describe: -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 --- a/documentation/content/en/articles/remote-install/_index.adoc +++ b/documentation/content/en/articles/remote-install/_index.adoc @@ -70,7 +70,7 @@ [.procedure] ==== -. As we have mentioned in the 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 --- a/documentation/content/en/articles/solid-state/_index.adoc +++ b/documentation/content/en/articles/solid-state/_index.adoc @@ -108,7 +108,7 @@ Remember that this value is in sectors by default. The fact that [.filename]#/var# is a read-write filesystem is an important distinction, as the [.filename]#/# partition (and any other partitions you may have on your flash media) should be mounted read-only. -Remember that in 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 @@ 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 @@ [[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 @@ 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 --- a/documentation/content/en/books/arch-handbook/mac/_index.adoc +++ b/documentation/content/en/books/arch-handbook/mac/_index.adoc @@ -1978,7 +1978,7 @@ | Description | Locking -3+|See 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 @@ | 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 --- a/documentation/content/en/books/arch-handbook/smp/_index.adoc +++ b/documentation/content/en/books/arch-handbook/smp/_index.adoc @@ -58,7 +58,7 @@ 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 --- a/documentation/content/en/books/design-44bsd/_index.adoc +++ b/documentation/content/en/books/design-44bsd/_index.adoc @@ -230,7 +230,7 @@ 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 --- a/documentation/content/en/books/dev-model/_index.adoc +++ b/documentation/content/en/books/dev-model/_index.adoc @@ -252,9 +252,9 @@ The core utilities, known as userland, provide the interface that identifies FreeBSD, both user interface, shared libraries and external interfaces to connecting clients. Currently, 162 people are involved in userland development and maintenance, many being maintainers for their own part of the code. -Maintainership will be discussed in the 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 @@ 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 @@ [[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 @@ * 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 @@ 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 @@ ==== 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ .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 --- a/documentation/content/en/books/developers-handbook/tools/_index.adoc +++ b/documentation/content/en/books/developers-handbook/tools/_index.adoc @@ -180,7 +180,7 @@ As the edit-compile-run-debug cycle is rather tedious when using separate programs, many commercial compiler makers have produced Integrated Development Environments (IDEs for short). FreeBSD does not include an IDE in the base system, but package:devel/kdevelop[] is available in the Ports Collection and many use Emacs for this purpose. -Using Emacs as an IDE is discussed in 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 @@ ==== 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 --- a/documentation/content/en/books/fdp-primer/editor-config/_index.adoc +++ b/documentation/content/en/books/fdp-primer/editor-config/_index.adoc @@ -52,7 +52,7 @@ [[editor-config-vim]] == Vim -Install from package:editors/vim[], then follow the configuration instructions in 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 --- a/documentation/content/en/books/handbook/advanced-networking/_index.adoc +++ b/documentation/content/en/books/handbook/advanced-networking/_index.adoc @@ -154,7 +154,7 @@ The final line (destination subnet `224`) deals with multicasting. Various attributes of each route can be seen in the `Flags` column. -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 @@ .... 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 --- a/documentation/content/en/books/handbook/audit/_index.adoc +++ b/documentation/content/en/books/handbook/audit/_index.adoc @@ -126,7 +126,7 @@ Expressions contain a list of event classes to match. Selection expressions are evaluated from left to right, and two expressions are combined by appending one onto the other. -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 @@ 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 --- a/documentation/content/en/books/handbook/basics/_index.adoc +++ b/documentation/content/en/books/handbook/basics/_index.adoc @@ -345,7 +345,7 @@ 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 @@ 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 @@ 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 @@ 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]. When referring to a partition in a slice, include the disk name, `s`, the slice number, and then the partition letter. -Examples are shown in crossref:basics[basics-disk-slice-part]. +Examples are shown in crossref:basics[basics-disk-slice-part,.Sample Disk, Slice, and Partition Names]. GPT partitions include the disk name, `p`, and then the partition number. -crossref:basics[basics-concept-disk-model] shows a conceptual model of a disk layout using MBR slices. +crossref:basics[basics-concept-disk-model,.Conceptual Model of a Disk] shows a conceptual model of a disk layout using MBR slices. When installing FreeBSD, configure the disk slices if using MBR, and create partitions within the slice to be used for FreeBSD. If using GPT, configure partitions for each file system. @@ -1423,7 +1423,7 @@ .... `device`:: -An existing device name as explained in crossref:basics[disks-naming]. +An existing device name as explained in crossref:basics[disks-naming,.Disk Device Names]. `mount-point`:: An existing directory on which to mount the file system. @@ -1684,7 +1684,7 @@ Another feature of the shell is the use of environment variables. Environment variables are a variable/key pair stored in the shell's environment. This environment can be read by any program invoked by the shell, and thus contains a lot of program configuration. -crossref:basics[shell-env-vars] provides a list of common environment variables and their meanings. +crossref:basics[shell-env-vars,.Common Environment Variables] provides a list of common environment variables and their meanings. Note that the names of environment variables are always in uppercase. [[shell-env-vars]] @@ -1859,7 +1859,7 @@ Many applications which modify files or require typed input will automatically open a text editor. To change the default editor, set the `EDITOR` environment variable as described -in crossref:basics[shells]. +in crossref:basics[shells, Shells]. [[basics-devices]] == Devices and Device Nodes diff --git a/documentation/content/en/books/handbook/boot/_index.adoc b/documentation/content/en/books/handbook/boot/_index.adoc --- a/documentation/content/en/books/handbook/boot/_index.adoc +++ b/documentation/content/en/books/handbook/boot/_index.adoc @@ -217,7 +217,7 @@ Finally, by default, loader issues a 10 second wait for key presses, and boots the kernel if it is not interrupted. If interrupted, the user is presented with a prompt which understands the command set, where the user may adjust variables, unload all modules, load modules, and then finally boot or reboot. -crossref:boot[boot-loader-commands] lists the most commonly used loader commands. +crossref:boot[boot-loader-commands,.Loader Built-In Commands] lists the most commonly used loader commands. For a complete discussion of all available commands, refer to man:loader[8]. [[boot-loader-commands]] @@ -306,7 +306,7 @@ === Last Stage Once the kernel is loaded by either loader or by boot2, which bypasses loader, it examines any boot flags and adjusts its behavior as necessary. -crossref:boot[boot-kernel] lists the commonly used boot flags. +crossref:boot[boot-kernel,.Kernel Interaction During Boot] lists the commonly used boot flags. Refer to man:boot[8] for more information on the other boot flags. [[boot-kernel]] @@ -398,7 +398,7 @@ These "device hints" are used by device drivers for device configuration. Device hints may also be specified at the Stage 3 boot loader prompt, as -demonstrated in crossref:boot[boot-loader]. +demonstrated in crossref:boot[boot-loader, Stage Three]. Variables can be added using `set`, removed with `unset`, and viewed `show`. Variables set in [.filename]#/boot/device.hints# can also be overridden. Device hints entered at the boot loader are not permanent and will not be applied on the next reboot. diff --git a/documentation/content/en/books/handbook/bsdinstall/_index.adoc b/documentation/content/en/books/handbook/bsdinstall/_index.adoc --- a/documentation/content/en/books/handbook/bsdinstall/_index.adoc +++ b/documentation/content/en/books/handbook/bsdinstall/_index.adoc @@ -173,11 +173,11 @@ * `*-dvd1.iso*`: This file contains all of the files needed to install FreeBSD, its source, and the Ports Collection. It also contains a set of popular binary packages for installing a window manager and some applications so that a complete system can be installed from media without requiring a connection to the Internet. This file should be burned to optical media. * `*-memstick.img*`: This file contains all of the files needed to install FreeBSD, its source, and the Ports Collection. Write this file to a USB stick - as shown in crossref:bsdinstall[bsdinstall-usb]. + as shown in crossref:bsdinstall[bsdinstall-usb, Writing an Image File to USB]. * `*-mini-memstick.img*`: Like `*-bootonly.iso*`, does not include installation files, but downloads them as needed. A working internet connection is required during installation. It should be written to a USB stick as shown in - crossref:bsdinstall[bsdinstall-usb]. + crossref:bsdinstall[bsdinstall-usb, Writing an Image File to USB]. After downloading the image file, download at least one _checksum_ file from the same directory. There are two _checksum_ files available, named after the release number and the architecture name. @@ -284,7 +284,7 @@ This section describes how to boot the system from the installation media which was prepared using the instructions in -crossref:bsdinstall[bsdinstall-installation-media]. +crossref:bsdinstall[bsdinstall-installation-media, Prepare the Installation Media]. When using a bootable USB stick, plug in the USB stick before turning on the computer. When booting from CD or DVD, turn on the computer and insert the media at the first opportunity. How to configure the system to boot from the inserted media depends upon the architecture. @@ -310,7 +310,7 @@ * `Cons`: Allow to continue the installation by `video`, `serial`, `Dual (serial primary)` or `Dual (Video primary)` * `Kernel`: Loads a different kernel. * `Boot Options`: Opens the menu shown in, and described under, - crossref:bsdinstall[bsdinstall-boot-options-menu]. + crossref:bsdinstall[bsdinstall-boot-options-menu,.FreeBSD Boot Options Menu]. [[bsdinstall-boot-options-menu]] .FreeBSD Boot Options Menu @@ -331,7 +331,7 @@ After making the needed selections, press kbd:[1] or kbd:[Backspace] to return to the main boot menu, then press kbd:[Enter] to continue booting into FreeBSD. A series of boot messages will appear as FreeBSD carries out its hardware device probes and loads the installation program. Once the boot is complete, the welcome menu shown in -crossref:bsdinstall[bsdinstall-choose-mode] will be displayed. +crossref:bsdinstall[bsdinstall-choose-mode,.Welcome Menu] will be displayed. [[bsdinstall-choose-mode]] .Welcome Menu @@ -342,7 +342,7 @@ Otherwise, use the right or left arrows or the colorized letter to select the desired menu item. The btn:[Shell] can be used to access a FreeBSD shell in order to use command line utilities to prepare the disks before installation. The btn:[Live CD] option can be used to try out FreeBSD before installing it. -The live version is described in crossref:bsdinstall[using-live-cd]. +The live version is described in crossref:bsdinstall[using-live-cd, Using the Live CD]. [TIP] ==== @@ -362,14 +362,14 @@ === Selecting the Keymap Menu Before starting the process, bsdinstall will load the keymap files as shown in -crossref:bsdinstall[bsdinstall-keymap-loading]. +crossref:bsdinstall[bsdinstall-keymap-loading,.Keymap Loading]. [[bsdinstall-keymap-loading]] .Keymap Loading image::bsdinstall-keymap-loading.png[Keymap loading] After the keymaps have been loaded, bsdinstall displays the menu shown in -crossref:bsdinstall[bsdinstall-keymap-10]. +crossref:bsdinstall[bsdinstall-keymap-10,.Keymap Selection Menu]. Use the up and down arrows to select the keymap that most closely represents the mapping of the keyboard attached to the system. Press kbd:[Enter] to save the selection. @@ -385,7 +385,7 @@ In addition, when selecting a different keymap, the user can try the keymap and ensure it is correct before proceeding, as shown in -crossref:bsdinstall[bsdinstall-keymap-testing]. +crossref:bsdinstall[bsdinstall-keymap-testing,.Keymap Testing Menu]. [[bsdinstall-keymap-testing]] .Keymap Testing Menu @@ -435,10 +435,10 @@ [[bsdinstall-netinstall]] === Installing from the Network -The menu shown in crossref:bsdinstall[bsdinstall-netinstall-notify] only appears when installing from a `-bootonly.iso` or `-mini-memstick.img`, as this installation media does not hold copies of the installation files. +The menu shown in crossref:bsdinstall[bsdinstall-netinstall-notify,.Installing from the Network] only appears when installing from a `-bootonly.iso` or `-mini-memstick.img`, as this installation media does not hold copies of the installation files. Since the installation files must be retrieved over a network connection, this menu indicates that the network interface must be configured first. If this menu is shown in any step of the process, remember to follow the -instructions in crossref:bsdinstall[bsdinstall-config-network-dev]. +instructions in crossref:bsdinstall[bsdinstall-config-network-dev, Configuring Network Interfaces]. [[bsdinstall-netinstall-notify]] .Installing from the Network @@ -536,7 +536,7 @@ GPT is usually the most appropriate choice for amd64 computers. Older computers that are not compatible with GPT should use MBR. The other partition schemes are generally used for uncommon or older computers. -More information is available in crossref:bsdinstall[partition-schemes]. +More information is available in crossref:bsdinstall[partition-schemes,.Partitioning Schemes]. [[bsdinstall-ufs-scheme]] .Select Partition Scheme @@ -561,7 +561,7 @@ image::bsdinstall-final-confirmation.png[Menu indicating to the user that all changes will be written to disk and informing that if he decides to continue the existing data will be permanently deleted.] To continue with the installation process, go to -crossref:bsdinstall[bsdinstall-fetching-distribution]. +crossref:bsdinstall[bsdinstall-fetching-distribution, Fetching Distribution Files]. [[bsdinstall-part-manual]] === Manual Partitioning @@ -625,7 +625,7 @@ Note that `/tmp` can be added later as a memory-based file system (man:tmpfs[5]) on systems with sufficient memory. ==== -See crossref:bsdinstall[bsdinstall-part-manual-splitfs] for an example. +See crossref:bsdinstall[bsdinstall-part-manual-splitfs,.Creating Traditional Split File System Partitions] for an example. The `Size` may be entered with common abbreviations: _K_ for kilobytes, _M_ for megabytes, or _G_ for gigabytes. @@ -705,7 +705,7 @@ After the custom partitions have been created, select btn:[Finish] to continue with the installation and go to -crossref:bsdinstall[bsdinstall-fetching-distribution]. +crossref:bsdinstall[bsdinstall-fetching-distribution, Fetching Distribution Files]. [[bsdinstall-part-zfs]] === Guided Partitioning Using Root-on-ZFS @@ -724,7 +724,7 @@ constitute the pool. The automatic ZFS installer currently only supports the creation of a single top level vdev, except in stripe mode. To create more complex pools, use the instructions in - crossref:bsdinstall[bsdinstall-part-shell] to create the pool. + crossref:bsdinstall[bsdinstall-part-shell, Shell Mode Partitioning] to create the pool. * `Rescan Devices` - Repopulate the list of available disks. * `Disk Info` - This menu can be used to inspect each disk, including its partition table and various other information such as the device model number and serial number, if available. * `Pool Name` - Establish the name of the pool. The default name is _zroot_. @@ -808,7 +808,7 @@ The installation then proceeds normally. To continue with the installation, go to -crossref:bsdinstall[bsdinstall-fetching-distribution]. +crossref:bsdinstall[bsdinstall-fetching-distribution, Fetching Distribution Files]. [[bsdinstall-part-shell]] === Shell Mode Partitioning @@ -870,7 +870,7 @@ image::bsdinstall-configure-network-interface.png[Menu showing the different network interfaces to configure.] If an Ethernet interface is selected, the installer will skip ahead to the menu -shown in crossref:bsdinstall[bsdinstall-configure-net-ipv4]. +shown in crossref:bsdinstall[bsdinstall-configure-net-ipv4,.Choose IPv4 Networking]. If a wireless network interface is chosen, the system will instead scan for wireless access points: [[bsdinstall-wireless-scan]] @@ -1088,7 +1088,7 @@ image::bsdinstall-adduser1.png[Menu requesting if a user want to be added to the system.] Follow the prompts and input the requested information for the user account. -The example shown in crossref:bsdinstall[bsdinstall-add-user2] creates the `asample` user account. +The example shown in crossref:bsdinstall[bsdinstall-add-user2,.Enter User Information] creates the `asample` user account. [[bsdinstall-add-user2]] .Enter User Information @@ -1136,13 +1136,13 @@ Use this menu to make any changes or to do any additional configuration before completing the installation. -* `Add User` - Described in crossref:bsdinstall[bsdinstall-addusers]. -* `Root Password` - Described in crossref:bsdinstall[bsdinstall-post-root]. -* `Hostname` - Described in crossref:bsdinstall[bsdinstall-hostname]. -* `Network` - Described in crossref:bsdinstall[bsdinstall-config-network-dev]. -* `Services` - Described in crossref:bsdinstall[bsdinstall-sysconf]. -* `System Hardening` - Described in crossref:bsdinstall[bsdinstall-hardening]. -* `Time Zone` - Described in crossref:bsdinstall[bsdinstall-timezone]. +* `Add User` - Described in crossref:bsdinstall[bsdinstall-addusers, Add Users]. +* `Root Password` - Described in crossref:bsdinstall[bsdinstall-post-root, Setting the `root` Password]. +* `Hostname` - Described in crossref:bsdinstall[bsdinstall-hostname, Setting the Hostname]. +* `Network` - Described in crossref:bsdinstall[bsdinstall-config-network-dev, Configuring Network Interfaces]. +* `Services` - Described in crossref:bsdinstall[bsdinstall-sysconf, Enabling Services]. +* `System Hardening` - Described in crossref:bsdinstall[bsdinstall-hardening, Enabling Hardening Security Options]. +* `Time Zone` - Described in crossref:bsdinstall[bsdinstall-timezone, Setting the Time Zone]. * `Handbook` - Download and install the FreeBSD Handbook. Once configuration is complete, select btn:[Exit]. @@ -1175,7 +1175,7 @@ To review these messages once the system has been up for some time, type `less /var/run/dmesg.boot` from a command prompt. Press kbd:[q] to return to the command line after viewing. -If sshd was enabled in crossref:bsdinstall[bsdinstall-config-serv], the first boot might be a bit slower as the system generates SSH host keys. +If sshd was enabled in crossref:bsdinstall[bsdinstall-config-serv,.Selecting Additional Services to Enable], the first boot might be a bit slower as the system generates SSH host keys. Subsequent boots will be faster. The fingerprints of the keys are then displayed as in the following example: @@ -1261,7 +1261,7 @@ == Using the Live CD The welcome menu of bsdinstall, shown in -crossref:bsdinstall[bsdinstall-choose-mode], provides a btn:[Live CD] option. +crossref:bsdinstall[bsdinstall-choose-mode,.Welcome Menu], provides a btn:[Live CD] option. This is useful for those who are still wondering whether FreeBSD is the right operating system for them and want to test some of the features before installing. The following points should be noted before using the btn:[Live CD]: diff --git a/documentation/content/en/books/handbook/config/_index.adoc b/documentation/content/en/books/handbook/config/_index.adoc --- a/documentation/content/en/books/handbook/config/_index.adoc +++ b/documentation/content/en/books/handbook/config/_index.adoc @@ -127,7 +127,7 @@ |Contains descriptive information about the local host name, configuration details for any potential network interfaces and which services should be started up at system initial boot time. More information in -crossref:bsdinstall[configtuning-core-configuration] +crossref:bsdinstall[configtuning-core-configuration, Managing System-Specific Configuration] |[.filename]#/etc/security# |OpenBSM audit configuration files, see man:audit[8] for more information. @@ -143,7 +143,7 @@ |[.filename]#/etc/sysctl.conf# |Contains settings for the kernel. More information in -crossref:bsdinstall[configtuning-sysctl] +crossref:bsdinstall[configtuning-sysctl, The sysctl utility] |=== diff --git a/documentation/content/en/books/handbook/cutting-edge/_index.adoc b/documentation/content/en/books/handbook/cutting-edge/_index.adoc --- a/documentation/content/en/books/handbook/cutting-edge/_index.adoc +++ b/documentation/content/en/books/handbook/cutting-edge/_index.adoc @@ -229,7 +229,7 @@ ==== Always keep a copy of the [.filename]#GENERIC# kernel in [.filename]#/boot/GENERIC#. It will be helpful in diagnosing a variety of problems and in performing version upgrades. -Refer to crossref:cutting-edge[freebsd-update-custom-kernel-9x] for instructions on how to get a copy of the [.filename]#GENERIC# kernel. +Refer to crossref:cutting-edge[freebsd-update-custom-kernel-9x, Custom Kernels with FreeBSD 9.X and Later] for instructions on how to get a copy of the [.filename]#GENERIC# kernel. ==== Unless the default configuration in [.filename]#/etc/freebsd-update.conf# has been changed, @@ -277,7 +277,7 @@ [NOTE] ==== If the system is running a custom kernel, make sure that a copy of the [.filename]#GENERIC# kernel exists in [.filename]#/boot/GENERIC# before starting the upgrade. -Refer to crossref:cutting-edge[freebsd-update-custom-kernel-9x] for instructions on how to get a copy of the [.filename]#GENERIC# kernel. +Refer to crossref:cutting-edge[freebsd-update-custom-kernel-9x, Custom Kernels with FreeBSD 9.X and Later] for instructions on how to get a copy of the [.filename]#GENERIC# kernel. ==== Before upgrading to a new version, ensure the existing FreeBSD installation is up to date with respect to security and errata patches: @@ -399,7 +399,7 @@ The upgrade is now complete. If this was a major version upgrade, reinstall all ports and packages as -described in crossref:cutting-edge[freebsdupdate-portsrebuild]. +described in crossref:cutting-edge[freebsdupdate-portsrebuild, Upgrading Packages After a Major Version Upgrade]. [[freebsd-update-custom-kernel-9x]] ==== Custom Kernels with FreeBSD 9.X and Later @@ -606,7 +606,7 @@ . Due to the size of the repository, some users choose to only synchronize the sections of source that interest them or which they are contributing patches to. However, users that plan to compile the operating system from source must download _all_ of FreeBSD-CURRENT, not just selected portions. + Before compiling FreeBSD-CURRENT, read [.filename]#/usr/src/Makefile# very -carefully and follow the instructions in crossref:cutting-edge[makeworld]. +carefully and follow the instructions in crossref:cutting-edge[makeworld, Updating FreeBSD from Source]. Read the {freebsd-current} and [.filename]#/usr/src/UPDATING# to stay up-to-date on other bootstrapping procedures that sometimes become necessary on the road to the next release. . Be active! FreeBSD-CURRENT users are encouraged to submit their suggestions for enhancements or bug fixes. Suggestions with accompanying code are always welcome. @@ -642,7 +642,7 @@ Branch names, such as `stable/13`, are listed at link:https://www.FreeBSD.org/releng/[www.freebsd.org/releng]. . Before compiling or upgrading to FreeBSD-STABLE , read [.filename]#/usr/src/Makefile# carefully and follow the instructions in - crossref:cutting-edge[makeworld]. Read the {freebsd-stable} and [.filename]#/usr/src/UPDATING# to keep up-to-date on other bootstrapping procedures that sometimes become necessary on the road to the next release. + crossref:cutting-edge[makeworld, Updating FreeBSD from Source]. Read the {freebsd-stable} and [.filename]#/usr/src/UPDATING# to keep up-to-date on other bootstrapping procedures that sometimes become necessary on the road to the next release. [[translate-n-number]] === The N-number @@ -739,7 +739,7 @@ .... <.> Get the latest version of the source. See -crossref:cutting-edge[updating-src-obtaining-src] for more information on obtaining and updating source. +crossref:cutting-edge[updating-src-obtaining-src, Updating the Source] for more information on obtaining and updating source. <.> Check [.filename]#/usr/src/UPDATING# for any manual steps required before or after building from source. @@ -834,7 +834,7 @@ 13.2-RELEASE .... -Based on crossref:cutting-edge[updating-src-obtaining-src-repopath], the source used to update `13.2-RELEASE` has a repository path of `releng/13.2`. +Based on crossref:cutting-edge[updating-src-obtaining-src-repopath,.FreeBSD Versions and Repository Branches], the source used to update `13.2-RELEASE` has a repository path of `releng/13.2`. That path is used when checking out the source: [source,shell] @@ -845,7 +845,7 @@ <.> Move the old directory out of the way. If there are no local modifications in this directory, it can be deleted. -<.> The path from crossref:cutting-edge[updating-src-obtaining-src-repopath] is added to the repository URL. The third parameter is the destination directory for the source code on the local system. +<.> The path from crossref:cutting-edge[updating-src-obtaining-src-repopath,.FreeBSD Versions and Repository Branches] is added to the repository URL. The third parameter is the destination directory for the source code on the local system. [[updating-src-building]] === Building from Source @@ -1115,7 +1115,7 @@ The build machine must have the kernel configuration files for each machine in its [.filename]#/usr/src/sys/arch/conf#. On the build machine, build the kernel and world as described in -crossref:cutting-edge[makeworld], +crossref:cutting-edge[makeworld, Updating FreeBSD from Source], but do not install anything on the build machine. Instead, install the built kernel on the test machine. On the test machine, mount [.filename]#/usr/src# and [.filename]#/usr/obj# via NFS. diff --git a/documentation/content/en/books/handbook/disks/_index.adoc b/documentation/content/en/books/handbook/disks/_index.adoc --- a/documentation/content/en/books/handbook/disks/_index.adoc +++ b/documentation/content/en/books/handbook/disks/_index.adoc @@ -353,7 +353,7 @@ ugen0.3: at usbus0, cfg=0 md=HOST spd=HIGH (480Mbps) pwr=ON (2mA) .... -If the device has not been formatted, refer to crossref:disks[disks-adding] for instructions on how to format and create partitions on the USB drive. +If the device has not been formatted, refer to crossref:disks[disks-adding, Adding Disks] for instructions on how to format and create partitions on the USB drive. If the drive comes with a file system, it can be mounted by `root` using the instructions in crossref:basics[mount-unmount,“Mounting and Unmounting File Systems”]. [WARNING] @@ -703,7 +703,7 @@ # dd if=/dev/cd0 of=file.iso bs=2048 .... -The resulting image file can be burned to CD as described in crossref:disks[cdrecord]. +The resulting image file can be burned to CD as described in crossref:disks[cdrecord, Burning a CD]. ==== [[mounting-cd]] @@ -775,7 +775,7 @@ crossref:disks[using-cdrecord] describes how to duplicate and burn an audio CD. If the FreeBSD version is less than 10.0 and the device is ATAPI, the `atapicam` -module must be first loaded using the instructions in crossref:disks[atapicam]. +module must be first loaded using the instructions in crossref:disks[atapicam, Supported Devices]. [[using-cdrecord]] [.procedure] @@ -796,7 +796,7 @@ % cdrecord -v dev=2,0 -dao -useinfo *.wav .... + -Make sure that _2,0_ is set appropriately, as described in crossref:disks[cdrecord]. +Make sure that _2,0_ is set appropriately, as described in crossref:disks[cdrecord, Burning a CD]. [[creating-dvds]] == Creating and Using DVD Media @@ -811,7 +811,7 @@ * DVD-RAM: This is a rewritable format which can be seen as a removable hard drive. However, this media is not compatible with most DVD-ROM drives and DVD-Video players as only a few DVD writers support the DVD-RAM format. Refer - to crossref:disks[creating-dvd-ram] for more information on DVD-RAM use. + to crossref:disks[creating-dvd-ram, Using a DVD-RAM] for more information on DVD-RAM use. * DVD+RW: This is a rewritable format defined by the https://en.wikipedia.org/wiki/DVD%2BRW_Alliance[DVD+RW Alliance]. A DVD+RW can be rewritten about 1000 times. * DVD+R: This format is the write once variation of the DVD+RW format. @@ -832,7 +832,7 @@ These tools use the SCSI subsystem to access the devices, therefore crossref:disks[atapicam,ATAPI/CAM support] must be loaded or statically compiled into the kernel. This support is not needed if the burner uses the USB interface. -Refer to crossref:disks[usb-disks] for more details on USB device configuration. +Refer to crossref:disks[usb-disks, USB Storage Devices] for more details on USB device configuration. DMA access must also be enabled for ATAPI devices, by adding the following line to [.filename]#/boot/loader.conf#: @@ -1843,7 +1843,7 @@ .Procedure: Encrypting a Partition with gbde . Add the New Hard Drive + -Install the new drive to the system as explained in crossref:disks[disks-adding]. +Install the new drive to the system as explained in crossref:disks[disks-adding, Adding Disks]. For the purposes of this example, a new hard drive partition has been added as [.filename]#/dev/ad4s1c# and [.filename]#/dev/ad0s1*# represents the existing standard FreeBSD partitions. + [source,shell] diff --git a/documentation/content/en/books/handbook/firewalls/_index.adoc b/documentation/content/en/books/handbook/firewalls/_index.adoc --- a/documentation/content/en/books/handbook/firewalls/_index.adoc +++ b/documentation/content/en/books/handbook/firewalls/_index.adoc @@ -245,7 +245,7 @@ Refer to the http://www.openbsd.org/faq/pf/[PF FAQ] for complete coverage of PF rulesets. To control PF, use `pfctl`. -crossref:firewalls[pfctl] summarizes some useful options to this command. +crossref:firewalls[pfctl,.Useful `pfctl` Options] summarizes some useful options to this command. Refer to man:pfctl[8] for a description of all available options: [[pfctl]] .Useful `pfctl` Options @@ -1067,7 +1067,7 @@ IPFW is included in the basic FreeBSD install as a kernel loadable module, meaning that a custom kernel is not needed in order to enable IPFW. For those users who wish to statically compile IPFW support into a custom -kernel, see crossref:firewalls[firewalls-ipfw-kernelconfig]. +kernel, see crossref:firewalls[firewalls-ipfw-kernelconfig, IPFW Kernel Options]. To configure the system to enable IPFW at boot time, add `firewall_enable="YES"` to [.filename]#/etc/rc.conf#: diff --git a/documentation/content/en/books/handbook/geom/_index.adoc b/documentation/content/en/books/handbook/geom/_index.adoc --- a/documentation/content/en/books/handbook/geom/_index.adoc +++ b/documentation/content/en/books/handbook/geom/_index.adoc @@ -338,7 +338,7 @@ The BIOS will see the mirror as two individual drives rather than a mirror. Since the drives are identical, it does not matter which is selected to boot. -See crossref:geom[gmirror-troubleshooting] if there are problems booting. +See crossref:geom[gmirror-troubleshooting, Troubleshooting] if there are problems booting. Powering down and disconnecting the original [.filename]#ada0# disk will allow it to be kept as an offline backup. In use, the mirror will behave just like the original single drive. @@ -556,7 +556,7 @@ Restart the system, booting from [.filename]#ada1#. If everything is working, the system will boot from [.filename]#mirror/gm0#, which now contains the same data as [.filename]#ada0# had previously. -See crossref:geom[gmirror-troubleshooting] if there are problems booting. +See crossref:geom[gmirror-troubleshooting, Troubleshooting] if there are problems booting. At this point, the mirror still consists of only the single [.filename]#ada1# disk. @@ -683,7 +683,7 @@ .... Any old metadata should be cleared from the replacement disk using the -instructions in crossref:geom[geom-mirror-metadata]. +instructions in crossref:geom[geom-mirror-metadata, Metadata Issues]. Then the replacement disk, [.filename]#ada4# for this example, is inserted into the mirror: [source,shell] diff --git a/documentation/content/en/books/handbook/jails/_index.adoc b/documentation/content/en/books/handbook/jails/_index.adoc --- a/documentation/content/en/books/handbook/jails/_index.adoc +++ b/documentation/content/en/books/handbook/jails/_index.adoc @@ -405,7 +405,7 @@ # service jail start classic .... -More information on how to manage jails can be found in the section crossref:jails[jail-management]. +More information on how to manage jails can be found in the section crossref:jails[jail-management, Jail Management]. [[thin-jail]] == Thin Jails @@ -515,7 +515,7 @@ .... More information on how to manage jails can be found in the section -crossref:jails[jail-management]. +crossref:jails[jail-management, Jail Management]. [[creating-thin-jail-nullfs]] === Creating a Thin Jail Using NullFS @@ -716,8 +716,8 @@ The next step is to create the jail as indicated above. -Either the crossref:jails[classic-jail] procedure and the -crossref:jails[thin-jail] procedure can be used. +Either the crossref:jails[classic-jail, Classic Jail (Thick Jail)] procedure and the +crossref:jails[thin-jail, Thin Jails] procedure can be used. The only thing that will change is the configuration in the [.filename]#/etc/jail.conf# file. The path [.filename]#/usr/local/jails/containers/vnet# will be used as an example for the created jail. @@ -790,7 +790,7 @@ .... The next step will be to create a jail as indicated above, for example in -crossref:jails[creating-thin-jail-openzfs-snapshots], but *without* performing the configuration. +crossref:jails[creating-thin-jail-openzfs-snapshots, Creating a Thin Jail Using OpenZFS Snapshots], but *without* performing the configuration. FreeBSD Linux jails require a specific configuration that will be detailed below. Once the jail has been created as explained above, execute the following command to perform required configuration for the jail and start it: diff --git a/documentation/content/en/books/handbook/l10n/_index.adoc b/documentation/content/en/books/handbook/l10n/_index.adoc --- a/documentation/content/en/books/handbook/l10n/_index.adoc +++ b/documentation/content/en/books/handbook/l10n/_index.adoc @@ -85,7 +85,7 @@ .... The _LanguageCode_ and _CountryCode_ are used to determine the country and the specific language variation. -crossref:l10n[locale-lang-country] provides some examples of __LanguageCode_CountryCode__: +crossref:l10n[locale-lang-country,.Common Language and Country Codes] provides some examples of __LanguageCode_CountryCode__: [[locale-lang-country]] .Common Language and Country Codes @@ -332,7 +332,7 @@ The `keychange` entry is usually needed to program function keys to match the selected terminal type because function key sequences cannot be defined in the keymap. Next, set the correct console terminal type in [.filename]#/etc/ttys# for all virtual terminal entries. -crossref:l10n[locale-charset] summarizes the available terminal types.: +crossref:l10n[locale-charset,.Defined Terminal Types for Character Sets] summarizes the available terminal types.: [[locale-charset]] .Defined Terminal Types for Character Sets @@ -364,7 +364,7 @@ |=== For languages with wide or multibyte characters, install a console for that language from the FreeBSD Ports Collection. -The available ports are summarized in crossref:l10n[locale-console]. +The available ports are summarized in crossref:l10n[locale-console,.Available Console from Ports Collection]. Once installed, refer to the port's [.filename]#pkg-message# or man pages for configuration and usage instructions. [[locale-console]] @@ -409,7 +409,7 @@ Application specific i18n settings such as fonts and menus can be tuned in [.filename]#~/.Xresources# and should allow users to view their selected language in graphical application menus. The X Input Method (XIM) protocol is an Xorg standard for inputting non-English characters. -crossref:l10n[locale-xim] summarizes the input method applications which are available in the FreeBSD Ports Collection. +crossref:l10n[locale-xim,.Available Input Methods] summarizes the input method applications which are available in the FreeBSD Ports Collection. Additional Fcitx and Uim applications are also available. [[locale-xim]] diff --git a/documentation/content/en/books/handbook/mac/_index.adoc b/documentation/content/en/books/handbook/mac/_index.adoc --- a/documentation/content/en/books/handbook/mac/_index.adoc +++ b/documentation/content/en/books/handbook/mac/_index.adoc @@ -150,7 +150,7 @@ [NOTE] ==== Some users have experienced problems with setting the `multilabel` flag on the root partition. -If this is the case, please review crossref:mac[mac-troubleshoot]. +If this is the case, please review crossref:mac[mac-troubleshoot, Troubleshooting the MAC Framework]. ==== Since the multi label policy is set on a per-file system basis, a multi label policy may not be needed if the file system layout is well designed. diff --git a/documentation/content/en/books/handbook/mail/_index.adoc b/documentation/content/en/books/handbook/mail/_index.adoc --- a/documentation/content/en/books/handbook/mail/_index.adoc +++ b/documentation/content/en/books/handbook/mail/_index.adoc @@ -81,7 +81,7 @@ Dozens of graphical programs are also available in the Ports Collection, including Claws Mail, Evolution, and Thunderbird. Some organizations provide a web mail program which can be accessed through a web browser. More information about installing and using a MUA on FreeBSD can be found in -crossref:mail[mail-agents]. +crossref:mail[mail-agents, Mail User Agents]. Mail Transfer Agent (MTA):: The Mail Transfer Agent (MTA) is responsible for receiving incoming mail and delivering outgoing mail. @@ -384,7 +384,7 @@ # pkg install dma .... -Perform the configuration as indicated in crossref:mail[configuring-dragonfly-mail-agent]. +Perform the configuration as indicated in crossref:mail[configuring-dragonfly-mail-agent, Configuring DragonFly Mail Agent (DMA)]. Then change all the entries in the file [.filename]#/etc/mail/mailer.conf# to man:dma[8]: diff --git a/documentation/content/en/books/handbook/mirrors/_index.adoc b/documentation/content/en/books/handbook/mirrors/_index.adoc --- a/documentation/content/en/books/handbook/mirrors/_index.adoc +++ b/documentation/content/en/books/handbook/mirrors/_index.adoc @@ -356,7 +356,7 @@ |======================================================= External mirrors maintained by project members are also available; please refer -to the crossref:mirrors[external-mirrors] section. +to the crossref:mirrors[external-mirrors, External mirrors] section. To clone a copy of the FreeBSD system source code repository: diff --git a/documentation/content/en/books/handbook/network-servers/_index.adoc b/documentation/content/en/books/handbook/network-servers/_index.adoc --- a/documentation/content/en/books/handbook/network-servers/_index.adoc +++ b/documentation/content/en/books/handbook/network-servers/_index.adoc @@ -895,7 +895,7 @@ + This line configures the client to provide anyone with a valid account in the NIS server's password maps an account on the client. There are many ways to configure the NIS client by modifying this line. -One method is described in crossref:network-servers[network-netgroups]. +One method is described in crossref:network-servers[network-netgroups, Using Netgroups]. For more detailed reading, refer to the book `Managing NFS and NIS`, published by O'Reilly Media. . To import all possible group entries from the NIS server, add this line to [.filename]#/etc/group#: + diff --git a/documentation/content/en/books/handbook/network/_index.adoc b/documentation/content/en/books/handbook/network/_index.adoc --- a/documentation/content/en/books/handbook/network/_index.adoc +++ b/documentation/content/en/books/handbook/network/_index.adoc @@ -616,7 +616,7 @@ The first step will be to configure the wireless network card to an interface. To find out what wireless network cards are in the system check the section -crossref:network[config-identify-network-adapter]. +crossref:network[config-identify-network-adapter, Identify Network Adapters]. [source,shell] .... diff --git a/documentation/content/en/books/handbook/ports/_index.adoc b/documentation/content/en/books/handbook/ports/_index.adoc --- a/documentation/content/en/books/handbook/ports/_index.adoc +++ b/documentation/content/en/books/handbook/ports/_index.adoc @@ -1307,4 +1307,4 @@ + If there is no response to the email, use Bugzilla to submit a bug report using the instructions in extref:{problem-reports}[Writing FreeBSD Problem Reports]. . Fix it! The extref:{porters-handbook}[Porter's Handbook] includes detailed information on the ports infrastructure so that you can fix the occasional broken port or even submit your own! -. Install the package instead of the port using the instructions in crossref:ports[pkgng-intro]. +. Install the package instead of the port using the instructions in crossref:ports[pkgng-intro, Using pkg for Binary Package Management]. diff --git a/documentation/content/en/books/handbook/printing/_index.adoc b/documentation/content/en/books/handbook/printing/_index.adoc --- a/documentation/content/en/books/handbook/printing/_index.adoc +++ b/documentation/content/en/books/handbook/printing/_index.adoc @@ -57,7 +57,7 @@ Basic printing can be set up quickly. The printer must be capable of printing plain `ASCII` text. -For printing to other types of files, see crossref:printing[printing-lpd-filters]. +For printing to other types of files, see crossref:printing[printing-lpd-filters, Filters]. [.procedure] **** @@ -125,7 +125,7 @@ [TIP] ==== If both lines do not start at the left border, but "stairstep" instead, see -crossref:printing[printing-lpd-filters-stairstep]. +crossref:printing[printing-lpd-filters-stairstep, Preventing Stairstepping on Plain Text Printers]. ==== + Text files can now be printed with `lpr`. diff --git a/documentation/content/en/books/handbook/security/_index.adoc b/documentation/content/en/books/handbook/security/_index.adoc --- a/documentation/content/en/books/handbook/security/_index.adoc +++ b/documentation/content/en/books/handbook/security/_index.adoc @@ -880,7 +880,7 @@ .... It is strongly recommended to follow the security improvements indicated in -crossref:security[security-sshd-security-options]. +crossref:security[security-sshd-security-options, SSH Server Security Options]. [[security-sshd-security-options]] === SSH Server Security Options diff --git a/documentation/content/en/books/handbook/serialcomms/_index.adoc b/documentation/content/en/books/handbook/serialcomms/_index.adoc --- a/documentation/content/en/books/handbook/serialcomms/_index.adoc +++ b/documentation/content/en/books/handbook/serialcomms/_index.adoc @@ -103,7 +103,7 @@ These two types of cables differ in how the wires are connected to the connector. Each wire represents a signal, with the defined signals summarized in -crossref:serialcomms[serialcomms-signal-names]. +crossref:serialcomms[serialcomms-signal-names,.RS-232C Signal Names]. A standard serial cable passes all of the RS-232C signals straight through. For example, the "Transmitted Data" pin on one end of the cable goes to the "Transmitted Data" pin on the other end. This is the type of cable used to connect a modem to the FreeBSD system, and is also appropriate for some terminals. @@ -113,7 +113,7 @@ A null-modem cable can be constructed using the pin connections summarized in crossref:serialcomms[nullmodem-db25], crossref:serialcomms[nullmodem-db9], and -crossref:serialcomms[nullmodem-db9-25]. +crossref:serialcomms[nullmodem-db9-25,.DB-9 to DB-25 Null-Modem Cable]. While the standard calls for a straight-through pin 1 to pin 1 "Protective Ground" line, it is often omitted. Some terminals work using only pins 2, 3, and 7, while others require different configurations. When in doubt, refer to the documentation for the hardware. @@ -502,7 +502,7 @@ When attaching a terminal to one of those ports, modify the default entry to set the required speed and terminal type, to turn the device `on` and, if needed, to change the port's `secure` setting. If the terminal is connected to another port, add an entry for the port. -crossref:serialcomms[ex-etc-ttys] configures two terminals in [.filename]#/etc/ttys#. +crossref:serialcomms[ex-etc-ttys,.Configuring Terminal Entries] configures two terminals in [.filename]#/etc/ttys#. The first entry configures a Wyse-50 connected to [.filename]#COM2#. The second entry configures an old computer running Procomm terminal software emulating a VT-100 terminal. The computer is connected to the sixth serial port on a multi-port serial card. @@ -611,7 +611,7 @@ FreeBSD needs the RTS and CTS signals for flow control at speeds above 2400 bps, the CD signal to detect when a call has been answered or the line has been hung up, and the DTR signal to reset the modem after a session is complete. Some cables are wired without all of the needed signals, so if a login session does not go away when the line hangs up, there may be a problem with the cable. -Refer to crossref:serialcomms[term-cables-null] for more information about these signals. +Refer to crossref:serialcomms[term-cables-null, Serial Cables and Ports] for more information about these signals. Like other UNIX(R)-like operating systems, FreeBSD uses the hardware signals to find out when a call has been answered or a line has been hung up and to hangup and reset the modem after a call. FreeBSD avoids sending commands to the modem or watching for status reports from the modem. @@ -693,7 +693,7 @@ For a slow CPU or a heavily loaded system without 16550A-based serial ports, this configuration may produce `uart` "silo" errors at 57.6 Kbps. The configuration of [.filename]#/etc/ttys# is similar to -crossref:serialcomms[ex-etc-ttys], but a different argument is passed to `getty` and `dialup` is used for the terminal type. +crossref:serialcomms[ex-etc-ttys,.Configuring Terminal Entries], but a different argument is passed to `getty` and `dialup` is used for the terminal type. Replace _xxx_ with the process `init` will run on the device: [.programlisting] @@ -1016,7 +1016,7 @@ . Prepare a serial cable. + Use either a null-modem cable or a standard serial cable and a null-modem adapter. -See crossref:serialcomms[term-cables-null] for a discussion on serial cables. +See crossref:serialcomms[term-cables-null, Serial Cables and Ports] for a discussion on serial cables. . Unplug the keyboard. + Many systems probe for the keyboard during the Power-On Self-Test (POST) and will generate an error if the keyboard is not detected. @@ -1167,7 +1167,7 @@ ==== While it is not required, it is possible to provide a `login` prompt over the serial line. To configure this, edit the entry for the serial port in [.filename]#/etc/ttys# -using the instructions in crossref:serialcomms[term-config]. +using the instructions in crossref:serialcomms[term-config, Terminal Configuration]. If the speed of the serial port has been changed, change `std.115200` to match the new setting. ==== diff --git a/documentation/content/en/books/handbook/x11/_index.adoc b/documentation/content/en/books/handbook/x11/_index.adoc --- a/documentation/content/en/books/handbook/x11/_index.adoc +++ b/documentation/content/en/books/handbook/x11/_index.adoc @@ -608,7 +608,7 @@ The URW font collection (package:x11-fonts/urwfonts[]) includes high quality versions of standard type1 fonts (Times Roman(TM), Helvetica(TM), Palatino(TM) and others). The Freefonts collection (package:x11-fonts/freefonts[]) includes many more fonts, but most of them are intended for use in graphics software such as the Gimp, and are not complete enough to serve as screen fonts. In addition, Xorg can be configured to use TrueType(R) fonts with a minimum of effort. -For more details on this, see the man:X[7] manual page or crossref:x11[truetype]. +For more details on this, see the man:X[7] manual page or crossref:x11[truetype, TrueType(R) Fonts]. To install the above Type1 font collections from binary packages, run the following commands: @@ -637,7 +637,7 @@ This will work but will be lost when the X session is closed, unless it is added to the startup file ([.filename]#~/.xinitrc# for a normal `startx` session, or [.filename]#~/.xsession# when logging in through a graphical login manager like XDM). A third way is to use the new [.filename]#/usr/local/etc/fonts/local.conf# as -demonstrated in crossref:x11[antialias]. +demonstrated in crossref:x11[antialias, Anti-Aliased Fonts]. [[truetype]] === TrueType(R) Fonts @@ -671,7 +671,7 @@ .... Now add the TrueType(R) directory to the font path. -This is just the same as described in crossref:x11[type1]: +This is just the same as described in crossref:x11[type1, Type1 Fonts]: [source,shell] .... diff --git a/documentation/content/en/books/handbook/zfs/_index.adoc b/documentation/content/en/books/handbook/zfs/_index.adoc --- a/documentation/content/en/books/handbook/zfs/_index.adoc +++ b/documentation/content/en/books/handbook/zfs/_index.adoc @@ -62,7 +62,7 @@ crossref:zfs[zfs-term-l2arc,L2ARC], and a disk-based synchronous write cache named crossref:zfs[zfs-term-zil,ZIL]. -A complete list of features and terminology is in crossref:zfs[zfs-term]. +A complete list of features and terminology is in crossref:zfs[zfs-term, ZFS Features and Terminology]. [[zfs-differences]] == What Makes ZFS Different diff --git a/documentation/content/en/books/porters-handbook/makefiles/_index.adoc b/documentation/content/en/books/porters-handbook/makefiles/_index.adoc --- a/documentation/content/en/books/porters-handbook/makefiles/_index.adoc +++ b/documentation/content/en/books/porters-handbook/makefiles/_index.adoc @@ -282,7 +282,7 @@ For some more advanced examples of setting `PORTVERSION`, when the software's versioning is really not compatible with FreeBSD's, or `DISTNAME` when the distribution file does not contain the version itself, see -crossref:makefiles[makefile-distname]. +crossref:makefiles[makefile-distname, `DISTNAME`]. [[makefile-naming-revepoch]] === `PORTREVISION` and `PORTEPOCH` @@ -1482,7 +1482,7 @@ |`GH_SUBDIR` |When the software needs an additional distribution file to be extracted within `${WRKSRC}`, this variable can be used. See the examples in -crossref:makefiles[makefile-master_sites-github-multiple] for more information. +crossref:makefiles[makefile-master_sites-github-multiple, Fetching Multiple Files from GitHub] for more information. |(none) |`GH_TUPLE` @@ -1654,13 +1654,13 @@ ==== Fetching Multiple Files from GitHub The `USE_GITHUB` framework also supports fetching multiple distribution files from different places in GitHub. -It works in a way very similar to crossref:makefiles[porting-master-sites-n]. +It works in a way very similar to crossref:makefiles[porting-master-sites-n, Multiple Distribution or Patches Files from Multiple Locations]. Multiple values are added to `GH_ACCOUNT`, `GH_PROJECT`, and `GH_TAGNAME`. Each different value is assigned a group. The main value can either have no group, or the `:DEFAULT` group. A value can be omitted if it is the same as the default as listed in -crossref:makefiles[makefile-master_sites-github-description]. +crossref:makefiles[makefile-master_sites-github-description,.`USE_GITHUB` Description]. `GH_TUPLE` can also be used when there are a lot of distribution files. It helps keep the account, project, tagname, and group information at the same place. @@ -1678,7 +1678,7 @@ ==== As this is only syntactic sugar above `DISTFILES` and `MASTER_SITES`, the group names must adhere to the restrictions on group names outlined in -crossref:makefiles[porting-master-sites-n] +crossref:makefiles[porting-master-sites-n, Multiple Distribution or Patches Files from Multiple Locations] ==== When fetching multiple files from GitHub, sometimes the default distribution file is not fetched from GitHub. @@ -1752,7 +1752,7 @@ ==== This is functionally equivalent to -crossref:makefiles[makefile-master_sites-github-multi], but using `GH_TUPLE`: +crossref:makefiles[makefile-master_sites-github-multi,.Use of `USE_GITHUB` with Multiple Distribution Files], but using `GH_TUPLE`: [.programlisting] .... @@ -1895,7 +1895,7 @@ |`GL_SUBDIR` |When the software needs an additional distribution file to be extracted within `${WRKSRC}`, this variable can be used. See the examples in - crossref:makefiles[makefile-master_sites-gitlab-multiple] for more information. + crossref:makefiles[makefile-master_sites-gitlab-multiple, Fetching Multiple Files from GitLab] for more information. |(none) |`GL_TUPLE` @@ -1959,12 +1959,12 @@ ==== Fetching Multiple Files from GitLab The `USE_GITLAB` framework also supports fetching multiple distribution files from different places from GitLab and GitLab hosted sites. -It works in a way very similar to crossref:makefiles[porting-master-sites-n] and -crossref:makefiles[makefile-master_sites-gitlab-multiple]. +It works in a way very similar to crossref:makefiles[porting-master-sites-n, Multiple Distribution or Patches Files from Multiple Locations] and +crossref:makefiles[makefile-master_sites-gitlab-multiple, Fetching Multiple Files from GitLab]. Multiple values are added to `GL_SITE`, `GL_ACCOUNT`, `GL_PROJECT` and `GL_COMMIT`. Each different value is assigned a group. -crossref:makefiles[makefile-master_sites-gitlab-description]. +crossref:makefiles[makefile-master_sites-gitlab-description,.`USE_GITLAB` Description]. `GL_TUPLE` can also be used when there are a lot of distribution files. It helps keep the site, account, project, commit, and group information at the same place. @@ -1982,7 +1982,7 @@ ==== As this is only syntactic sugar above `DISTFILES` and `MASTER_SITES`, the group names must adhere to the restrictions on group names outlined in -crossref:makefiles[porting-master-sites-n] +crossref:makefiles[porting-master-sites-n, Multiple Distribution or Patches Files from Multiple Locations] ==== When fetching multiple files using GitLab, sometimes the default distribution file is not fetched from a GitLab site. @@ -2058,7 +2058,7 @@ [example] ==== This is functionally equivalent to -crossref:makefiles[makefile-master_sites-gitlab-multi], but using `GL_TUPLE`: +crossref:makefiles[makefile-master_sites-gitlab-multi,.Use of `USE_GITLAB` with Multiple Distribution Files], but using `GL_TUPLE`: [.programlisting] .... @@ -2216,7 +2216,7 @@ We describe here a case of simplified `MASTER_SITES:n` usage. This will be sufficient for most scenarios. More detailed information are available in -crossref:makefiles[ports-master-sites-n-detailed]. +crossref:makefiles[ports-master-sites-n-detailed, Detailed Information]. Some applications consist of multiple distribution files that must be downloaded from a number of different sites. For example, Ghostscript consists of the core of the program, and then a large number of driver files that are used depending on the user's printer. @@ -2227,7 +2227,7 @@ For example, consider an application with the source split in two parts, [.filename]#source1.tar.gz# and [.filename]#source2.tar.gz#, which must be downloaded from two different sites. The port's [.filename]#Makefile# would include lines like -crossref:makefiles[ports-master-sites-n-example-simple-use-one-file-per-site]. +crossref:makefiles[ports-master-sites-n-example-simple-use-one-file-per-site,.Simplified Use of `MASTER_SITES:n` with One File Per Site]. [[ports-master-sites-n-example-simple-use-one-file-per-site]] .Simplified Use of `MASTER_SITES:n` with One File Per Site @@ -2247,7 +2247,7 @@ Multiple distribution files can have the same group. Continuing the previous example, suppose that there was a third distfile, [.filename]#source3.tar.gz#, that is downloaded from `ftp.example2.com`. The [.filename]#Makefile# would then be written like -crossref:makefiles[ports-master-sites-n-example-simple-use-more-than-one-file-per-site]. +crossref:makefiles[ports-master-sites-n-example-simple-use-more-than-one-file-per-site,.Simplified Use of `MASTER_SITES:n` with More Than One File Per Site]. [[ports-master-sites-n-example-simple-use-more-than-one-file-per-site]] .Simplified Use of `MASTER_SITES:n` with More Than One File Per Site @@ -2344,9 +2344,9 @@ elements, if the postfix immediate preceding character is not a `/` then `:n` will be considered a valid part of the element instead of a group postfix even if an element is postfixed with `:n`. See both - crossref:makefiles[ports-master-sites-n-example-detailed-use-master-site-subdir] + crossref:makefiles[ports-master-sites-n-example-detailed-use-master-site-subdir,.Detailed Use of `MASTER_SITES:n` in `MASTER_SITE_SUBDIR`] and - crossref:makefiles[ports-master-sites-n-example-detailed-use-complete-example-master-sites]. + crossref:makefiles[ports-master-sites-n-example-detailed-use-complete-example-master-sites,.Detailed Use of `MASTER_SITES:n` with Comma Operator, Multiple Files, Multiple Sites and Multiple Subdirectories]. + [[ports-master-sites-n-example-detailed-use-master-site-subdir]] .Detailed Use of `MASTER_SITES:n` in `MASTER_SITE_SUBDIR` @@ -2440,7 +2440,7 @@ + This has been simplified as much as possible. See -crossref:makefiles[ports-master-sites-n-example-detailed-use-master-site-sourceforge]. +crossref:makefiles[ports-master-sites-n-example-detailed-use-master-site-sourceforge,.Detailed Use of `MASTER_SITES:n` with SourceForge (`SF`)]. + [[ports-master-sites-n-example-detailed-use-master-site-sourceforge]] .Detailed Use of `MASTER_SITES:n` with SourceForge (`SF`) @@ -2459,7 +2459,7 @@ + All examples were done with `MASTER*` but they work exactly the same for `PATCH*` ones as can be seen in -crossref:makefiles[ports-master-sites-n-example-detailed-use-patch-sites]. +crossref:makefiles[ports-master-sites-n-example-detailed-use-patch-sites,.Simplified Use of `MASTER_SITES:n` with `PATCH_SITES`]. + [[ports-master-sites-n-example-detailed-use-patch-sites]] .Simplified Use of `MASTER_SITES:n` with `PATCH_SITES` @@ -2490,7 +2490,7 @@ with their matching group elements within both `MASTER_SITES` and `PATCH_SITES` which use matching group elements within both `MASTER_SITE_SUBDIR` and `PATCH_SITE_SUBDIR`. Check - crossref:makefiles[ports-master-sites-n-example-detailed-use-complete-example-master-sites]. + crossref:makefiles[ports-master-sites-n-example-detailed-use-complete-example-master-sites,.Detailed Use of `MASTER_SITES:n` with Comma Operator, Multiple Files, Multiple Sites and Multiple Subdirectories]. ** `fetch-list`: works like old `fetch-list` with the exception that it groups just like `do-fetch`. ** `master-sites` and `patch-sites`: (incompatible with older versions) only return the elements of group `DEFAULT`; in fact, they execute targets `master-sites-default` and `patch-sites-default` respectively. + @@ -2622,13 +2622,13 @@ A short name for the license or licenses if more than one license apply. -If it is one of the licenses listed in crossref:makefiles[licenses-license-list], only `LICENSE_FILE` and `LICENSE_DISTFILES` variables can be set. +If it is one of the licenses listed in crossref:makefiles[licenses-license-list,.Predefined License List], only `LICENSE_FILE` and `LICENSE_DISTFILES` variables can be set. If this is a license that has not been defined in the ports framework (see -crossref:makefiles[licenses-license-list]), the `LICENSE_PERMS` and `LICENSE_NAME` must be set, along with either `LICENSE_FILE` or `LICENSE_TEXT`. +crossref:makefiles[licenses-license-list,.Predefined License List]), the `LICENSE_PERMS` and `LICENSE_NAME` must be set, along with either `LICENSE_FILE` or `LICENSE_TEXT`. `LICENSE_DISTFILES` and `LICENSE_GROUPS` can also be set, but are not required. -The predefined licenses are shown in crossref:makefiles[licenses-license-list]. +The predefined licenses are shown in crossref:makefiles[licenses-license-list,.Predefined License List]. The current list is always available in [.filename]#Mk/bsd.licenses.db.mk#. [[licenses-license-ex1]] @@ -4168,58 +4168,58 @@ For easier access, a comprehensive list is provided: `PLIST_SUB`, `SUB_LIST`:: -For automatic `%%_OPT_%%` and `%%NO__OPT__%%` generation, see crossref:makefiles[options_sub]. +For automatic `%%_OPT_%%` and `%%NO__OPT__%%` generation, see crossref:makefiles[options_sub, `OPTIONS_SUB`]. + -For more complex usage, see crossref:makefiles[options-variables]. +For more complex usage, see crossref:makefiles[options-variables, Generic Variables Replacement, `OPT_VARIABLE` and `OPT_VARIABLE_OFF`]. `CONFIGURE_ARGS`:: -For `--enable-_x_` and `--disable-_x_`, see crossref:makefiles[options-configure_enable]. +For `--enable-_x_` and `--disable-_x_`, see crossref:makefiles[options-configure_enable, `OPT_CONFIGURE_ENABLE`]. + -For `--with-_x_` and `--without-_x_`, see crossref:makefiles[options-configure_with]. +For `--with-_x_` and `--without-_x_`, see crossref:makefiles[options-configure_with, `OPT_CONFIGURE_WITH`]. + -For all other cases, see crossref:makefiles[options-configure_on]. +For all other cases, see crossref:makefiles[options-configure_on, `OPT_CONFIGURE_ON` and `OPT_CONFIGURE_OFF`]. `CMAKE_ARGS`:: For arguments that are booleans (`on`, `off`, `true`, `false`, `0`, `1`) see -crossref:makefiles[options-cmake_bool]. +crossref:makefiles[options-cmake_bool, `OPT_CMAKE_BOOL` and `OPT_CMAKE_BOOL_OFF`]. + -For all other cases, see crossref:makefiles[options-cmake_on]. +For all other cases, see crossref:makefiles[options-cmake_on, `OPT_CMAKE_ON` and `OPT_CMAKE_OFF`]. `MESON_ARGS`:: -For arguments that take `true` or `false`, see crossref:makefiles[options-meson_true]. +For arguments that take `true` or `false`, see crossref:makefiles[options-meson_true, `OPT_MESON_TRUE` and `OPT_MESON_FALSE`]. + -For arguments that take `yes` or `no`, use crossref:makefiles[options-meson_yes]. +For arguments that take `yes` or `no`, use crossref:makefiles[options-meson_yes, `OPT_MESON_YES` and `OPT_MESON_NO`]. + -For arguments that take `enabled` or `disabled`, see crossref:makefiles[options-meson_enabled]. +For arguments that take `enabled` or `disabled`, see crossref:makefiles[options-meson_enabled, `OPT_MESON_ENABLED` and `OPT_MESON_DISABLED`]. + -For all other cases, use crossref:makefiles[options-meson_on]. +For all other cases, use crossref:makefiles[options-meson_on, `OPT_MESON_ON` and `OPT_MESON_OFF`]. `QMAKE_ARGS`:: -See crossref:makefiles[options-qmake_on]. +See crossref:makefiles[options-qmake_on, `OPT_QMAKE_ON` and `OPT_QMAKE_OFF`]. `USE_*`:: -See crossref:makefiles[options-use]. +See crossref:makefiles[options-use, `OPT_USE` and `OPT_USE_OFF`]. `*_DEPENDS`:: -See crossref:makefiles[options-dependencies]. +See crossref:makefiles[options-dependencies, Dependencies, `OPT_DEPTYPE` and `OPT_DEPTYPE_OFF`]. `*` (Any variable):: The most used variables have direct helpers, see -crossref:makefiles[options-variables]. +crossref:makefiles[options-variables, Generic Variables Replacement, `OPT_VARIABLE` and `OPT_VARIABLE_OFF`]. + -For any variable without a specific helper, see crossref:makefiles[options-vars]. +For any variable without a specific helper, see crossref:makefiles[options-vars, `OPT_VARS` and `OPT_VARS_OFF`]. Options dependencies:: When an option need another option to work, see -crossref:makefiles[options-implies]. +crossref:makefiles[options-implies, `OPT_IMPLIES`]. Options conflicts:: When an option cannot work if another is also enabled, see -crossref:makefiles[options-prevents]. +crossref:makefiles[options-prevents, `OPT_PREVENTS` and `OPT_PREVENTS_MSG`]. Build targets:: When an option need some extra processing, see -crossref:makefiles[options-targets]. +crossref:makefiles[options-targets, Additional Build Targets, `_target_-_OPT_-on` and `_target_-_OPT_-off`]. [[options_sub]] ==== `OPTIONS_SUB` @@ -4396,8 +4396,8 @@ [TIP] ==== -Most of the time, the helpers in crossref:makefiles[options-configure_enable] -and crossref:makefiles[options-configure_with] provide a shorter and more comprehensive functionality. +Most of the time, the helpers in crossref:makefiles[options-configure_enable, `OPT_CONFIGURE_ENABLE`] +and crossref:makefiles[options-configure_with, `OPT_CONFIGURE_WITH`] provide a shorter and more comprehensive functionality. ==== [[options-cmake-helpers]] @@ -4434,7 +4434,7 @@ [TIP] ==== -See crossref:makefiles[options-cmake_bool] for a shorter helper when the value is boolean. +See crossref:makefiles[options-cmake_bool, `OPT_CMAKE_BOOL` and `OPT_CMAKE_BOOL_OFF`] for a shorter helper when the value is boolean. ==== [[options-cmake_bool]] @@ -4744,7 +4744,7 @@ [WARNING] ==== Before using `OPT_VARS` and `OPT_VARS_OFF`, see if there is already a more -specific helper available in crossref:makefiles[options-variables]. +specific helper available in crossref:makefiles[options-variables, Generic Variables Replacement, `OPT_VARIABLE` and `OPT_VARIABLE_OFF`]. ==== When option _OPT_ is selected, and `OPT_VARS` defined, `_key_=_value_` and `_key_+=_value_` pairs are evaluated from `OPT_VARS`. @@ -5329,7 +5329,7 @@ .... On the other hand, if there is a DOCS option in the port, install the documentation in a `post-install-DOCS-on` target. -These targets are described in crossref:makefiles[options-targets]. +These targets are described in crossref:makefiles[options-targets, Additional Build Targets, `_target_-_OPT_-on` and `_target_-_OPT_-off`]. Here are some handy variables and how they are expanded by default when used in the [.filename]#Makefile#: diff --git a/documentation/content/en/books/porters-handbook/order/_index.adoc b/documentation/content/en/books/porters-handbook/order/_index.adoc --- a/documentation/content/en/books/porters-handbook/order/_index.adoc +++ b/documentation/content/en/books/porters-handbook/order/_index.adoc @@ -154,13 +154,13 @@ ==== `BROKEN_*` and `IGNORE_*` can be any generic variables, for example, `IGNORE_amd64`, `BROKEN_FreeBSD_10`, etc. With the exception of variables that depend on a crossref:uses[uses,`USES`], -place those in crossref:order[porting-order-uses]. +place those in crossref:order[porting-order-uses, `USES` and `USE_x`]. For instance, `IGNORE_WITH_PHP` only works if crossref:uses[uses-php,`php`] is set, and `BROKEN_SSL` only if crossref:uses[uses-ssl,`ssl`] is set. If the port is marked BROKEN when some conditions are met, and such conditions can only be tested after including [.filename]#bsd.port.options.mk# or [.filename]#bsd.port.pre.mk#, then those variables should be set later, in -crossref:order[porting-order-rest]. +crossref:order[porting-order-rest, The Rest of the Variables]. ==== [[porting-order-depends]] @@ -219,7 +219,7 @@ The `FOO` and `BAR` options do not have a standard description, so one need to be written. The other options already have one in [.filename]#Mk/bsd.options.desc.mk# so writing one is not needed. The `DOCS` and `EXAMPLES` use target helpers to install their files, they are shown here for completeness, -though they belong in crossref:order[porting-order-targets], so other variables and targets could be inserted before them. +though they belong in crossref:order[porting-order-targets, The Targets], so other variables and targets could be inserted before them. [.programlisting] .... diff --git a/documentation/content/en/books/porters-handbook/pkg-files/_index.adoc b/documentation/content/en/books/porters-handbook/pkg-files/_index.adoc --- a/documentation/content/en/books/porters-handbook/pkg-files/_index.adoc +++ b/documentation/content/en/books/porters-handbook/pkg-files/_index.adoc @@ -149,7 +149,7 @@ Multiline strings use the standard here document notation. The multiline delimiter _must_ start just after `<<` symbols without any whitespace and it _must_ consist of capital letters only. To finish a multiline string, add the delimiter string on a line of its own without any whitespace. -The message from crossref:pkg-files[porting-message-ucl-short-ex] can be written as: +The message from crossref:pkg-files[porting-message-ucl-short-ex,.UCL Short Strings] can be written as: [.programlisting] .... diff --git a/documentation/content/en/books/porters-handbook/plist/_index.adoc b/documentation/content/en/books/porters-handbook/plist/_index.adoc --- a/documentation/content/en/books/porters-handbook/plist/_index.adoc +++ b/documentation/content/en/books/porters-handbook/plist/_index.adoc @@ -217,7 +217,7 @@ The output of `makeplist` must be double checked for correctness as it tries to automatically guess a few things, and can get it wrong. User configuration files should be installed as [.filename]#filename.sample#, as -it is described in crossref:plist[plist-config]. +it is described in crossref:plist[plist-config, Configuration Files]. [.filename]#info/dir# must not be listed and appropriate [.filename]#install-info# lines must be added as noted in the crossref:makefiles[makefile-info,info files] section. Any libraries installed by the port must be listed as specified in the crossref:special[porting-shlibs,shared libraries] section. @@ -380,7 +380,7 @@ This does three things. First, add the first file passed as argument, the sample file, to the plist. Then, on installation, if the actual file is not found, copy the sample file to the actual file. And finally, on deinstallation, remove the actual file if it has not been modified. -See crossref:plist[plist-config] for more information. +See crossref:plist[plist-config, Configuration Files] for more information. [[plist-keywords-shared-mime-info]] === `@shared-mime-info` _directory_ @@ -503,7 +503,7 @@ ==== `@exec` _command_, `@unexec` _command_ (Deprecated) Execute _command_ as part of the installation or deinstallation process. -Please use crossref:plist[plist-keywords-base-exec] instead. +Please use crossref:plist[plist-keywords-base-exec, `@preexec` _command_, `@postexec` _command_, `@preunexec` _command_, `@postunexec` _command_] instead. [[plist-keywords-base-dirrm]] ==== `@dirrm` _directory_ (Deprecated) @@ -615,7 +615,7 @@ These keywords contains a man:sh[1] script to be executed before or after installation, deinstallation, or upgrade of the package. In addition to the usual `@exec %_foo_` placeholders described in -crossref:plist[plist-keywords-base-exec], there is a new one, `%@`, which represents the argument of the keyword. +crossref:plist[plist-keywords-base-exec, `@preexec` _command_, `@postexec` _command_, `@preunexec` _command_, `@postunexec` _command_], there is a new one, `%@`, which represents the argument of the keyword. [[plist-keywords-examples]] ==== Custom Keyword Examples diff --git a/documentation/content/en/books/porters-handbook/special/_index.adoc b/documentation/content/en/books/porters-handbook/special/_index.adoc --- a/documentation/content/en/books/porters-handbook/special/_index.adoc +++ b/documentation/content/en/books/porters-handbook/special/_index.adoc @@ -421,11 +421,11 @@ |`CMAKE_ON` |For each entry in `CMAKE_ON`, an enabled boolean value is added to -`CMAKE_ARGS`. See crossref:special[using-cmake-example2]. +`CMAKE_ARGS`. See crossref:special[using-cmake-example2,.`CMAKE_ON` and `CMAKE_OFF`]. |`CMAKE_OFF` |For each entry in `CMAKE_OFF`, a disabled boolean value is added to -`CMAKE_ARGS`. See crossref:special[using-cmake-example2]. +`CMAKE_ARGS`. See crossref:special[using-cmake-example2,.`CMAKE_ON` and `CMAKE_OFF`]. |`CMAKE_BUILD_TYPE` |Type of build (CMake predefined build profiles). Default is `Release`, or `Debug` if `WITH_DEBUG` is set. @@ -1620,7 +1620,7 @@ .... `USE_GNOME` components automatically add the dependencies they need. -Please see crossref:special[gnome-components] for an exhaustive list of all `USE_GNOME` components and which other components they imply and their dependencies. +Please see crossref:special[gnome-components, GNOME Components] for an exhaustive list of all `USE_GNOME` components and which other components they imply and their dependencies. Here is an example [.filename]#Makefile# for a GNOME port that uses many of the techniques outlined in this document. Please use it as a guide for creating new ports. @@ -1656,7 +1656,7 @@ This section explains which macros are available and how they are used. Like they are used in the above example. -The crossref:special[gnome-components] has a more in-depth explanation. +The crossref:special[gnome-components, GNOME Components] has a more in-depth explanation. `USE_GNOME` has to be set for these macros to be of use. `GLIB_SCHEMAS`:: @@ -2438,7 +2438,7 @@ Similar to crossref:special[using-cmake,CMake], qmake supports out-of-source builds, which can be enabled by specifying the `outsource` argument (see crossref:special[using-qmake-example,`USES= qmake` example]). -Also see crossref:special[using-qmake-arguments]. +Also see crossref:special[using-qmake-arguments,.Possible Arguments for `USES qmake`]. [[using-qmake-arguments]] .Possible Arguments for `USES= qmake` @@ -3096,7 +3096,7 @@ ==== This is a simple example for a KDE port. `USES= cmake` instructs the port to utilize CMake, a configuration tool widely -used by KDE projects (see crossref:special[using-cmake] for detailed usage). +used by KDE projects (see crossref:special[using-cmake, Using `cmake`] for detailed usage). `USE_KDE` brings dependency on KDE libraries. Required KDE components and other dependencies can be determined through the configure log. `USE_KDE` does not imply `USE_QT`. @@ -3300,7 +3300,7 @@ When the port is to be built using Apache Ant, it has to define `USE_ANT`. Ant is thus considered to be the sub-make command. When no `do-build` target is defined by the port, a default one will be set that runs Ant according to `MAKE_ENV`, `MAKE_ARGS` and `ALL_TARGET`. -This is similar to the `USES= gmake` mechanism, which is documented in crossref:special[building]. +This is similar to the `USES= gmake` mechanism, which is documented in crossref:special[building, Building Mechanisms]. [[java-best-practices]] === Best Practices @@ -3624,7 +3624,7 @@ [IMPORTANT] ==== All dependencies to Python ports using crossref:flavors[flavors-auto-python,Python flavors] (either with `USE_PYTHON=distutils` or `USE_PYTHON=flavors`) must have the Python flavor appended to their origin using `@${PY_FLAVOR}`. -See crossref:special[python-Makefile]. +See crossref:special[python-Makefile,.Makefile for a Simple Python Module]. ==== [[python-Makefile]] @@ -3808,7 +3808,7 @@ |package:x11-toolkits/wxgtk30[] |=== -The variables in crossref:special[wx-ver-sel-table] can be set to one or more of these combinations separated by spaces: +The variables in crossref:special[wx-ver-sel-table,.Variables to Select wxWidgets Versions] can be set to one or more of these combinations separated by spaces: [[wx-widgets-versions-specification]] .wxWidgets Version Specifications @@ -3874,7 +3874,7 @@ |=== The dependency type can be selected for each component by adding a suffix separated by a semicolon. -If not present then a default type will be used (see crossref:special[wx-def-dep-types]). +If not present then a default type will be used (see crossref:special[wx-def-dep-types,.Default wxWidgets Dependency Types]). These types are available: [[wx-widgets-dependency-table]] @@ -3979,7 +3979,7 @@ [[wx-defined-variables]] === Defined Variables -These variables are available in the port (after defining one from crossref:special[wx-ver-sel-table]). +These variables are available in the port (after defining one from crossref:special[wx-ver-sel-table,.Variables to Select wxWidgets Versions]). [[wx-widgets-variables]] .Variables Defined for Ports That Use wxWidgets @@ -4757,7 +4757,7 @@ [[using-databases]] == Using Databases -Use one of the `USES` macros from crossref:special[using-databases-uses] to add a dependency on a database. +Use one of the `USES` macros from crossref:special[using-databases-uses,.Database `USES` Macros] to add a dependency on a database. [[using-databases-uses]] .Database `USES` Macros diff --git a/documentation/content/en/books/porters-handbook/testing/_index.adoc b/documentation/content/en/books/porters-handbook/testing/_index.adoc --- a/documentation/content/en/books/porters-handbook/testing/_index.adoc +++ b/documentation/content/en/books/porters-handbook/testing/_index.adoc @@ -192,7 +192,7 @@ ==== All these tests are done automatically when running `poudriere testport` or `poudriere bulk -t`. It is highly recommended that every ports contributor install and test their ports with it. -See crossref:testing[testing-poudriere] for more information. +See crossref:testing[testing-poudriere, poudriere] for more information. ==== [[testing-poudriere]] @@ -443,7 +443,7 @@ [NOTE] ==== Ports trees without a method, see -crossref:testing[testing-poudriere-ports-tree-manual], cannot be updated like this and must be updated manually by the porter. +crossref:testing[testing-poudriere-ports-tree-manual, Using Manually Managed Ports Trees with poudriere], cannot be updated like this and must be updated manually by the porter. ==== [[testing-poudriere-testing-ports]] @@ -511,7 +511,7 @@ Presents the port configuration dialog before the port is built. The ports given after `-o` in the format `_category_/_portname_` will use the specified options, all dependencies will use the default options. Testing dependent ports with non-default options can be accomplished using sets, -see crossref:testing[testing-poudriere-sets]. +see crossref:testing[testing-poudriere-sets, Using Sets]. [TIP] ==== diff --git a/documentation/content/en/books/porters-handbook/uses/_index.adoc b/documentation/content/en/books/porters-handbook/uses/_index.adoc --- a/documentation/content/en/books/porters-handbook/uses/_index.adoc +++ b/documentation/content/en/books/porters-handbook/uses/_index.adoc @@ -1885,17 +1885,17 @@ `SHEBANG_REGEX`:: Contains _one_ extended regular expressions, and is used with the `-iregex` argument of man:find[1]. -See crossref:uses[uses-shebangfix-ex-regex]. +See crossref:uses[uses-shebangfix-ex-regex,.`USESshebangfix` with `SHEBANG_REGEX`]. `SHEBANG_GLOB`:: Contains a list of patterns used with the `-name` argument of man:find[1]. -See crossref:uses[uses-shebangfix-ex-glob]. +See crossref:uses[uses-shebangfix-ex-glob,.`USESshebangfix` with `SHEBANG_GLOB`]. `SHEBANG_FILES`:: Contains a list of files or man:sh[1] globs. The shebangfix macro is run from `${WRKSRC}`, so `SHEBANG_FILES` can contain paths that are relative to `${WRKSRC}`. It can also deal with absolute paths if files outside of `${WRKSRC}` require patching. -See crossref:uses[uses-shebangfix-ex-files]. +See crossref:uses[uses-shebangfix-ex-files,.`USESshebangfix` with `SHEBANG_FILES`]. Currently Bash, Java, Ksh, Lua, Perl, PHP, Python, Ruby, Tcl, and Tk are supported by default. @@ -1922,7 +1922,7 @@ ==== `_interp__OLD_CMD` contain multiple values. Any entry with spaces must be quoted. -See crossref:uses[uses-shebangfix-ex-ksh]. +See crossref:uses[uses-shebangfix-ex-ksh,.Specifying all the Paths When Adding an Interpreter to `USESshebangfix`]. ==== [IMPORTANT]