git: de30e744dc - main - Split Simplified Chinese porter's handbook

Go to: [ bottom of page ] [ top of archives ] [ this month ]
From: Sergio Carlavilla Delgado <carlavilla_at_FreeBSD.org>
Date: Sat, 27 Nov 2021 13:29:46 UTC
The branch main has been updated by carlavilla:

URL: https://cgit.FreeBSD.org/doc/commit/?id=de30e744dc40621846f0d4b01c0ff89557489a04

commit de30e744dc40621846f0d4b01c0ff89557489a04
Author:     Sergio Carlavilla Delgado <carlavilla@FreeBSD.org>
AuthorDate: 2021-11-27 13:27:21 +0000
Commit:     Sergio Carlavilla Delgado <carlavilla@FreeBSD.org>
CommitDate: 2021-11-27 13:27:21 +0000

    Split Simplified Chinese porter's handbook
---
 .../zh-cn/books/porters-handbook/_index.adoc       | 24 ++------
 .../content/zh-cn/books/porters-handbook/book.adoc | 67 ++++++++++++++++++++++
 .../books/porters-handbook/chapters-order.adoc     | 28 ++++-----
 .../keeping-up/{chapter.adoc => _index.adoc}       |  0
 .../makefile/{chapter.adoc => _index.adoc}         |  6 +-
 .../own-port/{chapter.adoc => _index.adoc}         |  2 +-
 .../pkg-files/{chapter.adoc => _index.adoc}        |  0
 .../plist/{chapter.adoc => _index.adoc}            |  0
 .../port-upgrading/{chapter.adoc => _index.adoc}   |  4 +-
 .../porting-dads/{chapter.adoc => _index.adoc}     |  2 +-
 .../porting-samplem/{chapter.adoc => _index.adoc}  |  0
 .../quick-porting/{chapter.adoc => _index.adoc}    |  0
 .../security/{chapter.adoc => _index.adoc}         |  0
 .../slow/{chapter.adoc => _index.adoc}             |  0
 .../special/{chapter.adoc => _index.adoc}          | 10 ++--
 .../testing/{chapter.adoc => _index.adoc}          |  2 +-
 .../why-port/{chapter.adoc => _index.adoc}         |  0
 17 files changed, 99 insertions(+), 46 deletions(-)

diff --git a/documentation/content/zh-cn/books/porters-handbook/_index.adoc b/documentation/content/zh-cn/books/porters-handbook/_index.adoc
index 162fe551a3..ef8f42161c 100644
--- a/documentation/content/zh-cn/books/porters-handbook/_index.adoc
+++ b/documentation/content/zh-cn/books/porters-handbook/_index.adoc
@@ -5,21 +5,22 @@ authors:
   - author: FreeBSD 中文计划
 copyright: 2000-2020 The FreeBSD Documentation Project
 trademarks: ["freebsd", "sun", "unix", "general"]
+next: books/porters-handbook/why-port
+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[]
@@ -45,23 +46,8 @@ endif::[]
 
 '''
 
-toc::[]
+include::{chapters-path}toc.adoc[]
 
 include::{chapters-path}toc-tables.adoc[]
 
 include::{chapters-path}toc-examples.adoc[]
-
-include::{chapters-path}why-port/chapter.adoc[leveloffset=+1]
-include::{chapters-path}own-port/chapter.adoc[leveloffset=+1]
-include::{chapters-path}quick-porting/chapter.adoc[leveloffset=+1]
-include::{chapters-path}slow/chapter.adoc[leveloffset=+1]
-include::{chapters-path}makefile/chapter.adoc[leveloffset=+1]
-include::{chapters-path}special/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}port-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}keeping-up/chapter.adoc[leveloffset=+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..3e0348636f
--- /dev/null
+++ b/documentation/content/zh-cn/books/porters-handbook/book.adoc
@@ -0,0 +1,67 @@
+---
+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}toc-tables.adoc[]
+
+include::{chapters-path}toc-examples.adoc[]
+
+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
index 1063d23868..5b56462bca 100644
--- a/documentation/content/zh-cn/books/porters-handbook/chapters-order.adoc
+++ b/documentation/content/zh-cn/books/porters-handbook/chapters-order.adoc
@@ -1,14 +1,14 @@
-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
+why-port/_index.adoc
+own-port/_index.adoc
+quick-porting/_index.adoc
+slow/_index.adoc
+makefile/_index.adoc
+special/_index.adoc
+plist/_index.adoc
+pkg-files/_index.adoc
+testing/_index.adoc
+port-upgrading/_index.adoc
+security/_index.adoc
+porting-dads/_index.adoc 
+porting-samplem/_index.adoc 
+keeping-up/_index.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
similarity index 100%
rename from documentation/content/zh-cn/books/porters-handbook/keeping-up/chapter.adoc
rename to documentation/content/zh-cn/books/porters-handbook/keeping-up/_index.adoc
diff --git a/documentation/content/zh-cn/books/porters-handbook/makefile/chapter.adoc b/documentation/content/zh-cn/books/porters-handbook/makefile/_index.adoc
similarity index 98%
rename from documentation/content/zh-cn/books/porters-handbook/makefile/chapter.adoc
rename to documentation/content/zh-cn/books/porters-handbook/makefile/_index.adoc
index 58ab9de20b..1343c993df 100644
--- a/documentation/content/zh-cn/books/porters-handbook/makefile/chapter.adoc
+++ b/documentation/content/zh-cn/books/porters-handbook/makefile/_index.adoc
@@ -1155,7 +1155,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` 组的内容， 等等。
@@ -1390,7 +1390,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 的信息。
 
 === 在依赖关系中指定最低版本
 
@@ -1743,7 +1743,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
similarity index 96%
rename from documentation/content/zh-cn/books/porters-handbook/own-port/chapter.adoc
rename to documentation/content/zh-cn/books/porters-handbook/own-port/_index.adoc
index b1441238d9..3969d2b6b4 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
@@ -44,7 +44,7 @@ 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
similarity index 100%
rename from documentation/content/zh-cn/books/porters-handbook/pkg-files/chapter.adoc
rename to documentation/content/zh-cn/books/porters-handbook/pkg-files/_index.adoc
diff --git a/documentation/content/zh-cn/books/porters-handbook/plist/chapter.adoc b/documentation/content/zh-cn/books/porters-handbook/plist/_index.adoc
similarity index 100%
rename from documentation/content/zh-cn/books/porters-handbook/plist/chapter.adoc
rename to documentation/content/zh-cn/books/porters-handbook/plist/_index.adoc
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
similarity index 97%
rename from documentation/content/zh-cn/books/porters-handbook/port-upgrading/chapter.adoc
rename to documentation/content/zh-cn/books/porters-handbook/port-upgrading/_index.adoc
index f09dd7e97b..a086a272c2 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
@@ -79,7 +79,7 @@ endif::[]
 再次强调， 请使用 man:diff[1] 而非 man:shar[1] 来发送现有 port 的更新！ 这可以帮助 ports committer 理解需要修改的内容。
 ====
 
-现在您已经了解了所需的所有操作， 您可能会像要阅读在 <<keeping-up>> 中关于如何保持最新的描述。
+现在您已经了解了所需的所有操作， 您可能会像要阅读在 crossref:keeping-up[keeping-up, 保持同步] 中关于如何保持最新的描述。
 
 [[cvs-diff]]
 == 使用 CVS 制作补丁
@@ -107,7 +107,7 @@ endif::[]
 % 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
similarity index 99%
rename from documentation/content/zh-cn/books/porters-handbook/porting-dads/chapter.adoc
rename to documentation/content/zh-cn/books/porters-handbook/porting-dads/_index.adoc
index b9e8cb4124..c601f5bab4 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
@@ -2726,7 +2726,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
similarity index 100%
rename from documentation/content/zh-cn/books/porters-handbook/porting-samplem/chapter.adoc
rename to documentation/content/zh-cn/books/porters-handbook/porting-samplem/_index.adoc
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
similarity index 100%
rename from documentation/content/zh-cn/books/porters-handbook/quick-porting/chapter.adoc
rename to documentation/content/zh-cn/books/porters-handbook/quick-porting/_index.adoc
diff --git a/documentation/content/zh-cn/books/porters-handbook/security/chapter.adoc b/documentation/content/zh-cn/books/porters-handbook/security/_index.adoc
similarity index 100%
rename from documentation/content/zh-cn/books/porters-handbook/security/chapter.adoc
rename to documentation/content/zh-cn/books/porters-handbook/security/_index.adoc
diff --git a/documentation/content/zh-cn/books/porters-handbook/slow/chapter.adoc b/documentation/content/zh-cn/books/porters-handbook/slow/_index.adoc
similarity index 100%
rename from documentation/content/zh-cn/books/porters-handbook/slow/chapter.adoc
rename to documentation/content/zh-cn/books/porters-handbook/slow/_index.adoc
diff --git a/documentation/content/zh-cn/books/porters-handbook/special/chapter.adoc b/documentation/content/zh-cn/books/porters-handbook/special/_index.adoc
similarity index 98%
rename from documentation/content/zh-cn/books/porters-handbook/special/chapter.adoc
rename to documentation/content/zh-cn/books/porters-handbook/special/_index.adoc
index fce05bfac8..e6e20d694d 100644
--- a/documentation/content/zh-cn/books/porters-handbook/special/chapter.adoc
+++ b/documentation/content/zh-cn/books/porters-handbook/special/_index.adoc
@@ -365,7 +365,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]
 ....
@@ -373,7 +373,7 @@ PLIST_SUB+=             NLS="@comment "
 %%NLS%%share/locale/no/LC_MESSAGES/foobar.mo
 ....
 
-在比较复杂的情形中， 您可能需要使用更高级的技术， 例如 <<plist-dynamic,动态生成装箱单>> 等。
+在比较复杂的情形中， 您可能需要使用更高级的技术， 例如 crossref:plist[plist-dynamic,动态生成装箱单] 等。
 
 === 处理消息编录目录
 
@@ -970,7 +970,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 进行联编
@@ -991,7 +991,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] 的开发人员仍鼓励移植软件的开发者在不麻烦的情况下尽可能从源代码完成联编。
 
@@ -999,7 +999,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
diff --git a/documentation/content/zh-cn/books/porters-handbook/testing/chapter.adoc b/documentation/content/zh-cn/books/porters-handbook/testing/_index.adoc
similarity index 98%
rename from documentation/content/zh-cn/books/porters-handbook/testing/chapter.adoc
rename to documentation/content/zh-cn/books/porters-handbook/testing/_index.adoc
index 85582be66d..be42694f12 100644
--- a/documentation/content/zh-cn/books/porters-handbook/testing/chapter.adoc
+++ b/documentation/content/zh-cn/books/porters-handbook/testing/_index.adoc
@@ -49,7 +49,7 @@ endif::[]
 
 [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
similarity index 100%
rename from documentation/content/zh-cn/books/porters-handbook/why-port/chapter.adoc
rename to documentation/content/zh-cn/books/porters-handbook/why-port/_index.adoc