git: d7795d4ca0 - main - Split Arch Handbook
Sergio Carlavilla Delgado
carlavilla at FreeBSD.org
Wed Mar 31 21:37:24 UTC 2021
The branch main has been updated by carlavilla:
URL: https://cgit.FreeBSD.org/doc/commit/?id=d7795d4ca0a29c9090c342d41ecf812fe5c9f1ed
commit d7795d4ca0a29c9090c342d41ecf812fe5c9f1ed
Author: Sergio Carlavilla Delgado <carlavilla at FreeBSD.org>
AuthorDate: 2021-03-31 21:36:24 +0000
Commit: Sergio Carlavilla Delgado <carlavilla at FreeBSD.org>
CommitDate: 2021-03-31 21:36:24 +0000
Split Arch Handbook
Split the porters handbook into different chapters like the handbook
---
.../content/en/books/arch-handbook/_index.adoc | 46 +---------
.../bibliography/{chapter.adoc => _index.adoc} | 0
.../content/en/books/arch-handbook/book.adoc | 97 ++++++++++++++++++++++
.../boot/{chapter.adoc => _index.adoc} | 12 +--
.../en/books/arch-handbook/chapters-order.adoc | 37 +++++----
.../driverbasics/{chapter.adoc => _index.adoc} | 4 +-
.../isa/{chapter.adoc => _index.adoc} | 0
.../jail/{chapter.adoc => _index.adoc} | 0
.../kobj/{chapter.adoc => _index.adoc} | 0
.../locking/{chapter.adoc => _index.adoc} | 0
.../mac/{chapter.adoc => _index.adoc} | 0
.../newbus/{chapter.adoc => _index.adoc} | 0
.../content/en/books/arch-handbook/parti.adoc | 10 +++
.../content/en/books/arch-handbook/partii.adoc | 10 +++
.../content/en/books/arch-handbook/partiii.adoc | 10 +++
.../pccard/{chapter.adoc => _index.adoc} | 0
.../pci/{chapter.adoc => _index.adoc} | 0
.../scsi/{chapter.adoc => _index.adoc} | 0
.../smp/{chapter.adoc => _index.adoc} | 0
.../sound/{chapter.adoc => _index.adoc} | 2 +-
.../sysinit/{chapter.adoc => _index.adoc} | 0
.../usb/{chapter.adoc => _index.adoc} | 0
.../arch-handbook/vm/{chapter.adoc => _index.adoc} | 0
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
similarity index 100%
rename from documentation/content/en/books/arch-handbook/bibliography/chapter.adoc
rename to 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
similarity index 99%
rename from documentation/content/en/books/arch-handbook/boot/chapter.adoc
rename to 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
similarity index 99%
rename from documentation/content/en/books/arch-handbook/driverbasics/chapter.adoc
rename to 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
similarity index 100%
rename from documentation/content/en/books/arch-handbook/isa/chapter.adoc
rename to 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
similarity index 100%
rename from documentation/content/en/books/arch-handbook/jail/chapter.adoc
rename to 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
similarity index 100%
rename from documentation/content/en/books/arch-handbook/kobj/chapter.adoc
rename to 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
similarity index 100%
rename from documentation/content/en/books/arch-handbook/locking/chapter.adoc
rename to 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
similarity index 100%
rename from documentation/content/en/books/arch-handbook/mac/chapter.adoc
rename to 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
similarity index 100%
rename from documentation/content/en/books/arch-handbook/newbus/chapter.adoc
rename to 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
similarity index 100%
rename from documentation/content/en/books/arch-handbook/pccard/chapter.adoc
rename to 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
similarity index 100%
rename from documentation/content/en/books/arch-handbook/pci/chapter.adoc
rename to 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
similarity index 100%
rename from documentation/content/en/books/arch-handbook/scsi/chapter.adoc
rename to 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
similarity index 100%
rename from documentation/content/en/books/arch-handbook/smp/chapter.adoc
rename to 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
similarity index 98%
rename from documentation/content/en/books/arch-handbook/sound/chapter.adoc
rename to 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
similarity index 100%
rename from documentation/content/en/books/arch-handbook/sysinit/chapter.adoc
rename to 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
similarity index 100%
rename from documentation/content/en/books/arch-handbook/usb/chapter.adoc
rename to 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
similarity index 100%
rename from documentation/content/en/books/arch-handbook/vm/chapter.adoc
rename to documentation/content/en/books/arch-handbook/vm/_index.adoc
More information about the dev-commits-doc-all
mailing list