Date: Wed, 31 Mar 2021 21:37:24 GMT From: Sergio Carlavilla Delgado <carlavilla@FreeBSD.org> To: doc-committers@FreeBSD.org, dev-commits-doc-all@FreeBSD.org Subject: git: d7795d4ca0 - main - Split Arch Handbook Message-ID: <202103312137.12VLbOpq059806@gitrepo.freebsd.org>
next in thread | raw e-mail | index | archive | help
The branch main has been updated by carlavilla: URL: https://cgit.FreeBSD.org/doc/commit/?id=d7795d4ca0a29c9090c342d41ecf812fe5c9f1ed commit d7795d4ca0a29c9090c342d41ecf812fe5c9f1ed Author: Sergio Carlavilla Delgado <carlavilla@FreeBSD.org> AuthorDate: 2021-03-31 21:36:24 +0000 Commit: Sergio Carlavilla Delgado <carlavilla@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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?202103312137.12VLbOpq059806>