git: f8fed61b80 - main - Split porters handbook
Sergio Carlavilla Delgado
carlavilla at FreeBSD.org
Wed Mar 31 21:14:18 UTC 2021
The branch main has been updated by carlavilla:
URL: https://cgit.FreeBSD.org/doc/commit/?id=f8fed61b80beb7ce384fdc0c36887ee44f10eb7c
commit f8fed61b80beb7ce384fdc0c36887ee44f10eb7c
Author: Sergio Carlavilla Delgado <carlavilla at FreeBSD.org>
AuthorDate: 2021-03-31 21:13:10 +0000
Commit: Sergio Carlavilla Delgado <carlavilla at FreeBSD.org>
CommitDate: 2021-03-31 21:13:10 +0000
Split porters handbook
Split the porters handbook into different chapters like the handbook
---
.../content/en/books/porters-handbook/_index.adoc | 68 +------------
.../content/en/books/porters-handbook/book.adoc | 81 ++++++++++++++++
.../en/books/porters-handbook/chapters-order.adoc | 36 +++----
.../flavors/{chapter.adoc => _index.adoc} | 8 +-
.../keeping-up/{chapter.adoc => _index.adoc} | 0
.../makefiles/{chapter.adoc => _index.adoc} | 39 ++++----
.../new-port/{chapter.adoc => _index.adoc} | 2 +-
.../order/{chapter.adoc => _index.adoc} | 106 ++++++++++-----------
.../pkg-files/{chapter.adoc => _index.adoc} | 12 +--
.../plist/{chapter.adoc => _index.adoc} | 22 ++---
.../porting-dads/{chapter.adoc => _index.adoc} | 20 ++--
.../porting-samplem/{chapter.adoc => _index.adoc} | 4 +-
.../porting-why/{chapter.adoc => _index.adoc} | 0
.../quick-porting/{chapter.adoc => _index.adoc} | 24 ++---
.../security/{chapter.adoc => _index.adoc} | 4 +-
.../slow-porting/{chapter.adoc => _index.adoc} | 10 +-
.../special/{chapter.adoc => _index.adoc} | 80 ++++++++--------
.../testing/{chapter.adoc => _index.adoc} | 6 +-
.../upgrading/{chapter.adoc => _index.adoc} | 14 +--
.../uses/{chapter.adoc => _index.adoc} | 52 +++++-----
.../versions/{chapter.adoc => _index.adoc} | 0
documentation/tools/books-toc-creator.py | 94 +++++++++---------
22 files changed, 351 insertions(+), 331 deletions(-)
diff --git a/documentation/content/en/books/porters-handbook/_index.adoc b/documentation/content/en/books/porters-handbook/_index.adoc
index 4d1f9c2a8e..0a2f7a0c11 100644
--- a/documentation/content/en/books/porters-handbook/_index.adoc
+++ b/documentation/content/en/books/porters-handbook/_index.adoc
@@ -3,80 +3,20 @@ title: FreeBSD Porter's Handbook
authors:
- author: The FreeBSD Documentation Project
copyright: 2000-2020 The FreeBSD Documentation Project
-releaseinfo: "$FreeBSD$"
-trademarks: ["freebsd", "sun", "unix", "general"]
+trademarks: ["freebsd", "sun", "unix", "general"]
+next: books/porters-handbook/porting-why
---
= FreeBSD Porter's Handbook
:doctype: book
:toc: macro
-:toclevels: 2
+:toclevels: 1
:icons: font
-:xrefstyle: basic
-:relfileprefix: ../
-:outfilesuffix:
:sectnums:
:sectnumlevels: 6
-:partnums:
-:chapter-signifier: Chapter
-:part-signifier: Part
:source-highlighter: rouge
:experimental:
-:skip-front-matter:
-
-ifeval::["{backend}" == "html5"]
-include::shared/mirrors.adoc[]
-include::shared/authors.adoc[]
-include::shared/releases.adoc[]
-include::shared/en/mailing-lists.adoc[]
-include::shared/en/teams.adoc[]
-include::shared/en/urls.adoc[]
-:chapters-path: content/en/books/porters-handbook/
-endif::[]
-
-ifeval::["{backend}" == "pdf"]
-include::../../../../shared/mirrors.adoc[]
-include::../../../../shared/authors.adoc[]
-include::../../../../shared/releases.adoc[]
-include::../../../../shared/en/mailing-lists.adoc[]
-include::../../../../shared/en/teams.adoc[]
-include::../../../../shared/en/urls.adoc[]
-:chapters-path:
-endif::[]
-
-ifeval::["{backend}" == "epub3"]
-include::../../../../shared/mirrors.adoc[]
-include::../../../../shared/authors.adoc[]
-include::../../../../shared/releases.adoc[]
-include::../../../../shared/en/mailing-lists.adoc[]
-include::../../../../shared/en/teams.adoc[]
-include::../../../../shared/en/urls.adoc[]
-:chapters-path:
-endif::[]
'''
-toc::[]
-
-include::{chapters-path}toc-tables.adoc[]
-
-include::{chapters-path}toc-examples.adoc[]
-
-include::{chapters-path}porting-why/chapter.adoc[leveloffset=+1, lines=7..21;32..-1]
-include::{chapters-path}new-port/chapter.adoc[leveloffset=+1, lines=7..21;32..-1]
-include::{chapters-path}quick-porting/chapter.adoc[leveloffset=+1, lines=7..21;32..-1]
-include::{chapters-path}slow-porting/chapter.adoc[leveloffset=+1, lines=7..21;32..-1]
-include::{chapters-path}makefiles/chapter.adoc[leveloffset=+1, lines=7..22;33..-1]
-include::{chapters-path}special/chapter.adoc[leveloffset=+1, lines=7..21;32..-1]
-include::{chapters-path}flavors/chapter.adoc[leveloffset=+1, lines=7..21;32..-1]
-include::{chapters-path}plist/chapter.adoc[leveloffset=+1, lines=7..21;32..-1]
-include::{chapters-path}pkg-files/chapter.adoc[leveloffset=+1, lines=7..21;32..-1]
-include::{chapters-path}testing/chapter.adoc[leveloffset=+1, lines=7..21;32..-1]
-include::{chapters-path}upgrading/chapter.adoc[leveloffset=+1, lines=7..21;32..-1]
-include::{chapters-path}security/chapter.adoc[leveloffset=+1, lines=7..21;32..-1]
-include::{chapters-path}porting-dads/chapter.adoc[leveloffset=+1, lines=7..23;34..-1]
-include::{chapters-path}porting-samplem/chapter.adoc[leveloffset=+1, lines=7..21;32..-1]
-include::{chapters-path}order/chapter.adoc[leveloffset=+1, lines=7..21;32..-1]
-include::{chapters-path}keeping-up/chapter.adoc[leveloffset=+1, lines=7..21;32..-1]
-include::{chapters-path}uses/chapter.adoc[leveloffset=+1, lines=7..22;33..-1]
-include::{chapters-path}versions/chapter.adoc[leveloffset=+1, lines=6..20;31..-1]
+include::content/en/books/porters-handbook/toc.adoc[]
diff --git a/documentation/content/en/books/porters-handbook/book.adoc b/documentation/content/en/books/porters-handbook/book.adoc
new file mode 100644
index 0000000000..3c56e705f4
--- /dev/null
+++ b/documentation/content/en/books/porters-handbook/book.adoc
@@ -0,0 +1,81 @@
+---
+title: FreeBSD Porter's Handbook
+authors:
+ - author: The FreeBSD Documentation Project
+copyright: 2000-2020 The FreeBSD Documentation Project
+trademarks: ["freebsd", "sun", "unix", "general"]
+---
+
+= FreeBSD Porter's Handbook
+:doctype: book
+:toc: macro
+:toclevels: 2
+:icons: font
+:xrefstyle: basic
+:relfileprefix: ../
+:outfilesuffix:
+:sectnums:
+:sectnumlevels: 6
+:partnums:
+:chapter-signifier: Chapter
+:part-signifier: Part
+:source-highlighter: rouge
+:experimental:
+:skip-front-matter:
+
+ifeval::["{backend}" == "html5"]
+include::shared/mirrors.adoc[]
+include::shared/authors.adoc[]
+include::shared/releases.adoc[]
+include::shared/en/mailing-lists.adoc[]
+include::shared/en/teams.adoc[]
+include::shared/en/urls.adoc[]
+:chapters-path: content/en/books/porters-handbook/
+endif::[]
+
+ifeval::["{backend}" == "pdf"]
+include::../../../../shared/mirrors.adoc[]
+include::../../../../shared/authors.adoc[]
+include::../../../../shared/releases.adoc[]
+include::../../../../shared/en/mailing-lists.adoc[]
+include::../../../../shared/en/teams.adoc[]
+include::../../../../shared/en/urls.adoc[]
+:chapters-path:
+endif::[]
+
+ifeval::["{backend}" == "epub3"]
+include::../../../../shared/mirrors.adoc[]
+include::../../../../shared/authors.adoc[]
+include::../../../../shared/releases.adoc[]
+include::../../../../shared/en/mailing-lists.adoc[]
+include::../../../../shared/en/teams.adoc[]
+include::../../../../shared/en/urls.adoc[]
+:chapters-path:
+endif::[]
+
+'''
+
+toc::[]
+
+include::{chapters-path}toc-tables.adoc[]
+
+include::{chapters-path}toc-examples.adoc[]
+
+include::{chapters-path}porting-why/_index.adoc[leveloffset=+1, lines=7..21;32..-1]
+include::{chapters-path}new-port/_index.adoc[leveloffset=+1, lines=7..21;32..-1]
+include::{chapters-path}quick-porting/_index.adoc[leveloffset=+1, lines=7..21;32..-1]
+include::{chapters-path}slow-porting/_index.adoc[leveloffset=+1, lines=7..21;32..-1]
+include::{chapters-path}makefiles/_index.adoc[leveloffset=+1, lines=7..22;33..-1]
+include::{chapters-path}special/_index.adoc[leveloffset=+1, lines=7..21;32..-1]
+include::{chapters-path}flavors/_index.adoc[leveloffset=+1, lines=7..21;32..-1]
+include::{chapters-path}plist/_index.adoc[leveloffset=+1, lines=7..21;32..-1]
+include::{chapters-path}pkg-files/_index.adoc[leveloffset=+1, lines=7..21;32..-1]
+include::{chapters-path}testing/_index.adoc[leveloffset=+1, lines=7..21;32..-1]
+include::{chapters-path}upgrading/_index.adoc[leveloffset=+1, lines=7..21;32..-1]
+include::{chapters-path}security/_index.adoc[leveloffset=+1, lines=7..21;32..-1]
+include::{chapters-path}porting-dads/_index.adoc[leveloffset=+1, lines=7..23;34..-1]
+include::{chapters-path}porting-samplem/_index.adoc[leveloffset=+1, lines=7..21;32..-1]
+include::{chapters-path}order/_index.adoc[leveloffset=+1, lines=7..21;32..-1]
+include::{chapters-path}keeping-up/_index.adoc[leveloffset=+1, lines=7..21;32..-1]
+include::{chapters-path}uses/_index.adoc[leveloffset=+1, lines=7..22;33..-1]
+include::{chapters-path}versions/_index.adoc[leveloffset=+1, lines=6..20;31..-1]
diff --git a/documentation/content/en/books/porters-handbook/chapters-order.adoc b/documentation/content/en/books/porters-handbook/chapters-order.adoc
index 3aaba51a43..81f5b000cb 100644
--- a/documentation/content/en/books/porters-handbook/chapters-order.adoc
+++ b/documentation/content/en/books/porters-handbook/chapters-order.adoc
@@ -1,18 +1,18 @@
-porting-why/chapter.adoc
-new-port/chapter.adoc
-quick-porting/chapter.adoc
-slow-porting/chapter.adoc
-makefiles/chapter.adoc
-special/chapter.adoc
-flavors/chapter.adoc
-plist/chapter.adoc
-pkg-files/chapter.adoc
-testing/chapter.adoc
-upgrading/chapter.adoc
-security/chapter.adoc
-porting-dads/chapter.adoc
-porting-samplem/chapter.adoc
-order/chapter.adoc
-keeping-up/chapter.adoc
-uses/chapter.adoc
-versions/chapter.adoc
+porting-why/_index.adoc
+new-port/_index.adoc
+quick-porting/_index.adoc
+slow-porting/_index.adoc
+makefiles/_index.adoc
+special/_index.adoc
+flavors/_index.adoc
+plist/_index.adoc
+pkg-files/_index.adoc
+testing/_index.adoc
+upgrading/_index.adoc
+security/_index.adoc
+porting-dads/_index.adoc
+porting-samplem/_index.adoc
+order/_index.adoc
+keeping-up/_index.adoc
+uses/_index.adoc
+versions/_index.adoc
diff --git a/documentation/content/en/books/porters-handbook/flavors/chapter.adoc b/documentation/content/en/books/porters-handbook/flavors/_index.adoc
similarity index 90%
rename from documentation/content/en/books/porters-handbook/flavors/chapter.adoc
rename to documentation/content/en/books/porters-handbook/flavors/_index.adoc
index dd17300133..0e540c204d 100644
--- a/documentation/content/en/books/porters-handbook/flavors/chapter.adoc
+++ b/documentation/content/en/books/porters-handbook/flavors/_index.adoc
@@ -180,7 +180,7 @@ lite_PKGNAMESUFFIX= -lite
[[flavors-auto-php]]
== `USES=php` and Flavors
-When using <<uses-php,`php`>> with one of these arguments, `phpize`, `ext`, `zend`, or `pecl`, the port will automatically have `FLAVORS` filled in with the PHP versions it supports.
+When using crossref:uses[uses-php,`php`] with one of these arguments, `phpize`, `ext`, `zend`, or `pecl`, the port will automatically have `FLAVORS` filled in with the PHP versions it supports.
[[flavors-auto-php-ex1]]
.Simple `USES=php` Extension
@@ -246,7 +246,7 @@ When adding a dependency on a PHP flavored port, use `@${PHP_FLAVOR}`. _Never_ u
[[flavors-auto-python]]
== `USES=python` and Flavors
-When using <<uses-python,`python`>> and `USE_PYTHON=distutils`, the port will automatically have `FLAVORS` filled in with the Python versions it supports.
+When using crossref:uses[uses-python,`python`] and `USE_PYTHON=distutils`, the port will automatically have `FLAVORS` filled in with the Python versions it supports.
[[flavors-auto-python-ex1]]
.Simple `USES=python`
@@ -330,8 +330,8 @@ USES= python:3.5+
[[flavors-auto-lua]]
== `USES=lua` and Flavors
-When using <<uses-lua,`lua:module`>> or <<uses-lua,`lua:flavors`>>, the port will automatically have `FLAVORS` filled in with the Lua versions it supports. However, it is not expected that ordinary applications (rather than Lua modules) should use this feature; most applications that embed or otherwise use Lua should simply use `USES=lua`.
+When using crossref:uses[uses-lua,`lua:module`] or crossref:uses[uses-lua,`lua:flavors`], the port will automatically have `FLAVORS` filled in with the Lua versions it supports. However, it is not expected that ordinary applications (rather than Lua modules) should use this feature; most applications that embed or otherwise use Lua should simply use `USES=lua`.
`LUA_FLAVOR` is available (and must be used) to depend on the correct version of dependencies regardless of whether the port used the `flavors` or `module` parameters.
-See <<using-lua,Using Lua>> for further information.
+See crossref:special[using-lua,Using Lua] for further information.
diff --git a/documentation/content/en/books/porters-handbook/keeping-up/chapter.adoc b/documentation/content/en/books/porters-handbook/keeping-up/_index.adoc
similarity index 100%
rename from documentation/content/en/books/porters-handbook/keeping-up/chapter.adoc
rename to documentation/content/en/books/porters-handbook/keeping-up/_index.adoc
diff --git a/documentation/content/en/books/porters-handbook/makefiles/chapter.adoc b/documentation/content/en/books/porters-handbook/makefiles/_index.adoc
similarity index 98%
rename from documentation/content/en/books/porters-handbook/makefiles/chapter.adoc
rename to documentation/content/en/books/porters-handbook/makefiles/_index.adoc
index bcfae7facc..f198adc83b 100644
--- a/documentation/content/en/books/porters-handbook/makefiles/chapter.adoc
+++ b/documentation/content/en/books/porters-handbook/makefiles/_index.adoc
@@ -30,7 +30,7 @@ include::shared/en/urls.adoc[]
toc::[]
-Configuring the [.filename]#Makefile# is pretty simple, and again we suggest looking at existing examples before starting. Also, there is a <<porting-samplem,sample Makefile>> in this handbook, so take a look and please follow the ordering of variables and sections in that template to make the port easier for others to read.
+Configuring the [.filename]#Makefile# is pretty simple, and again we suggest looking at existing examples before starting. Also, there is a crossref:porting-samplem[porting-samplem,sample Makefile] in this handbook, so take a look and please follow the ordering of variables and sections in that template to make the port easier for others to read.
Consider these problems in sequence during the design of the new [.filename]#Makefile#:
@@ -1538,7 +1538,7 @@ USE_GITHUB= nodefault
[IMPORTANT]
====
-When using `USE_GITHUB=nodefault`, the [.filename]#Makefile# must set `DISTFILES` in its <<porting-order-portname,top block>>. The definition should be:
+When using `USE_GITHUB=nodefault`, the [.filename]#Makefile# must set `DISTFILES` in its crossref:porting-order[porting-order-portname,top block]. The definition should be:
[.programlisting]
....
@@ -1888,7 +1888,7 @@ DISTNAME= foo
EXTRACT_SUFX= .tar.gzip
....
-The `USES=tar[:__xxx__]`, `USES=lha` or `USES=zip` automatically set `EXTRACT_SUFX` to the most common archives extensions as necessary, see <<uses,Using `USES` Macros>> for more details. If neither of these are set then `EXTRACT_SUFX` defaults to `.tar.gz`.
+The `USES=tar[:__xxx__]`, `USES=lha` or `USES=zip` automatically set `EXTRACT_SUFX` to the most common archives extensions as necessary, see crossref:uses[uses,Using `USES` Macros] for more details. If neither of these are set then `EXTRACT_SUFX` defaults to `.tar.gz`.
[NOTE]
====
@@ -2829,7 +2829,7 @@ Redistribution of the distribution files is permitted. The distribution files wi
[[licenses-license_perms-no-dist-mirror]]
`no-dist-mirror`::
-Redistribution of the distribution files is prohibited. This is equivalent to setting <<porting-restrictions-restricted,`RESTRICTED`>>. The distribution files will _not_ be added to the FreeBSD `MASTER_SITE_BACKUP` CDN.
+Redistribution of the distribution files is prohibited. This is equivalent to setting crossref:special[porting-restrictions-restricted,`RESTRICTED`]. The distribution files will _not_ be added to the FreeBSD `MASTER_SITE_BACKUP` CDN.
[[licenses-license_perms-dist-sell]]
`dist-sell`::
@@ -2837,7 +2837,7 @@ Selling of distribution files is permitted. The distribution files will be prese
[[licenses-license_perms-no-dist-sell]]
`no-dist-sell`::
-Selling of distribution files is prohibited. This is equivalent to setting <<porting-restrictions-no_cdrom,`NO_CDROM`>>.
+Selling of distribution files is prohibited. This is equivalent to setting crossref:special[porting-restrictions-no_cdrom,`NO_CDROM`].
[[licenses-license_perms-pkg-mirror]]
`pkg-mirror`::
@@ -2845,7 +2845,7 @@ Free redistribution of package is permitted. The package will be distributed on
[[licenses-license_perms-no-pkg-mirror]]
`no-pkg-mirror`::
-Free redistribution of package is prohibited. Equivalent to setting <<porting-restrictions-no_package,`NO_PACKAGE`>>. The package will _not_ be distributed from the FreeBSD package CDN https://pkg.freebsd.org/[https://pkg.freebsd.org/].
+Free redistribution of package is prohibited. Equivalent to setting crossref:special[porting-restrictions-no_package,`NO_PACKAGE`]. The package will _not_ be distributed from the FreeBSD package CDN https://pkg.freebsd.org/[https://pkg.freebsd.org/].
[[licenses-license_perms-pkg-sell]]
`pkg-sell`::
@@ -2853,7 +2853,7 @@ Selling of package is permitted. The package will be present on the installer im
[[licenses-license_perms-no-pkg-sell]]
`no-pkg-sell`::
-Selling of package is prohibited. This is equivalent to setting <<porting-restrictions-no_cdrom,`NO_CDROM`>>. The package will _not_ be present on the installer images.
+Selling of package is prohibited. This is equivalent to setting crossref:special[porting-restrictions-no_cdrom,`NO_CDROM`]. The package will _not_ be present on the installer images.
[[licenses-license_perms-auto-accept]]
`auto-accept`::
@@ -3072,7 +3072,7 @@ LICENSE_COMB= multi
[[makefile-portscout]]
== `PORTSCOUT`
-Portscout is an automated distfile check utility for the FreeBSD Ports Collection, described in detail in <<distfile-survey,Portscout: the FreeBSD Ports Distfile Scanner>>.
+Portscout is an automated distfile check utility for the FreeBSD Ports Collection, described in detail in crossref:keeping-up[distfile-survey,Portscout: the FreeBSD Ports Distfile Scanner].
`PORTSCOUT` defines special conditions within which the Portscout distfile scanner is restricted.
@@ -3225,7 +3225,7 @@ The dependency is checked from within the `extract` target. The _target_ part ca
[NOTE]
====
-Use this variable only if the extraction does not already work (the default assumes `tar`) and cannot be made to work using `USES=tar`, `USES=lha` or `USES=zip` described in <<uses,Using `USES` Macros>>.
+Use this variable only if the extraction does not already work (the default assumes `tar`) and cannot be made to work using `USES=tar`, `USES=lha` or `USES=zip` described in crossref:uses[uses,Using `USES` Macros].
====
[[makefile-patch_depends]]
@@ -3252,11 +3252,10 @@ Parameters can be added to define different features and dependencies used by th
USES= feature[:arguments]
....
-For the complete list of values, please see <<uses,Using `USES` Macros>>.
+For the complete list of values, please see crossref:uses[uses,Using `USES` Macros].
[WARNING]
====
-
`USES` cannot be assigned after inclusion of [.filename]#bsd.port.pre.mk#.
====
@@ -3296,7 +3295,7 @@ The port requires GCC (`gcc` or `{g-plus-plus}`) to build. Some ports need any G
|===
-Variables related to gmake and [.filename]#configure# are described in <<building,Building Mechanisms>>, while autoconf, automake and libtool are described in <<using-autotools,Using GNU Autotools>>. Perl related variables are described in <<using-perl,Using Perl>>. X11 variables are listed in <<using-x11,Using X11>>. <<using-gnome,Using Gnome>> deals with GNOME and <<using-kde,Using KDE>> with KDE related variables. <<using-java,Using Java>> documents Java variables, while <<using-php,Web Applications, Apache and PHP>> contains information on Apache, PHP and PEAR modules. Python is discussed in <<using-python,Using Python>>, while Ruby in <<using-ruby,Using Ruby>>. <<using-sdl,Using SDL>> provides variables used for SDL applications and finally, <<using-xfce,Using Xfce>> contains information on Xfce.
+Variables related to gmake and [.filename]#configure# are described in crossref:special[building,Building Mechanisms], while autoconf, automake and libtool are described in crossref:special[using-autotools,Using GNU Autotools]. Perl related variables are described in crossref:special[using-perl,Using Perl]. X11 variables are listed in crossref:special[using-x11,Using X11]. crossref:special[using-gnome,Using Gnome] deals with GNOME and crossref:special[using-kde,Using KDE] with KDE related variables. crossref:special[using-java,Using Java] documents Java variables, while crossref:special[using-php,Web Applications, Apache and PHP] contains information on Apache, PHP and PEAR modules. Python is discussed in crossref:special[using-python,Using Python], while Ruby in crossref:special[using-ruby,Using Ruby]. crossref:special[using-sdl,Using SDL] provides variables used for SDL applications and finally, crossref:special[using-xfce,Using Xfce] contains information on Xfce.
[[makefile-version-dependency]]
=== Minimal Version of a Dependency
@@ -4558,7 +4557,7 @@ There are three different variables to register a conflict between packages and
[NOTE]
====
-The conflict variables automatically set the variable `IGNORE`, which is more fully documented in <<dads-noinstall,Marking a Port Not Installable with `BROKEN`, `FORBIDDEN`, or `IGNORE`>>.
+The conflict variables automatically set the variable `IGNORE`, which is more fully documented in crossref:porting-dads[dads-noinstall,Marking a Port Not Installable with `BROKEN`, `FORBIDDEN`, or `IGNORE`].
====
When removing one of several conflicting ports, it is advisable to retain `CONFLICTS` in those other ports for a few months to cater for users who only update once in a while.
@@ -4649,7 +4648,7 @@ The `install` phase is very important to the end user because it adds files to t
[[install-macros]]
=== `INSTALL_*` Macros
-Use the macros provided in [.filename]#bsd.port.mk# to ensure correct modes of files in the port's `*-install` targets. Set ownership directly in [.filename]#pkg-plist# with the corresponding entries, such as `@(_owner_,_group_,)`, `@owner _owner_`, and `@group _group_`. These operators work until overridden, or until the end of [.filename]#pkg-plist#, so remember to reset them after they are no longer needed. The default ownership is `root:wheel`. See <<plist-keywords-base,Base Keywords>> for more information.
+Use the macros provided in [.filename]#bsd.port.mk# to ensure correct modes of files in the port's `*-install` targets. Set ownership directly in [.filename]#pkg-plist# with the corresponding entries, such as `@(_owner_,_group_,)`, `@owner _owner_`, and `@group _group_`. These operators work until overridden, or until the end of [.filename]#pkg-plist#, so remember to reset them after they are no longer needed. The default ownership is `root:wheel`. See crossref:plist[plist-keywords-base,Base Keywords] for more information.
* `INSTALL_PROGRAM` is a command to install binary executables.
* `INSTALL_SCRIPT` is a command to install executable scripts.
@@ -4694,7 +4693,7 @@ Use man:file[1] on a file to determine if it has been stripped. Binaries are rep
====
When `WITH_DEBUG` is defined, elf files _must not_ be stripped.
-The variables (`STRIP_CMD`, `INSTALL_PROGRAM`, `INSTALL_LIB`, ...) and <<uses,`USES`>> provided by the framework handle this automatically.
+The variables (`STRIP_CMD`, `INSTALL_PROGRAM`, `INSTALL_LIB`, ...) and crossref:uses[uses,`USES`] provided by the framework handle this automatically.
Some software, add `-s` to their `LDFLAGS`, in this case, either remove `-s` if `WITH_DEBUG` is set, or remove it unconditionally and use `STRIP_CMD` in `post-install`.
====
@@ -4702,7 +4701,7 @@ Some software, add `-s` to their `LDFLAGS`, in this case, either remove `-s` if
[[install-copytree]]
=== Installing a Whole Tree of Files
-Sometimes, a large number of files must be installed while preserving their hierarchical organization. For example, copying over a whole directory tree from `WRKSRC` to a target directory under `PREFIX`. Note that `PREFIX`, `EXAMPLESDIR`, `DATADIR`, and other path variables must always be prepended with `STAGEDIR` to respect staging (see <<staging,Staging>>).
+Sometimes, a large number of files must be installed while preserving their hierarchical organization. For example, copying over a whole directory tree from `WRKSRC` to a target directory under `PREFIX`. Note that `PREFIX`, `EXAMPLESDIR`, `DATADIR`, and other path variables must always be prepended with `STAGEDIR` to respect staging (see crossref:special[staging,Staging]).
Two macros exist for this situation. The advantage of using these macros instead of `cp` is that they guarantee proper file ownership and permissions on target files. The first macro, `COPYTREE_BIN`, will set all the installed files to be executable, thus being suitable for installing into [.filename]#PREFIX/bin#. The second macro, `COPYTREE_SHARE`, does not set executable permissions on files, and is therefore suitable for installing files under [.filename]#PREFIX/share# target.
@@ -4743,7 +4742,7 @@ If the software has some documentation other than the standard man and info page
Create a new directory for the port. The directory name is `DOCSDIR`. This usually equals `PORTNAME`. However, if the user might want different versions of the port to be installed at the same time, the whole `PKGNAME` can be used.
-Since only the files listed in [.filename]#pkg-plist# are installed, it is safe to always install documentation to `STAGEDIR` (see <<staging,Staging>>). Hence `.if` blocks are only needed when the installed files are large enough to cause significant I/O overhead.
+Since only the files listed in [.filename]#pkg-plist# are installed, it is safe to always install documentation to `STAGEDIR` (see crossref:special[staging,Staging]). Hence `.if` blocks are only needed when the installed files are large enough to cause significant I/O overhead.
[.programlisting]
....
@@ -4768,7 +4767,7 @@ Here are some handy variables and how they are expanded by default when used in
The `DOCS` option only controls additional documentation installed in `DOCSDIR`. It does not apply to standard man pages and info pages. Things installed in `EXAMPLESDIR` are controlled by the `EXAMPLES` option.
====
-These variables are exported to `PLIST_SUB`. Their values will appear there as pathnames relative to [.filename]#PREFIX# if possible. That is, [.filename]#share/doc/PORTNAME# will be substituted for `%%DOCSDIR%%` in the packing list by default, and so on. (See more on [.filename]#pkg-plist# substitution <<plist-sub,here>>.)
+These variables are exported to `PLIST_SUB`. Their values will appear there as pathnames relative to [.filename]#PREFIX# if possible. That is, [.filename]#share/doc/PORTNAME# will be substituted for `%%DOCSDIR%%` in the packing list by default, and so on. (See more on [.filename]#pkg-plist# substitution crossref:plist[plist-sub,here].)
All conditionally installed documentation files and directories are included in [.filename]#pkg-plist# with the `%%PORTDOCS%%` prefix, for example:
@@ -4789,7 +4788,7 @@ PORTDOCS= README.* ChangeLog docs/*
====
The equivalents of `PORTDOCS` for files installed under `DATADIR` and `EXAMPLESDIR` are `PORTDATA` and `PORTEXAMPLES`, respectively.
-The contents of [.filename]#pkg-message# are displayed upon installation. See <<porting-message,the section on using [.filename]#pkg-message#>> for details. [.filename]#pkg-message# does not need to be added to [.filename]#pkg-plist#.
+The contents of [.filename]#pkg-message# are displayed upon installation. See crossref:pkg-files[porting-message,the section on using [.filename]#pkg-message#] for details. [.filename]#pkg-message# does not need to be added to [.filename]#pkg-plist#.
====
[[install-subdirs]]
@@ -4836,7 +4835,7 @@ USES= python:3.4+,build
BINARY_ALIAS= python3=${PYTHON_CMD}
....
-See <<using-python,Using Python>> for more information about `USES=python`.
+See crossref:special[using-python,Using Python] for more information about `USES=python`.
====
[NOTE]
diff --git a/documentation/content/en/books/porters-handbook/new-port/chapter.adoc b/documentation/content/en/books/porters-handbook/new-port/_index.adoc
similarity index 93%
rename from documentation/content/en/books/porters-handbook/new-port/chapter.adoc
rename to documentation/content/en/books/porters-handbook/new-port/_index.adoc
index aec419af0a..32eee5a9ea 100644
--- a/documentation/content/en/books/porters-handbook/new-port/chapter.adoc
+++ b/documentation/content/en/books/porters-handbook/new-port/_index.adoc
@@ -31,7 +31,7 @@ toc::[]
Interested in making a new port, or upgrading existing ports? Great!
-What follows are some guidelines for creating a new port for FreeBSD. To upgrade an existing port, read this, then read <<port-upgrading,Upgrading a Port>>.
+What follows are some guidelines for creating a new port for FreeBSD. To upgrade an existing port, read this, then read crossref:port-upgrading[port-upgrading,Upgrading a Port].
When this document is not sufficiently detailed, refer to [.filename]#/usr/ports/Mk/bsd.port.mk#, which is included by all port [.filename]#Makefiles#. Even those not hacking [.filename]##Makefile##s daily can gain much knowledge from it. Additionally, specific questions can be sent to the {freebsd-ports}.
diff --git a/documentation/content/en/books/porters-handbook/order/chapter.adoc b/documentation/content/en/books/porters-handbook/order/_index.adoc
similarity index 60%
rename from documentation/content/en/books/porters-handbook/order/chapter.adoc
rename to documentation/content/en/books/porters-handbook/order/_index.adoc
index 398f3cf645..ff8e404f44 100644
--- a/documentation/content/en/books/porters-handbook/order/chapter.adoc
+++ b/documentation/content/en/books/porters-handbook/order/_index.adoc
@@ -62,23 +62,23 @@ In the following blocks, only set the variables that are required by the port. D
This block is the most important. It defines the port name, version, distribution file location, and category. The variables must be in this order:
-* <<makefile-portname,`PORTNAME`>>
-* <<makefile-versions,`PORTVERSION`][<<portversion-footnote, 1>>>>
-* <<makefile-versions,`DISTVERSIONPREFIX`>>
-* <<makefile-versions,`DISTVERSION`][<<portversion-footnote, 1>>>>
-* <<makefile-versions,`DISTVERSIONSUFFIX`>>
-* <<makefile-portrevision,`PORTREVISION`>>
-* <<makefile-portepoch,`PORTEPOCH`>>
-* <<makefile-categories,`CATEGORIES`>>
-* <<makefile-master_sites,`MASTER_SITES`>>
-* <<makefile-master_sites-shorthand,`MASTER_SITE_SUBDIR`>> (deprecated)
-* <<porting-pkgnameprefix-suffix,`PKGNAMEPREFIX`>>
-* <<porting-pkgnameprefix-suffix,`PKGNAMESUFFIX`>>
-* <<makefile-distname,`DISTNAME`>>
-* <<makefile-extract_sufx,`EXTRACT_SUFX`>>
-* <<makefile-distfiles-definition,`DISTFILES`>>
-* <<makefile-dist_subdir,`DIST_SUBDIR`>>
-* <<makefile-extract_only,`EXTRACT_ONLY`>>
+* crossref:makefiles[makefile-portname,`PORTNAME`]
+* crossref:makefiles[makefile-versions,`PORTVERSION`][<<portversion-footnote, 1>>]
+* crossref:makefiles[makefile-versions,`DISTVERSIONPREFIX`]
+* crossref:makefiles[makefile-versions,`DISTVERSION`][<<portversion-footnote, 1>>]
+* crossref:makefiles[makefile-versions,`DISTVERSIONSUFFIX`]
+* crossref:makefiles[makefile-portrevision,`PORTREVISION`]
+* crossref:makefiles[makefile-portepoch,`PORTEPOCH`]
+* crossref:makefiles[makefile-categories,`CATEGORIES`]
+* crossref:makefiles[makefile-master_sites,`MASTER_SITES`]
+* crossref:makefiles[makefile-master_sites-shorthand,`MASTER_SITE_SUBDIR`] (deprecated)
+* crossref:makefiles[porting-pkgnameprefix-suffix,`PKGNAMEPREFIX`]
+* crossref:makefiles[porting-pkgnameprefix-suffix,`PKGNAMESUFFIX`]
+* crossref:makefiles[makefile-distname,`DISTNAME`]
+* crossref:makefiles[makefile-extract_sufx,`EXTRACT_SUFX`]
+* crossref:makefiles[makefile-distfiles-definition,`DISTFILES`]
+* crossref:makefiles[makefile-dist_subdir,`DIST_SUBDIR`]
+* crossref:makefiles[makefile-extract_only,`EXTRACT_ONLY`]
[[portversion-footnote]]
[IMPORTANT]
@@ -91,31 +91,31 @@ Only one of PORTVERSION and DISTVERSION can be used.
This block is optional. The variables are:
-* <<porting-patchfiles,`PATCH_SITES`>>
-* <<porting-patchfiles,`PATCHFILES`>>
-* <<porting-patchfiles,`PATCH_DIST_STRIP`>>
+* crossref:makefiles[porting-patchfiles,`PATCH_SITES`]
+* crossref:makefiles[porting-patchfiles,`PATCHFILES`]
+* crossref:makefiles[porting-patchfiles,`PATCH_DIST_STRIP`]
[[porting-order-maintainer]]
== `MAINTAINER` Block
This block is mandatory. The variables are:
-* <<makefile-maintainer,`MAINTAINER`>>
-* <<makefile-comment,`COMMENT`>>
+* crossref:makefiles[makefile-maintainer,`MAINTAINER`]
+* crossref:makefiles[makefile-comment,`COMMENT`]
[[porting-order-license]]
== `LICENSE` Block
This block is optional, although it is highly recommended. The variables are:
-* <<licenses-license,`LICENSE`>>
-* <<licenses-license_comb,`LICENSE_COMB`>>
-* <<licenses-license_groups,`LICENSE_GROUPS`>> or `LICENSE_GROUPS_NAME`
-* <<licenses-license_name,`LICENSE_NAME`>> or `LICENSE_NAME_NAME`
-* <<licenses-license_text,`LICENSE_TEXT`>> or `LICENSE_TEXT_NAME`
-* <<licenses-license_file,`LICENSE_FILE`>> or `LICENSE_FILE_NAME`
-* <<licenses-license_perms,`LICENSE_PERMS`>> or `LICENSE_PERMS_NAME_`
-* <<licenses-license_distfiles,`LICENSE_DISTFILES`>> or `LICENSE_DISTFILES_NAME`
+* crossref:makefiles[licenses-license,`LICENSE`]
+* crossref:makefiles[licenses-license_comb,`LICENSE_COMB`]
+* crossref:makefiles[licenses-license_groups,`LICENSE_GROUPS`] or `LICENSE_GROUPS_NAME`
+* crossref:makefiles[licenses-license_name,`LICENSE_NAME`] or `LICENSE_NAME_NAME`
+* crossref:makefiles[licenses-license_text,`LICENSE_TEXT`] or `LICENSE_TEXT_NAME`
+* crossref:makefiles[licenses-license_file,`LICENSE_FILE`] or `LICENSE_FILE_NAME`
+* crossref:makefiles[licenses-license_perms,`LICENSE_PERMS`] or `LICENSE_PERMS_NAME_`
+* crossref:makefiles[licenses-license_distfiles,`LICENSE_DISTFILES`] or `LICENSE_DISTFILES_NAME`
If there are multiple licenses, sort the different LICENSE_VAR_NAME variables by license name.
@@ -124,21 +124,21 @@ If there are multiple licenses, sort the different LICENSE_VAR_NAME variables by
This block is optional. The variables are:
-* <<dads-deprecated,`DEPRECATED`>>
-* <<dads-deprecated,`EXPIRATION_DATE`>>
-* <<dads-noinstall,`FORBIDDEN`>>
-* <<dads-noinstall,`BROKEN`>>
-* <<dads-noinstall,`BROKEN_*`>>
-* <<dads-noinstall,`IGNORE`>>
-* <<dads-noinstall,`IGNORE_*`>>
-* <<dads-noinstall,`ONLY_FOR_ARCHS`>>
-* <<dads-noinstall,`ONLY_FOR_ARCHS_REASON*`>>
-* <<dads-noinstall,`NOT_FOR_ARCHS`>>
-* <<dads-noinstall,`NOT_FOR_ARCHS_REASON*`>>
+* crossref:porting-dads[dads-deprecated,`DEPRECATED`]
+* crossref:porting-dads[dads-deprecated,`EXPIRATION_DATE`]
+* crossref:porting-dads[dads-noinstall,`FORBIDDEN`]
+* crossref:porting-dads[dads-noinstall,`BROKEN`]
+* crossref:porting-dads[dads-noinstall,`BROKEN_*`]
+* crossref:porting-dads[dads-noinstall,`IGNORE`]
+* crossref:porting-dads[dads-noinstall,`IGNORE_*`]
+* crossref:porting-dads[dads-noinstall,`ONLY_FOR_ARCHS`]
+* crossref:porting-dads[dads-noinstall,`ONLY_FOR_ARCHS_REASON*`]
+* crossref:porting-dads[dads-noinstall,`NOT_FOR_ARCHS`]
+* crossref:porting-dads[dads-noinstall,`NOT_FOR_ARCHS_REASON*`]
[NOTE]
====
-`BROKEN_*` and `IGNORE_*` can be any generic variables, for example, `IGNORE_amd64`, `BROKEN_FreeBSD_10`, etc. With the exception of variables that depend on a <<uses,`USES`>>, place those in <<porting-order-uses>>. For instance, `IGNORE_WITH_PHP` only works if <<xuses-php,`php`>> is set, and `BROKEN_SSL` only if <<uses-ssl,`ssl`>> is set.
+`BROKEN_*` and `IGNORE_*` can be any generic variables, for example, `IGNORE_amd64`, `BROKEN_FreeBSD_10`, etc. With the exception of variables that depend on a crossref:uses[uses,`USES`], place those in <<porting-order-uses>>. For instance, `IGNORE_WITH_PHP` only works if crossref:uses[xuses-php,`php`] is set, and `BROKEN_SSL` only if crossref:uses[uses-ssl,`ssl`] is set.
If the port is marked BROKEN when some conditions are met, and such conditions can only be tested after including [.filename]#bsd.port.options.mk# or [.filename]#bsd.port.pre.mk#, then those variables should be set later, in <<porting-order-rest>>.
====
@@ -148,12 +148,12 @@ If the port is marked BROKEN when some conditions are met, and such conditions c
This block is optional. The variables are:
-* <<makefile-fetch_depends,`FETCH_DEPENDS`>>
-* <<makefile-extract_depends,`EXTRACT_DEPENDS`>>
-* <<makefile-patch_depends,`PATCH_DEPENDS`>>
-* <<makefile-build_depends,`BUILD_DEPENDS`>>
-* <<makefile-lib_depends,`LIB_DEPENDS`>>
-* <<makefile-run_depends,`RUN_DEPENDS`>>
+* crossref:makefiles:[makefile-fetch_depends,`FETCH_DEPENDS`]
+* crossref:makefiles:[makefile-extract_depends,`EXTRACT_DEPENDS`]
+* crossref:makefiles:[makefile-patch_depends,`PATCH_DEPENDS`]
+* crossref:makefiles:[makefile-build_depends,`BUILD_DEPENDS`]
+* crossref:makefiles:[makefile-lib_depends,`LIB_DEPENDS`]
+* crossref:makefiles:[makefile-run_depends,`RUN_DEPENDS`]
* `TEST_DEPENDS`
[[porting-order-flavors]]
@@ -161,7 +161,7 @@ This block is optional. The variables are:
This block is optional.
-Start this section with defining `FLAVORS`. Continue with the possible Flavors helpers. See <<flavors-using,Using FLAVORS>> for more Information.
+Start this section with defining `FLAVORS`. Continue with the possible Flavors helpers. See crossref:flavors[flavors-using,Using FLAVORS] for more Information.
Constructs setting variables not available as helpers using `.if ${FLAVOR:U} == foo` should go in their respective sections below.
@@ -170,10 +170,10 @@ Constructs setting variables not available as helpers using `.if ${FLAVOR:U} ==
Start this section with defining `USES`, and then possible `USE_x`.
-Keep related variables close together. For example, if using <<makefile-master_sites-github,`USE_GITHUB`>>, always put the `GH_*` variables right after it.
+Keep related variables close together. For example, if using crossref:makefiles[makefile-master_sites-github,`USE_GITHUB`], always put the `GH_*` variables right after it.
[[porting-order-variables]]
-== Standard [.filename]#bsd.port.mk# Variables
+== Standard bsd.port.mk Variables
This section block is for variables that can be defined in [.filename]#bsd.port.mk# that do not belong in any of the previous section blocks.
@@ -182,7 +182,7 @@ Order is not important, however try to keep similar variables together. For exam
[[porting-order-options]]
== Options and Helpers
-If the port uses the <<makefile-options,options framework>>, define `OPTIONS_DEFINE` and `OPTIONS_DEFAULT` first, then the other `OPTIONS_*` variables first, then the `*_DESC` descriptions, then the options helpers. Try and sort all of those alphabetically.
+If the port uses the crossref:makefiles[makefile-options,options framework], define `OPTIONS_DEFINE` and `OPTIONS_DEFAULT` first, then the other `OPTIONS_*` variables first, then the `*_DESC` descriptions, then the options helpers. Try and sort all of those alphabetically.
[[porting-order-options-ex1]]
.Options Variables Order Example
@@ -237,7 +237,6 @@ After all the variables are defined, the optional man:make[1] targets can be def
[TIP]
====
-
When using options helpers target keep them alphabetically sorted, but keep the `*-on` before the `*-off`. When also using the main target, keep the main target before the optional ones:
[.programlisting]
@@ -254,5 +253,4 @@ post-install-X11-on:
post-install-X11-off:
# Install bits that should be there if X11 is disabled
....
-
====
diff --git a/documentation/content/en/books/porters-handbook/pkg-files/chapter.adoc b/documentation/content/en/books/porters-handbook/pkg-files/_index.adoc
similarity index 96%
rename from documentation/content/en/books/porters-handbook/pkg-files/chapter.adoc
rename to documentation/content/en/books/porters-handbook/pkg-files/_index.adoc
index 3185c4e180..9a8bd74cea 100644
--- a/documentation/content/en/books/porters-handbook/pkg-files/chapter.adoc
+++ b/documentation/content/en/books/porters-handbook/pkg-files/_index.adoc
@@ -5,7 +5,7 @@ next: books/porters-handbook/testing
---
[[pkg-files]]
-= [.filename]#pkg-*#
+= pkg-*
:doctype: book
:toc: macro
:toclevels: 1
@@ -32,7 +32,7 @@ toc::[]
There are some tricks we have not mentioned yet about the [.filename]#pkg-*# files that come in handy sometimes.
[[porting-message]]
-== [.filename]#pkg-message#
+== pkg-message
To display a message when the package is installed, place the message in [.filename]#pkg-message#. This capability is often useful to display additional installation steps to be taken after a `pkg install` or `pkg upgrade`.
@@ -192,7 +192,7 @@ When displaying a message on upgrade, it is important to limit when it is being
====
[[pkg-install]]
-== [.filename]#pkg-install#
+== pkg-install
If the port needs to execute commands when the binary package is installed with `pkg add` or `pkg install`, use [.filename]#pkg-install#. This script will automatically be added to the package. It will be run twice by `pkg`, the first time as `${SH} pkg-install ${PKGNAME} PRE-INSTALL` before the package is installed, and the second time as `${SH} pkg-install ${PKGNAME} POST-INSTALL` after it has been installed. `$2` can be tested to determine which mode the script is being run in. The `PKG_PREFIX` environmental variable will be set to the package installation directory.
@@ -202,7 +202,7 @@ This script is here to help you set up the package so that it is as ready to use
====
[[pkg-deinstall]]
-== [.filename]#pkg-deinstall#
+== pkg-deinstall
This script executes when a package is removed.
@@ -214,9 +214,9 @@ This script is here to help you set up the package so that it is as ready to use
====
[[pkg-names]]
-== Changing the Names of [.filename]#pkg-*#
+== Changing the Names of pkg-*
-All the names of [.filename]#pkg-\*# are defined using variables that can be changed in the [.filename]#Makefile# if needed. This is especially useful when sharing the same [.filename]#pkg-*# files among several ports or when it is necessary to write to one of these files. See <<porting-wrkdir,writing to places other than `WRKDIR`>> for why it is a bad idea to write directly into the directory containing the [.filename]#pkg-*# files.
+All the names of [.filename]#pkg-\*# are defined using variables that can be changed in the [.filename]#Makefile# if needed. This is especially useful when sharing the same [.filename]#pkg-*# files among several ports or when it is necessary to write to one of these files. See crossref:porting-dads[porting-wrkdir,writing to places other than `WRKDIR`] for why it is a bad idea to write directly into the directory containing the [.filename]#pkg-*# files.
Here is a list of variable names and their default values. (`PKGDIR` defaults to `${MASTERDIR}`.)
diff --git a/documentation/content/en/books/porters-handbook/plist/chapter.adoc b/documentation/content/en/books/porters-handbook/plist/_index.adoc
similarity index 94%
rename from documentation/content/en/books/porters-handbook/plist/chapter.adoc
rename to documentation/content/en/books/porters-handbook/plist/_index.adoc
index 7fed24b734..e1868a6f4f 100644
--- a/documentation/content/en/books/porters-handbook/plist/chapter.adoc
+++ b/documentation/content/en/books/porters-handbook/plist/_index.adoc
@@ -5,7 +5,7 @@ next: books/porters-handbook/pkg-files
---
[[plist]]
-= Advanced [.filename]#pkg-plist# Practices
+= Advanced pkg-plist Practices
:doctype: book
:toc: macro
:toclevels: 1
@@ -30,9 +30,9 @@ include::shared/en/urls.adoc[]
toc::[]
[[plist-sub]]
-== Changing [.filename]#pkg-plist# Based on Make Variables
+== Changing pkg-plist Based on Make Variables
-Some ports, particularly the `p5-` ports, need to change their [.filename]#pkg-plist# depending on what options they are configured with (or version of `perl`, in the case of `p5-` ports). To make this easy, any instances in [.filename]#pkg-plist# of `%%OSREL%%`, `%%PERL_VER%%`, and `%%PERL_VERSION%%` will be substituted appropriately. The value of `%%OSREL%%` is the numeric revision of the operating system (for example, `4.9`). `%%PERL_VERSION%%` and `%%PERL_VER%%` is the full version number of `perl` (for example, `5.8.9`). Several other `%%_VARS_%%` related to port's documentation files are described in <<install-documentation,the relevant section>>.
+Some ports, particularly the `p5-` ports, need to change their [.filename]#pkg-plist# depending on what options they are configured with (or version of `perl`, in the case of `p5-` ports). To make this easy, any instances in [.filename]#pkg-plist# of `%%OSREL%%`, `%%PERL_VER%%`, and `%%PERL_VERSION%%` will be substituted appropriately. The value of `%%OSREL%%` is the numeric revision of the operating system (for example, `4.9`). `%%PERL_VERSION%%` and `%%PERL_VER%%` is the full version number of `perl` (for example, `5.8.9`). Several other `%%_VARS_%%` related to port's documentation files are described in crossref:makefiles[install-documentation,the relevant section].
To make other substitutions, set `PLIST_SUB` with a list of `_VAR=VALUE_` pairs and instances of `%%_VAR_%%` will be substituted with _VALUE_ in [.filename]#pkg-plist#.
@@ -46,7 +46,7 @@ PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSION}
in the [.filename]#Makefile# and use `%%OCTAVE_VERSION%%` wherever the version shows up in [.filename]#pkg-plist#. When the port is upgraded, it will not be necessary to edit dozens (or in some cases, hundreds) of lines in [.filename]#pkg-plist#.
-If files are installed conditionally on the options set in the port, the usual way of handling it is prefixing [.filename]#pkg-plist# lines with a `%%OPT%%` for lines needed when the option is enabled, or `%%NO_OPT%%` when the option is disabled, and adding `OPTIONS_SUB=yes` to the [.filename]#Makefile#. See <<options_sub,`OPTIONS_SUB`>> for more information.
+If files are installed conditionally on the options set in the port, the usual way of handling it is prefixing [.filename]#pkg-plist# lines with a `%%OPT%%` for lines needed when the option is enabled, or `%%NO_OPT%%` when the option is disabled, and adding `OPTIONS_SUB=yes` to the [.filename]#Makefile#. See crossref:makefiles[options_sub,`OPTIONS_SUB`] for more information.
For instance, if there are files that are only installed when the `X11` option is enabled, and [.filename]#Makefile# has:
@@ -125,7 +125,7 @@ Instead, install sample files with a [.filename]#filename.sample# extension. The
@sample etc/orbit.conf.sample
....
-If there is a very good reason not to install a working configuration file by default, only list the sample filename in [.filename]#pkg-plist#, without the `@sample` followed by a space part, and add a <<porting-message,message>> pointing out that the user must copy and edit the file before the software will work.
+If there is a very good reason not to install a working configuration file by default, only list the sample filename in [.filename]#pkg-plist#, without the `@sample` followed by a space part, and add a crossref:pkg-files[porting-message,message] pointing out that the user must copy and edit the file before the software will work.
[TIP]
====
@@ -166,7 +166,7 @@ While the use of dynamic package lists is not forbidden, maintainers should use
First, make sure the port is almost complete, with only [.filename]#pkg-plist# missing. Running `make makeplist` will show an example for [.filename]#pkg-plist#. The output of `makeplist` must be double checked for correctness as it tries to automatically guess a few things, and can get it wrong.
-User configuration files should be installed as [.filename]#filename.sample#, as it is described in <<plist-config>>. [.filename]#info/dir# must not be listed and appropriate [.filename]#install-info# lines must be added as noted in the <<makefile-info,info files>> section. Any libraries installed by the port must be listed as specified in the <<porting-shlibs,shared libraries>> section.
+User configuration files should be installed as [.filename]#filename.sample#, as it is described in <<plist-config>>. [.filename]#info/dir# must not be listed and appropriate [.filename]#install-info# lines must be added as noted in the crossref:makefiles[makefile-info,info files] section. Any libraries installed by the port must be listed as specified in the crossref:special[porting-shlibs,shared libraries] section.
[[plist-autoplist-regex]]
=== Expanding `PLIST_SUB` with Regular Expressions
@@ -262,20 +262,20 @@ The arguments are optional. If only the group and mode need to be changed, use:
[WARNING]
====
-If a keyword is used on an <<makefile-options,optional>> entry, it must to be added after the helper:
+If a keyword is used on an crossref:makefiles[makefile-options,optional] entry, it must to be added after the helper:
[.programlisting]
....
%%FOO%%@sample etc/orbit.conf.sample
....
-This is because the options plist helpers are used to comment out the line, so they need to be put first. See <<options_sub,`OPTIONS_SUB`>> for more information.
+This is because the options plist helpers are used to comment out the line, so they need to be put first. See crossref:makefiles[options_sub,`OPTIONS_SUB`] for more information.
====
[[plist-keywords-desktop-file-utils]]
=== `@desktop-file-utils`
-Will run `update-desktop-database -q` after installation and deinstallation. _Never_ use directly, add <<uses-desktop-file-utils,`USES=desktop-file-utils`>> to the [.filename]#Makefile#.
+Will run `update-desktop-database -q` after installation and deinstallation. _Never_ use directly, add crossref:uses[uses-desktop-file-utils,`USES=desktop-file-utils`] to the [.filename]#Makefile#.
[[plist-keywords-fc]]
=== `@fc` _directory_
@@ -300,7 +300,7 @@ Runs `glib-compile-schemas` on installation and deinstallation.
[[plist-keywords-info]]
=== `@info` _file_
-Add the file passed as argument to the plist, and updates the info document index on installation and deinstallation. Additionally, it removes the index if empty on deinstallation. This should never be used manually, but always through `INFO`. See <<makefile-info,Info Files>> for more information.
+Add the file passed as argument to the plist, and updates the info document index on installation and deinstallation. Additionally, it removes the index if empty on deinstallation. This should never be used manually, but always through `INFO`. See crossref:makefiles[makefile-info,Info Files] for more information.
[[plist-keywords-kld]]
=== `@kld` _directory_
@@ -334,7 +334,7 @@ On installation, add the full path to _file_ to [.filename]#/etc/shells#, while
[[plist-keywords-terminfo]]
=== `@terminfo`
-Do not use by itself. If the port installs [.filename]#*.terminfo# files, add <<uses-terminfo,USES=terminfo>> to its [.filename]#Makefile#.
+Do not use by itself. If the port installs [.filename]#*.terminfo# files, add crossref:uses[uses-terminfo,USES=terminfo] to its [.filename]#Makefile#.
On installation and deinstallation, if `tic` is present, refresh [.filename]#${PREFIX}/shared/misc/terminfo.db# from the [.filename]#*.terminfo# files in [.filename]#${PREFIX}/shared/misc#.
diff --git a/documentation/content/en/books/porters-handbook/porting-dads/chapter.adoc b/documentation/content/en/books/porters-handbook/porting-dads/_index.adoc
similarity index 95%
rename from documentation/content/en/books/porters-handbook/porting-dads/chapter.adoc
rename to documentation/content/en/books/porters-handbook/porting-dads/_index.adoc
index 699e3c5b85..abb3fcbdd9 100644
--- a/documentation/content/en/books/porters-handbook/porting-dads/chapter.adoc
+++ b/documentation/content/en/books/porters-handbook/porting-dads/_index.adoc
@@ -39,7 +39,7 @@ Here is a list of common dos and don'ts that are encountered during the porting
[[porting-wrkdir]]
== `WRKDIR`
-Do not write anything to files outside `WRKDIR`. `WRKDIR` is the only place that is guaranteed to be writable during the port build (see link:{handbook}#PORTS-CD[ installing ports from a CDROM] for an example of building ports from a read-only tree). The [.filename]##pkg-*## files can be modified by <<pkg-names,redefining a variable>> rather than overwriting the file.
+Do not write anything to files outside `WRKDIR`. `WRKDIR` is the only place that is guaranteed to be writable during the port build (see link:{handbook}#PORTS-CD[ installing ports from a CDROM] for an example of building ports from a read-only tree). The [.filename]##pkg-*## files can be modified by crossref:pkg-files[pkg-names,redefining a variable] rather than overwriting the file.
[[porting-wrkdirprefix]]
== `WRKDIRPREFIX`
@@ -71,10 +71,10 @@ to the proper place in the [.filename]#.c# file.
#endif
....
-A complete list of `{freebsd-version}` values is available in <<versions,__FreeBSD_version Values>>.
+A complete list of `{freebsd-version}` values is available in crossref:versions[versions,__FreeBSD_version Values].
[[dads-after-port-mk]]
-== Writing Something After [.filename]#bsd.port.mk#
+== Writing Something After bsd.port.mk
Do not write anything after the `.include <bsd.port.mk>` line. It usually can be avoided by including [.filename]#bsd.port.pre.mk# somewhere in the middle of the [.filename]#Makefile# and [.filename]#bsd.port.post.mk# at the end.
@@ -103,13 +103,13 @@ Here are some important variables defined in [.filename]#bsd.port.pre.mk# (this
|The release version of the operating system (for example, `2.1.5` or `2.2.7`)
|`OSVERSION`
-|The numeric version of the operating system; the same as <<versions,`{freebsd-version}`>>.
+|The numeric version of the operating system; the same as crossref:versions[versions,`{freebsd-version}`].
|`LOCALBASE`
|The base of the "local" tree (for example, `/usr/local`)
|`PREFIX`
-|Where the port installs itself (see <<porting-prefix,more on `PREFIX`>>).
+|Where the port installs itself (see crossref:testing[porting-prefix,more on `PREFIX`]).
|===
[NOTE]
@@ -250,7 +250,7 @@ Some build systems such as CMake, ninja, and GNU configure are set up for verbos
Do send applicable changes and patches to the upstream maintainer for inclusion in the next release of the code. This makes updating to the next release that much easier.
[[dads-readme]]
-== [.filename]#README.html#
+== README.html
[.filename]#README.html# is not part of the port, but generated by `make readme`. Do not include this file in patches or commits.
@@ -262,7 +262,7 @@ If `make readme` fails, make sure that the default value of `ECHO_MSG` has not b
[[dads-noinstall]]
== Marking a Port Not Installable with `BROKEN`, `FORBIDDEN`, or `IGNORE`
-In certain cases, users must be prevented from installing a port. There are several variables that can be used in a port's [.filename]#Makefile# to tell the user that the port cannot be installed. The value of these make variables will be the reason that is shown to users for why the port refuses to install itself. Please use the correct make variable. Each variable conveys radically different meanings, both to users and to automated systems that depend on [.filename]##Makefile##s, such as <<build-cluster,the ports build cluster>>, <<freshports,FreshPorts>>, and <<portsmon,portsmon>>.
+In certain cases, users must be prevented from installing a port. There are several variables that can be used in a port's [.filename]#Makefile# to tell the user that the port cannot be installed. The value of these make variables will be the reason that is shown to users for why the port refuses to install itself. Please use the correct make variable. Each variable conveys radically different meanings, both to users and to automated systems that depend on [.filename]##Makefile##s, such as crossref:keeping-up[build-cluster,the ports build cluster], crossref:keeping-up[freshports,FreshPorts], and crossref:keeping-up[portsmon,portsmon].
[[dads-noinstall-variables]]
=== Variables
@@ -288,7 +288,7 @@ For instance, use `BROKEN` when a port:
+
[NOTE]
====
-If a port would conflict with a currently installed port (for example, if they install a file in the same place that performs a different function), <<conflicts,use `CONFLICTS` instead>>. `CONFLICTS` will set `IGNORE` by itself.
+If a port would conflict with a currently installed port (for example, if they install a file in the same place that performs a different function), crossref:makefiles[conflicts,use `CONFLICTS` instead]. `CONFLICTS` will set `IGNORE` by itself.
====
[[dads-noinstall-notes]]
@@ -388,7 +388,7 @@ There is no set policy on how much notice to give. Current practice seems to be
The correct way for a [.filename]#Makefile# to signal that the port cannot be installed due to some external factor (for instance, the user has specified an illegal combination of build options) is to set a non-blank value to `IGNORE`. This value will be formatted and shown to the user by `make install`.
-It is a common mistake to use `.error` for this purpose. The problem with this is that many automated tools that work with the ports tree will fail in this situation. The most common occurrence of this is seen when trying to build [.filename]#/usr/ports/INDEX# (see <<make-describe,Running `make describe`>>). However, even more trivial commands such as `make maintainer` also fail in this scenario. This is not acceptable.
+It is a common mistake to use `.error` for this purpose. The problem with this is that many automated tools that work with the ports tree will fail in this situation. The most common occurrence of this is seen when trying to build [.filename]#/usr/ports/INDEX# (see crossref:testing[make-describe,Running `make describe`]). However, even more trivial commands such as `make maintainer` also fail in this scenario. This is not acceptable.
[[dot-error-breaks-index]]
.How to Avoid Using `.error`
@@ -410,7 +410,7 @@ IGNORE=option is not supported
====
[[dads-sysctl]]
-== Usage of [.filename]#sysctl#
+== Usage of sysctl
The usage of [.filename]#sysctl# is discouraged except in targets. This is because the evaluation of any ``makevar``s, such as used during `make index`, then has to run the command, further slowing down that process.
diff --git a/documentation/content/en/books/porters-handbook/porting-samplem/chapter.adoc b/documentation/content/en/books/porters-handbook/porting-samplem/_index.adoc
similarity index 96%
rename from documentation/content/en/books/porters-handbook/porting-samplem/chapter.adoc
rename to documentation/content/en/books/porters-handbook/porting-samplem/_index.adoc
index 9a7dbc37a2..c835d0009b 100644
--- a/documentation/content/en/books/porters-handbook/porting-samplem/chapter.adoc
+++ b/documentation/content/en/books/porters-handbook/porting-samplem/_index.adoc
@@ -5,7 +5,7 @@ next: books/porters-handbook/order
---
[[porting-samplem]]
-= A Sample [.filename]#Makefile#
+= A Sample Makefile
:doctype: book
:toc: macro
:toclevels: 1
@@ -31,7 +31,7 @@ toc::[]
Here is a sample [.filename]#Makefile# that can be used to create a new port. Make sure to remove all the extra comments (ones between brackets).
-The format shown is the recommended one for ordering variables, empty lines between sections, and so on. This format is designed so that the most important information is easy to locate. We recommend using <<porting-portlint,portlint>> to check the [.filename]#Makefile#.
+The format shown is the recommended one for ordering variables, empty lines between sections, and so on. This format is designed so that the most important information is easy to locate. We recommend using crossref:quick-porting[porting-portlint,portlint] to check the [.filename]#Makefile#.
[.programlisting]
....
diff --git a/documentation/content/en/books/porters-handbook/porting-why/chapter.adoc b/documentation/content/en/books/porters-handbook/porting-why/_index.adoc
similarity index 100%
rename from documentation/content/en/books/porters-handbook/porting-why/chapter.adoc
rename to documentation/content/en/books/porters-handbook/porting-why/_index.adoc
diff --git a/documentation/content/en/books/porters-handbook/quick-porting/chapter.adoc b/documentation/content/en/books/porters-handbook/quick-porting/_index.adoc
similarity index 88%
rename from documentation/content/en/books/porters-handbook/quick-porting/chapter.adoc
rename to documentation/content/en/books/porters-handbook/quick-porting/_index.adoc
index 1c22755703..27227a5b15 100644
--- a/documentation/content/en/books/porters-handbook/quick-porting/chapter.adoc
+++ b/documentation/content/en/books/porters-handbook/quick-porting/_index.adoc
@@ -29,13 +29,13 @@ include::shared/en/urls.adoc[]
toc::[]
-This section describes how to quickly create a new port. For applications where this quick method is not adequate, the full "Slow Porting" process is described in <<slow-porting,Slow Porting>>.
+This section describes how to quickly create a new port. For applications where this quick method is not adequate, the full "Slow Porting" process is described in crossref:slow-porting[slow-porting,Slow Porting].
First, get the original tarball and put it into `DISTDIR`, which defaults to [.filename]#/usr/ports/distfiles#.
[NOTE]
====
-These steps assume that the software compiled out-of-the-box. In other words, absolutely no changes were required for the application to work on a FreeBSD system. If anything had to be changed, refer to <<slow-porting,Slow Porting>>.
+These steps assume that the software compiled out-of-the-box. In other words, absolutely no changes were required for the application to work on a FreeBSD system. If anything had to be changed, refer to crossref:slow-porting[slow-porting,Slow Porting].
====
[NOTE]
@@ -51,7 +51,7 @@ This setting enables the "developer mode" that displays deprecation warnings and
====
[[porting-makefile]]
-== Writing the [.filename]#Makefile#
+== Writing the Makefile
The minimal [.filename]#Makefile# would look something like this:
*** 955 LINES SKIPPED ***
More information about the dev-commits-doc-all
mailing list