git: f80baa00f6 - main - Split Traditional Chinese porter's handbook
- Go to: [ bottom of page ] [ top of archives ] [ this month ]
Date: Sat, 27 Nov 2021 19:07:39 UTC
The branch main has been updated by carlavilla:
URL: https://cgit.FreeBSD.org/doc/commit/?id=f80baa00f69a34e7329040f03657389ccbd76763
commit f80baa00f69a34e7329040f03657389ccbd76763
Author: Sergio Carlavilla Delgado <carlavilla@FreeBSD.org>
AuthorDate: 2021-11-27 19:07:11 +0000
Commit: Sergio Carlavilla Delgado <carlavilla@FreeBSD.org>
CommitDate: 2021-11-27 19:07:11 +0000
Split Traditional Chinese porter's handbook
---
.../zh-tw/books/porters-handbook/_index.adoc | 28 +-
.../content/zh-tw/books/porters-handbook/book.adoc | 70 ++
.../books/porters-handbook/chapters-order.adoc | 36 +-
.../flavors/{chapter.adoc => _index.adoc} | 132 ++-
.../books/porters-handbook/keeping-up/_index.adoc | 129 +++
.../books/porters-handbook/keeping-up/chapter.adoc | 93 --
.../makefiles/{chapter.adoc => _index.adoc} | 1066 ++++++++++++++------
.../new-port/{chapter.adoc => _index.adoc} | 2 +-
.../zh-tw/books/porters-handbook/order/_index.adoc | 279 +++++
.../books/porters-handbook/order/chapter.adoc | 271 -----
.../pkg-files/{chapter.adoc => _index.adoc} | 82 +-
.../plist/{chapter.adoc => _index.adoc} | 208 ++--
.../porting-dads/{chapter.adoc => _index.adoc} | 186 +++-
.../porting-samplem/{chapter.adoc => _index.adoc} | 17 +-
.../porting-why/{chapter.adoc => _index.adoc} | 0
.../quick-porting/{chapter.adoc => _index.adoc} | 11 +-
.../security/{chapter.adoc => _index.adoc} | 92 +-
.../slow-porting/{chapter.adoc => _index.adoc} | 11 +-
.../special/{chapter.adoc => _index.adoc} | 996 ++++++++++++------
.../books/porters-handbook/testing/_index.adoc | 659 ++++++++++++
.../books/porters-handbook/testing/chapter.adoc | 537 ----------
.../books/porters-handbook/upgrading/_index.adoc | 294 ++++++
.../books/porters-handbook/upgrading/chapter.adoc | 228 -----
.../uses/{chapter.adoc => _index.adoc} | 581 +++++++----
.../versions/{chapter.adoc => _index.adoc} | 630 ++++++++++--
25 files changed, 4380 insertions(+), 2258 deletions(-)
diff --git a/documentation/content/zh-tw/books/porters-handbook/_index.adoc b/documentation/content/zh-tw/books/porters-handbook/_index.adoc
index 9a78c5fe23..d15a9897e4 100644
--- a/documentation/content/zh-tw/books/porters-handbook/_index.adoc
+++ b/documentation/content/zh-tw/books/porters-handbook/_index.adoc
@@ -4,21 +4,22 @@ authors:
- author: The FreeBSD Documentation Project
copyright: 2000-2020 The FreeBSD Documentation Project
trademarks: ["freebsd", "sun", "unix", "general"]
+next: books/porters-handbook/porting-why
+add_single_page_link: true
isIndex: true
---
= FreeBSD Porter 手冊
:doctype: book
:toc: macro
-:toclevels: 2
+:toclevels: 1
:icons: font
:sectnums:
:sectnumlevels: 6
:partnums:
:source-highlighter: rouge
:experimental:
-:book: true
-:pdf: false
+:images-path: books/porters-handbook/
ifdef::env-beastie[]
ifdef::backend-html5[]
@@ -44,27 +45,8 @@ endif::[]
'''
-toc::[]
+include::{chapters-path}toc.adoc[]
include::{chapters-path}toc-tables.adoc[]
include::{chapters-path}toc-examples.adoc[]
-
-include::{chapters-path}porting-why/chapter.adoc[leveloffset=+1]
-include::{chapters-path}new-port/chapter.adoc[leveloffset=+1]
-include::{chapters-path}quick-porting/chapter.adoc[leveloffset=+1]
-include::{chapters-path}slow-porting/chapter.adoc[leveloffset=+1]
-include::{chapters-path}makefiles/chapter.adoc[leveloffset=+1]
-include::{chapters-path}special/chapter.adoc[leveloffset=+1]
-include::{chapters-path}flavors/chapter.adoc[leveloffset=+1]
-include::{chapters-path}plist/chapter.adoc[leveloffset=+1]
-include::{chapters-path}pkg-files/chapter.adoc[leveloffset=+1]
-include::{chapters-path}testing/chapter.adoc[leveloffset=+1]
-include::{chapters-path}upgrading/chapter.adoc[leveloffset=+1]
-include::{chapters-path}security/chapter.adoc[leveloffset=+1]
-include::{chapters-path}porting-dads/chapter.adoc[leveloffset=+1]
-include::{chapters-path}porting-samplem/chapter.adoc[leveloffset=+1]
-include::{chapters-path}order/chapter.adoc[leveloffset=+1]
-include::{chapters-path}keeping-up/chapter.adoc[leveloffset=+1]
-include::{chapters-path}uses/chapter.adoc[leveloffset=+1]
-include::{chapters-path}versions/chapter.adoc[leveloffset=+1]
diff --git a/documentation/content/zh-tw/books/porters-handbook/book.adoc b/documentation/content/zh-tw/books/porters-handbook/book.adoc
new file mode 100644
index 0000000000..c7af3b198e
--- /dev/null
+++ b/documentation/content/zh-tw/books/porters-handbook/book.adoc
@@ -0,0 +1,70 @@
+---
+title: FreeBSD Porter 手冊
+authors:
+ - author: The FreeBSD Documentation Project
+copyright: 2000-2020 The FreeBSD Documentation Project
+trademarks: ["freebsd", "sun", "unix", "general"]
+add_split_page_link: true
+---
+
+= FreeBSD Porter 手冊
+:doctype: book
+:toc: macro
+:toclevels: 2
+:icons: font
+:sectnums:
+:sectnumlevels: 6
+:partnums:
+:source-highlighter: rouge
+:experimental:
+:book: true
+:pdf: false
+
+ifdef::env-beastie[]
+ifdef::backend-html5[]
+include::shared/authors.adoc[]
+include::shared/mirrors.adoc[]
+include::shared/releases.adoc[]
+include::shared/attributes/attributes-{{% lang %}}.adoc[]
+include::shared/{{% lang %}}/teams.adoc[]
+include::shared/{{% lang %}}/mailing-lists.adoc[]
+include::shared/{{% lang %}}/urls.adoc[]
+:chapters-path: content/{{% lang %}}/books/porters-handbook/
+endif::[]
+ifdef::backend-pdf,backend-epub3[]
+:chapters-path:
+include::../../../../../shared/asciidoctor.adoc[]
+endif::[]
+endif::[]
+
+ifndef::env-beastie[]
+:chapters-path:
+include::../../../../../shared/asciidoctor.adoc[]
+endif::[]
+
+'''
+
+toc::[]
+
+include::{chapters-path}toc-tables.adoc[]
+
+include::{chapters-path}toc-examples.adoc[]
+
+include::{chapters-path}porting-why/_index.adoc[leveloffset=+1]
+include::{chapters-path}new-port/_index.adoc[leveloffset=+1]
+include::{chapters-path}quick-porting/_index.adoc[leveloffset=+1]
+include::{chapters-path}slow-porting/_index.adoc[leveloffset=+1]
+include::{chapters-path}makefiles/_index.adoc[leveloffset=+1]
+include::{chapters-path}special/_index.adoc[leveloffset=+1]
+include::{chapters-path}flavors/_index.adoc[leveloffset=+1]
+include::{chapters-path}plist/_index.adoc[leveloffset=+1]
+include::{chapters-path}pkg-files/_index.adoc[leveloffset=+1]
+include::{chapters-path}testing/_index.adoc[leveloffset=+1]
+include::{chapters-path}upgrading/_index.adoc[leveloffset=+1]
+include::{chapters-path}security/_index.adoc[leveloffset=+1]
+include::{chapters-path}porting-dads/_index.adoc[leveloffset=+1]
+include::{chapters-path}porting-samplem/_index.adoc[leveloffset=+1]
+include::{chapters-path}order/_index.adoc[leveloffset=+1]
+include::{chapters-path}keeping-up/_index.adoc[leveloffset=+1]
+include::{chapters-path}uses/_index.adoc[leveloffset=+1]
+include::{chapters-path}versions/_index.adoc[leveloffset=+1]
diff --git a/documentation/content/zh-tw/books/porters-handbook/chapters-order.adoc b/documentation/content/zh-tw/books/porters-handbook/chapters-order.adoc
index 3aaba51a43..81f5b000cb 100644
--- a/documentation/content/zh-tw/books/porters-handbook/chapters-order.adoc
+++ b/documentation/content/zh-tw/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/zh-tw/books/porters-handbook/flavors/chapter.adoc b/documentation/content/zh-tw/books/porters-handbook/flavors/_index.adoc
similarity index 64%
rename from documentation/content/zh-tw/books/porters-handbook/flavors/chapter.adoc
rename to documentation/content/zh-tw/books/porters-handbook/flavors/_index.adoc
index d7fb913a66..06c0a73d82 100644
--- a/documentation/content/zh-tw/books/porters-handbook/flavors/chapter.adoc
+++ b/documentation/content/zh-tw/books/porters-handbook/flavors/_index.adoc
@@ -2,6 +2,8 @@
title: Chapter 7. Flavors
prev: books/porters-handbook/special
next: books/porters-handbook/plist
+description: Flavors are a way to have multiple variations of a port
+tags: ["Ports", "Flavors", "introduction", "how-to", "guide"]
---
[[flavors]]
@@ -45,7 +47,8 @@ endif::[]
[[flavors-intro]]
== An Introduction to Flavors
-Flavors are a way to have multiple variations of a port. The port is built multiple times, with variations.
+Flavors are a way to have multiple variations of a port.
+The port is built multiple times, with variations.
For example, a port can have a normal version with many features and quite a few dependencies, and a light "lite" version with only basic features and minimal dependencies.
@@ -54,18 +57,17 @@ Another example could be, a port can have a GTK flavor and a QT flavor, dependin
[[flavors-using]]
== Using FLAVORS
-To declare a port having multiple flavors, add `FLAVORS` to its [.filename]#Makefile#. The first flavor in `FLAVORS` is the default flavor.
+To declare a port having multiple flavors, add `FLAVORS` to its [.filename]#Makefile#.
+The first flavor in `FLAVORS` is the default flavor.
[TIP]
====
-
It can help simplify the logic of the [.filename]#Makefile# to also define `FLAVOR` as:
[.programlisting]
....
FLAVOR?= ${FLAVORS:[1]}
....
-
====
[IMPORTANT]
@@ -77,7 +79,6 @@ To distinguish flavors from options, which are always uppercase letters, flavor
.Basic Flavors Usage
[example]
====
-
If a port has a "lite" slave port, the slave port can be removed, and the port can be converted to flavors with:
[.programlisting]
@@ -90,18 +91,12 @@ lite_PKGNAMESUFFIX= -lite
.endif
....
-[NOTE]
-****
-The first flavor is the default one, and is called, here, `default`. It is not an obligation, and if possible, use a more specific flavor name, like in <<flavors-using-ex2>>.
-****
-
====
[[flavors-using-ex2]]
.Another Basic Flavors Usage
[example]
====
-
If a port has a `-nox11` slave port, the slave port can be removed, and the port can be converted to flavors with:
[.programlisting]
@@ -121,48 +116,42 @@ nox11_PKGNAMESUFFIX= -nox11
.More Complex Flavors Usage
[example]
====
-
-Here is a slightly edited excerpt of what is present in package:devel/libpeas[], a port that uses the <<flavors-auto-python,Python flavors>>. With the default Python 2 and 3 versions being 2.7 and 3.6, it will automatically get `FLAVORS=py27 py36`
+Here is a slightly edited excerpt of what is present in package:devel/libpeas[], a port that uses the <<flavors-auto-python,Python flavors>>.
+With the default Python 2 and 3 versions being 2.7 and 3.6, it will automatically get `FLAVORS=py27 py36`
[.programlisting]
....
USES= gnome python
-USE_PYTHON= flavors <.>
+USE_PYTHON= flavors
-.if ${FLAVOR:Upy27:Mpy2*} <.>
-USE_GNOME= pygobject3 <.>
+.if ${FLAVOR:Upy27:Mpy2*}
+USE_GNOME= pygobject3
CONFIGURE_ARGS+= --enable-python2 --disable-python3
-BUILD_WRKSRC= ${WRKSRC}/loaders/python <.>
-INSTALL_WRKSRC= ${WRKSRC}/loaders/python <.>
+BUILD_WRKSRC= ${WRKSRC}/loaders/python
+INSTALL_WRKSRC= ${WRKSRC}/loaders/python
.else # py3*
-USE_GNOME+= py3gobject3 <.>
+USE_GNOME+= py3gobject3
CONFIGURE_ARGS+= --disable-python2 --enable-python3 \
- ac_cv_path_PYTHON3_CONFIG=${LOCALBASE}/bin/python${PYTHON_VER}-config <.>
+ ac_cv_path_PYTHON3_CONFIG=${LOCALBASE}/bin/python${PYTHON_VER}-config
-BUILD_WRKSRC= ${WRKSRC}/loaders/python3 <.>
-INSTALL_WRKSRC= ${WRKSRC}/loaders/python3 <.>
+BUILD_WRKSRC= ${WRKSRC}/loaders/python3
+INSTALL_WRKSRC= ${WRKSRC}/loaders/python3
.endif
-py34_PLIST= ${.CURDIR}/pkg-plist-py3 <.>
-py35_PLIST= ${.CURDIR}/pkg-plist-py3 <.>
-py36_PLIST= ${.CURDIR}/pkg-plist-py3 <.>
+py34_PLIST= ${.CURDIR}/pkg-plist-py3
+py35_PLIST= ${.CURDIR}/pkg-plist-py3
+py36_PLIST= ${.CURDIR}/pkg-plist-py3
....
-<.> This port does not use `USE_PYTHON=distutils` but needs Python flavors anyway.
-
-<.> To guard against `FLAVOR` being empty, which would cause a man:make[1] error, use `${FLAVOR:U}` in string comparisons instead of `${FLAVOR}`.
-
-<.> <.> The Gnome Python gobject3 bindings have two different names, one for Python 2, pygobject3 and one for Python 3, py3gobject3.
-
-<.> The `configure` script has to run in [.filename]#${WRKSRC}#, but we are only interested in building and installing the Python 2 or Python 3 parts of the software, so set the build and install base directories appropriately.
-
-<.> Hint about the correct Python 3 config script path name.
-
-<.> The packing list is different when the built with Python 3. As there are three possible Python 3 versions, set `PLIST` for all three using the <<flavors-using-helpers,helper>>.
-
+This port does not use `USE_PYTHON=distutils` but needs Python flavors anyway.
+To guard against `FLAVOR` being empty, which would cause a man:make[1] error, use `${FLAVOR:U}` in string comparisons instead of `${FLAVOR}`.
+The Gnome Python gobject3 bindings have two different names, one for Python 2, pygobject3 and one for Python 3, py3gobject3.
+The `configure` script has to run in [.filename]#${WRKSRC}#, but we are only interested in building and installing the Python 2 or Python 3 parts of the software, so set the build and install base directories appropriately.
+Hint about the correct Python 3 config script path name.
+The packing list is different when the built with Python 3. As there are three possible Python 3 versions, set `PLIST` for all three using the <<flavors-using-helpers,helper>>.
====
[[flavors-using-helpers]]
@@ -172,31 +161,31 @@ To make the [.filename]#Makefile# easier to write, a few flavors helpers exist.
This list of helpers will set their variable:
-* `flavor_PKGNAMEPREFIX`
-* `flavor_PKGNAMESUFFIX`
-* `flavor_PLIST`
-* `flavor_DESCR`
+* `_flavor__PKGNAMEPREFIX`
+* `_flavor__PKGNAMESUFFIX`
+* `_flavor__PLIST`
+* `_flavor__DESCR`
This list of helpers will append to their variable:
-* `flavor_CONFLICTS`
-* `flavor_CONFLICTS_BUILD`
-* `flavor_CONFLICTS_INSTALL`
-* `flavor_PKG_DEPENDS`
-* `flavor_EXTRACT_DEPENDS`
-* `flavor_PATCH_DEPENDS`
-* `flavor_FETCH_DEPENDS`
-* `flavor_BUILD_DEPENDS`
-* `flavor_LIB_DEPENDS`
-* `flavor_RUN_DEPENDS`
-* `flavor_TEST_DEPENDS`
+* `_flavor__CONFLICTS`
+* `_flavor__CONFLICTS_BUILD`
+* `_flavor__CONFLICTS_INSTALL`
+* `_flavor__PKG_DEPENDS`
+* `_flavor__EXTRACT_DEPENDS`
+* `_flavor__PATCH_DEPENDS`
+* `_flavor__FETCH_DEPENDS`
+* `_flavor__BUILD_DEPENDS`
+* `_flavor__LIB_DEPENDS`
+* `_flavor__RUN_DEPENDS`
+* `_flavor__TEST_DEPENDS`
+
[[flavors-helpers-ex1]]
.Flavor Specific `PKGNAME`
[example]
====
-
-As all packages must have a different package name, flavors must change theirs, using `flavor_PKGNAMEPREFIX` and `flavor_PKGNAMESUFFIX` makes this easy:
+As all packages must have a different package name, flavors must change theirs, using `_flavor__PKGNAMEPREFIX` and `_flavor__PKGNAMESUFFIX` makes this easy:
[.programlisting]
....
@@ -209,18 +198,13 @@ lite_PKGNAMESUFFIX= -lite
[[flavors-auto-php]]
== `USES=php` and Flavors
-When using <<uses-php,USES=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.
-
-[NOTE]
-====
-All the examples assume the currently supported PHP versions are 5.6, 7.0, 7.1, and 7.2.
-====
+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
[example]
====
-
This will generate package for all the supported versions:
[.programlisting]
@@ -262,7 +246,6 @@ PHP applications that are flavorized _must_ append `PHP_PKGNAMESUFFIX` to their
.Flavorizing a PHP Application
[example]
====
-
Adding Flavors support to a PHP application is straightforward:
[.programlisting]
@@ -276,20 +259,20 @@ USES= php:flavors
[TIP]
====
-
-When adding a dependency on a PHP flavored port, use `@${PHP_FLAVOR}`. _Never_ use `FLAVOR` directly.
+When adding a dependency on a PHP flavored port, use `@${PHP_FLAVOR}`.
+_Never_ use `FLAVOR` directly.
====
[[flavors-auto-python]]
== `USES=python` and Flavors
-When using <<uses-python,`USES=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`
[example]
====
-
Supposing the current Python supported versions are 2.7, 3.4, 3.5, and 3.6, and the default Python 2 and 3 versions are 2.7 and 3.6, a port with:
[.programlisting]
@@ -313,7 +296,6 @@ Will get these flavors: `py27`, `py34`, `py35` and `py36`.
.`USES=python` with Version Requirements
[example]
====
-
Supposing the current Python supported versions are 2.7, 3.4, 3.5, and 3.6, and the default Python 2 and 3 versions are 2.7 and 3.6, a port with:
[.programlisting]
@@ -349,13 +331,13 @@ USE_PYTHON= distutils allflavors
Will get these flavors: `py34`, `py35`, and `py36`.
====
-`PY_FLAVOR` is available to depend on the correct version of Python modules. All dependencies on flavored Python ports should use `PY_FLAVOR`, and not `FLAVOR` directly..
+`PY_FLAVOR` is available to depend on the correct version of Python modules.
+All dependencies on flavored Python ports should use `PY_FLAVOR`, and not `FLAVOR` directly..
[[flavors-auto-python-ex3]]
.For a Port Not Using `distutils`
[example]
====
-
If the default Python 3 version is 3.6, the following will set `PY_FLAVOR` to `py36`:
[.programlisting]
@@ -366,3 +348,15 @@ USES= python:3.5+
....
====
+
+[[flavors-auto-lua]]
+== `USES=lua` and Flavors
+
+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 crossref:special[using-lua,Using Lua] for further information.
diff --git a/documentation/content/zh-tw/books/porters-handbook/keeping-up/_index.adoc b/documentation/content/zh-tw/books/porters-handbook/keeping-up/_index.adoc
new file mode 100644
index 0000000000..195910b56e
--- /dev/null
+++ b/documentation/content/zh-tw/books/porters-handbook/keeping-up/_index.adoc
@@ -0,0 +1,129 @@
+---
+title: Chapter 16. Keeping Up
+prev: books/porters-handbook/order
+next: books/porters-handbook/uses
+description: How to keep up the FreeBSD Ports Collection
+tags: ["keeping up", "ports", "updating", "FreshPorts"]
+---
+
+[[keeping-up]]
+= Keeping Up
+:doctype: book
+:toc: macro
+:toclevels: 1
+:icons: font
+:sectnums:
+:sectnumlevels: 6
+:sectnumoffset: 16
+:partnums:
+:source-highlighter: rouge
+:experimental:
+:images-path: books/porters-handbook/
+
+ifdef::env-beastie[]
+ifdef::backend-html5[]
+:imagesdir: ../../../../images/{images-path}
+endif::[]
+ifndef::book[]
+include::shared/authors.adoc[]
+include::shared/mirrors.adoc[]
+include::shared/releases.adoc[]
+include::shared/attributes/attributes-{{% lang %}}.adoc[]
+include::shared/{{% lang %}}/teams.adoc[]
+include::shared/{{% lang %}}/mailing-lists.adoc[]
+include::shared/{{% lang %}}/urls.adoc[]
+toc::[]
+endif::[]
+ifdef::backend-pdf,backend-epub3[]
+include::../../../../../shared/asciidoctor.adoc[]
+endif::[]
+endif::[]
+
+ifndef::env-beastie[]
+toc::[]
+include::../../../../../shared/asciidoctor.adoc[]
+endif::[]
+
+The FreeBSD Ports Collection is constantly changing.
+Here is some information on how to keep up.
+
+[[freshports]]
+== FreshPorts
+
+One of the easiest ways to learn about updates that have already been committed is by subscribing to http://www.FreshPorts.org/[FreshPorts].
+Multiple ports can be monitored.
+Maintainers are strongly encouraged to subscribe, because they will receive notification of not only their own changes, but also any changes that any other FreeBSD committer has made.
+(These are often necessary to keep up with changes in the underlying ports framework-although it would be most polite to receive an advance heads-up from those committing such changes, sometimes this is overlooked or impractical.
+Also, in some cases, the changes are very minor in nature.
+We expect everyone to use their best judgement in these cases.)
+
+To use FreshPorts, an account is required.
+Those with registered email addresses at `@FreeBSD.org` will see the opt-in link on the right-hand side of the web pages.
+Those who already have a FreshPorts account but are not using a `@FreeBSD.org` email address can change the email to `@FreeBSD.org`, subscribe, then change it back again.
+
+FreshPorts also has a sanity test feature which automatically tests each commit to the FreeBSD ports tree.
+If subscribed to this service, a committer will receive notifications of any errors which FreshPorts detects during sanity testing of their commits.
+
+[[cgit]]
+== The Web Interface to the Source Repository
+
+It is possible to browse the files in the source repository by using a web interface.
+Changes that affect the entire port system are now documented in the https://cgit.freebsd.org/ports/tree/CHANGES[CHANGES] file.
+Changes that affect individual ports are now documented in the https://cgit.FreeBSD.org/ports/tree/UPDATING[UPDATING] file.
+However, the definitive answer to any question is undoubtedly to read the source code of https://cgit.FreeBSD.org/ports/tree/Mk/bsd.port.mk[bsd.port.mk], and associated files.
+
+[[ports-mailing-list]]
+== The FreeBSD Ports Mailing List
+
+As a ports maintainer, consider subscribing to {freebsd-ports}.
+Important changes to the way ports work will be announced there, and then committed to [.filename]#CHANGES#.
+
+If the volume of messages on this mailing list is too high, consider following {freebsd-ports-announce} which contains only announcements.
+
+[[build-cluster]]
+== The FreeBSD Port Building Cluster
+
+One of the least-publicized strengths of FreeBSD is that an entire cluster of machines is dedicated to continually building the Ports Collection, for each of the major OS releases and for each Tier-1 architecture.
+
+Individual ports are built unless they are specifically marked with `IGNORE`.
+Ports that are marked with `BROKEN` will still be attempted, to see if the underlying problem has been resolved.
+(This is done by passing `TRYBROKEN` to the port's [.filename]#Makefile#.)
+
+[[distfile-survey]]
+== Portscout: the FreeBSD Ports Distfile Scanner
+
+The build cluster is dedicated to building the latest release of each port with distfiles that have already been fetched.
+However, as the Internet continually changes, distfiles can quickly go missing.
+http://portscout.FreeBSD.org[Portscout], the FreeBSD Ports distfile scanner, attempts to query every download site for every port to find out if each distfile is still available.
+Portscout can generate HTML reports and send emails about newly available ports to those who request them.
+Unless not otherwise subscribed, maintainers are asked to check periodically for changes, either by hand or using the RSS feed.
+
+Portscout's first page gives the email address of the port maintainer, the number of ports the maintainer is responsible for, the number of those ports with new distfiles, and the percentage of those ports that are out-of-date.
+The search function allows for searching by email address for a specific maintainer, and for selecting whether only out-of-date ports are shown.
+
+Upon clicking on a maintainer's email address, a list of all of their ports is displayed, along with port category, current version number, whether or not there is a new version, when the port was last updated, and finally when it was last checked.
+A search function on this page allows the user to search for a specific port.
+
+Clicking on a port name in the list displays the http://freshports.org[FreshPorts] port information.
+
+Additional documentation is available in the https://github.com/freebsd/portscout[Portscout repository].
+
+[[portsmon]]
+== The FreeBSD Ports Monitoring System
+
+Another handy resource is the http://portsmon.FreeBSD.org[FreeBSD Ports Monitoring System] (also known as `portsmon`).
+This system comprises a database that processes information from several sources and allows it to be browsed via a web interface.
+Currently, the ports Problem Reports (PRs), the error logs from the build cluster, and individual files from the ports collection are used.
+In the future, this will be expanded to include the distfile survey, as well as other sources.
+
+To get started, use the http://portsmon.FreeBSD.org/portoverview.py[Overview of One Port] search page to find all the information about a port.
+
+This is the only resource available that maps PR entries to portnames.
+PR submitters do not always include the portname in their Synopsis, although we would prefer that they did.
+So, `portsmon` is a good place to find out whether an existing port has any PRs filed against it, any build errors,
+or if a new port the porter is considering creating has already been submitted.
+
+[NOTE]
+======
+The FreeBSD Ports Monitoring System (portsmon) is currently not working due to latest Python updates.
+======
diff --git a/documentation/content/zh-tw/books/porters-handbook/keeping-up/chapter.adoc b/documentation/content/zh-tw/books/porters-handbook/keeping-up/chapter.adoc
deleted file mode 100644
index d7007ede19..0000000000
--- a/documentation/content/zh-tw/books/porters-handbook/keeping-up/chapter.adoc
+++ /dev/null
@@ -1,93 +0,0 @@
----
-title: Chapter 16. Keeping Up
-prev: books/porters-handbook/order
-next: books/porters-handbook/uses
----
-
-[[keeping-up]]
-= Keeping Up
-:doctype: book
-:toc: macro
-:toclevels: 1
-:icons: font
-:sectnums:
-:sectnumlevels: 6
-:sectnumoffset: 16
-:partnums:
-:source-highlighter: rouge
-:experimental:
-:images-path: books/porters-handbook/
-
-ifdef::env-beastie[]
-ifdef::backend-html5[]
-:imagesdir: ../../../../images/{images-path}
-endif::[]
-ifndef::book[]
-include::shared/authors.adoc[]
-include::shared/mirrors.adoc[]
-include::shared/releases.adoc[]
-include::shared/attributes/attributes-{{% lang %}}.adoc[]
-include::shared/{{% lang %}}/teams.adoc[]
-include::shared/{{% lang %}}/mailing-lists.adoc[]
-include::shared/{{% lang %}}/urls.adoc[]
-toc::[]
-endif::[]
-ifdef::backend-pdf,backend-epub3[]
-include::../../../../../shared/asciidoctor.adoc[]
-endif::[]
-endif::[]
-
-ifndef::env-beastie[]
-toc::[]
-include::../../../../../shared/asciidoctor.adoc[]
-endif::[]
-
-The FreeBSD Ports Collection is constantly changing. Here is some information on how to keep up.
-
-[[freshports]]
-== FreshPorts
-
-One of the easiest ways to learn about updates that have already been committed is by subscribing to http://www.FreshPorts.org/[FreshPorts]. Multiple ports can be monitored. Maintainers are strongly encouraged to subscribe, because they will receive notification of not only their own changes, but also any changes that any other FreeBSD committer has made. (These are often necessary to keep up with changes in the underlying ports framework-although it would be most polite to receive an advance heads-up from those committing such changes, sometimes this is overlooked or impractical. Also, in some cases, the changes are very minor in nature. We expect everyone to use their best judgement in these cases.)
-
-To use FreshPorts, an account is required. Those with registered email addresses at `@FreeBSD.org` will see the opt-in link on the right-hand side of the web pages. Those who already have a FreshPorts account but are not using a `@FreeBSD.org` email address can change the email to `@FreeBSD.org`, subscribe, then change it back again.
-
-FreshPorts also has a sanity test feature which automatically tests each commit to the FreeBSD ports tree. If subscribed to this service, a committer will receive notifications of any errors which FreshPorts detects during sanity testing of their commits.
-
-[[svnweb]]
-== The Web Interface to the Source Repository
-
-It is possible to browse the files in the source repository by using a web interface. Changes that affect the entire port system are now documented in the http://svnweb.FreeBSD.org/ports/head/CHANGES[CHANGES] file. Changes that affect individual ports are now documented in the http://svnweb.FreeBSD.org/ports/head/UPDATING[UPDATING] file. However, the definitive answer to any question is undoubtedly to read the source code of http://svnweb.FreeBSD.org/ports/head/Mk/bsd.port.mk[bsd.port.mk], and associated files.
-
-[[ports-mailing-list]]
-== The FreeBSD Ports Mailing List
-
-As a ports maintainer, consider subscribing to {freebsd-ports}. Important changes to the way ports work will be announced there, and then committed to [.filename]#CHANGES#.
-
-If the volume of messages on this mailing list is too high, consider following {freebsd-ports-announce} which contains only announcements.
-
-[[build-cluster]]
-== The FreeBSD Port Building Cluster
-
-One of the least-publicized strengths of FreeBSD is that an entire cluster of machines is dedicated to continually building the Ports Collection, for each of the major OS releases and for each Tier-1 architecture.
-
-Individual ports are built unless they are specifically marked with `IGNORE`. Ports that are marked with `BROKEN` will still be attempted, to see if the underlying problem has been resolved. (This is done by passing `TRYBROKEN` to the port's [.filename]#Makefile#.)
-
-[[distfile-survey]]
-== Portscout: the FreeBSD Ports Distfile Scanner
-
-The build cluster is dedicated to building the latest release of each port with distfiles that have already been fetched. However, as the Internet continually changes, distfiles can quickly go missing. http://portscout.FreeBSD.org[Portscout], the FreeBSD Ports distfile scanner, attempts to query every download site for every port to find out if each distfile is still available. Portscout can generate HTML reports and send emails about newly available ports to those who request them. Unless not otherwise subscribed, maintainers are asked to check periodically for changes, either by hand or using the RSS feed.
-
-Portscout's first page gives the email address of the port maintainer, the number of ports the maintainer is responsible for, the number of those ports with new distfiles, and the percentage of those ports that are out-of-date. The search function allows for searching by email address for a specific maintainer, and for selecting whether only out-of-date ports are shown.
-
-Upon clicking on a maintainer's email address, a list of all of their ports is displayed, along with port category, current version number, whether or not there is a new version, when the port was last updated, and finally when it was last checked. A search function on this page allows the user to search for a specific port.
-
-Clicking on a port name in the list displays the http://freshports.org[FreshPorts] port information.
-
-[[portsmon]]
-== The FreeBSD Ports Monitoring System
-
-Another handy resource is the http://portsmon.FreeBSD.org[FreeBSD Ports Monitoring System] (also known as `portsmon`). This system comprises a database that processes information from several sources and allows it to be browsed via a web interface. Currently, the ports Problem Reports (PRs), the error logs from the build cluster, and individual files from the ports collection are used. In the future, this will be expanded to include the distfile survey, as well as other sources.
-
-To get started, use the http://portsmon.FreeBSD.org/portoverview.py[Overview of One Port] search page to find all the information about a port.
-
-This is the only resource available that maps PR entries to portnames. PR submitters do not always include the portname in their Synopsis, although we would prefer that they did. So, `portsmon` is a good place to find out whether an existing port has any PRs filed against it, any build errors, or if a new port the porter is considering creating has already been submitted.
diff --git a/documentation/content/zh-tw/books/porters-handbook/makefiles/chapter.adoc b/documentation/content/zh-tw/books/porters-handbook/makefiles/_index.adoc
similarity index 68%
rename from documentation/content/zh-tw/books/porters-handbook/makefiles/chapter.adoc
rename to documentation/content/zh-tw/books/porters-handbook/makefiles/_index.adoc
index 7e15a3648e..fbc0f6cd7b 100644
--- a/documentation/content/zh-tw/books/porters-handbook/makefiles/chapter.adoc
+++ b/documentation/content/zh-tw/books/porters-handbook/makefiles/_index.adoc
@@ -2,6 +2,8 @@
title: Chapter 5. Configuring the Makefile
prev: books/porters-handbook/slow-porting
next: books/porters-handbook/special
+description: Configuring the Makefile for FreeBSD Ports
+tags: ["makefiles", "configuring", "naming", "versions"]
---
[[makefiles]]
@@ -43,16 +45,20 @@ toc::[]
include::../../../../../shared/asciidoctor.adoc[]
endif::[]
-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#:
[[makefile-source]]
== The Original Source
-Does it live in `DISTDIR` as a standard ``gzip``ped tarball named something like [.filename]#foozolix-1.2.tar.gz#? If so, go on to the next step. If not, the distribution file format might require overriding one or more of `DISTVERSION`, `DISTNAME`, `EXTRACT_CMD`, `EXTRACT_BEFORE_ARGS`, `EXTRACT_AFTER_ARGS`, `EXTRACT_SUFX`, or `DISTFILES`.
+Does it live in `DISTDIR` as a standard ``gzip``ped tarball named something like [.filename]#foozolix-1.2.tar.gz#? If so, go on to the next step.
+If not, the distribution file format might require overriding one or more of `DISTVERSION`, `DISTNAME`, `EXTRACT_CMD`, `EXTRACT_BEFORE_ARGS`, `EXTRACT_AFTER_ARGS`, `EXTRACT_SUFX`, or `DISTFILES`.
-In the worst case, create a custom `do-extract` target to override the default. This is rarely, if ever, necessary.
+In the worst case, create a custom `do-extract` target to override the default.
+This is rarely, if ever, necessary.
[[makefile-naming]]
== Naming
@@ -62,11 +68,14 @@ The first part of the port's [.filename]#Makefile# names the port, describes its
[[makefile-portname]]
=== `PORTNAME`
-Set `PORTNAME` to the base name of the software. It is used as the base for the FreeBSD package, and for <<makefile-distname,`DISTNAME`>>.
+Set `PORTNAME` to the base name of the software.
+It is used as the base for the FreeBSD package, and for <<makefile-distname,`DISTNAME`>>.
[IMPORTANT]
====
-The package name must be unique across the entire ports tree. Make sure that the `PORTNAME` is not already in use by an existing port, and that no other port already has the same `PKGBASE`. If the name has already been used, add either <<porting-pkgnameprefix-suffix,`PKGNAMEPREFIX` or `PKGNAMESUFFIX`>>.
+The package name must be unique across the entire ports tree.
+Make sure that the `PORTNAME` is not already in use by an existing port, and that no other port already has the same `PKGBASE`.
+If the name has already been used, add either <<porting-pkgnameprefix-suffix,`PKGNAMEPREFIX` or `PKGNAMESUFFIX`>>.
====
[[makefile-versions]]
@@ -74,7 +83,9 @@ The package name must be unique across the entire ports tree. Make sure that the
Set `DISTVERSION` to the version number of the software.
-`PORTVERSION` is the version used for the FreeBSD package. It will be automatically derived from `DISTVERSION` to be compatible with FreeBSD's package versioning scheme. If the version contains _letters_, it might be needed to set `PORTVERSION` and not `DISTVERSION`.
+`PORTVERSION` is the version used for the FreeBSD package.
+It will be automatically derived from `DISTVERSION` to be compatible with FreeBSD's package versioning scheme.
+If the version contains _letters_, it might be needed to set `PORTVERSION` and not `DISTVERSION`.
[IMPORTANT]
====
@@ -85,12 +96,12 @@ From time to time, some software will use a version scheme that is not compatibl
[TIP]
====
-
-When updating a port, it is possible to use man:pkg-version[8]'s `-t` argument to check if the new version is greater or lesser than before. See <<makefile-versions-ex-pkg-version>>.
+When updating a port, it is possible to use man:pkg-version[8]'s `-t` argument to check if the new version is greater or lesser than before.
+See <<makefile-versions-ex-pkg-version>>.
====
[[makefile-versions-ex-pkg-version]]
-.Using man:pkg-version[8] to Compare Versions.
+.Using man:pkg-version[8] to Compare Versions
[example]
====
`pkg version -t` takes two versions as arguments, it will respond with `<`, `=` or `>` if the first version is less, equal, or more than the second version, respectively.
@@ -120,7 +131,8 @@ When updating a port, it is possible to use man:pkg-version[8]'s `-t` argument t
[NOTE]
****
-In here, the `a`, `b`, and `p` are used as if meaning "alpha", "beta" or "pre-release" and "patch level", but they are only letters and are sorted alphabetically, so any letter can be used, and they will be sorted appropriately.
+In here, the `a`, `b`, and `p` are used as if meaning "alpha", "beta" or "pre-release" and "patch level",
+but they are only letters and are sorted alphabetically, so any letter can be used, and they will be sorted appropriately.
****
====
@@ -174,7 +186,8 @@ DISTVERSIONPREFIX= v
DISTVERSION= 1_2_4
....
-Some of the time, projects using GitHub will use their name in their versions. For example, the version could be `nekoto-1.2-4`:
+Some of the time, projects using GitHub will use their name in their versions.
+For example, the version could be `nekoto-1.2-4`:
[.programlisting]
....
@@ -247,7 +260,8 @@ PORTNAME= nekoto
PORTVERSION= 1.2p4
....
-In this case, using `DISTVERSION` is not possible because it would generate a version of `1.2.p4` which would be before `1.2` and not after. man:pkg-version[8] will verify this:
+In this case, using `DISTVERSION` is not possible because it would generate a version of `1.2.p4` which would be before `1.2` and not after.
+man:pkg-version[8] will verify this:
[source,shell]
....
@@ -269,9 +283,11 @@ For some more advanced examples of setting `PORTVERSION`, when the software's ve
[[makefile-portrevision]]
==== `PORTREVISION`
-`PORTREVISION` is a monotonically increasing value which is reset to 0 with every increase of `DISTVERSION`, typically every time there is a new official vendor release. If `PORTREVISION` is non-zero, the value is appended to the package name. Changes to `PORTREVISION` are used by automated tools like man:pkg-version[8] to determine that a new package is available.
+`PORTREVISION` is a monotonically increasing value which is reset to 0 with every increase of `DISTVERSION`, typically every time there is a new official vendor release. If `PORTREVISION` is non-zero, the value is appended to the package name.
+Changes to `PORTREVISION` are used by automated tools like man:pkg-version[8] to determine that a new package is available.
-`PORTREVISION` must be increased each time a change is made to the port that changes the generated package in any way. That includes changes that only affect a package built with non-default <<makefile-options,options>>.
+`PORTREVISION` must be increased each time a change is made to the port that changes the generated package in any way.
+That includes changes that only affect a package built with non-default <<makefile-options,options>>.
Examples of when `PORTREVISION` must be bumped:
@@ -288,22 +304,28 @@ Examples of changes which do not require a `PORTREVISION` bump:
* Trivial patches to the distfile such as correction of typos, which are not important enough that users of the package have to go to the trouble of upgrading.
* Build fixes which cause a package to become compilable where it was previously failing. As long as the changes do not introduce any functional change on any other platforms on which the port did previously build. Since `PORTREVISION` reflects the content of the package, if the package was not previously buildable then there is no need to increase `PORTREVISION` to mark a change.
-A rule of thumb is to decide whether a change committed to a port is something which _some_ people would benefit from having. Either because of an enhancement, fix, or by virtue that the new package will actually work at all. Then weigh that against that fact that it will cause everyone who regularly updates their ports tree to be compelled to update. If yes, `PORTREVISION` must be bumped.
+A rule of thumb is to decide whether a change committed to a port is something which _some_ people would benefit from having.
+Either because of an enhancement, fix, or by virtue that the new package will actually work at all.
+Then weigh that against that fact that it will cause everyone who regularly updates their ports tree to be compelled to update.
+If yes, `PORTREVISION` must be bumped.
[NOTE]
====
-People using binary packages will _never_ see the update if `PORTREVISION` is not bumped. Without increasing `PORTREVISION`, the package builders have no way to detect the change and thus, will not rebuild the package.
+People using binary packages will _never_ see the update if `PORTREVISION` is not bumped.
+Without increasing `PORTREVISION`, the package builders have no way to detect the change and thus, will not rebuild the package.
====
[[makefile-portepoch]]
==== `PORTEPOCH`
-From time to time a software vendor or FreeBSD porter will do something silly and release a version of their software which is actually numerically less than the previous version. An example of this is a port which goes from foo-20000801 to foo-1.0 (the former will be incorrectly treated as a newer version since 20000801 is a numerically greater value than 1).
+From time to time a software vendor or FreeBSD porter will do something silly and release a version of their software which is actually numerically less than the previous version.
+An example of this is a port which goes from foo-20000801 to foo-1.0 (the former will be incorrectly treated as a newer version since 20000801 is a numerically greater value than 1).
[TIP]
====
-
-The results of version number comparisons are not always obvious. `pkg version` (see man:pkg-version[8]) can be used to test the comparison of two version number strings. For example:
+The results of version number comparisons are not always obvious.
+`pkg version` (see man:pkg-version[8]) can be used to test the comparison of two version number strings.
+For example:
[source,shell]
....
@@ -314,13 +336,21 @@ The results of version number comparisons are not always obvious. `pkg version`
The `>` output indicates that version 0.031 is considered greater than version 0.29, which may not have been obvious to the porter.
====
-In situations such as this, `PORTEPOCH` must be increased. If `PORTEPOCH` is nonzero it is appended to the package name as described in section 0 above. `PORTEPOCH` must never be decreased or reset to zero, because that would cause comparison to a package from an earlier epoch to fail. For example, the package would not be detected as out of date. The new version number, `1.0,1` in the above example, is still numerically less than the previous version, 20000801, but the `,1` suffix is treated specially by automated tools and found to be greater than the implied suffix `,0` on the earlier package.
+In situations such as this, `PORTEPOCH` must be increased.
+If `PORTEPOCH` is nonzero it is appended to the package name as described in section 0 above.
+`PORTEPOCH` must never be decreased or reset to zero, because that would cause comparison to a package from an earlier epoch to fail.
+For example, the package would not be detected as out of date.
+The new version number, `1.0,1` in the above example, is still numerically less than the previous version, 20000801, but the `,1` suffix is treated specially by automated tools and found to be greater than the implied suffix `,0` on the earlier package.
-Dropping or resetting `PORTEPOCH` incorrectly leads to no end of grief. If the discussion above was not clear enough, please consult the {freebsd-ports}.
+Dropping or resetting `PORTEPOCH` incorrectly leads to no end of grief.
+If the discussion above was not clear enough, please consult the {freebsd-ports}.
-It is expected that `PORTEPOCH` will not be used for the majority of ports, and that sensible use of `DISTVERSION`, or that use `PORTVERSION` carefully, can often preempt it becoming necessary if a future release of the software changes the version structure. However, care is needed by FreeBSD porters when a vendor release is made without an official version number - such as a code "snapshot" release. The temptation is to label the release with the release date, which will cause problems as in the example above when a new "official" release is made.
+It is expected that `PORTEPOCH` will not be used for the majority of ports, and that sensible use of `DISTVERSION`, or that use `PORTVERSION` carefully, can often preempt it becoming necessary if a future release of the software changes the version structure.
+However, care is needed by FreeBSD porters when a vendor release is made without an official version number - such as a code "snapshot" release.
+The temptation is to label the release with the release date, which will cause problems as in the example above when a new "official" release is made.
-For example, if a snapshot release is made on the date `20000917`, and the previous version of the software was version `1.2`, do not use `20000917` for `DISTVERSION`. The correct way is a `DISTVERSION` of `1.2.20000917`, or similar, so that the succeeding release, say `1.3`, is still a numerically greater value.
+For example, if a snapshot release is made on the date `20000917`, and the previous version of the software was version `1.2`, do not use `20000917` for `DISTVERSION`.
+The correct way is a `DISTVERSION` of `1.2.20000917`, or similar, so that the succeeding release, say `1.3`, is still a numerically greater value.
[[makefile-portrevision-example]]
==== Example of `PORTREVISION` and `PORTEPOCH` Usage
@@ -335,7 +365,8 @@ DISTVERSION= 0.10
`PKGNAME` becomes `gtkmumble-0.10`.
-A security hole is discovered which requires a local FreeBSD patch. `PORTREVISION` is bumped accordingly.
+A security hole is discovered which requires a local FreeBSD patch.
+`PORTREVISION` is bumped accordingly.
[.programlisting]
....
@@ -346,7 +377,9 @@ PORTREVISION= 1
`PKGNAME` becomes `gtkmumble-0.10_1`
-A new version is released by the vendor, numbered `0.2` (it turns out the author actually intended `0.10` to actually mean `0.1.0`, not "what comes after 0.9" - oops, too late now). Since the new minor version `2` is numerically less than the previous version `10`, `PORTEPOCH` must be bumped to manually force the new package to be detected as "newer". Since it is a new vendor release of the code, `PORTREVISION` is reset to 0 (or removed from the [.filename]#Makefile#).
+A new version is released by the vendor, numbered `0.2` (it turns out the author actually intended `0.10` to actually mean `0.1.0`, not "what comes after 0.9" - oops, too late now).
+Since the new minor version `2` is numerically less than the previous version `10`, `PORTEPOCH` must be bumped to manually force the new package to be detected as "newer".
+Since it is a new vendor release of the code, `PORTREVISION` is reset to 0 (or removed from the [.filename]#Makefile#).
[.programlisting]
....
@@ -357,7 +390,8 @@ PORTEPOCH= 1
`PKGNAME` becomes `gtkmumble-0.2,1`
-The next release is 0.3. Since `PORTEPOCH` never decreases, the version variables are now:
+The next release is 0.3.
+Since `PORTEPOCH` never decreases, the version variables are now:
[.programlisting]
....
@@ -370,47 +404,69 @@ PORTEPOCH= 1
[NOTE]
====
-If `PORTEPOCH` were reset to `0` with this upgrade, someone who had installed the `gtkmumble-0.10_1` package would not detect the `gtkmumble-0.3` package as newer, since `3` is still numerically less than `10`. Remember, this is the whole point of `PORTEPOCH` in the first place.
+If `PORTEPOCH` were reset to `0` with this upgrade, someone who had installed the `gtkmumble-0.10_1` package would not detect the `gtkmumble-0.3` package as newer, since `3` is still numerically less than `10`.
+Remember, this is the whole point of `PORTEPOCH` in the first place.
====
[[porting-pkgnameprefix-suffix]]
=== `PKGNAMEPREFIX` and `PKGNAMESUFFIX`
-Two optional variables, `PKGNAMEPREFIX` and `PKGNAMESUFFIX`, are combined with `PORTNAME` and `PORTVERSION` to form `PKGNAME` as `${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}`. Make sure this conforms to our <<porting-pkgname,guidelines for a good package name>>. In particular, the use of a hyphen (`-`) in `PORTVERSION` is _not_ allowed. Also, if the package name has the _language-_ or the _-compiled.specifics_ part (see below), use `PKGNAMEPREFIX` and `PKGNAMESUFFIX`, respectively. Do not make them part of `PORTNAME`.
+Two optional variables, `PKGNAMEPREFIX` and `PKGNAMESUFFIX`, are combined with `PORTNAME` and `PORTVERSION` to form `PKGNAME` as `${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}`.
+Make sure this conforms to our <<porting-pkgname,guidelines for a good package name>>.
+In particular, the use of a hyphen (`-`) in `PORTVERSION` is _not_ allowed.
+Also, if the package name has the _language-_ or the _-compiled.specifics_ part (see below), use `PKGNAMEPREFIX` and `PKGNAMESUFFIX`, respectively.
+Do not make them part of `PORTNAME`.
[[porting-pkgname]]
=== Package Naming Conventions
-These are the conventions to follow when naming packages. This is to make the package directory easy to scan, as there are already thousands of packages and users are going to turn away if they hurt their eyes!
+These are the conventions to follow when naming packages.
+This is to make the package directory easy to scan, as there are already thousands of packages and users are going to turn away if they hurt their eyes!
Package names take the form of [.filename]#language_region-name-compiled.specifics-version.numbers#.
-The package name is defined as `${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}`. Make sure to set the variables to conform to that format.
+The package name is defined as `${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}`.
+Make sure to set the variables to conform to that format.
[[porting-pkgname-language]]
*** 10672 LINES SKIPPED ***