17 files changed, 470 insertions, 276 deletions

diff --git a/documentation/content/zh-cn/books/porters-handbook/_index.adoc b/documentation/content/zh-cn/books/porters-handbook/_index.adoc
index b4a362601b..75e4312f38 100644
--- a/documentation/content/zh-cn/books/porters-handbook/_index.adoc
+++ b/documentation/content/zh-cn/books/porters-handbook/_index.adoc
@@ -5,79 +5,42 @@ authors:
   - author: FreeBSD 中文计划
 copyright: 2000-2020 The FreeBSD Documentation Project
 trademarks: ["freebsd", "sun", "unix", "general"]
-releaseinfo: "$FreeBSD$" 
+next: books/porters-handbook/why-port
+add_single_page_link: true
+showBookMenu: true
+weight: 0
+path: "/books/porters-handbook/"
 ---
 
 = FreeBSD Porter 手册
 :doctype: book
 :toc: macro
-:toclevels: 2
+:toclevels: 1
 :icons: font
-:xrefstyle: basic
-:relfileprefix: ../
-:outfilesuffix:
 :sectnums:
 :sectnumlevels: 6
 :partnums:
 :source-highlighter: rouge
 :experimental:
-:skip-front-matter:
-:toc-title: 目录
-:part-signifier: 部分
-:appendix-caption: 附录
-:table-caption: 表
-:figure-caption: 图
-:example-caption: 例
+:images-path: books/porters-handbook/
 
-ifeval::["{backend}" == "html5"]
-include::shared/mirrors.adoc[]
+ifdef::env-beastie[]
+ifdef::backend-html5[]
 include::shared/authors.adoc[]
+include::shared/mirrors.adoc[]
 include::shared/releases.adoc[]
-include::shared/zh-cn/mailing-lists.adoc[]
-include::shared/zh-cn/teams.adoc[]
-include::shared/zh-cn/urls.adoc[]
-:chapters-path: content/zh-cn/books/porters-handbook/
+include::shared/attributes/attributes-{{% lang %}}.adoc[]
+include::shared/{{% lang %}}/teams.adoc[]
+include::shared/{{% lang %}}/mailing-lists.adoc[]
+include::shared/{{% lang %}}/urls.adoc[]
+endif::[]
+ifdef::backend-pdf,backend-epub3[]
+include::../../../../../shared/asciidoctor.adoc[]
 endif::[]
-
-ifeval::["{backend}" == "pdf"]
-include::../../../../shared/mirrors.adoc[]
-include::../../../../shared/authors.adoc[]
-include::../../../../shared/releases.adoc[]
-include::../../../../shared/zh-cn/mailing-lists.adoc[]
-include::../../../../shared/zh-cn/teams.adoc[]
-include::../../../../shared/zh-cn/urls.adoc[]
-:chapters-path:
 endif::[]
 
-ifeval::["{backend}" == "epub3"]
-include::../../../../shared/mirrors.adoc[]
-include::../../../../shared/authors.adoc[]
-include::../../../../shared/releases.adoc[]
-include::../../../../shared/zh-cn/mailing-lists.adoc[]
-include::../../../../shared/zh-cn/teams.adoc[]
-include::../../../../shared/zh-cn/urls.adoc[]
-:chapters-path:
+ifndef::env-beastie[]
+include::../../../../../shared/asciidoctor.adoc[]
 endif::[]
 
 '''
-
-toc::[]
-
-include::{chapters-path}toc-tables.adoc[]
-
-include::{chapters-path}toc-examples.adoc[]
-
-include::{chapters-path}why-port/chapter.adoc[leveloffset=+1, lines=7..24;35..-1]
-include::{chapters-path}own-port/chapter.adoc[leveloffset=+1, lines=7..24;35..-1]
-include::{chapters-path}quick-porting/chapter.adoc[leveloffset=+1, lines=7..24;35..-1]
-include::{chapters-path}slow/chapter.adoc[leveloffset=+1, lines=7..24;35..-1]
-include::{chapters-path}makefile/chapter.adoc[leveloffset=+1, lines=7..24;35..-1]
-include::{chapters-path}special/chapter.adoc[leveloffset=+1, lines=7..24;35..-1]
-include::{chapters-path}plist/chapter.adoc[leveloffset=+1, lines=7..24;35..-1]
-include::{chapters-path}pkg-files/chapter.adoc[leveloffset=+1, lines=7..24;35..-1]
-include::{chapters-path}testing/chapter.adoc[leveloffset=+1, lines=7..24;35..-1]
-include::{chapters-path}port-upgrading/chapter.adoc[leveloffset=+1, lines=7..24;35..-1]
-include::{chapters-path}security/chapter.adoc[leveloffset=+1, lines=7..24;35..-1]
-include::{chapters-path}porting-dads/chapter.adoc[leveloffset=+1, lines=7..24;35..-1] 
-include::{chapters-path}porting-samplem/chapter.adoc[leveloffset=+1, lines=7..24;35..-1] 
-include::{chapters-path}keeping-up/chapter.adoc[leveloffset=+1, lines=6..23;34..-1] 
diff --git a/documentation/content/zh-cn/books/porters-handbook/book.adoc b/documentation/content/zh-cn/books/porters-handbook/book.adoc
new file mode 100644
index 0000000000..5a95059ce3
--- /dev/null
+++ b/documentation/content/zh-cn/books/porters-handbook/book.adoc
@@ -0,0 +1,63 @@
+---
+title: FreeBSD Porter 手册
+authors: 
+  - author: The FreeBSD Documentation Project
+  - author: FreeBSD 中文计划
+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}why-port/_index.adoc[leveloffset=+1]
+include::{chapters-path}own-port/_index.adoc[leveloffset=+1]
+include::{chapters-path}quick-porting/_index.adoc[leveloffset=+1]
+include::{chapters-path}slow/_index.adoc[leveloffset=+1]
+include::{chapters-path}makefile/_index.adoc[leveloffset=+1]
+include::{chapters-path}special/_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}port-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}keeping-up/_index.adoc[leveloffset=+1]
diff --git a/documentation/content/zh-cn/books/porters-handbook/chapters-order.adoc b/documentation/content/zh-cn/books/porters-handbook/chapters-order.adoc
deleted file mode 100644
index 1063d23868..0000000000
--- a/documentation/content/zh-cn/books/porters-handbook/chapters-order.adoc
+++ /dev/null
@@ -1,14 +0,0 @@
-why-port/chapter.adoc
-own-port/chapter.adoc
-quick-porting/chapter.adoc
-slow/chapter.adoc
-makefile/chapter.adoc
-special/chapter.adoc
-plist/chapter.adoc
-pkg-files/chapter.adoc
-testing/chapter.adoc
-port-upgrading/chapter.adoc
-security/chapter.adoc
-porting-dads/chapter.adoc 
-porting-samplem/chapter.adoc 
-keeping-up/chapter.adoc
diff --git a/documentation/content/zh-cn/books/porters-handbook/keeping-up/chapter.adoc b/documentation/content/zh-cn/books/porters-handbook/keeping-up/_index.adoc
index c462303c33..1c9791cf47 100644
--- a/documentation/content/zh-cn/books/porters-handbook/keeping-up/chapter.adoc
+++ b/documentation/content/zh-cn/books/porters-handbook/keeping-up/_index.adoc
@@ -1,6 +1,9 @@
 ---
 title: 第 14 章 保持同步
 prev: books/porters-handbook/porting-samplem
+showBookMenu: true
+weight: 14
+path: "/books/porters-handbook/keeping-up/"
 ---
 
 [[keeping-up]]
@@ -10,26 +13,36 @@ prev: books/porters-handbook/porting-samplem
 :toclevels: 1
 :icons: font
 :sectnums:
+:sectnumlevels: 6
+:sectnumoffset: 14
+:partnums:
 :source-highlighter: rouge
 :experimental:
-:skip-front-matter:
-:xrefstyle: basic
-:relfileprefix: ../
-:outfilesuffix:
-:sectnumoffset: 14
-:toc-title: 目录
-:table-caption: 表
-:figure-caption: 图
-:example-caption: 例
+:images-path: books/porters-handbook/
 
-include::shared/mirrors.adoc[]
+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/zh-cn/mailing-lists.adoc[]
-include::shared/zh-cn/teams.adoc[]
-include::shared/zh-cn/urls.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::[]
 
 FreeBSD 的 Ports Collection 在持续地进行修改。 这里提供了一些关于如何保持同步的信息。
 
diff --git a/documentation/content/zh-cn/books/porters-handbook/makefile/chapter.adoc b/documentation/content/zh-cn/books/porters-handbook/makefile/_index.adoc
index 53c4a17bfd..4e62f674ce 100644
--- a/documentation/content/zh-cn/books/porters-handbook/makefile/chapter.adoc
+++ b/documentation/content/zh-cn/books/porters-handbook/makefile/_index.adoc
@@ -2,6 +2,9 @@
 title: 第 5 章 配置 Makefile
 prev: books/porters-handbook/slow
 next: books/porters-handbook/special
+showBookMenu: true
+weight: 5
+path: "/books/porters-handbook/makefile/"
 ---
 
 [[makefile]]
@@ -11,26 +14,36 @@ next: books/porters-handbook/special
 :toclevels: 1
 :icons: font
 :sectnums:
+:sectnumlevels: 6
+:sectnumoffset: 5
+:partnums:
 :source-highlighter: rouge
 :experimental:
-:skip-front-matter:
-:xrefstyle: basic
-:relfileprefix: ../
-:outfilesuffix:
-:sectnumoffset: 5
-:toc-title: 目录
-:table-caption: 表
-:figure-caption: 图
-:example-caption: 例
+:images-path: books/porters-handbook/
 
-include::shared/mirrors.adoc[]
+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/zh-cn/mailing-lists.adoc[]
-include::shared/zh-cn/teams.adoc[]
-include::shared/zh-cn/urls.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::[]
 
 配置 [.filename]#Makefile# 是相当简单的， 我们在此建议您在开始之前看一下现有的例子。 在这份手册里也有一个 <<porting-samplem,Makefile例子>>， 照着里面变量的顺序来写能使得您的 port 更容易地被其它人看懂。
 
@@ -682,7 +695,7 @@ _-compiled.specifics_ 部分应该通过 `PKGNAMESUFFIX` 变量来设置。
 
 我们目前的做法是避免建立新的物理分类， 除非有非常多的 port 应被归入这一分类， 或者 port 属于某一特定的小团体 (例如， 与某种人类语言相关)， 或两者皆是。
 
-这样做的原因是这类修改会让 committer 和用户都不得不进行 link:{committers-guide}#ports[许多工作] 来在 Ports Collection 进行或追踪修改。 此外， 提议新的分类通常都会引起争论。 (可能这是因为关于某个分类是否 "太大" 一直没有非常一致的意见的缘故， 另一方面， 分类是否能够能够有助于浏览 (以及多少个分类是合适的)， 等等， 也都是问题。)
+这样做的原因是这类修改会让 committer 和用户都不得不进行 extref:{committers-guide}[许多工作, ports] 来在 Ports Collection 进行或追踪修改。 此外， 提议新的分类通常都会引起争论。 (可能这是因为关于某个分类是否 "太大" 一直没有非常一致的意见的缘故， 另一方面， 分类是否能够能够有助于浏览 (以及多少个分类是合适的)， 等等， 也都是问题。)
 
 下面是具体的步骤：
 
@@ -699,7 +712,7 @@ _-compiled.specifics_ 部分应该通过 `PKGNAMESUFFIX` 变量来设置。
 ** (此外， 作为一项加分因素， 您还可以按照 Committer 指南所介绍的流程， 提供一些其它需要修改的文件。)
 
 . 由于这是一项影响 ports 基础设施的变动， 它不仅涉及 repo-copy 的使用， 而且也可能会影响联编集群的回归测试操作， 因此这类 PR 应分派给 {portmgr}。
-. 如果这一 PR 得到批准， 某个 committer 将按照在 link:{committers-guide}#PORTS[ Committer 指南] 中所介绍的步骤来完成余下的工作。
+. 如果这一 PR 得到批准， 某个 committer 将按照在 extref:{committers-guide}[ Committer 指南, ports] 中所介绍的步骤来完成余下的工作。
 ====
 
 提议新的虚拟分类和上述过程类似， 但会容易许多， 因为不需要实际地移动任何 port。 这种情况下， PR 应附带的补丁， 就只需要修改影响到的 port 的 Makefile， 以便在其中的 `CATEGORIES` 中加入新的分类了。
@@ -1145,7 +1158,7 @@ PATCHFILES=     patch1:test
 ** `fetch-list`： 和旧式的 `fetch-list` 类似， 但以同 `do-fetch` 相似的方式处理组。
 ** `master-sites` 和 `patch-sites`： (与旧版本不兼容) 仅返回组 `DEFAULT` 的元素； 事实上， 它们会执行 `master-sites-default` 和 `patch-sites-default` 这两个 target。
 + 
-更进一步， 使用 `master-sites-all` 或 `patch-sites-all` 这两个 target 之一， 要比直接检查 `MASTER_SITES` 或 `PATCH_SITES` 更好。 此外， 未来版本可能不再保证直接检查能够正确工作。 请参见 <<porting-master-sites-n-new-port-targets-master-sites-all>> 以了解关于这些新 target 的更多技术细节。
+更进一步， 使用 `master-sites-all` 或 `patch-sites-all` 这两个 target 之一， 要比直接检查 `MASTER_SITES` 或 `PATCH_SITES` 更好。 此外， 未来版本可能不再保证直接检查能够正确工作。 请参见 <<porting-master-sites-n-new-port-targets-master-sites-all, B>> 以了解关于这些新 target 的更多技术细节。
 
 . port 中的新 target
 .. 一系列 `master-sites-_n_` 和 `patch-sites-_n_` target 可以分别用来列出 `MASTER_SITES` 和 `PATCH_SITES` 中的 _n_ 组的内容。 例如， `master-sites-DEFAULT` 和 `patch-sites-DEFAULT` 都会返回 `DEFAULT` 组的内容， 而 `master-sites-test` 和 `patch-sites-test` 则返回 `test` 组的内容， 等等。
@@ -1380,7 +1393,7 @@ USE_GCC=3.4
 |此 port 需要使用某一特定版本的 `gcc` 才能完成编译。 可以使用类似 `3.4` 这样的值来精确指定版本。 如果希望使用不低于某一版本的编译器， 则可以用 `3.4+` 这样的形式。 如果与所希望的版本吻合， 则将使用基本系统中所提供的 `gcc`， 反之， 系统会从 ports 中安装所希望版本的 `gcc`， 并调整 `CC` 以及 `CXX` 变量的设置。
 |===
 
-与 gmake 和 [.filename]#configure# 脚本有关的变量在 <<building>> 中进行了介绍， 而 autoconf、 automake 以及 libtool 的介绍则可以在 <<using-autotools>> 找到。 <<using-perl>> 介绍了与 Perl 有关的的变量。 <<using-x11>> 中列出了关于 X11 的变量。 关于 GNOME 的变量在 <<using-gnome>>， 而关于 KDE 的则在 <<using-kde>>。 <<using-java>> 讲述了和 Java 有关的变量， 而 <<using-php>> 则包含了关于 Apache、 PHP 以及 PEAR 的介绍性信息。 关于 Python， 在 <<using-python>> 进行了讨论， 而关于 Ruby 的介绍， 则可以在 <<using-ruby>> 中找到。 <<using-sdl>> 提供了用于 SDL 应用程序的变量介绍， 最后， <<using-xfce>> 包含了关于 Xfce 的信息。
+与 gmake 和 [.filename]#configure# 脚本有关的变量在 crossref:special[building, 联编机制] 中进行了介绍， 而 autoconf、 automake 以及 libtool 的介绍则可以在 crossref:special[using-autotools, 利用 GNU autotools] 找到。 crossref:special[using-perl, 使用 perl] 介绍了与 Perl 有关的的变量。 crossref:special[using-x11, 使用 X11] 中列出了关于 X11 的变量。 关于 GNOME 的变量在 crossref:special[using-gnome, 使用 GNOME]， 而关于 KDE 的则在 crossref:special[using-kde, 使用 KDE]。 crossref:special[using-java, 使用 Java] 讲述了和 Java 有关的变量， 而 crossref:special[using-php, "Web 应用， Apache 和 PHP"] 则包含了关于 Apache、 PHP 以及 PEAR 的介绍性信息。 关于 Python， 在 crossref:special[using-python, 使用 Python] 进行了讨论， 而关于 Ruby 的介绍， 则可以在 crossref:special[using-ruby, 使用 Ruby] 中找到。 crossref:special[using-sdl, 使用 SDL] 提供了用于 SDL 应用程序的变量介绍， 最后， crossref:special[using-xfce, 使用 Xfce] 包含了关于 Xfce 的信息。
 
 === 在依赖关系中指定最低版本
 
@@ -1733,7 +1746,7 @@ NO_WRKSUBDIR= yes
 
 [NOTE]
 ====
-这些用于描述冲突的变量会自动地设置 `IGNORE`， 后者的完整介绍， 可以在 <<dads-noinstall>> 找到。
+这些用于描述冲突的变量会自动地设置 `IGNORE`， 后者的完整介绍， 可以在 crossref:porting-dads[dads-noinstall, 使用 `BROKEN`、 `FORBIDDEN` 或 `IGNORE` 阻止用户安装 port] 找到。
 ====
 
 在删去相互冲突的 port 时， 建议将 `CONFLICTS` 保留几个月， 以便让那些不经常更新系统的用户能够看到。
diff --git a/documentation/content/zh-cn/books/porters-handbook/own-port/chapter.adoc b/documentation/content/zh-cn/books/porters-handbook/own-port/_index.adoc
index 7fd92bd1e2..3f09d54bcc 100644
--- a/documentation/content/zh-cn/books/porters-handbook/own-port/chapter.adoc
+++ b/documentation/content/zh-cn/books/porters-handbook/own-port/_index.adoc
@@ -2,6 +2,9 @@
 title: 第 2 章 自行制作新 port
 prev: books/porters-handbook/why-port
 next: books/porters-handbook/quick-porting
+showBookMenu: true
+weight: 2
+path: "/books/porters-handbook/own-port/"
 ---
 
 [[own-port]]
@@ -11,30 +14,40 @@ next: books/porters-handbook/quick-porting
 :toclevels: 1
 :icons: font
 :sectnums:
+:sectnumlevels: 6
+:sectnumoffset: 2
+:partnums:
 :source-highlighter: rouge
 :experimental:
-:skip-front-matter:
-:xrefstyle: basic
-:relfileprefix: ../
-:outfilesuffix:
-:sectnumoffset: 2
-:toc-title: 目录
-:table-caption: 表
-:figure-caption: 图
-:example-caption: 例
+:images-path: books/porters-handbook/
 
-include::shared/mirrors.adoc[]
+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/zh-cn/mailing-lists.adoc[]
-include::shared/zh-cn/teams.adoc[]
-include::shared/zh-cn/urls.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::[]
 
 那么， 您有兴趣创建自己的 port 或升级现有的 port？ 太好了。
 
-下面的内容将会提供一些创建FreeBSD port的指导。 如果想升级一个现有的 port， 那么您应该在看完这些内容并阅读 <<port-upgrading>>。
+下面的内容将会提供一些创建FreeBSD port的指导。 如果想升级一个现有的 port， 那么您应该在看完这些内容并阅读 crossref:port-upgrading[port-upgrading,升级一个 port]。
 
 因为这份文档不是十分详细， 您还应该再参考一下 [.filename]#/usr/ports/Mk/bsd.port.mk#， 所有 port 的 Makefile 文件都会包含它。 即使不是每天都去摆弄 Makefile， 您也会从那个文件里面获得很多知识， 里面的注释非常详细。 还有要补充一下，如果您有其它的问题， 可以给link:{freebsd-ports} 这个 mailing list 发信。
 
diff --git a/documentation/content/zh-cn/books/porters-handbook/pkg-files/chapter.adoc b/documentation/content/zh-cn/books/porters-handbook/pkg-files/_index.adoc
index 670efa4734..e44206577f 100644
--- a/documentation/content/zh-cn/books/porters-handbook/pkg-files/chapter.adoc
+++ b/documentation/content/zh-cn/books/porters-handbook/pkg-files/_index.adoc
@@ -2,6 +2,9 @@
 title: 第 8 章 pkg-* 文件
 prev: books/porters-handbook/plist
 next: books/porters-handbook/testing
+showBookMenu: true
+weight: 8
+path: "/books/porters-handbook/pkg-files/"
 ---
 
 [[pkg-files]]
@@ -11,26 +14,36 @@ next: books/porters-handbook/testing
 :toclevels: 1
 :icons: font
 :sectnums:
+:sectnumlevels: 6
+:sectnumoffset: 8
+:partnums:
 :source-highlighter: rouge
 :experimental:
-:skip-front-matter:
-:xrefstyle: basic
-:relfileprefix: ../
-:outfilesuffix:
-:sectnumoffset: 8
-:toc-title: 目录
-:table-caption: 表
-:figure-caption: 图
-:example-caption: 例
+:images-path: books/porters-handbook/
 
-include::shared/mirrors.adoc[]
+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/zh-cn/mailing-lists.adoc[]
-include::shared/zh-cn/teams.adoc[]
-include::shared/zh-cn/urls.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::[]
 
 前面有一些没有提及的关于 [.filename]#pkg-*# 文件的技巧， 它们可以方便地完成许多任务。
 
diff --git a/documentation/content/zh-cn/books/porters-handbook/plist/chapter.adoc b/documentation/content/zh-cn/books/porters-handbook/plist/_index.adoc
index ce7378c451..ba3c579e61 100644
--- a/documentation/content/zh-cn/books/porters-handbook/plist/chapter.adoc
+++ b/documentation/content/zh-cn/books/porters-handbook/plist/_index.adoc
@@ -2,6 +2,9 @@
 title: 第 7 章 高级 pkg-plist 用法
 prev: books/porters-handbook/special
 next: books/porters-handbook/pkg-files
+showBookMenu: true
+weight: 7
+path: "/books/porters-handbook/plist/"
 ---
 
 [[plist]]
@@ -11,26 +14,36 @@ next: books/porters-handbook/pkg-files
 :toclevels: 1
 :icons: font
 :sectnums:
+:sectnumlevels: 6
+:sectnumoffset: 7
+:partnums:
 :source-highlighter: rouge
 :experimental:
-:skip-front-matter:
-:xrefstyle: basic
-:relfileprefix: ../
-:outfilesuffix:
-:sectnumoffset: 7
-:toc-title: 目录
-:table-caption: 表
-:figure-caption: 图
-:example-caption: 例
+:images-path: books/porters-handbook/
 
-include::shared/mirrors.adoc[]
+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/zh-cn/mailing-lists.adoc[]
-include::shared/zh-cn/teams.adoc[]
-include::shared/zh-cn/urls.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::[]
 
 [[plist-sub]]
 == 根据 make 变量对 [.filename]#pkg-plist# 进行修改
diff --git a/documentation/content/zh-cn/books/porters-handbook/port-upgrading/chapter.adoc b/documentation/content/zh-cn/books/porters-handbook/port-upgrading/_index.adoc
index b5fb7f9070..b66c469a61 100644
--- a/documentation/content/zh-cn/books/porters-handbook/port-upgrading/chapter.adoc
+++ b/documentation/content/zh-cn/books/porters-handbook/port-upgrading/_index.adoc
@@ -2,6 +2,9 @@
 title: 第 10 章 升级一个 port
 prev: books/porters-handbook/testing
 next: books/porters-handbook/security
+showBookMenu: true
+weight: 10
+path: "/books/porters-handbook/port-upgrading/"
 ---
 
 [[port-upgrading]]
@@ -11,28 +14,38 @@ next: books/porters-handbook/security
 :toclevels: 1
 :icons: font
 :sectnums:
+:sectnumlevels: 6
+:sectnumoffset: 10
+:partnums:
 :source-highlighter: rouge
 :experimental:
-:skip-front-matter:
-:xrefstyle: basic
-:relfileprefix: ../
-:outfilesuffix:
-:sectnumoffset: 10
-:toc-title: 目录
-:table-caption: 表
-:figure-caption: 图
-:example-caption: 例
+:images-path: books/porters-handbook/
 
-include::shared/mirrors.adoc[]
+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/zh-cn/mailing-lists.adoc[]
-include::shared/zh-cn/teams.adoc[]
-include::shared/zh-cn/urls.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::[]
 
-如果您发现某个 port 相对原作者所发布的版本已经过时， 则首先需要确认的是您的 port 是最新的。 您可以在 FreeBSD FTP 镜像的 [.filename]#ports/ports-current# 目录中找到它们。 但是， 如果您正在使用较多的 port， 则可能使用 CVSup 来保持 Ports Collection 最新更为简单， 这在 link:{handbook}#CVSUP-CONFIG[使用手册] 中进行了介绍。 此外， 这样做也有助于保持 port 依赖关系的正确性。
+如果您发现某个 port 相对原作者所发布的版本已经过时， 则首先需要确认的是您的 port 是最新的。 您可以在 FreeBSD FTP 镜像的 [.filename]#ports/ports-current# 目录中找到它们。 但是， 如果您正在使用较多的 port， 则可能使用 CVSup 来保持 Ports Collection 最新更为简单， 这在 extref:{handbook}[使用手册, CVSUP-CONFIG] 中进行了介绍。 此外， 这样做也有助于保持 port 依赖关系的正确性。
 
 下一步是检查是否已经有在等待的更新。 要完成这项工作， 可以采用下列两种方法之一。 有一个用于搜索 http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query[ FreeBSD 问题报告 (PR) 数据库] (也被称作 `GNATS`)。 在下拉框中选择 `ports`， 然后输入 port 的名字。
 
@@ -53,11 +66,11 @@ toc::[]
 
 为了简化常用的补丁文件操作， 您可以使用 [.filename]#/usr/ports/Tools/scripts/patchtool.py#。 使用之前， 请首先阅读 [.filename]#/usr/ports/Tools/scripts/README.patchtool#。
 
-如果 port 目前还无人维护， 而且您自己经常使用它， 请考虑自荐为它的维护者。 FreeBSD 有超过 4000 个没有维护者的 port， 而这正是最需要志愿人员的领域。 (要了解关于维护者的任务描述， 请参见 link:{developers-handbook}#POLICIES-MAINTAINER[ 开发手册中的相关部分]。)
+如果 port 目前还无人维护， 而且您自己经常使用它， 请考虑自荐为它的维护者。 FreeBSD 有超过 4000 个没有维护者的 port， 而这正是最需要志愿人员的领域。 (要了解关于维护者的任务描述， 请参见 extref:{developers-handbook}[开发手册中的相关部分, POLICIES-MAINTAINER]。)
 
 将 diff 发送给我们的最佳方式是通过 man:send-pr[1] (category 一栏写 `ports`)。 如果您正维护那个 port， 请务必在 synopsis 的开头写上 `[maintainer update]`， 并将您的 PR 的 "Class" 设置为 `maintainer-update`。 反之， 您的 PR 的 "Class" 就应该是 `change-request`。 请在信中逐个提及每一个删除或增加的文件， 因为这些都必须明确地在使用 man:cvs[1] 进行 commit 时明确地指定。 如果 diff 超过了 20K， 请考虑压缩并对其进行 uuencode； 否则， 简单地将其原样加入 PR 即可。
 
-在您 man:send-pr[1] 之前， 请再次阅读 Problem Reports 一文中的 link:{problem-reports}#pr-writing/[ 如何撰写问题报告] 小节； 它给出了丰富的关于如何撰写更好的问题报告的介绍。
+在您 man:send-pr[1] 之前， 请再次阅读 Problem Reports 一文中的 extref:{problem-reports}[如何撰写问题报告, pr-writing] 小节； 它给出了丰富的关于如何撰写更好的问题报告的介绍。
 
 [IMPORTANT]
 ====
@@ -69,7 +82,7 @@ toc::[]
 再次强调， 请使用 man:diff[1] 而非 man:shar[1] 来发送现有 port 的更新！ 这可以帮助 ports committer 理解需要修改的内容。
 ====
 
-现在您已经了解了所需的所有操作， 您可能会像要阅读在 <<keeping-up>> 中关于如何保持最新的描述。
+现在您已经了解了所需的所有操作， 您可能会像要阅读在 crossref:keeping-up[keeping-up, 保持同步] 中关于如何保持最新的描述。
 
 [[cvs-diff]]
 == 使用 CVS 制作补丁
@@ -85,7 +98,7 @@ toc::[]
 
 <.> 当然， 这可以是您指定的任意目录； 联编 port 并不局限于 [.filename]#/usr/ports/# 的子目录。
 
-<.> R_CVSROOT 是任何一个公共的 cvs 镜像服务器， 您可以在 link:{handbook}#cvsup/[FreeBSD 使用手册] 中挑选一个。
+<.> R_CVSROOT 是任何一个公共的 cvs 镜像服务器， 您可以在 extref:{handbook}mirrors/[FreeBSD 使用手册, cvsup] 中挑选一个。
 
 <.> pdnsd 是 port 的模块名字； 通常说来它和 port 的名字一样， 不过也有些例外， 特别是那些本地化类别 (package:german/selfhtml[] 对应的模块名字是 de-selfhtml)； 您可以通过 link:https://www.FreeBSD.org/cgi/cvsweb.cgi/ports[cvsweb 界面] 查询， 或者也可以指定完整路径， 例如在我们这个例子中是 [.filename]#ports/dns/pdnsd#。
 
@@ -97,7 +110,7 @@ toc::[]
 % cvs remove deleted_file
 ....
 
-请反复检查 <<porting-testing>> 列出的事项并使用 <<porting-portlint>> 进行检查。
+请反复检查 crossref:quick-porting[porting-testing, 测试 port] 列出的事项并使用 crossref:quick-porting[porting-portlint, 用 portlint 来检查 port] 进行检查。
 
 [source,shell]
 ....
diff --git a/documentation/content/zh-cn/books/porters-handbook/porting-dads/chapter.adoc b/documentation/content/zh-cn/books/porters-handbook/porting-dads/_index.adoc
index a31a409b40..8f1218d401 100644
--- a/documentation/content/zh-cn/books/porters-handbook/porting-dads/chapter.adoc
+++ b/documentation/content/zh-cn/books/porters-handbook/porting-dads/_index.adoc
@@ -2,6 +2,9 @@
 title: 第 12 章 该做什么和不该做什么
 prev: books/porters-handbook/security
 next: books/porters-handbook/porting-samplem
+showBookMenu: true
+weight: 12
+path: "/books/porters-handbook/porting-dads/"
 ---
 
 [[porting-dads]]
@@ -11,36 +14,46 @@ next: books/porters-handbook/porting-samplem
 :toclevels: 1
 :icons: font
 :sectnums:
+:sectnumlevels: 6
+:sectnumoffset: 12
+:partnums:
 :source-highlighter: rouge
 :experimental:
-:skip-front-matter:
-:xrefstyle: basic
-:relfileprefix: ../
-:outfilesuffix:
-:sectnumoffset: 12
-:toc-title: 目录
-:table-caption: 表
-:figure-caption: 图
-:example-caption: 例
+:images-path: books/porters-handbook/
 
-include::shared/mirrors.adoc[]
+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/zh-cn/mailing-lists.adoc[]
-include::shared/zh-cn/teams.adoc[]
-include::shared/zh-cn/urls.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::[]
 
 [[dads-intro]]
 == 介绍
 
-这里是一些在移植软件时可能会遇到的常见问题。 您应按照这个列表检查自己的 port， 同样地， 您也可以帮助检查 http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query[PR 数据库] 中由其它人提交的 port。 请按照在 link:{contributing}#CONTRIB-GENERAL[问题报告和一般性注释] 中介绍的方法提交您的看法。 帮助检查 PR 数据库中的 ports 即能够帮助我们更快地 commit 它们， 也能证明您清楚地了解如何完成这些工作。
+这里是一些在移植软件时可能会遇到的常见问题。 您应按照这个列表检查自己的 port， 同样地， 您也可以帮助检查 http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query[PR 数据库] 中由其它人提交的 port。 请按照在 extref:{contributing}[问题报告和一般性注释, CONTRIB-GENERAL] 中介绍的方法提交您的看法。 帮助检查 PR 数据库中的 ports 即能够帮助我们更快地 commit 它们， 也能证明您清楚地了解如何完成这些工作。
 
 [[porting-wrkdir]]
 == `WRKDIR` (联编时使用的临时目录)
 
-任何时候都不要在 `WRKDIR` 以外的位置写文件。 `WRKDIR` 是在 port 联编过程中唯一的一处一定可写的地方 (参见 link:{handbook}#PORTS-CD[如何从 CDROM 安装 port] 以了解从只读的目录中联编和安装 port 的例子)。 如果您需要改变 [.filename]##pkg-*## 文件， 请按照 <<porting-pkgfiles,重新定义某个变量>> 介绍的方法， 而不是覆盖它们来实现。
+任何时候都不要在 `WRKDIR` 以外的位置写文件。 `WRKDIR` 是在 port 联编过程中唯一的一处一定可写的地方 (参见 extref:{handbook}ports[如何从 CDROM 安装 port, PORTS-CD] 以了解从只读的目录中联编和安装 port 的例子)。 如果您需要改变 [.filename]##pkg-*## 文件， 请按照 <<porting-pkgfiles,重新定义某个变量>> 介绍的方法， 而不是覆盖它们来实现。
 
 [[porting-wrkdirprefix]]
 == `WRKDIRPREFIX` (用于联编的临时目录的父目录名)
@@ -2716,7 +2729,7 @@ IGNORE= is unsupported on FreeBSD 5.x
 
 在 [.filename]#Makefile# 中给出信号， 表示由于某种外界因素 (例如， 用户指定了无效的联编选项) 而无法安装的方法是将变量 `IGNORE` 设为一非空值。 这个值将被格式化， 并在用户执行 `make install` 是给出提示。
 
-用 `.error` 实现这一目的是一种常见的误用。 这样做的问题是， 许多在 ports 树上运行的自动化工具会因此而失败。 最常见的情况见于联编 [.filename]#/usr/ports/INDEX# 的过程 (参见 <<make-describe>>)。 然而， 即使十分普通的命令， 例如 `make maintainer`， 在这种情况下也会失败。 这是不可接受的。
+用 `.error` 实现这一目的是一种常见的误用。 这样做的问题是， 许多在 ports 树上运行的自动化工具会因此而失败。 最常见的情况见于联编 [.filename]#/usr/ports/INDEX# 的过程 (参见 crossref:testing[make-describe, 运行 make describe])。 然而， 即使十分普通的命令， 例如 `make maintainer`， 在这种情况下也会失败。 这是不可接受的。
 
 [[dot-error-breaks-index]]
 .怎样避免使用 `.error`
diff --git a/documentation/content/zh-cn/books/porters-handbook/porting-samplem/chapter.adoc b/documentation/content/zh-cn/books/porters-handbook/porting-samplem/_index.adoc
index 437b43628e..fe294a557d 100644
--- a/documentation/content/zh-cn/books/porters-handbook/porting-samplem/chapter.adoc
+++ b/documentation/content/zh-cn/books/porters-handbook/porting-samplem/_index.adoc
@@ -2,6 +2,9 @@
 title: 第 13 章 示范的 Makefile
 prev: books/porters-handbook/porting-dads
 next: books/porters-handbook/keeping-up
+showBookMenu: true
+weight: 13
+path: "/books/porters-handbook/porting-samplem/"
 ---
 
 [[porting-samplem]]
@@ -11,26 +14,36 @@ next: books/porters-handbook/keeping-up
 :toclevels: 1
 :icons: font
 :sectnums:
+:sectnumlevels: 6
+:sectnumoffset: 13
+:partnums:
 :source-highlighter: rouge
 :experimental:
-:skip-front-matter:
-:xrefstyle: basic
-:relfileprefix: ../
-:outfilesuffix:
-:sectnumoffset: 13
-:toc-title: 目录
-:table-caption: 表
-:figure-caption: 图
-:example-caption: 例
+:images-path: books/porters-handbook/
 
-include::shared/mirrors.adoc[]
+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/zh-cn/mailing-lists.adoc[]
-include::shared/zh-cn/teams.adoc[]
-include::shared/zh-cn/urls.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::[]
 
 这里是一个您可以在建立新 port 时参考的 [.filename]#Makefile#。 请务必删除不需要的那些注释 (方括号中间的文字)！
 
diff --git a/documentation/content/zh-cn/books/porters-handbook/quick-porting/chapter.adoc b/documentation/content/zh-cn/books/porters-handbook/quick-porting/_index.adoc
index 3383e753c5..c041c0b458 100644
--- a/documentation/content/zh-cn/books/porters-handbook/quick-porting/chapter.adoc
+++ b/documentation/content/zh-cn/books/porters-handbook/quick-porting/_index.adoc
@@ -2,6 +2,9 @@
 title: 第 3 章 简单的 port
 prev: books/porters-handbook/own-port
 next: books/porters-handbook/slow
+showBookMenu: true
+weight: 3
+path: "/books/porters-handbook/quick-porting/"
 ---
 
 [[quick-porting]]
@@ -11,26 +14,36 @@ next: books/porters-handbook/slow
 :toclevels: 1
 :icons: font
 :sectnums:
+:sectnumlevels: 6
+:sectnumoffset: 3
+:partnums:
 :source-highlighter: rouge
 :experimental:
-:skip-front-matter:
-:xrefstyle: basic
-:relfileprefix: ../
-:outfilesuffix:
-:sectnumoffset: 3
-:toc-title: 目录
-:table-caption: 表
-:figure-caption: 图
-:example-caption: 例
+:images-path: books/porters-handbook/
 
-include::shared/mirrors.adoc[]
+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/zh-cn/mailing-lists.adoc[]
-include::shared/zh-cn/teams.adoc[]
-include::shared/zh-cn/urls.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::[]
 
 这一章将介绍如何快速创建一个全新的 port。 很多时候， 这点内容是不够的， 您需要阅读这份文档中更深入的内容。
 
@@ -190,7 +203,7 @@ PLIST_DIRS=     lib/X11/oneko
 
 既然已经对所制作的 port 相当满意了， 剩下的工作， 便是将它放进 FreeBSD 的主 ports 树， 以便让更多的人从中受益。 我们并不需要您的 [.filename]#work# 目录以及 [.filename]#pkgname.tgz# 包， 因此现在可以删除它们了。 假定您的 port 的名字是 oneko， 接下来要做的是 `cd` 到 `oneko` 所在的目录， 然后输入命令： `shar find oneko > oneko.shar`
 
-将这个 `oneko.shar` 文件作为附件， 使用 man:send-pr[1] 程序提交 (请参阅 link:{contributing}#CONTRIB-GENERAL[Bug Reports and General Commentary] 以了解关于 man:send-pr[1] 的进一步详情) 将其送出。 请务必将您的 bug 报告分类 (category) 为 `ports` 并把子分类 (class) 设置为 `change-request` (不要把报告表及为机密的， 即 `confidential`！)。 此外， 在 PR 的描述 ("Description") 一栏中的内容应该是 port 的简要介绍 (例如 `COMMENT` 内容的简化版本)， 而 shar 文件则应填入修正 ("Fix") 栏中。
+将这个 `oneko.shar` 文件作为附件， 使用 man:send-pr[1] 程序提交 (请参阅 extref:{contributing}[Bug Reports and General Commentary, CONTRIB-GENERAL] 以了解关于 man:send-pr[1] 的进一步详情) 将其送出。 请务必将您的 bug 报告分类 (category) 为 `ports` 并把子分类 (class) 设置为 `change-request` (不要把报告表及为机密的， 即 `confidential`！)。 此外， 在 PR 的描述 ("Description") 一栏中的内容应该是 port 的简要介绍 (例如 `COMMENT` 内容的简化版本)， 而 shar 文件则应填入修正 ("Fix") 栏中。
 
 [NOTE]
 ====
@@ -201,4 +214,4 @@ PLIST_DIRS=     lib/X11/oneko
 
 在您提交的您的 port 以后请耐心等待。 有时在一个 port 正式加入 FreeBSD 之前需要花费好几个月， 尽管也有可能是几天。 您可以查看 http://www.FreeBSD.org/cgi/query-pr-summary.cgi?category=ports[ 正等待被 commit 到 FreeBSD 的 port PR]。
 
-一旦我们看过了您的报告， 有必要的话我们会联系您， 并把它放到 ports 树里。 您的名字也会出现在 link:{contributors}#contrib-additional/[Additional FreeBSD Contributors] 和其它的文件。 不是很棒吗!?  :-)
+一旦我们看过了您的报告， 有必要的话我们会联系您， 并把它放到 ports 树里。 您的名字也会出现在 extref:{contributors}[Additional FreeBSD Contributors, contrib-additional] 和其它的文件。 不是很棒吗!?  :-)
diff --git a/documentation/content/zh-cn/books/porters-handbook/security/chapter.adoc b/documentation/content/zh-cn/books/porters-handbook/security/_index.adoc
index a2f0b6bbf7..6814f31745 100644
--- a/documentation/content/zh-cn/books/porters-handbook/security/chapter.adoc
+++ b/documentation/content/zh-cn/books/porters-handbook/security/_index.adoc
@@ -2,6 +2,9 @@
 title: 第 11 章 Ports 的安全
 prev: books/porters-handbook/port-upgrading
 next: books/porters-handbook/porting-dads
+showBookMenu: true
+weight: 11
+path: "/books/porters-handbook/security/"
 ---
 
 [[security]]
@@ -11,26 +14,36 @@ next: books/porters-handbook/porting-dads
 :toclevels: 1
 :icons: font
 :sectnums:
+:sectnumlevels: 6
+:sectnumoffset: 11
+:partnums:
 :source-highlighter: rouge
 :experimental:
-:skip-front-matter:
-:xrefstyle: basic
-:relfileprefix: ../
-:outfilesuffix:
-:sectnumoffset: 11
-:toc-title: 目录
-:table-caption: 表
-:figure-caption: 图
-:example-caption: 例
+:images-path: books/porters-handbook/
 
-include::shared/mirrors.adoc[]
+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/zh-cn/mailing-lists.adoc[]
-include::shared/zh-cn/teams.adoc[]
-include::shared/zh-cn/urls.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::[]
 
 [[security-intro]]
 == 安全为何如此重要
diff --git a/documentation/content/zh-cn/books/porters-handbook/slow/chapter.adoc b/documentation/content/zh-cn/books/porters-handbook/slow/_index.adoc
index 75c039ac44..84e54a19e0 100644
--- a/documentation/content/zh-cn/books/porters-handbook/slow/chapter.adoc
+++ b/documentation/content/zh-cn/books/porters-handbook/slow/_index.adoc
@@ -2,6 +2,9 @@
 title: 第 4 章 复杂的 Porting
 prev: books/porters-handbook/quick-porting
 next: books/porters-handbook/makefile
+showBookMenu: true
+weight: 4
+path: "/books/porters-handbook/slow/"
 ---
 
 [[slow]]
@@ -11,26 +14,36 @@ next: books/porters-handbook/makefile
 :toclevels: 1
 :icons: font
 :sectnums:
+:sectnumlevels: 6
+:sectnumoffset: 4
+:partnums:
 :source-highlighter: rouge
 :experimental:
-:skip-front-matter:
-:xrefstyle: basic
-:relfileprefix: ../
-:outfilesuffix:
-:sectnumoffset: 4
-:toc-title: 目录
-:table-caption: 表
-:figure-caption: 图
-:example-caption: 例
+:images-path: books/porters-handbook/
 
-include::shared/mirrors.adoc[]
+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/zh-cn/mailing-lists.adoc[]
-include::shared/zh-cn/teams.adoc[]
-include::shared/zh-cn/urls.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::[]
 
 好了， 也许工作没那么简单， port 需要做些修改才能够在 FreeBSD 上跑起来。 在这一章里， 我们将会一步步举例来介绍应该如何修改来使您的 port 能在 FreeBSD 上面运行。
 
diff --git a/documentation/content/zh-cn/books/porters-handbook/special/chapter.adoc b/documentation/content/zh-cn/books/porters-handbook/special/_index.adoc
index 27edaed819..1cc3698735 100644
--- a/documentation/content/zh-cn/books/porters-handbook/special/chapter.adoc
+++ b/documentation/content/zh-cn/books/porters-handbook/special/_index.adoc
@@ -2,6 +2,9 @@
 title: 第 6 章 特殊情况
 prev: books/porters-handbook/makefile
 next: books/porters-handbook/plist
+showBookMenu: true
+weight: 6
+path: "/books/porters-handbook/special/"
 ---
 
 [[special]]
@@ -11,26 +14,36 @@ next: books/porters-handbook/plist
 :toclevels: 1
 :icons: font
 :sectnums:
+:sectnumlevels: 6
+:sectnumoffset: 6
+:partnums:
 :source-highlighter: rouge
 :experimental:
-:skip-front-matter:
-:xrefstyle: basic
-:relfileprefix: ../
-:outfilesuffix:
-:sectnumoffset: 6
-:toc-title: 目录
-:table-caption: 表
-:figure-caption: 图
-:example-caption: 例
+:images-path: books/porters-handbook/
 
-include::shared/mirrors.adoc[]
+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/zh-cn/mailing-lists.adoc[]
-include::shared/zh-cn/teams.adoc[]
-include::shared/zh-cn/urls.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::[]
 
 有一些您在创建port时的特殊情况，我们在这里提一下。
 
@@ -355,7 +368,7 @@ PLIST_SUB+=             NLS="@comment "
 .endif
 ....
 
-您要做的下一件事是合理地安排装箱单文件， 使其根据用户配置来决定是否将消息编录 (message catalog) 文件放入最终的装箱单。 前面已经介绍了在 [.filename]#Makefile# 中所需的写法， 这种做法在 <<plist-sub,高级 [.filename]#pkg-plist# 用法>> 这节中进行了介绍。 简单地说， 在 [.filename]#pkg-plist# 中出现的 ``%%NLS%%`` 均会在禁用 NLS 时自动替换为 "``@comment ``"， 反之则替换为空串。 这样， 在最终的装箱单中带 ``%%NLS%%`` 的行， 在 NLS 关闭的情况下就会变为注释， 反之， 这些前缀就会自动删掉。 现在需要做的事情就是把 ``%%NLS%%`` 插到 [.filename]#pkg-plist# 中的消息编录文件的那些行开头， 例如：
+您要做的下一件事是合理地安排装箱单文件， 使其根据用户配置来决定是否将消息编录 (message catalog) 文件放入最终的装箱单。 前面已经介绍了在 [.filename]#Makefile# 中所需的写法， 这种做法在 crossref:plist[plist-sub,高级 [.filename]#pkg-plist# 用法] 这节中进行了介绍。 简单地说， 在 [.filename]#pkg-plist# 中出现的 ``%%NLS%%`` 均会在禁用 NLS 时自动替换为 "``@comment ``"， 反之则替换为空串。 这样， 在最终的装箱单中带 ``%%NLS%%`` 的行， 在 NLS 关闭的情况下就会变为注释， 反之， 这些前缀就会自动删掉。 现在需要做的事情就是把 ``%%NLS%%`` 插到 [.filename]#pkg-plist# 中的消息编录文件的那些行开头， 例如：
 
 [.programlisting]
 ....
@@ -363,7 +376,7 @@ PLIST_SUB+=             NLS="@comment "
 %%NLS%%share/locale/no/LC_MESSAGES/foobar.mo
 ....
 
-在比较复杂的情形中， 您可能需要使用更高级的技术， 例如 <<plist-dynamic,动态生成装箱单>> 等。
+在比较复杂的情形中， 您可能需要使用更高级的技术， 例如 crossref:plist[plist-dynamic,动态生成装箱单] 等。
 
 === 处理消息编录目录
 
@@ -960,7 +973,7 @@ QT_COMPONENTS= qmake_build moc_build rcc_build uic_build
 |其它 port 安装的 JAR 文件所在的目录。 默认值： [.filename]#${LOCALBASE}/shared/java/classes#。
 |===
 
-相关的项也会定义在 `PLIST_SUB` (在 <<plist-sub>> 中进行介绍) 和 `SUB_LIST` 中。
+相关的项也会定义在 `PLIST_SUB` (在 crossref:plist[plist-sub, 根据 `make` 变量对 pkg-plist 进行修改] 中进行介绍) 和 `SUB_LIST` 中。
 
 [[java-building-with-ant]]
 === 采用 Ant 进行联编
@@ -981,7 +994,7 @@ PLIST_FILES+= %%JAVAJARDIR%%/myport.jar
 
 无论您正制作哪一类的 port (库或者应用程序)， 附加的文档都应安装到和其它 port <<install-documentation,同样的位置>>。 已经知道， JavaDoc 会根据 JDK 版本的不同而产生不同的文件。 对于那些不打算强制使用某一特定版本 JDK 的 port 而言， 这无疑提高了制作装箱单 ([.filename]#pkg-plist#) 的难度。 这是为什么强烈建议使用 `PORTDOCS` 宏的原因。 更进一步， 即使您能够预测 `javadoc` 将要生成的文件， 所需的 [.filename]#pkg-plist# 的尺寸， 也是鼓吹使用 `PORTDOCS` 的一大理由。
 
-`DATADIR` 的默认值是 [.filename]#${PREFIX}/shared/${PORTNAME}#。 对 Java port 而言将 `DATADIR` 改为 [.filename]#${JAVASHAREDIR}/${PORTNAME}# 是一个好主意。 当然， `DATADIR` 会自动加到 `PLIST_SUB` 中 (在 <<plist-sub>> 有所介绍) 因此您可以在 [.filename]#pkg-plist# 中直接使用 `%%DATADIR%%`。
+`DATADIR` 的默认值是 [.filename]#${PREFIX}/shared/${PORTNAME}#。 对 Java port 而言将 `DATADIR` 改为 [.filename]#${JAVASHAREDIR}/${PORTNAME}# 是一个好主意。 当然， `DATADIR` 会自动加到 `PLIST_SUB` 中 (在 crossref:plist[plist-sub, 根据 `make` 变量对 pkg-plist 进行修改] 有所介绍) 因此您可以在 [.filename]#pkg-plist# 中直接使用 `%%DATADIR%%`。
 
 撰写本文时， 对是应该从源代码联编， 还是直接安装预编译的 Java ports 安装包并没有明确的规定。 尽管如此， http://www.freebsd.org/java/[FreeBSD Java Project] 的开发人员仍鼓励移植软件的开发者在不麻烦的情况下尽可能从源代码完成联编。
 
@@ -989,7 +1002,7 @@ PLIST_FILES+= %%JAVAJARDIR%%/myport.jar
 
 在 PR 中的 `java` 类别， 主要是用于 FreeBSD Java project 移植 JDK 本身之用。 因而， 提交您的 Java port 时， 应归入 `ports` 类别， 除非您正尝试解决的问题是 JDK 实现本身或 [.filename]#bsd.java.mk# 的。
 
-类似地， 您应参考 <<makefile-categories>> 中所详述的关于 `CATEGORIES` 在 Java port 中的使用规则。
+类似地， 您应参考 crossref:makefile[makefile-categories, 分类] 中所详述的关于 `CATEGORIES` 在 Java port 中的使用规则。
 
 [[using-php]]
 == Web 应用， Apache 和 PHP
@@ -2100,7 +2113,7 @@ USE_XFCE=        mcsmanager configenv
 [[rc-scripts]]
 == 启动和停止服务 (rc 脚本)
 
-[.filename]#rc.d# 脚本在系统启动时用于启动服务， 并为管理员提供停止、 启动和重新启动某个服务的标准方法。 Ports 安装的脚本会集成到系统的 [.filename]#rc.d# 框架中。 关于如何使用它的说明， 可以在 link:{handbook}#configtuning-rcd/[使用手册的 rc.d 章节] 找到。 关于可用命令的详细解释， 则可以在 man:rc[8] 和 man:rc.subr[8] 找到。 最后， 您可以参阅 link:{rc-scripting}[这篇文章] 了解撰写 [.filename]#rc.d# 脚本的最佳实践。
+[.filename]#rc.d# 脚本在系统启动时用于启动服务， 并为管理员提供停止、 启动和重新启动某个服务的标准方法。 Ports 安装的脚本会集成到系统的 [.filename]#rc.d# 框架中。 关于如何使用它的说明， 可以在 extref:{handbook}config-tuning/[使用手册的 rc.d 章节, configtuning-rcd] 找到。 关于可用命令的详细解释， 则可以在 man:rc[8] 和 man:rc.subr[8] 找到。 最后， 您可以参阅 extref:{rc-scripting}[这篇文章] 了解撰写 [.filename]#rc.d# 脚本的最佳实践。
 
 可以安装一或多个 [.filename]#rc.d# 脚本：
 
diff --git a/documentation/content/zh-cn/books/porters-handbook/testing/chapter.adoc b/documentation/content/zh-cn/books/porters-handbook/testing/_index.adoc
index f515d6b1cd..a08fc98e2d 100644
--- a/documentation/content/zh-cn/books/porters-handbook/testing/chapter.adoc
+++ b/documentation/content/zh-cn/books/porters-handbook/testing/_index.adoc
@@ -2,6 +2,9 @@
 title: 第 9 章 测试您的 port
 prev: books/porters-handbook/pkg-files
 next: books/porters-handbook/port-upgrading
+showBookMenu: true
+weight: 9
+path: "/books/porters-handbook/testing/"
 ---
 
 [[testing]]
@@ -11,26 +14,36 @@ next: books/porters-handbook/port-upgrading
 :toclevels: 1
 :icons: font
 :sectnums:
+:sectnumlevels: 6
+:sectnumoffset: 9
+:partnums:
 :source-highlighter: rouge
 :experimental:
-:skip-front-matter:
-:xrefstyle: basic
-:relfileprefix: ../
-:outfilesuffix:
-:sectnumoffset: 9
-:toc-title: 目录
-:table-caption: 表
-:figure-caption: 图
-:example-caption: 例
+:images-path: books/porters-handbook/
 
-include::shared/mirrors.adoc[]
+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/zh-cn/mailing-lists.adoc[]
-include::shared/zh-cn/teams.adoc[]
-include::shared/zh-cn/urls.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::[]
 
 [[make-describe]]
 == 运行 `make describe`
@@ -39,7 +52,7 @@ toc::[]
 
 [NOTE]
 ====
-无论在 [.filename]#make.conf# 中设置了什么选项， 这个文件都应能够正确地生成。 因此， 应避免在 (例如) 某个依赖关系无法满足时使用 `.error`。 (参见 <<dads-dot-error>>。)
+无论在 [.filename]#make.conf# 中设置了什么选项， 这个文件都应能够正确地生成。 因此， 应避免在 (例如) 某个依赖关系无法满足时使用 `.error`。 (参见 crossref:porting-dads[dads-dot-error, 避免使用 .error 结构]。)
 ====
 
 如果 `make describe` 只是产生一个字符串， 而不是错误信息， 可能就没什么问题。 请参见 [.filename]#bsd.port.mk# 以了解所生成的串的意义。
diff --git a/documentation/content/zh-cn/books/porters-handbook/why-port/chapter.adoc b/documentation/content/zh-cn/books/porters-handbook/why-port/_index.adoc
index 8764466f84..d0cac55a3e 100644
--- a/documentation/content/zh-cn/books/porters-handbook/why-port/chapter.adoc
+++ b/documentation/content/zh-cn/books/porters-handbook/why-port/_index.adoc
@@ -2,6 +2,9 @@
 title: 第 1 章 介绍
 prev: books/porters-handbook/
 next: books/porters-handbook/own-port
+showBookMenu: true
+weight: 1
+path: "/books/porters-handbook/why-port/"
 ---
 
 [[why-port]]
@@ -11,26 +14,36 @@ next: books/porters-handbook/own-port
 :toclevels: 1
 :icons: font
 :sectnums:
+:sectnumlevels: 6
+:sectnumoffset: 1
+:partnums:
 :source-highlighter: rouge
 :experimental:
-:skip-front-matter:
-:xrefstyle: basic
-:relfileprefix: ../
-:outfilesuffix:
-:sectnumoffset: 1
-:toc-title: 目录
-:table-caption: 表
-:figure-caption: 图
-:example-caption: 例
+:images-path: books/porters-handbook/
 
-include::shared/mirrors.adoc[]
+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/zh-cn/mailing-lists.adoc[]
-include::shared/zh-cn/teams.adoc[]
-include::shared/zh-cn/urls.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::[]
 
 几乎每个人都是通过 FreeBSD Ports Collection 在 FreeBSD 上面装应用程序 ("`ports`")的。 就像FreeBSD的其它部分一样， 它主要来自于志愿者的努力。 所以在阅读这份文档的时候请务必记住这些。