git: a9f81805c3 - main - fdp-primer: reduce confusion around section levels

The branch main has been updated by grahamperrin:

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

commit a9f81805c39b8a6e0ec6e87ce6d7151764ea850c
Author:     Graham Perrin <grahamperrin@FreeBSD.org>
AuthorDate: 2022-11-30 19:16:52 +0000
Commit:     Graham Perrin <grahamperrin@FreeBSD.org>
CommitDate: 2022-11-30 19:16:52 +0000

    fdp-primer: reduce confusion around section levels
    
    Approved by:           carlavilla
    Differential revision: https://reviews.freebsd.org/D37572
---
 .../content/en/books/fdp-primer/structure/_index.adoc       | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

diff --git a/documentation/content/en/books/fdp-primer/structure/_index.adoc b/documentation/content/en/books/fdp-primer/structure/_index.adoc
index d92af964e1..b35fb23373 100644
--- a/documentation/content/en/books/fdp-primer/structure/_index.adoc
+++ b/documentation/content/en/books/fdp-primer/structure/_index.adoc
@@ -147,9 +147,16 @@ This section contains specific notes about particular documents managed by the F
 
 The books are written in AsciiDoc.
 
-The books are organized as an AsciiDoc `book`.
-The books are divided into ``part``s, each of which contains several ``chapter``s.
-``chapter``s are further subdivided into sections (`=`) and subsections (`==`, `===`) and so on.
+For each FreeBSD book, the AsciiDoc document type (aka doctype) is `book`.
+Books have ``part``s, each of which contains several ``chapter``s.
+
+When the document is converted to HTML 5 (using the built-in `html5` backend):
+
+* AsciiDoc section level 0 (`=`) at the beginning of a ``chapter`` of a `book` will be `<h1>`
+* AsciiDoc section level 1 (`==`) must be used for the first logical section of a chapter, and will be `<h2>`
+* AsciiDoc section level 2 (`===`) must be used for the first logical subsection, and will be `<h3>`
+
+– and so on. Reference: link:https://docs.asciidoctor.org/asciidoc/latest/sections/titles-and-levels/[Section Titles and Levels | Asciidoctor Docs].
 
 [[structure-document-books-physical]]
 === Physical Organization