23 files changed, 159 insertions, 69 deletions

diff --git a/documentation/content/en/books/arch-handbook/_index.adoc b/documentation/content/en/books/arch-handbook/_index.adoc
index f9c7976e7f..2ae3066029 100644
--- a/documentation/content/en/books/arch-handbook/_index.adoc
+++ b/documentation/content/en/books/arch-handbook/_index.adoc
@@ -5,26 +5,18 @@ authors:
 copyright: Copyright © 2000-2006, 2012-2013 The FreeBSD Documentation Project
 releaseinfo: "$FreeBSD$" 
 trademarks: ["freebsd", "apple", "microsoft", "unix", "general"] 
+next: books/arch-handbook/parti
 ---
 
 = FreeBSD Architecture Handbook
 :doctype: book
 :toc: macro
-:toclevels: 2
+:toclevels: 1
 :icons: font
-:xrefstyle: basic
-:relfileprefix: ../
-:outfilesuffix:
 :sectnums:
 :sectnumlevels: 6
-:partnums:
-:chapter-signifier: Chapter
-:part-signifier: Part
 :source-highlighter: rouge
 :experimental:
-:skip-front-matter:
-:book: true
-:pdf: false
 
 ifeval::["{backend}" == "html5"]
 include::shared/mirrors.adoc[]
@@ -65,36 +57,4 @@ The latest version of this document is always available from the link:https://ww
 
 '''
 
-toc::[]
-
-// Section one
-[[kernel]]
-= Kernel
-
-include::{chapters-path}boot/chapter.adoc[leveloffset=+1, lines=7..21;32..-1]
-include::{chapters-path}locking/chapter.adoc[leveloffset=+1, lines=7..21;32..-1]
-include::{chapters-path}kobj/chapter.adoc[leveloffset=+1, lines=7..21;32..-1]
-include::{chapters-path}jail/chapter.adoc[leveloffset=+1, lines=7..21;32..-1]
-include::{chapters-path}sysinit/chapter.adoc[leveloffset=+1], lines=7..21;32..-1]
-include::{chapters-path}mac/chapter.adoc[leveloffset=+1, lines=12..26;37..-1]
-include::{chapters-path}vm/chapter.adoc[leveloffset=+1, lines=7..21;32..-1]
-include::{chapters-path}smp/chapter.adoc[leveloffset=+1, lines=7..21;32..-1]
-
-// Section two
-[[devicedrivers]]
-= Device Drivers
-
-include::{chapters-path}driverbasics/chapter.adoc[leveloffset=+1, lines=7..21;32..-1]
-include::{chapters-path}isa/chapter.adoc[leveloffset=+1, lines=7..21;32..-1]
-include::{chapters-path}pci/chapter.adoc[leveloffset=+1, lines=7..21;32..-1]
-include::{chapters-path}scsi/chapter.adoc[leveloffset=+1, lines=7..21;32..-1]
-include::{chapters-path}usb/chapter.adoc[leveloffset=+1, lines=7..21;32..-1]
-include::{chapters-path}newbus/chapter.adoc[leveloffset=+1, lines=12..26;37..-1]
-include::{chapters-path}sound/chapter.adoc[leveloffset=+1, lines=7..21;32..-1]
-include::{chapters-path}pccard/chapter.adoc[leveloffset=+1, lines=7..21;32..-1]
-
-// Section three
-[[appendices]]
-= Appendices
-
-include::{chapters-path}bibliography/chapter.adoc[leveloffset=+1, lines=6..19;28..-1]
+include::content/en/books/arch-handbook/toc.adoc[]
diff --git a/documentation/content/en/books/arch-handbook/bibliography/chapter.adoc b/documentation/content/en/books/arch-handbook/bibliography/_index.adoc
index a33b858ee5..a33b858ee5 100644
--- a/documentation/content/en/books/arch-handbook/bibliography/chapter.adoc
+++ b/documentation/content/en/books/arch-handbook/bibliography/_index.adoc
diff --git a/documentation/content/en/books/arch-handbook/book.adoc b/documentation/content/en/books/arch-handbook/book.adoc
new file mode 100644
index 0000000000..4fbb953a12
--- /dev/null
+++ b/documentation/content/en/books/arch-handbook/book.adoc
@@ -0,0 +1,97 @@
+---
+title: FreeBSD Architecture Handbook
+authors: 
+  - author: The FreeBSD Documentation Project
+copyright: Copyright © 2000-2006, 2012-2013 The FreeBSD Documentation Project
+releaseinfo: "$FreeBSD$" 
+trademarks: ["freebsd", "apple", "microsoft", "unix", "general"] 
+---
+
+= FreeBSD Architecture Handbook
+:doctype: book
+:toc: macro
+:toclevels: 2
+:icons: font
+:xrefstyle: basic
+:relfileprefix: ../
+:outfilesuffix:
+:sectnums:
+:sectnumlevels: 6
+:partnums:
+:chapter-signifier: Chapter
+:part-signifier: Part
+:source-highlighter: rouge
+:experimental:
+:skip-front-matter:
+:book: true
+:pdf: false
+
+ifeval::["{backend}" == "html5"]
+include::shared/mirrors.adoc[]
+include::shared/authors.adoc[]
+include::shared/releases.adoc[]
+include::shared/en/mailing-lists.adoc[]
+include::shared/en/teams.adoc[]
+include::shared/en/urls.adoc[]
+:chapters-path: content/en/books/arch-handbook/
+endif::[]
+
+ifeval::["{backend}" == "pdf"]
+include::../../../../shared/mirrors.adoc[]
+include::../../../../shared/authors.adoc[]
+include::../../../../shared/releases.adoc[]
+include::../../../../shared/en/mailing-lists.adoc[]
+include::../../../../shared/en/teams.adoc[]
+include::../../../../shared/en/urls.adoc[]
+:chapters-path:
+endif::[]
+
+ifeval::["{backend}" == "epub3"]
+include::../../../../shared/mirrors.adoc[]
+include::../../../../shared/authors.adoc[]
+include::../../../../shared/releases.adoc[]
+include::../../../../shared/en/mailing-lists.adoc[]
+include::../../../../shared/en/teams.adoc[]
+include::../../../../shared/en/urls.adoc[]
+:chapters-path:
+endif::[]
+
+[.abstract-title]
+Abstract
+
+Welcome to the FreeBSD Architecture Handbook. This manual is a _work in progress_ and is the work of many individuals. Many sections do not yet exist and some of those that do exist need to be updated. If you are interested in helping with this project, send email to the {freebsd-doc}.
+
+The latest version of this document is always available from the link:https://www.FreeBSD.org/[FreeBSD World Wide Web server]. It may also be downloaded in a variety of formats and compression options from the https://download.freebsd.org/ftp/doc/[FreeBSD FTP server] or one of the numerous link:{handbook}#mirrors-ftp/[mirror sites].
+
+'''
+
+toc::[]
+
+// Section one
+include::{chapters-path}parti.adoc[lines=7..8]
+
+include::{chapters-path}boot/_index.adoc[leveloffset=+1, lines=7..21;32..-1]
+include::{chapters-path}locking/_index.adoc[leveloffset=+1, lines=7..21;32..-1]
+include::{chapters-path}kobj/_index.adoc[leveloffset=+1, lines=7..21;32..-1]
+include::{chapters-path}jail/_index.adoc[leveloffset=+1, lines=7..21;32..-1]
+include::{chapters-path}sysinit/_index.adoc[leveloffset=+1], lines=7..21;32..-1]
+include::{chapters-path}mac/_index.adoc[leveloffset=+1, lines=12..26;37..-1]
+include::{chapters-path}vm/_index.adoc[leveloffset=+1, lines=7..21;32..-1]
+include::{chapters-path}smp/_index.adoc[leveloffset=+1, lines=7..21;32..-1]
+
+// Section two
+include::{chapters-path}partii.adoc[lines=7..8]
+
+include::{chapters-path}driverbasics/_index.adoc[leveloffset=+1, lines=7..21;32..-1]
+include::{chapters-path}isa/_index.adoc[leveloffset=+1, lines=7..21;32..-1]
+include::{chapters-path}pci/_index.adoc[leveloffset=+1, lines=7..21;32..-1]
+include::{chapters-path}scsi/_index.adoc[leveloffset=+1, lines=7..21;32..-1]
+include::{chapters-path}usb/_index.adoc[leveloffset=+1, lines=7..21;32..-1]
+include::{chapters-path}newbus/_index.adoc[leveloffset=+1, lines=12..26;37..-1]
+include::{chapters-path}sound/_index.adoc[leveloffset=+1, lines=7..21;32..-1]
+include::{chapters-path}pccard/_index.adoc[leveloffset=+1, lines=7..21;32..-1]
+
+// Section three
+include::{chapters-path}partiii.adoc[lines=7..8]
+
+include::{chapters-path}bibliography/_index.adoc[leveloffset=+1, lines=6..19;28..-1]
diff --git a/documentation/content/en/books/arch-handbook/boot/chapter.adoc b/documentation/content/en/books/arch-handbook/boot/_index.adoc
index 01d56238ce..44b4e3c1be 100644
--- a/documentation/content/en/books/arch-handbook/boot/chapter.adoc
+++ b/documentation/content/en/books/arch-handbook/boot/_index.adoc
@@ -55,7 +55,7 @@ Here is an example of the output generated by the different boot stages. Actual
 |`boot0`
 a|
 
-[source,shell]
+[source,bash]
 ....
 F1    FreeBSD
 F2    BSD
@@ -65,7 +65,7 @@ F5    Disk 2
 |`boot2` footnote:[This prompt will appear if the user presses a key just after selecting an OS to boot at the boot0 stage.]
 a|
 
-[source,shell]
+[source,bash]
 ....
 >>FreeBSD/i386 BOOT
 Default: 1:ad(1,a)/boot/loader
@@ -75,7 +75,7 @@ boot:
 |[.filename]#loader#
 a|
 
-[source,shell]
+[source,bash]
 ....
 BTX loader 1.00 BTX version is 1.02
 Consoles: internal video/keyboard
@@ -92,7 +92,7 @@ Loading /boot/defaults/loader.conf
 |kernel
 a|
 
-[source,shell]
+[source,bash]
 ....
 Copyright (c) 1992-2013 The FreeBSD Project.
 Copyright (c) 1979, 1980, 1983, 1986, 1988, 1989, 1991, 1992, 1993, 1994
@@ -490,7 +490,7 @@ main.5:
 .[.filename]#sys/boot/i386/boot2/boot1.S# [[boot-boot1-main5]]
 Recall that at this point, register `%si` points to the FreeBSD slice entry in the MBR partition table, so a call to `nread` will effectively read sectors at the beginning of this partition. The argument passed on register `%dh` tells `nread` to read 16 disk sectors. Recall that the first 512 bytes, or the first sector of the FreeBSD slice, coincides with the [.filename]#boot1# program. Also recall that the file written to the beginning of the FreeBSD slice is not [.filename]#/boot/boot1#, but [.filename]#/boot/boot#. Let us look at the size of these files in the filesystem:
 
-[source,shell]
+[source,bash]
 ....
 -r--r--r--  1 root  wheel   512B Jan  8 00:15 /boot/boot0
 -r--r--r--  1 root  wheel   512B Jan  8 00:15 /boot/boot1
@@ -1225,7 +1225,7 @@ The first `__asm` instruction will create an ELF section within the kernel's exe
 
 Running objdump on a kernel binary, you may notice the presence of such small sections:
 
-[source,shell]
+[source,bash]
 ....
 % objdump -h /kernel
   7 .set.cons_set 00000014  c03164c0  c03164c0  002154c0  2**2
diff --git a/documentation/content/en/books/arch-handbook/chapters-order.adoc b/documentation/content/en/books/arch-handbook/chapters-order.adoc
index af38e8536e..ab4d8f3079 100644
--- a/documentation/content/en/books/arch-handbook/chapters-order.adoc
+++ b/documentation/content/en/books/arch-handbook/chapters-order.adoc
@@ -1,17 +1,20 @@
-boot/chapter.adoc
-locking/chapter.adoc
-kobj/chapter.adoc
-jail/chapter.adoc
-sysinit/chapter.adoc
-mac/chapter.adoc
-vm/chapter.adoc
-smp/chapter.adoc
-driverbasics/chapter.adoc
-isa/chapter.adoc
-pci/chapter.adoc
-scsi/chapter.adoc
-usb/chapter.adoc
-newbus/chapter.adoc
-sound/chapter.adoc
-pccard/chapter.adoc
-bibliography/chapter.adoc
+parti.adoc
+boot/_index.adoc
+locking/_index.adoc
+kobj/_index.adoc
+jail/_index.adoc
+sysinit/_index.adoc
+mac/_index.adoc
+vm/_index.adoc
+smp/_index.adoc
+partii.adoc
+driverbasics/_index.adoc
+isa/_index.adoc
+pci/_index.adoc
+scsi/_index.adoc
+usb/_index.adoc
+newbus/_index.adoc
+sound/_index.adoc
+pccard/_index.adoc
+partiii.adoc
+bibliography/_index.adoc
diff --git a/documentation/content/en/books/arch-handbook/driverbasics/chapter.adoc b/documentation/content/en/books/arch-handbook/driverbasics/_index.adoc
index 1f7a6614e2..07732d34bb 100644
--- a/documentation/content/en/books/arch-handbook/driverbasics/chapter.adoc
+++ b/documentation/content/en/books/arch-handbook/driverbasics/_index.adoc
@@ -113,7 +113,7 @@ KMOD=skeleton
 
 Running `make` with this makefile will create a file [.filename]#skeleton.ko# that can be loaded into the kernel by typing:
 
-[source,shell]
+[source,bash]
 ....
 # kldload -v ./skeleton.ko
 ....
@@ -300,7 +300,7 @@ DEV_MODULE(echo, echo_loader, NULL);
 
 With this driver loaded try:
 
-[source,shell]
+[source,bash]
 ....
 # echo -n "Test Data" > /dev/echo
 # cat /dev/echo
diff --git a/documentation/content/en/books/arch-handbook/isa/chapter.adoc b/documentation/content/en/books/arch-handbook/isa/_index.adoc
index a51c91ad1d..a51c91ad1d 100644
--- a/documentation/content/en/books/arch-handbook/isa/chapter.adoc
+++ b/documentation/content/en/books/arch-handbook/isa/_index.adoc
diff --git a/documentation/content/en/books/arch-handbook/jail/chapter.adoc b/documentation/content/en/books/arch-handbook/jail/_index.adoc
index 4ea78c7bb8..4ea78c7bb8 100644
--- a/documentation/content/en/books/arch-handbook/jail/chapter.adoc
+++ b/documentation/content/en/books/arch-handbook/jail/_index.adoc
diff --git a/documentation/content/en/books/arch-handbook/kobj/chapter.adoc b/documentation/content/en/books/arch-handbook/kobj/_index.adoc
index 01321c5c62..01321c5c62 100644
--- a/documentation/content/en/books/arch-handbook/kobj/chapter.adoc
+++ b/documentation/content/en/books/arch-handbook/kobj/_index.adoc
diff --git a/documentation/content/en/books/arch-handbook/locking/chapter.adoc b/documentation/content/en/books/arch-handbook/locking/_index.adoc
index 517c615b99..517c615b99 100644
--- a/documentation/content/en/books/arch-handbook/locking/chapter.adoc
+++ b/documentation/content/en/books/arch-handbook/locking/_index.adoc
diff --git a/documentation/content/en/books/arch-handbook/mac/chapter.adoc b/documentation/content/en/books/arch-handbook/mac/_index.adoc
index f33be4228e..f33be4228e 100644
--- a/documentation/content/en/books/arch-handbook/mac/chapter.adoc
+++ b/documentation/content/en/books/arch-handbook/mac/_index.adoc
diff --git a/documentation/content/en/books/arch-handbook/newbus/chapter.adoc b/documentation/content/en/books/arch-handbook/newbus/_index.adoc
index 797011d3f8..797011d3f8 100644
--- a/documentation/content/en/books/arch-handbook/newbus/chapter.adoc
+++ b/documentation/content/en/books/arch-handbook/newbus/_index.adoc
diff --git a/documentation/content/en/books/arch-handbook/parti.adoc b/documentation/content/en/books/arch-handbook/parti.adoc
new file mode 100644
index 0000000000..1239a7c024
--- /dev/null
+++ b/documentation/content/en/books/arch-handbook/parti.adoc
@@ -0,0 +1,10 @@
+---
+title: Part I. Kernel
+prev: books/arch-handbook/
+next: books/arch-handbook/boot
+---
+
+[[kernel]]
+= Kernel
+
+include::content/en/books/arch-handbook/toc-1.adoc[]
diff --git a/documentation/content/en/books/arch-handbook/partii.adoc b/documentation/content/en/books/arch-handbook/partii.adoc
new file mode 100644
index 0000000000..595673da2a
--- /dev/null
+++ b/documentation/content/en/books/arch-handbook/partii.adoc
@@ -0,0 +1,10 @@
+---
+title: Part II. Device Drivers
+prev: books/arch-handbook/smp
+next: books/arch-handbook/driverbasics
+---
+
+[[devicedrivers]]
+= Device Drivers
+
+include::content/en/books/arch-handbook/toc-2.adoc[]
diff --git a/documentation/content/en/books/arch-handbook/partiii.adoc b/documentation/content/en/books/arch-handbook/partiii.adoc
new file mode 100644
index 0000000000..b11632ef34
--- /dev/null
+++ b/documentation/content/en/books/arch-handbook/partiii.adoc
@@ -0,0 +1,10 @@
+---
+title: Part III. Appendices
+prev: books/arch-handbook/pccard
+next: books/arch-handbook/bibliography
+---
+
+[[appendices]]
+= Appendices
+
+include::content/en/books/arch-handbook/toc-3.adoc[]
diff --git a/documentation/content/en/books/arch-handbook/pccard/chapter.adoc b/documentation/content/en/books/arch-handbook/pccard/_index.adoc
index 1b7be9e711..1b7be9e711 100644
--- a/documentation/content/en/books/arch-handbook/pccard/chapter.adoc
+++ b/documentation/content/en/books/arch-handbook/pccard/_index.adoc
diff --git a/documentation/content/en/books/arch-handbook/pci/chapter.adoc b/documentation/content/en/books/arch-handbook/pci/_index.adoc
index b4a7b72c9c..b4a7b72c9c 100644
--- a/documentation/content/en/books/arch-handbook/pci/chapter.adoc
+++ b/documentation/content/en/books/arch-handbook/pci/_index.adoc
diff --git a/documentation/content/en/books/arch-handbook/scsi/chapter.adoc b/documentation/content/en/books/arch-handbook/scsi/_index.adoc
index 6192c65cbd..6192c65cbd 100644
--- a/documentation/content/en/books/arch-handbook/scsi/chapter.adoc
+++ b/documentation/content/en/books/arch-handbook/scsi/_index.adoc
diff --git a/documentation/content/en/books/arch-handbook/smp/chapter.adoc b/documentation/content/en/books/arch-handbook/smp/_index.adoc
index a47de5f260..a47de5f260 100644
--- a/documentation/content/en/books/arch-handbook/smp/chapter.adoc
+++ b/documentation/content/en/books/arch-handbook/smp/_index.adoc
diff --git a/documentation/content/en/books/arch-handbook/sound/chapter.adoc b/documentation/content/en/books/arch-handbook/sound/_index.adoc
index a68ebe64f8..a7b6567206 100644
--- a/documentation/content/en/books/arch-handbook/sound/chapter.adoc
+++ b/documentation/content/en/books/arch-handbook/sound/_index.adoc
@@ -59,7 +59,7 @@ Under [.filename]#/usr/src/sys/dev/sound/#, the [.filename]#pcm/# directory hold
 [[pcm-probe-and-attach]]
 == Probing, Attaching, etc.
 
-Sound drivers probe and attach in almost the same way as any hardware driver module. You might want to look at the <<isa-driver,ISA>> or <<pci,PCI>> specific sections of the handbook for more information.
+Sound drivers probe and attach in almost the same way as any hardware driver module. You might want to look at the crossref:isa-driver[isa-driver,ISA] or crossref:pci[pci,PCI] specific sections of the handbook for more information.
 
 However, sound drivers differ in some ways:
 
diff --git a/documentation/content/en/books/arch-handbook/sysinit/chapter.adoc b/documentation/content/en/books/arch-handbook/sysinit/_index.adoc
index dab2239d7a..dab2239d7a 100644
--- a/documentation/content/en/books/arch-handbook/sysinit/chapter.adoc
+++ b/documentation/content/en/books/arch-handbook/sysinit/_index.adoc
diff --git a/documentation/content/en/books/arch-handbook/usb/chapter.adoc b/documentation/content/en/books/arch-handbook/usb/_index.adoc
index 18a06c4a0b..18a06c4a0b 100644
--- a/documentation/content/en/books/arch-handbook/usb/chapter.adoc
+++ b/documentation/content/en/books/arch-handbook/usb/_index.adoc
diff --git a/documentation/content/en/books/arch-handbook/vm/chapter.adoc b/documentation/content/en/books/arch-handbook/vm/_index.adoc
index 12b9bf56e6..12b9bf56e6 100644
--- a/documentation/content/en/books/arch-handbook/vm/chapter.adoc
+++ b/documentation/content/en/books/arch-handbook/vm/_index.adoc