git: 9285d9057d - main - Fix HTML validation errors - remove h7 tag, document the rule in FDP

The branch main has been updated by vladlen:

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

commit 9285d9057d266f84a296676bca5b10c6f5442076
Author:     Vladlen Popolitov <vladlen@FreeBSD.org>
AuthorDate: 2026-09-27 17:28:50 +0000
Commit:     Vladlen Popolitov <vladlen@FreeBSD.org>
CommitDate: 2026-09-27 17:28:50 +0000

    Fix HTML validation errors - remove h7 tag, document the rule in FDP
    
    ""Listening Side"" and ""Initiating Side"" in the Developers Handbook
    used level 5 headings, which render as <h7> in single-page HTML
    output for books and fail W3C validation.
    
    Replace them with a bold phrase, and add a WARNING to the
    Asciidoctor chapter of the FDP Primer that level 5 headings are
    unusable in books.
    
    Reviewed by: carlavilla
    Approved by: carlavilla
    Differential Revision: https://reviews.freebsd.org/D60070
    PR: 297509
---
 .../content/en/books/developers-handbook/ipv6/_index.adoc      |  8 ++++----
 .../content/en/books/fdp-primer/asciidoctor-primer/_index.adoc | 10 ++++++++++
 2 files changed, 14 insertions(+), 4 deletions(-)

diff --git a/documentation/content/en/books/developers-handbook/ipv6/_index.adoc b/documentation/content/en/books/developers-handbook/ipv6/_index.adoc
index aa4a4f50ab..1a5fc2cd3e 100644
--- a/documentation/content/en/books/developers-handbook/ipv6/_index.adoc
+++ b/documentation/content/en/books/developers-handbook/ipv6/_index.adoc
@@ -520,7 +520,7 @@ FreeBSD 4.x     configurable            supported
 
 The following sections will give you more details, and how you can configure the behavior.
 
-Comments on listening side:
+Comments on *listening side:*
 
 It looks that RFC2553 talks too little on wildcard bind issue, especially on the port space issue, failure mode and relationship between AF_INET/INET6 wildcard bind.
 There can be several separate interpretation for this RFC which conform to it but behaves differently.
@@ -558,7 +558,7 @@ To resolve this issue more easily, there is system dependent man:setsockopt[2] o
 
 When this call succeed, then this socket only receive IPv6 packets.
 
-Comments on initiating side:
+Comments on *initiating side:*
 
 Advise to application implementers: to implement a portable IPv6 application (which works on multiple IPv6 kernels), we believe that the following is the key to the success:
 
@@ -590,7 +590,7 @@ Kernel configuration is summarized as follows:
 +
 `sysctl net.inet6.ip6.mapped_addr=0`
 
-====== Listening Side
+Comments on *listening side:*
 
 Each socket can be configured to support special AF_INET6 wildcard bind (enabled by default).
 You can disable it on each socket basis with man:setsockopt[2] like below.
@@ -610,7 +610,7 @@ Wildcard AF_INET6 socket grabs IPv4 connection if and only if the following cond
 
 There is no problem with open/close ordering.
 
-====== Initiating Side
+Comments on  *initiating side:*
 
 FreeBSD 4.x supports outgoing connection to IPv4 mapped address (::ffff:10.1.1.1), if the node is configured to support IPv4 mapped address.
 
diff --git a/documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc b/documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc
index 67ba576464..eb9cb7cb82 100644
--- a/documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc
+++ b/documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc
@@ -134,6 +134,16 @@ The following syntax is not correct.
 ....
 ====
 
+[WARNING]
+====
+In books, do not use level 5 headings.
+
+When AsciiDoc sources are assembled into a book, section levels are offset by one (plus the book title itself).
+A level 5 heading (`======`) then renders as an `h7` in single-page HTML output, which is not valid HTML and breaks the document heading hierarchy.
+
+If a block of text needs to be visually separated, use a different AsciiDoc construct instead, for example a paragraph with a bold phrase, a `NOTE`, `TIP`, or `IMPORTANT` admonition, a `[sidebar]` block, or a description list (`term::`).
+====
+
 [[asciidoctor-paragraphs]]
 == Paragraphs